plotcf


Latest version: 0.9.00 (To be released)  new
Current version: 0.8.24 (released on 2009-11-02)
plotcf is a command-line tool for plotting data from CAA CDF and CEF files. The philosophy behind plotcf is that it should be possible to plot data from CDF and CEF files easily, with an absolute minimum amount of effort required from the user (example uses would be data browsing, or experimenting with different moments calculations). The metadata from CDF and CEF files is used to automatically generate nice plots. Of course, it is also possible for users to have complete control over plots made by plotcf. Because plotcf is a command-line program, batch-processing can easily be done.

Even though it was developed by the PEACE team and has been tested most thoroughly with PEACE data files, plotcf is meant to be a general plotting tool and is able to plot data from other Cluster instruments.

CDF files are preferred to CEF files as they are binary files and hence can have a smaller file size and can be read much more quickly than ASCII CEF files.

plotcf is still in an early stage of development. Feature requests and bug reports are most welcome. Please email adl@mssl.ucl.ac.uk.


Downloads


The current beta version of plotcf can be downloaded here:

Linux x86 (32-bit) Mandrake 9.2
Linux x86 (32-bit) Fedora Core 7, OpenSUSE 11
Linux x86_64 (64-bit) Fedora Core 9
Mac OS X (Intel) Mac OS 10.5.5
Solaris (SPARC) Solaris 10
source code Qt 4.4 or above and CDF libraries required

Don't know which Linux version to download? If you have a very old installation, download this, otherwise, download this. If you're still not sure, try this. If you have a 64-bit operating system, try this.

Installation instructions for Linux/UNIX and Mac OS X, as well as instructions on how to compile plotcf, are available here. Note that the Linux (except 64-bit) and Solaris binaries as well as the source code are updated every night (UK time), however the 64-bit Linux and Mac OS X binaries are only updated whenever there are major changes or improvements made.


Known Limitations


The current version of plotcf should not be expected to work on every single CAA product. Please let us know if you are having trouble plotting a particular product that you would like to be able to plot.

The current version of plotcf is not able to plot more than about a day of data. Midnight crossings are handled correctly, however, if you need to plot data for a time interval that includes midnight.


Examples


A library of example plots from all CAA data products is available (not yet complete).

Here are a few examples. Click on each of the examples to see the full-size image.

C4_CP_WHI_NATURAL example C2_CP_PEA_MOMENTS example C1_CP_FGM_SPIN example

C1_CP_PEA_PITCH_SPINAV example C1_CP_PEA_PITCH_SPINAV example C1_CP_PEA_PITCH_SPINAV example


Basic usage

Time-series plots and spectrograms

To plot all variables with PARAMETER_TYPE = DATA, just specify the CDF/CEF filename(s):

plotcf <filename1> [<filename2> ...] &

Above we have put & at the end of the line, so that plotcf is run in the background, and the command prompt will return immediately.

Each variable will be plotted in an individual panel. All components of vectors and tensors for a single variable will be plotted in a single panel. In this case the different components are indicated by different colours.

If SCALEMIN and SCALEMAX are specified in the variable metadata, these values will be used for the y-axis limits (or for the colour-bar limits for the case of spectrograms). If these are not specified, the lowest and highest values of the actual data will be used instead for the y-axis limits for time-series plots. For spectrograms, the y-axis limits used are always the lowest and highest energies in the energy table.

Wheel plots

To make a wheel plot of the variable with PARAMETER_TYPE = DATA:

plotcf <filename1> -wheel

If there is more than one variable with PARAMETER_TYPE = DATA you will need to specify exactly what variable to plot (see below).

Sauvaud plots

A Sauvaud plot is a stack of angle-time spectrograms for each energy bin. To make a Sauvaud plot of the variable with PARAMETER_TYPE = DATA:

plotcf <filename1> -sauvaud

If there is more than one variable with PARAMETER_TYPE = DATA you will need to specify exactly what variable to plot (see below).

Line spectra plots

A line spectra plot is a slice of data for a given spin, azimuth and (avg) polar. It is now possible to plot line spectra from 3D, PITCH_3D and PITCH_SPIN files
by specifying -slice-3d, -slice-pitch3d and slice-pitch, respectively as plot type
and corresponding arguments to these plot types as detailed down the page. 
plotcf <filename1> [<filename2> ...] [-slice-pitch][-slice-3d][slice-pitch3d]

Short-cuts

plotcf provides a number of short-cuts in order to quickly make commonly used plots.

To plot all variables with PROPERTY = "Number_Density":

plotcf <filename1> [<filename2> ...] -n

To plot all variables with PROPERTY = "Velocity":

plotcf <filename1> [<filename2> ...] -v

To make a plot with all variables with PROPERTY = "Number_Density" in one panel and all variables with PROPERTY = "Velocity" in the next 3 panels:

plotcf <filename1> [<filename2> ...] -nv

To plot all variables with PROPERTY = "Temperature":

plotcf <filename1> [<filename2> ...] -t

To plot all variables with PROPERTY = "Number_Density" in one panel and all variables with PROPERTY = "Temperature" in a second panel:

plotcf <filename1> [<filename2> ...] -nt

To plot all variables with PROPERTY = "Number_Density" in one panel, all variables with PROPERTY = "Velocity" in the next 3 panels, and all variables with PROPERTY = "Temperature" in the next panel:

plotcf <filename1> [<filename2> ...] -nvt

A spectrogram can easily be included in the first panel (above all panels showing moments) by specifying a PEACE 2-D or 3-D distribution file before specifying files containing moments. The EFW spacecraft potential can automatically be overlaid on the spectrogram just by specifying the appropriate file.

If an FGM spin-resolution B-field file is specified, the B-field vector will automatically be shown in the final panel just by specifying an appropriate file.

There are some short-cuts available for use with PEACE pitch angle products:

plotcf <filename1> -ppa

This will make a plot with 3 panels, showing the parallel, perpendicular and anti-parallel pitch angle spectrograms. If an EFW potential file is specified, the potential will be overlaid on the spectrogram.

plotcf <filename1> -app

This will make a plot with 3 panels, showing the anti-parallel, perpendicular and parallel pitch angle spectrograms. If an EFW potential file is specified, the potential willb e overlaid on the spectrogram.


Global plot settings


Plots can be easily customized with the following options:

-st HH:MM:SS
specifies a start time of HH:MM:SS

-sp HH:MM:SS
specifies an end time of HH:MM:SS

-title "My plot title"
sets the plot title to My plot title. The title string supports rich text, i.e. you can include HTML tags for formatting. This enables the title to include subscripts and superscripts, for example. A few commonly-used tags are:

bold <b></b>
italic <i></i>
superscript <sup></sup>
subscript <sub></sub>

Note that rich text is not available on Linux and Unix systems when the -nodisplay option is used.

-o filename
saves the plot to a file with name filename. The file format is defined by the filename extension. Examples: -nodisplay
don't display the plot on the screen. This option is useful for batch processing. On Linux/Unix systems, X11 is not required when this option is used. Rich text is not available on Linux/Unix systems when this option is used.

-smooth <seconds>
use box-car averaging to smooth all time-series data. A time should be specified in seconds.

-grid
draw a grid using dotted lines.

-ctable <table>
specify a colour table to be used for all spectrograms. The default value is 0; a value of 1 is a colour table similar to what is used for CSDS spectrograms; a value of 2 is similar to the IDL blue-red.034 colour table.


Advanced usage


Plotting specific variables

To obtain a list of all varables with PARAMETER_TYPE = "Data" in the specified file(s), use:

plotcf <filename1> [<filename2> ...] -list

Each variable will be listed and assigned a number.

To plot a specific variable, use:

plotcf <filename1> [<filename2> ...] -plot <varnum>

where <varnum> is the variable number, as given from the output of -list. To plot a number of variables, each in a separate panel, use:

plotcf <filename1> [<filename2> ...] -plot <var1>,<var2>,...

To plot more than one variable in a single panel, use, for example:

plotcf <filename1> [<filename2> ...] -plot 0:<var1>/<var2>,1:<var5>/<var6>/<var7>

This will create a plot with two panels. The first panel will have <var1> and <var2>, while the second panel will have <var5>, <var6> and <var7>. Panels are labelled as numbers, with the first panel being number 0.

Individual components of vectors can be selected easily, by appending x, y, or z to the variable number. For example, to make a plot of the z-components only of some vectors:

plotcf <filename1> <filename2> -plot 0:<var1>z/<var4>z

In this example, the z-components of variables 1 and 4 will be plotted together in a single panel. A plot of the x-, y- and z-components of a single vector, for example, could be made in the following way:

plotcf <filename1> -plot 0:1x,1:1y,2:1z

Note that unless individual components of vectors are specified, all 3 components will be in a single panel.

Specifying colours

The colour of each variable when plotted can be specified using names from the list of colours defined in the list of SVG colour keyword names provided by the World Wide Web Consortium.

In the example below, we will plot variables 2, 4 and 6 in red, green and blue, respectively:

plotcf <filename1> <filename2> -plot 0:<var2>/<var4>/<var6> -colour 0:red/green/blue

Specifying y-axis labels

Y-axis labels can be specified by using the -ylabel option and providing a comma-delimited list of panel numbers and y-axis labels.

In the example below, we will plot variables 2, 4 and 6 in separate panels, with the titles Density, Velocity, and Temperature.

plotcf <filename1> <filename2> -plot <var2>,<var4>,<var6> -ylabel 0:"Density",1:"Velocity",2:"Temperature"

Specifying colour bar labels

Colour bar labels can be specified by using the -clabel option and providing a comma-delimeted list of panel numbers and colour bar labels.

In the example below we set the colour bar label for two panels:

plotcf <filename1> -clabel 0:"Differential Energy Flux",1:"Phase Space Density"

Setting y-axis limits

Y-axis limits can be specified for each panel by using -ymin and -ymax. You can either set all panels to have the same lower and upper y-axis limits, or set the limits individually for each panel.

In the example below we set all panels to have the same lower and upper y-axis limits. The -v option is used to plot the velocity variables from each file in this example.

plotcf <filename1> <filename2> -v -ymin -400 -ymax 400

Here, the x-, y- and z-components of the velocity will be plotted with the same y-axis limits.

To set different limits for each panel, you need to provide a comma-delimited list of panel numbers and limits. In the next example, we set different limits for each of the 3 panels:

plotcf <filename1> <filename2> -v -ymin 0:-400,1:-200,2:-200 -ymax 0:400,1:200,2:200

Setting y-axis scale types

By default, the y-axis scale type, either linear or log, is defined by SCALETYP in the metadata (if it exists). If SCALETYP is not defined, linear will be used by default. The user, however, can override this and set the scale type manually.

For example, here we set the first panel to have a log y-scale and the second panel to have a linear y-scale:

plotcf <filename1> -yscale 0:log,1:linear

Setting colour bar limits

Colour bar limits for spectrograms can be set using -cmin and -cmax. You can set either all panels to have the same lower and upper colour bar limits, or set the limits individually for each panel. Comma-delimited lists of panel numbers and limits need to be specified for -cmin and -cmax if each panel is to have different limits.

In the example below, we set the limits for panel 0 only:

plotcf <filename1> -cmin 0:1e-06 -cmax 0:1e-03

Plot panel heights

By default all plot panels have the same height, however it is possible for users to decrease or increase the size of one or more panels. In the example below, plot panel 0 is increased in size by 50%, and plot panel 1 is decreased in size by 50%.

plotcf <filename> -height 0:1.5,1:0.5

Note that the heights of all plot panels are always rescaled so that the entire plot image is filled.

Legends

By default, when multiple variables are plotted in a single panel, legend names are obtained from the variable metadata. Alternatively, users can specify a comma-delimited list of panel numbers and legends. For example:

plotcf <filename1> <filename2> -plot 0:0,5 -legend 0:"PEA density"/"HIA density"

In this example variables 0 and 5 are plotted in a single panel, with legends PEA density and HIA density.

Lines and symbols

It is possible for the user to specify how the data should be plotted. Different line styles and symbols are possible. This is done using the -style option. A comma-delimited list of panel numbers and line/symbol styles is given. The available styles are: In the example below, we use a solid line and a filled circle:

plotcf <filename1> <filename2> -plot 0:0,3 -style 0:lineSolid/circleFilled

Spectrograms: plotting multiple polar bins

By default, all polar bins (or pitch angle bins) are averaged when spectrograms are plotted. This behaviour can be changed by using the -polar option. A comma-delimited list of panels and polar bin is given, for example:

plotcf <filename1> -polar 0:0/5/11

In order to plot all polar bins, use all, for example:

plotcf <filename1> -polar 0:all

In this example panel 0 will actually consist of multiple panels: each polar bin will be shown in it's own panel. A single colour bar box is used for the complete set of panels. When all or multiple polar bins are plotted, plot settings, such as labels and axis limits, can only be changed for the complete set of panels.

When the all option is used, the plot will consist of two columns of panels, rather than one column consisting of a large number of panels. This improves the clarity of the individual spectrograms.


Wheel plots


There are a number of ways in which wheel plots can be customized. As expected, y-axis limits can be specified in the following way:

plotcf <filename1> -wheel -ymin 10 -ymax 4000

and colour bar limits can also be specified in a similar way:

plotcf <filename1> -wheel -cmin 1e-06 -cmax 1e-03

To generate a wheel plot for a particular time, use the -time option. This will use the first data record with the exact time specified or the nearest data record after the time specified by the user. The time can be in one of 3 formats: YYYY-MM-DDTHH:MM:SS.SSSZ, HH:MM:SS.SSS or HH:MM:SS. Example usage:

plotcf <filename1> -wheel -time 05:56:06.459

It is only necessary to use the full date and time format option if the data file contains records from more than one day. If no time is specified, the first data record in the file is used. Note that -st cannot be used to specif the time for making a wheel plot.

The PEACE PITCH_SPIN product only contains one pitch-angle distribution per spin, and is shown in a wheel plot on the LHS. To show the reflection of this data on the RHS, use -wheel ga. In order to show background level data on the RHS, for example when plotting PITCH_SPIN, use -wheel bl.

There are some additional options for PITCH_FULL, PITCH_FULL_LAR, PITCH_3D, and PITCH_3D_LAR only. The choice of data variables to be plotted can be specified using the -en option. By default (i.e. without this option), all 4 data variables are plotted, i.e. top, LEEA overlap, HEEA overlap and bottom energy regions. The possibilities are:
Example:

plotcf <filename1> -wheel -en oloh


Sauvaud plots


There are a number of ways in which Sauvaud plots can be customized. Y-axis limits can be specified in the following way:

plotcf <filename1> -sauvaud -ymin 10 -ymax 4000

and colour bar limits can also be specified in a similar way:

plotcf <filename1> -sauvaud -cmin 1e-06 -cmax 1e-03

Other global settings, such as specifying begin and end times, can be used.

When PITCH_FULL, PITCH_FULL_LAR, PITCH_3D or PITCH_3D_LAR data is used, as with wheel plots, it is possible to specify what data variable to use.
Currently only a single variable can be plotted at the same time.

Another option can be used for any of the PITCH_* data products. -status will include a small panel containing the PADSelectionQuality status variable. For example:

plotcf <filename1> -sauvaud -en ol -status

will plot the LEEA data in the energy overlap region, and include a plot panel showing the PADSelectionQuality status variable.


Line Spectra Plots


There are three types of slice plots depending on input data files.To get line spectra plots from PITCH_SPIN and PITCH_FULL plots the syntax is:

plotcf <filename1>[<filename2> <filename3>...] -slice-pitch
      [<ppa>/<para>/<perp>/<antipara>/<all>/[<pa1>/<pa2>/<pa3>/...]] [bl] -time HH:MM:SS


Other global settings, such as specifying x and y axis ranges, legends etc., can be used.

Below is a description of the arguments:
If -time is mentioned and given a time in HH:MM:SS format, plotcf plots the spin that is closest to the time specified. If no time is specified, plocf plots the first spin from the files.



Spacecraft potential


Sign of EFW spacecraft potential

Whenever the EFW spacecraft potential is plotted in the same panel as PEACE data, the sign of the EFW spacecraft potential is automatically changed to become positive.

Overlaying the EFW spacecraft potential on a PEACE spectrogram

This is easily done using the -scp-show option, and specifying at least one CAA file containing PEACE 3D/2D data and one file containing EFW spacecraft potential data. The EFW spacecraft potential (with positive sign) will be overlaid on all panels containing PEACE 3D/2D spectrograms.
If a plot contains spectrograms for multiple spacecraft, EFW potential files for each spacecraft can be given in any order. The correct EFW file will be used for each PEACE spectrogram.

Spacecraft potential correction

This can be done using the -scp-corr option, and specifying at least one CAA file containing PEACE 3D/2D data and one file containing EFW spacecraft potential data (either spin resolution or high-resolution).

An offset can be easily added to the EFW potential. Use -scp-corr <offset>, where <offset> should be given in eV, and is added to the positive spacecraft potential.

If a plot contains spectrograms for multiple spacecraft, EFW potential files for each spacecraft can be given in any order. The correct EFW file will be used for each PEACE spectrogram.


Frequently asked questions


Q: Why is my spectrogram completely empty?

If no values are indicated on the colour bar, it means that there are no limits specified in the variable metadata, i.e. SCALEMIN and SCALEMAX are not defined. in this situation, you will need to manually set the colour bar lower and upper limits. Unfortunately there are many products in the CAA that don't have SCALEMIN and SCALEMAX (as well as other useful metadata) defined.

Q: Why are some components of vectors or tensors labelled as NULL?

If you are plotting a CDF file, the likely cause for this is that Qtran truncated the names of some variables, but didn't truncate the names when referenced from other variables. This means that plotcf is unable to determine the names of the components. If you generated the CDF file from a CEF file yourself, ensure that you are using Qtran 3.5.4 or above.
 




Last update: 2009-11-01, A.D. Lahiff