plotaz
QPEACE V2.4 February 2003
Software to display and manipulate azimuthal slices of data from the Cluster
PEACE instrument (and perhaps other similar instruments) from data held in
the IDFS (see www.idfs.org) format. plotaz draws on QPeace modules, which
may have wider applicability. At present, plotaz works correctly with the
various 3-D PEACE modes, including 3DX, 3DR, and LER, and also with the original
PAD data and the newer SPINPAD (which is equivalent to the 3D products with
only one sweep per "spin"). At present, QPEACE software does not correctly
handle PAD data taken in HAR mode.
Contents
Copyright and License
Requirements
Authors
History
Running Plotaz
Use
IDFS Lineage
Energy/Velocity Options
Phase Space Options
Analysis Options
Plot Output
Liouville Mapping and Slicing
Concepts
Sources
Pitch Angles
Energy/Velocity
Units and Phase Space Units
Slices
Wheel Plots
Combined Wheel and Slice
Plots
Troubleshooting
Copyright and License
This software is made available under the GNU Public License. SwRI IDFS
software is licencsed separately and does NOT form part of this software.
Some of this software also uses freely available software including the PGPLOT
graphics library and the QT widget library. These libraries are subject to
their own licensing conditions.
Requirements
plotaz is distributed as a binary executable with dynamic linkage for Linux
(Mandrake) and Sun/Solaris. Various system and utility libraries can also
be found on the www distribution site if needed. The full source code is
delivered in the tarr'ed distribution.
plotaz is a C++ application, which draws on QPeace software, which is
written mainly in C. Separate programmer's documentation is provided for
generic QPeace routines. plotaz is a widget application using the QT toolkit.
It is developed primarily on a Linux workstation (Mandrake) and tested regularly
on Sun Solaris. Early versions were developed on a Redhat system without difficulty.
Graphics uses the C language interface to the PGPLOT library (see http://www.astro.caltech.edu/~tjp/pgplot/).
In order to compile against IDFS modules, users will need appropriate licensing
authority for the IDFS software (see www.idfs.org).
Running plotaz requires a local pgplot xwindow server (pgxwin_server -
unless only gif and postscript file output is required) and a fully functional
SDDAS/IDFS system. As of Version 2.2, an attempt is made to automatically
promote data from the IDFS server; use the SDDAS catalog browser to see
if the files are held locally or to fetch them manually.
Authors
Steve Schwartz (s.j.schwartz@qmw.ac.uk) is the original author and formal
PEACE Co-Investigator.
History
26 November 2000 First issue; up-dated 20 June 2001
January 2002 Added attempt at autopromote (courtesy Joey Mukherjee, SwRI);
added capability to take a slice of a sweep, to map a sweep to a new one
based on specified potential difference, field magnitude, and Liouville's
theorem, and to plot all these results as line traces.
February 2003 Finalised autopromote; added function to add parallel velocity
shift in Liouville map to remove any parallel bulk velocity, move into de
Hoffmann-Teller or other special frame, etc.
Running plotaz
Be sure the plotaz executable is in your search path (it is delivered in
the bin directory of the QPeace software), and that the pgplot xwindow server
pgxwin_server and fonts (grfonts.dat) are available, e.g., by placing them
in a directory and setting the environment variable PGPLOT_DIR to point to
that directory. plotaz should run without these if the plots are sent
to gif or postscript files. A script PLOTAZ is provided which sets the shell
and pgplot environment variables if you do not want to add the PGPLOT_DIR
environment variable to your .cshrc. Edit this script to point to your local
copies.
The application takes no arguments and brings up the single GUI shown.
Use
IDFS "Lineage"
Use the pull-down buttons on the left to select the data source (virtual
instrument) for the desired "primary" azimuthal slices. Then push the "Primary
Lineage ->" button to transfer this information to the top right segment
of the GUI. The Primary Slice is used to autoscale the energy scale and counts/phase
space scales, and is also used to define the polar/energy bins for any analysis.
Type the time of interest in the Primary Slice time fields. TIP: <Tab>
takes you from one field to the next. Also select the azimuthal slice, in
degrees from PEACE t_zero. Zero degrees corresponds to sunward-flowing electrons,
but as the spin axis is directed approximately southward, the azimuth increases
in the opposite direction to, e.g., GSE azimuths (see the PEACE diagram for a guide to the PEACE instrument,
mounting, and coordinate systems). QPEACE software including PLOTAZ converts
directions as necessary to represent all velocities, etc., as FLOW
directions. The time corresponds NOT to the time of the azimuthal slice,
but to the beginning of the spin.
NOTE: The lineage buttons for Mission, Instrument, ... are NOT coupled to
one another to facilitate quick change from one spacecraft to another, etc.
This means that you can easily select a non-existent combination, which will
show up as a simple failure to open the selected data source message on the
console.
Similarly select the Secondary Slice parameters. If the lineage is the
same as the Primary, simply push the "Secondary Lineage ->" button. The
"Copy Time" button transfers the Primary Slice time to the Secondary Slice
box.
Both slices offer the option of re-binning in pitch angle. This uses high-resolution
magnetic field data together with the instrument measurements to calculate
accurate pitch angles. The pull-down allows the user to set equal size bins
in either degrees or cosines (i.e., equal solid angles); the number of such
bins is held in the right-most boxes which are editable. All PAD (but not
SPINPAD) and 3D data can be rebinned this way if the field data can be found.
All angles are shown in FLOW directions; specifying an azimuth of
0 degrees corresponds to particles travelling toward the sun (but the spin
axis is directed southward so PEACE azimuths increase in the opposite sense
to GSE. See the PEACE diagram). A polar
[or pitch] angle of 0 degrees corresponds to particles travelling along the
spin axis [or magnetic field in the case of pitch angle distributions].
Energy/Velocity Options
Change these options as desired. Both energy (eV) and velocity (km/s) are
possible. Log scaling produces a double log axis. Note to specify the energy
min and max values on the plot you must change the pull-down button to show
"Userscale->" in addition to entering the values in the corresponding
boxes. After plotaz runs, the min, max boxes are populated with the values
used in the plots.
Phase Space Options
Counts/Accummulation, Differential Energy Flux (essentially calibrated
and geometry-factor-applied counts) and phase space density are provided.
Options and scaling as per Energy/Velocity Options.
Analysis Options
If none is selected here, pushing the Run button will result in a single
polar plot with the Primary and Secondary Slices on the left and right respectively,
as shown in the first example.
Selecting any of the arithmetic options will result in two plots; the top
shows the individual slices, and the bottom the result of the indicated arithmetic
operation. If the two slices do not share the same angle/energy bins, the
second is interpolated onto the first prior to the arithmetic operation. This
interpolation is performed by converting counts to counts/area and then mapping
onto the Primary bins weighted by the area of overlap between bins, before
converting back to counts. In the case of phase space density, this is mapped
directly, weighted again by area of overlap.
Plot Output
Several output formats are supported, including screen (X-window), gif,
and postscript files in colour or grayscale. The Plot File Stem box specifies
the path and name of the desired output file; .ps or .gif are appended as
appropriate.
For X-window plotting, inserting an integer into the Xwin number box will
request pgplot to open and use that pgplot window. This enables the user to
retain more than one plot (by selecting different numbers on successive runs)
and/or to ensure that the application doesn't erase a window drawn by another
application. Pgplot X-windows are re-sizeable and the output at the next
Run is scaled accordingly.
Various environment variables can be set and are used by pgplot to set
plot page sizes. For example, here is an extract from a possible .cshrc
file (though these could also be put inside the plotaz_script if desired):
setenv PGPLOT_DIR /usr/lib/pgplot
# A4 pages: ps defaults otherwise are 7800x10500 milli-inches
# Offsets from corner of page
setenv PGPLOT_PS_WIDTH 7560
setenv PGPLOT_PS_HEIGHT 10800
setenv PGPLOT_PS_HOFFSET 350
setenv PGPLOT_PS_VOFFSET 350
# GIFs: standard defaults are 850 x 680 pixels = 10 x 8 in [85 pix/in]
setenv PGPLOT_GIF_WIDTH 926
setenv PGPLOT_GIF_HEIGHT 638
# Xwindows default width as fraction of display width
setenv PGPLOT_XW_WIDTH 0.6
Liouville Mapping and Slicing
Plotaz will also perform Liouville mapping of pitch angle distributions
and can take slices of pitch angle distributions. Pushing the 'Run then Slice'n'Map'
Button on the Plotaz main gui will do two things:
- It will run plotaz as normal
- It will bring up the following secondary gui
Concepts
- Primary and Secondary refer to the azimuthal sweeps retrieved and
plotted in the main Plotaz gui
- Velocity shifting ADDS the speed inserted in the box to the parallel
component of all energy/velocity bins, and then interpolates the result back
onto a circular grid. The effect is essentially to move the sweep in the 0
degree direction by this amount. The original sweep is first increased in
resolution to avoid leaving holes; the result is a compromise between speed
and quality (which could be altered by recompiling after editing the entries
in the plotaz header file). Both primary and secondary sweeps can be shifted
by independent amounts.
- Liouville Mapping (if desired) is performed on the PRIMARY sweep
by specifying the magnetic field magnitude corresponding to the primary sweep
and a new one at the "mapped" location - only the ratio of these two fields
is needed, so B1 can be left as 1. The electrostatic potential difference
between the "mapped" and primary location is also needed. Liouville mapping
assumes energy and magnetic moment are conserved. See Chapter 7 by Schwartz,
Daly, and Fazakerley, of Analysis Methods for Multi-spacecraft Data (ISSI,
Bern) for a thorough discussion of Liouville mappint techniques and limitations.
Mapping can be performed on the original sweep, a parallel velocity shifted
one, or both.
- Pitch Angle Distributions are required for Liouville mapping, although
slices can be taken of any azimuthal sweep.
- Liouville Mapping can only be performed for sweeps retrieved
in PHASE SPACE DENSITY units, not counts, differential energy fluxes, etc.
- "Pitch angles" for slicing and mapping assume the sweep is a pitch
angle one, with 0 degrees corresponding to the field-aligned flow direction.
Similarly positive and negative portions of the cuts correspond to positive
and negative FLOW directions respectively.
- "Pitch angles" are measured in the spacecraft frame; if the bulk
velocity is comparable to that of the electrons of interest, these pitch
angles and any mapping will not be appropriate unless the bulk shift is applied.
- Gyrotropy/axial symmetry is assumed to obtain both positive and negative
portions of the 1-D slice. NOTE that for non-pitch angle data, this algorithm
does NOT give the slice along a single line; the + and - halves are orientated
differently.
Sources
One of
- None
- Primary - as retrieved in main Plotaz gui
- Shifted Primary - adding the parallel velocity specified in the relevant
box
- Mapped Primary - using Liouville's Theorem and summarised above to
generate a new pitch angle distribution based only on the original primary
sweep
- Shifted then Mapped Primary - using Liouville's Theorem to map the
primary sweep AFTER it has been shifted along the parallel axis.
- Secondary - as retrieved in main Plotaz gui
- Shifted Secondary
- Mapped/Secondary - the ratio of mapped to secondary, using the arithmetic
functions as described in the Analysis section for the main plotaz gui
- Shifted Mapped/Shifted Secondary - ratio of the "Shifted then Mapped"
primary to the shifted secondary
- Mapped-Secondary - the difference of these two
- Shifted Mapped-Shifted Secondary - the difference of these two
Pitch Angles
are any real value in the range 0-180; values outside that range are treated
as 0 (if negative) or 180 (if > 180).
Energy/Velocity
Units and Phase Space Units
are those retrieved using the main plotaz gui, although the plot scaling
can be separately controlled in the Slice'n'Map gui.
Slices
For simple slices of sweep data, up to six traces may be selected using
the bottom half of the gui. If no wheel plots are requested, the plot contains
only slices as shown in the following example. Note that +0 degrees on the
plots corresponds to particles travelling along the spin axis or, in the case
of pitch angle distributions, +0 degree pitch angle particles. Legends provide
a summary of the source, shifting, and mapping options together with start/end
time (for a quantity based on a single sweep) or start times of the two sweeps
in the case of arithmetic operations. Note/Caution: the shifting (and to
a lesser extent mapping) tends to exaggerate the granularity of the original
data.
Wheel Plots
These can be made from the same set of sources and specified using the
top portion of the Slice'n'Map gui. If no slices are specified, the plot
contains only the wheels, such as the following example which shows a shifted
then mapped distribution on the left and a distribution shifted in the opposite
direction on the right. [Note in this artificial example the mapping yields
a discontinuity at 90 degrees due to the large velocity shift which created
a large +/- asymmetry.]
Combined Wheel and Slice
Plots
These are generated by selecting sources in both the Wheel and Slice sections
of the gui, and produce a single page.
Troubleshooting
Lineage
Most problems stem from:
- the specification of the IDFS lineage being incorrect, or
- no data being held locally for the requested time
Note that the elements making up the lineage are treated independently,
so it is possible to specify a non-existent lineage. On the other hand,
this makes selecting the same virtual instrument on another spacecraft quite
easy and quick.
plotaz silently does nothing in these circumstances, though some error
messages may be written to the console from which it was launched which
may be helpful
Plotting
If the plot fails to appear on the screen, this is probably a problem with
the pgplot installation. Pgplot may issue an error message to the console.
- check to ensure that there is an environment variable PGPLOT_DIR set
which contains the pgxwin_server and grfonts.dat file.
- try generating a gif or postscript file
- check if pgplot re-used a plot window which is displayed on a different
"desktop"
If a plot file is specified but doesn't appear, perhaps plotaz was launched
from a directory other than the one in which you are looking for the file.
Try specifying a full path for the file.
Bugs and Features
plotaz tries to identify missing values prior to any arithmetic, although
in practice the default missing value is taken to be zero.. Thus in the
division of one slice by another, a value of zero corresponds to one of zero,
infinity, or a missing value in one of the original slices.
plotaz does not yet handle PAD data in HAR mode, though it should handle
the SPINPAD equivalent (which can NOT be re-binned in pitch angle using high
resolution magnetic field data).
Report bugs and comments to: csc_support@qmw.ac.uk
Peace Diagram
Go to QM Space Plasma Home Page
Page maintained by: Steve Schwartz (s.j.schwartz@qmul.ac.uk)
Last updated: 10 February 2003