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.

qjas gui

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.


qjas sample plot

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: 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

Plotting

Exporting

Bugs and Features


Report bugs and comments to: csc_support@qmw.ac.uk

PEACE Diagram

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