Command line interface to Madrigal

Madrigal contains a number of command line applications that allow access to Madrigal data. Some of these require local access to the files on the Madrigal server, some use the remote API and so can be run from anywhere. This section describes the isprint application in detail, which is relevant both to direct users of the isprint application, and to users of the many API isprint methods that use the same arguments as the isprint command line application.

Command line applications:

Local applications (run only on a madrigal server)

isprint (arguments are used by many isprint API methods)
printCedarRecords
summarizeCedarFile
translateCedarFile

Remote applications (can be run from anywhere - included in python, Matlab, or IDL remote API downloads)

globalDownload.py (download files from multiple Madrigal experiments - python version)
globalDownload.m (download files from multiple Madrigal experiments - Matlab version)
madglobaldownload.pro (download files from multiple Madrigal experiments - IDL version)
globalIsprint.py (search over multiple Madrigal experiments and store ascii results in a file - python version)
globalIsprint.m (search over multiple Madrigal experiments and store ascii results in a file - Matlab version)
madglobalprint.pro (search over multiple Madrigal experiments and store ascii results in a file - IDL version)
madrigalPColor.py - plot PColor plot of data from a given Madrigal file
madrigaScatter.py - plot scatter plot of data from a given Madrigal file

Isprint

The application isprint is used to display both measured and derived data from one particular Cedar/Madrigal file. The input file can be any valid Cedar format. It will generate a table of user selected parameters subject to user specified filters. The name isprint original referred to "Incoherent scatter print" but the application now generically prints any data file in the Cedar format. The engine underlying isprint is the main method for outputting Madrigal data. This application is located in madroot/bin.

The isprint application:

Works with any Cedar file format.
Treats measured and derived parameters in the same way.
Accepts any parameter (or two parameters added, subtracted, multiplied, or divided) as a filter, with any number of allowed ranges.
Keeps track of 1D versus 2D data, and only prints one line of data if only 1D parameters are requested.

To use isprint, the user needs to specify four things:

The full filename
The parameters desired to be displayed (if any)
Any filters to limit the amount of data shown (if any)
Any non-default formatting options

The full filename

file= path to file (this argument is required)
Example: file=/opt/madrigal/experiments/1998/mlh/20jan98/mlh980120g.001

The parameters desired to be displayed

Simply enter the desired parameter mnemonic (case-insensitive). They will be displayed in the order entered. If none given, only the header records will be displayed.
Example: azm gdalt Range ti Dti

Any filters to limit the amount of data shown

Time range

date1=mm/dd/yyyy - starting date to be examined. If time1 not given, defaults to 0 UT.
Example: date1=01/20/1998

time1=hh:mm:ss - starting UT time to be examined. If date1 given, is applied to date1. If not, applies on the first day of the experiment.
Example: time1=13:30:00

date2=mm/dd/yyyy - ending date to be examined. If time2 not given, defaults to 0 UT.
Example: date2=01/21/1998

time2=hh:mm:ss - ending UT time to be examined - If date2 not given, refers to date1. If date1 and date2 not given, refers to 1st day.
Example: time2=15:45:00

In the follow arguments ranges are used. If any range value is not given, it may be used to indicate no lower or upper limit (but the comma is always required). Ranges are inclusive of the end points.

Geodetic altitude

z=lower alt limit1, upper alt limit1 [or lower alt limit2 , upper alt limit2 ...] (km)
Example 1: z=100,500 This would limit the geodetic altitude to 100 to 500 km.
Example 2: z=100,200or300,400 This would limit the geodetic altitude to 100 to 200 km or 300 to 400 km.
Example 3: z=,200or300,400 Since the lower limit of the first range is missing, this would limit the geodetic altitude to anything below 200 km or from 300 to 400 km.

Azimuth (from -180 to 180)

az=lower az limit1, upper az limit1 [or lower az limit2 , upper az limit2 ...] (from -180 to 180 degrees)
Example 1: az=100,120 This would limit the azimuth to 100 to 120 degrees.
Example 2: az=-180,-90or90,180 This would limit the azimuth to between -180 and -90 degrees or to between 90 and 180 degrees. Note this allows a filter to go through 180 degrees.

Elevation (from 0 to 90)

el=lower el limit1, upper el limit1 [or lower el limit2 , upper el limit2 ...] (from 0 to 90)
Example 1: el=0,45 This would limit the elevation from 0 to 45 degrees.

Pulse length (in seconds)

plen=lower pl limit1, upper pl limit1 [or lower pl limit2 , upper pl limit2 ...] (pulse len in sec)
Example 1: plen=,5e-4 This would limit the pulse length to 5e-4 seconds or less.

Free form filters

filter=[mnemonic] or [mnemonic1,[+-*/]mnemonic2] , lower limit1 , upper limit1 [or lower limit2 , upper limit2 ...] (any number of filters may be added)
Example: filter=ti,500,1000or2000,3000 Limits the data to points where Ti is between 500 and 1000 degrees or between 2000 and 3000 degrees. Note that the units are always those of the Cedar standard.
Example: filter=gdalt,-,sdwht,0, This filter implies "gdalt - sdwht" must be greater than 0.0. Since sdwht is shadow height (the distance above any point on the earth where the sun is first visible), this filter implies that only data in direct sunlight will be displayed.
Example: filter=ti,/,Dti,100, Limits the data to points where the ratio Ti/dTi is more than 100.

Format options

header=t or f (defaults to header=t, show headers at the beginning of each record)
Example: header=f

badval=bad value string (defaults to "missing")
Example: badval=n/a

assumed=assumed value string (defaults to "assumed")
Example: assumed=-32766

knownbad=known bad value string (defaults to "knownbad")
Example: knownbad=WARNING-BADVALUE

mxchar=maximum characters per line (defaults to no maximum)
Example: mxchar=80

Example: isprint file=/opt/madrigal/experiments/1998/mlh/20jan98/mil980120g.003 date1=01/20/1998 time1=15:00:00 date2=01/20/1998 time2=16:00:00 z=200,300or500,600 badval=noData filter=gdalt,-,sdwht,0, filter=ti,500,1000 uth gdalt gdlat glon ti te

This example would show data from mil980120g.003 between 15 and 16 UT on 01/20/1998 where altitude is either between 200 and 300 km or between 500 and 600 km, and where gdalt-sdwht is greater than 0 (point is in sunlight), and where ti is between 500 and 1000. "noData" would be printed if data was not available.

printCedarRecords

printCedarRecord prints specified records of a CEDAR file. The file may be any of the 5 supported CEDAR formats (Madrigal, Blocked Binary, Cbf, Unblocked Binary or ASCII"), and may include any mixture of prologue, header and data records. The format of the file is determined automatically. This application is located in madroot/bin.

Usage: printCedarRecords filename firstRecord lastRecord

summarizeCedarFile

summarizeCedarFile prints a one line per record summary of a CEDAR file. The file may be any of the 5 supported CEDAR formats (Madrigal, Blocked Binary, Cbf, Unblocked Binary or ASCII"), and may include any mixture of prologue, header and data records. The format of the file is determined automatically. This application is located in madroot/bin.

Usage: summarize CedarFilefilename

translateCedarFile

This program copies a Cedar file to another file containing the same Cedar records. There are five supported formats:

0 - Madrigal
1 - Blocked Binary
2 - Cbf
3 - Unblocked Binary
4 - Ascii

The format of the input file is detected automatically.

Usage: translateCedarFile inputFile outputFile outputFileFormat

madrigalPColor.py

madrigalPColor.py is a command-line application that creates PColor plots from Madrigal. For example, it could be used to plot electron density versus altitude and time for a given Madrigal experiment file.

This application can be run from anywhere, and is included in the python Madrigal remote API download. Use of this module requires matplotlib (matplotlib.sourceforge.net).

Usage:

python madrigalPColor.py  --url=<url> --file=<file> --parm=<parm>
       --output=<output> --name=<name> --email=<email> --affiliation=<affiliation>
     [--filter=<filter> --title=<title> --startHour=startHour --endHour=endHour
    --minAlt=minimum_altitude --maxAlt=maximum_altitude --minParm=minimum_parm_value 
    --maxParm=maximum_parameter_value]

See isprint for details of how filters work.

Example:

python madrigalPColor.py  --url=http://madrigal.haystack.mit.edu/madrigal \
       --file=/opt/madrigal/experiments/1998/mlh/20jan98/mlh980120g.002 --parm=nel \
       --output=/tmp/mlh_20jan98.png --name="Bill Rideout" --email=brideout@haystack.mit.edu \
       --affiliation=MIT --filter="filter=elm,80,90 filter=gdalt,,500"

madrigalScatter.py

madrigalScatter.py is a command-line application that creates scatter plots from Madrigal. For example, it could be used to Kp versus time for a given Madrigal experiment file.

This application can be run from anywhere, and is included in the python Madrigal remote API download. Use of this module requires matplotlib (matplotlib.sourceforge.net).

Usage:

python madrigalScatter.py  --url=<url> --file=<file> --parm=<parm>
   --output=<output> --name=<name> --email=<email> --affiliation=<affiliation>
   [--filter=<filter> --title=<title> --startHour=startHour --endHour=endHour
    --yMin=y_minimum --yMax=y_maximum]

See isprint for details of how filters work.

Example:

python madrigalScatter.py  --url=http://madrigal.haystack.mit.edu/madrigal \
   --file=/opt/madrigal/experiments/1998/mlh/20jan98/mlh980120g.002 --parm=systmp \
   --output=/tmp/mlh_20jan98.png --name="Bill Rideout" --email=brideout@haystack.mit.edu \
   --affiliation=MIT --filter="filter=elm,80,90"