qjas
QPEACE Version 2.3 July 2002
Software to display angle-time spectrograms stacked by energy of data from
individual energy sweeps of the Cluster PEACE instrument (and perhaps other
similar instruments) from data held in the IDFS (see www.idfs.org) format.
The plot format is based on a design developed by J-A Sauvaud, CESR, Toulouse.
When viewed from afar, the separate spectrograms merge to resemble an omni-directional
energy-time spectrogram. Within each spectrogram, the angular dependence
of a given energy level is revealed.
qjas will also export such sweep-organised data to an ISTP/Cluster compliant
CDF file or to a flat ascii file with attached header conformant with the
proposed Cluster Exchange Format (see http://www.space-plasma.qmul.ac.uk/DOC/).
qjas draws on QPeace modules, which may have wider applicability. At present,
qjas works correctly with the various 3-D PEACE modes, including 3DX, 3DR,
and LER, in which the angle dimension corresponds to polar angle of each
sensor; as time advances successive sweeps are plotted together with a panel
showing the asimuth. Qjas also renders the original PAD data and the newer
SPINPAD (which is equivalent to the 3D products with only one sweep per "spin")
in which the angle dimension corresponds to pitch angle. As of Version
2.3, QJAS will use the high resolution magnetic field to rebin either PAD
or 3D data (but not SPINPAD) into pitch angles, returning one pitch angle
distribution each spin. A Custom Energy Bin facility allows the user to restrict
the energy range and/or number of energy bins used.
Contents
Copyright and Licence
Requirements
Authors
History
Running qjas
Use
IDFS Lineage
Energy/Velocity Options
Phase Space Options
Plot Output
Data Export
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
qjas 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.
qjas is a C++ application, which draws on QPeace software, which is written
mainly in C. Separate programmer's documentation is provided for generig
QPeace routines. Qjas 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 qjas requires a local pgplot xwindow server (pgxwin_server - unless
only gif and postscript file output is required) and a fully functional SDDAS/IDFS
system. Promotion of data held in remote IDFS data servers is currently being
implemented. Qjas handles IDFS data locally. If promotion does not work,
use the SDDAS Data Catalog utility to promote any data and metadata from
an IDFS server prior to running qjas.
Authors
Steve Schwartz (s.j.schwartz@qmw.ac.uk) is the original author and formal
PEACE Co-Investigator.
History
20 June 2001 First issue
31 July 2001 Includes file export
January 2002 File export conforms to Cluster Exchange Format; attempt to
include data promotion (courtesy Joey Mukherjee, SwRI).
July 2002 Added rebinning in pitch angle and custom energy bins.
Running qjas
Be sure the qjas 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. qjas should run without these if the plots are sent
to gif or postscript files. A script QJAS 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.
Pushing the Help button brings up a text browser containing this documentation.
Use
IDFS "Lineage"
Use the pull-down buttons on the left to select the data source (virtual
instrument) for the plot. Here you can also choose to re-bin the data into
pitch angles (in the spacecraft reference frame) using high resolution magnetic
field data (for PAD, LER, and 3D data). The edit box allows you to
specify the number of bins, which can be equally spaced in angle or cosine
from the pa binning options pull down. All scaling options on counts preserve
the total number of counts and so distort the resulting distribution; use
differential energy flux for physically meaningful normalisation.
Type the times of interest in the time fields.
TIP: <Tab> takes you from one field to the next.
The "Copy Time" button transfers all entries in the start time to the end
time, after which you can edit the appropriate end time field, e.g., to plot
one hour of data.
Energy/Velocity Options
Change these options as desired. Both energy (eV) and velocity (km/s) are
possible. Instrument bins uses the bins as gathered by the instrument. Custom
bins allow you to choose the number, scaling, and range of bins. Interpolation
is performed based on a pseudo-spherical polar algorithm.
Phase Space Options
Counts/Accummulation, Differential Energy Flux (essentially calibrated and
geometry-factor-applied counts) and phase space density are provided. Options
and scaling can be adjusted using the pull-down menus and editing the appropriate
fields. On return, the actual values used in the plot are shown in the min/max
boxes. Note that to specify min/max values the pull-down selection must show
"Userscale" or the entered values will be ignored and the plot autoscaled.
Plot Output
Pushing the run button will generate a plot covering the requested time interval,
as shown in the example below.
- Each horizontal band is an angle-time spectrogram for a single
energy band. The centre energy (or velocity) is shown down the left side
of the plot.
- Within each band are "Instrument FLOW Angles". The angle scale
is shown to the right of the top-most energy sub-panel. For 3D data, this
angle is the polar FLOW direction corresponding to each the anode. For the
original PAD data and SPINPAD, this angle is the FLOW angle of a measurement
with respect to the magnetic field direction, so that fluxes ascribed to
0 degree FLOW directions correspond to particles travelling in the same direction
as the magnetic field vector (0 degree pitch angles).
- The bottom-most panel shows the PEACE azimuth corresponding to the
measurement. Zero azimuth corresponds to a plane containing particles FLOWing
toward the Sun, based on the spacecraft configuration and PEACE reset 3.8
degrees after the Sun pulse. For PAD data this is the angle through which
LEEA rotates from start of spin to be looking in +B direction. This
azimuth may be in error and should not be trusted. Note that since the spin
axis points southward, the PEACE azimuth increases in the opposite direction
to the GSE azimuth. See the PEACE diagram at
the end of these notes.
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 stem name of the desired output file. The suffix ".gif" or ".ps"
are added to the stem name.
For X-window plotting, inserting an integer into this 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 QJAS 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
Data Export
qjas will also export the same data it uses in its plot, namely multiple
2-D angle-energy sweeps. Output includes all energy-angle bin information
(written for each record to cope with changing instrument modes). Three output
formats are supported:
- Ascii Cluster Exchange format is a flat comma-delimited data file with
an attached header. The file format conforms with the proposed Cluster Exchange
Format (cef). For readability, each variable is put on a separate line; 2-D
arrays, in particular the sweep data, is broken into rows corresponding to
the rows of the matrix. [cef specifies C-ordering for arrays, with which the
above is consistent for 2-D arrays]
- Ascii Tabular (qft) is similar to the above but the data entries are
in tabulated fields for easier reading. Note that for large arrays, line
lengths become very long and not all editors/systems handle these particularly
well.
- CDF files roughly conforming to ISTP/Cluster standards.
The Export File Stem box is used to hold the path and output file name stem;
the suffices ".cef", ".qft", or ".cdf" are added as appropriate to the file
name.
Troubleshooting
Although not especially verbose, qjas does issue various warnings and errors
to the console window from which it was launched, and this may provide clues
as to the source of the problem(s).
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.
- qjas 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 qjas 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.
Exporting
- First make sure the lineage and time are valid, e.g., by plotting the
data.
- Most cdf problems are due to an error or missing CDF_BIN or GENERIC_PATH
not being set correctly. CDF_BIN should point to the system directory containing
the executable skeletoncdf. GENERIC_PATH should be set to point to the directory
which contains a copy of the skeleton file generic.skt [this is supplied
in the distribution in QPEACE_HOME/bin].
- Other general problems are usually due to write permission errors.
Try setting a full pathname and file in the file stem box, e.g.,
- /home/sjs/output_file which you are certain you have write permission
for.
Bugs and Features
- qjas tends to use a value of zero as a missing or indeterminant value
(e.g., divide by zero).
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@qmw.ac.uk)
Last updated: 9 July 2002