plotaz

Software to display and manipulate azimuthal slices of data from the Cluster and Doublestar PEACE instruments (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 PAD and  SPINPAD data (which are equivalent to the 3D products with only one sweep per "spin").
 

Contents

IDFS Lineage
Energy/Velocity Options
Phase Space Options
Analysis Options
Plot Output
Save/Restore

Concepts
Sources
Pitch Angles
Energy/Velocity Units and Phase Space Units
Slices
Wheel Plots
Combined Wheel and Slice Plots

Copyright and License

Requirements

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. plotaz has also been successfully built under MacOsX, and SwRI provides an SDDAS-aware version which may be particularly helpful for MacOsX users and others for whom the distributed binary code doesn't run properly and who do not have access to the modules (especially idfs and perhaps pgplot) on which plotaz depends. 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.

Authors

History

Running plotaz

The application takes no arguments and brings up the single GUI shown.
 

Using plotaz

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. The Advance to Next Segment button will attempt to re-adjust the time to the next equivalent segment (number of seconds, sweeps, or spins) depending on the gathering and rebinning options chosen. This feature is not guaranteed, and may skip some intervals, especially when used with PAD data which has only two (SPINPAD has one) sweep per spin. Gathering by sweeps (recall for SPINPAD 1sweep = 1 spin) is more reliable. For simple sequences, the sister application qjas will plot a sequence of wheels in addition to its special spectrogram plot, and such sequences are robust in that the entire set is acquired and then cut into the relevant pieces. This option is available under the plot file options.

Gathering

Azimuthal Slicing (only if Gathering set to "No Gather")

Secondary Slice

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.

Pitch Angle Rebinning

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.

Spacecraft Potential Correction

Plotaz will correct the energy bins and, if appropriate, phase space science values, for the effects of the spacecraft potential. This correction can be given as a constant value in Volts, entered in the first box to the right of the option pull-down, or extracted in the case of Cluster from the EFW U_probe prime parameter data held in idfs format. In the case of a gap in the EFW data larger than the value in seconds given in the second text box, or if the EFW data is missing altogether, the constant value is used. Velocities are converted to energy, corrected for spacecraft potential, and then converted back again.

The action taken in correcting the phase space science values depends on the units selected (see Phase Space Options below):

PEACE and Plotaz Geometry

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

Phase Space Options

Analysis Options

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

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

Save/Restore

As of version 3.10, plotaz can save to a single file all the entries and selections on both the main gui and the subsidiary Slice'n'Map gui to a file. The buttons bring up a file browser, and there are no restrictions on file names or file extensions. The files are simple ascii parameter-value files and can be hand-edited if desired. All white-space is stripped, and all parameter names are in uppercase. Selected items from pull-downs are stored by the order down the pull-down menu, starting at 0. This method is not future-proof, and no error-checking is performed, except that unrecognised parameter names are ignored.

Liouville Mapping and Slicing

1. It will run plotaz as normal
2. It will bring up the following secondary gui

Concepts

1. Primary and Secondary refer to the azimuthal sweeps retrieved and plotted in the main Plotaz gui
2. 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.
3. 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.
4. Pitch Angle Distributions are required for Liouville mapping, although slices can be taken of any azimuthal sweep.
5. Liouville Mapping can only be performed for sweeps  retrieved in PHASE SPACE DENSITY units, not counts, differential energy fluxes, etc.
6. "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.
7. "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.
8. 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

1. None
2. Primary - as retrieved in main Plotaz gui
3. Shifted Primary - adding the parallel velocity specified in the relevant box
4. Mapped Primary - using Liouville's Theorem and summarised above to generate a new pitch angle distribution based only on the original primary sweep
5. Shifted then Mapped Primary - using Liouville's Theorem to map the primary sweep AFTER it has been shifted along the parallel axis.
6. Secondary - as retrieved in main Plotaz gui
7. Shifted Secondary
8. Mapped/Secondary - the ratio of mapped to secondary, using the arithmetic functions as described in the Analysis section for the main plotaz gui
9. Shifted Mapped/Shifted Secondary - ratio of the "Shifted then Mapped" primary to the shifted secondary
10. Mapped-Secondary - the difference of these two
11. Shifted Mapped-Shifted Secondary - the difference of these two

Pitch Angles

Energy/Velocity Units and Phase Space Units

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 wheel plots corresponds to particles travelling along the spin axis or, in the case of pitch angle distributions, +0 degree pitch angle particles. The positive (toward the right) portion of the slice corresponds to particles flowing in the direction of the chosen cut angle. The negative portion corresponds to particles travelling in a direction (180 - <cut angle>), so that both halves are taken from a single (primary or secondary) source sweep wheel. 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

Troubleshooting

Launching

Lineage

• the specification of the IDFS lineage being incorrect, or
• no data being held locally for the requested time

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

• 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"

Bugs and Features

Report bugs and comments to: s.schwartz@imperial.ac.uk

Peace Diagram