T H E I N M S A N A L Y S I S L I B R A R Y I S S U P P L I E D "A S - I S",
WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.
++++Version 2007170
This release adds routines for trajectory and pointing display, for SPICE kernel
management and for programming utilities. The ion tuning coefficients for all
encounters through T32 are incorporated into inms_ion_sensitivity. A number of
the plotting routines were modified to display closest approach time
and to improve format.
NEW ROUTINES
inms_plot_geom Clots trajectory and pointing with respect to target
or Saturn.
inms_get_spice_kernels Invokes FTP to download missing SPICE kernels
IIS_frame_definitions.txt A SPICE frames text kernel defining the Ionospheric
Interaction System frame for Titan and Enceladus
inms_auxiliary_value Computes latitude, west longitude, ram angle, and
speed with respect to a target body or Saturn
inms_dump_structure Creates a comma-separated value file containing the
contents of a structure array
inms_idl_type Determines the IDL type that best matches a PDS type
inms_reduce_qb_scan Performs the quad bias scan data reduction - Alpha Version
CHANGED ROUTINES:
inms_test Adds example geometry plot (calls inms_plot_geom)
inms_ion_sensitivity Include all tuning model coefficients through T32
inms_add_aux_axis Now produces axis from either L1A or Spectra structure arrays
Optionally replaces west longitude with local solar time
inms_plot_mass_history Now uses inms_add_aux_axis
inms_plot_stacked_spectra Now uses inms_add_aux_axis
inms_plot_state Displays vertical line at time of closest approach
inms_plot_mt_line Improved graphic format
inms_plot_mt_spectra Improved graphic format
inms_plot_series Improved graphic format
inms_plot_compare Improved graphic format
inms_get_spectra Store time of closest approach
inms_define_xSpecRec Added closest approach time to spectra structure
inms_prepare_plot Color tables no longer implicitly changed. Updated prolog
inms_make_window Added portrait orientation
inms_reduce_ql_scan Correct indexing error in annotations
inms_read_fmt_file Produces complete structure template eliminating the need
for inms_create_l1a_template
inms_get_data Streamlined data structure creation
inms_kernel_list Converted from function to procedure
inms_doy2utc Correct error handler
DEPRECIATED ROUTINES:
The functionality of these routines have been replaced and improved by
new routines. These routines should not be used in new code.
inms_saturn_latitude Use inms_auxiliary_value
inms_saturn_wLongitude Use inms_auxiliary_value
inms_ram_angle Use inms_auxiliary_value
inms_create_l1a_template Replaced by inms_read_fmt_file
Last modified: Tue Jun 19 17:59:48 2007.
| Routine Name | Purpose |
|---|---|
| inms_add_aux_axes | adds auxiliary axes to a plot |
| inms_auxiliary_value | computes lat, lon, ram angle, from data |
| inms_build_locator | creates a selector expression for use in a where statement |
| inms_chebyshev | evaluate chebyshev polynomials by recursion |
| inms_close_windows | closes all open windows |
| inms_compare_utc | compares two UTC time structures |
| inms_compute_density | Simplified density calculation (depreciated) |
| inms_compute_mean_spectra | computes the mean of a collection of spectra |
| inms_compute_summed_spectra | sums spectra contained in a collection |
| inms_create_l1a_template | creates template used in reading L1A files (Obsolete) |
| inms_deconvolve | extracts species abundances by mass deconvolution |
| inms_define_xSpecRec.pro | defines the contents of a spectra record |
| inms_doy2date | converts a day of year numeric date to a calendar date string |
| inms_doy2julian | converts calendar strings to Julian dates |
| inms_doy2utc | converts calendar strings to UTC time structure |
| inms_dump_structure | Creates a CSV file filled with data from a structure |
| inms_file_format | obtains the file format for a specified file type |
| inms_format_time | converts time of day in milliseconds to hours, minutes, seconds |
| inms_format_time_tick | a callback function to format time axis tick labels |
| inms_get_data | reads a Level 1A INMS data file |
| inms_get_series | extracts a subset of data from a Level 1A data structure |
| inms_get_spectra | Extracts one or more spectra from Level 1A data |
| inms_get_spice_kernels | reads a spice furnish text kernel and gets missing files |
| inms_grid_spectra | interpolates mass spectra to uniform time grid |
| inms_hkg_labels | provides list of axis labels for housekeeping data |
| inms_idl_type | determines IDL type based on PDS type name and value range |
| inms_init_ss_position | initializes the spice toolkit for use by inms_ss_position (depreciated) |
| inms_ion_sensitivity | Computes INMS ion sensitivity |
| inms_ion_transmission | computes the effect of angle on transmission |
| inms_is_image | indicates whether an image file is being created |
| inms_is_publication | returns publication quality output flag |
| inms_kernel_list | produces a list of SPICE kernels present or missing |
| inms_l1A_files_read | provides list of Level 1A files last read by inms_get_data |
| inms_l1a_labels | provides list of axis labels for l1A data |
| inms_label_ticks | produces formatted time strings for use as tick labels |
| inms_list_cal_species | lists species contained in calibration data structure |
| inms_list_files | annotates a plot with a list of names |
| inms_make_pds_label | make a pds label file |
| inms_make_profiles | computes density profiles by deconvolution |
| inms_make_scalar | returns an initialized scalar of a specified type |
| inms_make_window | creates a new X window for graphics |
| inms_mdy2doy | converts a date from YYYYMMDD to YYYYDDD |
| inms_neat_ticks | determines values for tick labeling plot keywords |
| inms_parse_file_name | extracts constituent fields from INMS archive file names |
| inms_parse_l1A_name | extracts constituent fields from L1A file names |
| inms_parse_time | extracts fields from date/time strings |
| inms_plot_cal_ptrn | plots calibration cracking patterns curves |
| inms_plot_cal_sens | plots sensitivities as function of species |
| inms_plot_compare | plots count rate time series from Level 1A data and spectra |
| inms_plot_density_profiles | plots one or more density profiles with altitude |
| inms_plot_geom | plots geometric quantities as function of time |
| inms_plot_histogram | plots a mass spectra histogram |
| inms_plot_hkg | plots one or more housekeeping data items |
| inms_plot_mass_history | plots count rate time series from spectra arrays |
| inms_plot_mass_profile | plots signal altitude profiles from spectra |
| inms_plot_mt_line | plots count rate time series from Level 1A data |
| inms_plot_mt_spectra | plots mass time spectra from Level 1A data |
| inms_plot_series | plots one or more housekeeping data items |
| inms_plot_stacked_spectra | plots a collection of spectra as a color coded mass/time spectra |
| inms_plot_state | Plots mass, cycle, or sequence table transitions |
| inms_post_message | Posts a message as a dialog if possible |
| inms_prepare_plot | initializes plotting for X, PS or PNG |
| inms_put_annotations | writes annotations on plot in specified location |
| inms_query_l1a | Extracts configuration data from a Level 1A data structure |
| inms_ram_angle | computes the ram angle (Depreciated use inms_auxiliary_value) |
| inms_ram_coefficient | computes density enhancement in closed source due to velocity |
| inms_read_cal | reads a calibration data spreadsheet |
| inms_read_fmt_file | Reads PDS compiant structure file |
| inms_read_jcamp | reads mass spectrometer data in the JCAMP/DX format |
| inms_read_label | reads a PDS compliant label |
| inms_reduce_qb_scan | reduce quad bias scan data |
| inms_reduce_ql_scan | performs analysis of quad lens scan |
| inms_remove_quotes | removes enclosing quotation marks |
| inms_saturn_latitude | computes the latitude w.r.t Saturn (Depreciated use inms_auxiliary_value) |
| inms_saturn_wlongitude | computes the west longitude w.r.t. Saturn (Depreciated use inms_auxiliary_value) |
| inms_select_cal | selects a calibration record from the calibrtion structure |
| inms_set_charsize | returns scaled character size |
| inms_spectra_aux_values | determines values of ancilliary data |
| inms_spectra_calculations | performs arithmetic with spectra |
| inms_ss_position | computes the position of the subsolar point (depreciated) |
| inms_subtract_background | performs background removal |
| inms_svd_solve | Solves aX=b using Singular Value Decomposition |
| inms_tabulate_spectra | Writes the contents of the spectra record |
| inms_test | executes a sequence of routines to verify installation |
| inms_utc2date | converts a UTC time to a calendar date string |
| inms_utc_increment | increments a UTC time by a specified amount |
| inms_validate_cal_data | confirms a structure is a calibration data structure |
| inms_validate_hkg_data | confirms validity of housekeeping data structures |
| inms_validate_l1a_data | confirms a structure is a valid Level 1A data structure |
| inms_validate_spectra_data | confirms a structure is a spectra data structure |
| inms_validate_time | confirms that a string is a properly formated date/time |
| inms_weighted_mean | computes the estimate of the mean & std deviation |
| inms_write_image | transfers an image from an pixel map and saves to a file |
| l_getdim | transforms the results of where() to dimensions |
| sprl_color_triad | returns the a 3 element byte array corresponding to the named color |
| sprl_colorplot | plots a function of two variables in color |
| sprl_create_list | forms a list of unique elements in an array |
| sprl_cvt_jdate_mdy | converts the specified Julian date to the month, day and year |
| sprl_cvt_jdate_odate | converts a Julian day number to an ordinal date |
| sprl_cvt_jtime_tod | converts the fractional part of a Julian date to time |
| sprl_cvt_odate_jdate | converts an ordinal date/time to a Julian date |
| sprl_date_plotted | annotates a plot with the current date |
| sprl_discrete_color_list.pro | Definitions of discrete colors |
| sprl_draw_flag | draws a flag at a specified location |
| sprl_draw_scale | draws a color bar scale at the specified location |
| sprl_error_plot | Plots data points with x & y error bars |
| sprl_find_color | returns the numerical value corresponding to the named color |
| sprl_is_decomposed | indicates if a true color display is in use |
| sprl_isnumeric | Tests if a string represents a valid number |
| sprl_load_blue_sequential | loads the blue sequential color table |
| sprl_load_catagorical_colors | loads the discrete colors defined in SPRL_DISCRETE_COLOR_LIST.PRO |
| sprl_load_colors | interface to set of color table loading routines |
| sprl_load_divergent_colors | loads a divergent color table (blue) |
| sprl_load_red_sequential | loads the red sequential color table |
| sprl_load_spectrum_sequential | loads the spectrum sequential color table |
| sprl_plot_sym | generated user defined plot symbols |
NAME:
inms_add_aux_axes - adds auxiliary axes to a plot
pro inms_add_aux_axes, axData, $
anXticks, $ ;; (i) the x positions of the tick marks
nYpos, $ ;; (i/o) the position of the first axis
nYspacing, $ ;; (i) the spacing between axes
time=time, $ ;; (i) if set, specifies indpendant variable
target=target, $ ;; (i) set to specify target based coordinates
catime=catime, $ ;; (i) if set add time to closest approach scale
lst=lst ;; (i) if set replace wLon with local solar time
PURPOSE:
adds additional auxiliary axes below the main x axis
RESTRICTION:
routine assumes that the axis transform information created
by plot or contour is valid. This routine should be called
immediately after the routine that displays the data to be annotated
ARGUMENTS:
axData - a structure containing the data
anXticks - the location in data units of each tick mark on the prime axis
nYpos - the location of the axis, upon return it contains
the position at which the next axis would be plotted
nYspacing - the spacing between axes
nYpos and nYspacing are in normal coordinates
/target - a keyword which specifies whether additional axis contain
s/c position wrt Saturn or wrt the current target body. If set
the auxilliary axis is with respect to the target body, not
Saturn
/lst - a keyword which controls the display of longitude
If present, local solar time is displayed as an auxiliary axis
If absent, west longitude is displayed a san auxiliary axis
/catime - a keyword which controls the addition of a time to closest
approach axis. If /target is set and /catime is set, a
fourth auxilliary axis is displayed showing the time to closest approach
time - A keyword containing a value of time for each element of the
axData array of structures. Used when the independent variable
is not an field of the axData structure.
METHOD:
Determines whether the input data consists of L1A or Spectra Records
Extracts or calculates time from closest approach, altitude, latitude,
and local solar time.
Interpolates those values to the values of the tick marks. If the time
keyword supplies a vector, that vector is taken as the independant vector,
otherwise the time of day in seconds (uttime or nUttime) is used. The
axis routine is used to display the resulting scale
CHANGES:
13-Jul-2004 DAG initial coding
20-August-2004 NAB simply changed 'bp_add_aux_axes' to 'inms_*'
26-August-2004 NAB changed to use structure created by inms_get_data
13-October-2004 DAG allow plotting of either saturn or target coordinates
24-Jun-2004 DAG allow use of alternative independent variable data
28-Jun-2004 DAG corrected prolog
30-Sep-2006 DAG Adjust size of characters annotating axis
16-Nov-2006 DAG Add time to closest approach to axis when /catime and /target are
present
10-Apr-2007 DAG Use data from either L1A or Spectra record array for aux axis
Add switch to replace west longitude with solar zenith angle
(Routine contained in inms_add_aux_axes.pro)
NAME:
inms_auxiliary_value - computes lat, lon, ram angle, from data
Created by David A. Gell on 2007-03-21.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
function inms_auxiliary_value, axData, $
lat=lat, $
wlon=wlon, $
ram=ram, $
speed=speed, $
saturn=saturn, $
debug=debug
PURPOSE:
computes gemetric value from data in input l1a structure array
RETURNS;
a vector containing the desired quantity with a value corresponding
to each entry in the input l1a data array. returns -1 if an error
occurs. Angles are returned in degrees
ARGUMENTS:
axData - an array of L1a data records for which auxiliary values
are required
KEYWORD PARAMETERS:
/lat - if present latitude in degrees returned
/wlon - if present west longitude returned
/ram - if present angle of instrument boresight with
respect to spacecraft velocity returned
/speed - if present the speed of the spacecraft in the target or
saturn coordinate frame is returned
/saturn - if present geometry is refered to Saturn
if absent geometry is refered totarget body
RESTRICTIONS:
METHOD:
EXAMPLE:
MODIFICATION HISTORY:
date by description
21 Mar 2007 D. A. Gell Initial coding
16 Apr 2007 D. A. Gell correct variable usage
(Routine contained in inms_auxiliary_value.pro)
NAME:
inms_build_locator - creates a selector expression for use in a where statement
function inms_build_locator, sStructName, $ ;;(i) string holding name of variable
debug=debug, $ ;;(i) debug switch
_extra=extra ;;(i) selectors
PURPOSE:
create a expression to be used in a where statement to locate data
RETURN VALUE:
a string containing a logical expression for use in a where statement.
returns a null string in the event of an error.
ARGUMENTS:
sStructname: a string containing the name of the l1A structure variable
to which the locator will be applied
extra A series of keyword expressions where the keyword name is an
INMS level 1A data item and the value is either a scalar or
a 1 dimensional element vector. In the first case the
keyword expression
KEYWORD=VALUE
a clause of the form
AND SSTRUCTNAME.KEYWORD EQ VALUE
is added to the selection criteria. If the vector has
two elements as follows
KEYWORD=[MIN, MAX]
then the a clause of the form
AND SSTRUCTNAME.KEYWORD GE VALUE[0]
AND SSTRUCTNAME.KEYWORD LE VALUE[1]
is added to the selection criteria. If the vector has more
than two elements
KEYWORD=[V1, V2,...VN-1]
then a clause of the form
AND (SSTRUCTNAME.KEYWORD EQ VALUE[0]
OR SSTRUCTNAME.KEYWORD EQ VALUE[1]
OR SSTRUCTNAME.KEYWORD EQ VALUE[2] ...
OR SSTRUCTNAME.KEYWORD EQ VALUE[N-1] )
is added to the selection criteria
In addition the keywords /INGRESS and /EGRESS may be
specified to select data with decreasing altitude or
increasing altitude, respectively
ROUTINES REQUIRED
inms_file_format
CHANGES:
28-JUL-2004 DAG Initial Coding
14-Sep-2004 DAG Relax type testing, check if string or numeric and
if numeric cast to match field
05-Oct-2004 DAG Allow keywords to be adorned with a leading
underscore (_) to insure uniqueness. Make string
comparisions case blind (force all values to lowercase)
18-Nov-2004 DAG Ensure that sclk delimiter is T (not t)
30-Nov-2004 DAG Replaced make_scalar with inms_make_scalar
19-Jan-2005 DAG Updated to be compatable with inms_create_l1a_template
changes
26-Jan-2005 DAG Improve comment readability
22-Jun-2005 DAG Replace inms_create_l1a_template by inms_file_format
29-Aug-2006 DAG don't add quote marks to sclk
20-Sep-2006 DAG Use error handler and inms_post_message
14-Dec-2006 DAG Added selection for ingress or egress to target
(Routine contained in inms_build_locator.pro)
NAME:
inms_chebyshev - evaluate chebyshev polynomials by recursion
function inms_chebyshev, nX, $ ;; (i) the value of the argument of the
;;; polynomials
nM, $ ;; (i) the order of the polynomial
xrange=xrange ;; the range of data
PURPOSE: evaluate the chebyshev polyminals at value x for use as
basis vectors for curve fits
ARGUMENTS:
nX - the value, between xrange[0] and xrange[1]
for which the basis function are required. If a
vector is supplied, the result is a two dimensional array
nM - the number of basis functions to be evaluated
XRANGE - the range of data
RETURN VALUE:
An array each row of M elements containing the value of the first M
chebyshev polynomials for the the corresponding nX value.
[ T0[x] | T1[X] | T2[X] ... T(M-1)[X] ]
METHOD: Uses the recursion formula, see Press, et.al, "Numerical Recipies"
section 5.6
USAGE:
The function must be called with the xrange keyword parameter set prior to
calling a curve fitting function to which this routine is supplied as the
basis functions. This stores the range of the abscissa required to
transform the independent variable to the interval [-1,1]
ndummy=inms_chebyshev(xrange=[5000080L, 6000000L])
anR=curvefit(... function='inms_chebyshev'...)
CHANGES:
27-Dec-2004 DA Gell Corrected order of arguments in replicate statement
used to initialize anBasis[*,0] correcting error in
reconstructions
06-Oct-2006 DA Gell Extracted from inms_grid_spectra for use in other
generic fits
(Routine contained in inms_chebyshev.pro)
NAME:
inms_close_windows - closes all open windows
pro inms_close_windows
PURPOSE:
Closes all open windows
USAGE:
inms_close_windows
CHANGES:
19-JAN-2005 DA GELL Initial coding
(Routine contained in inms_close_windows.pro)
NAME:
inms_compare_utc - compares two UTC time structures
function inms_compare_utc, xUTC1, xUTC2
PURPOSE: Compares two times in UTC format
ARGUMENTS;
xUTC1, xUTC2 UTC time structures to compare
each anonymous structure contains two fields as follows
xUTC={nDate:0L, nMSecs:0L}
nDate contains the ordinal date formed by adding the
day-of-year to 1000 times the year, xUCT.nDate=1000L*nYear + long(nDOY)
nMSecs contains the time of day in milliseconds
RETURN VALUE:
-1 IF xUTC1 < xUTC2
0 IF xUTC1 == XUTC2
1 IF xUTC1 > XUTC2
CHANGES
28-Feb-2005 DA Gell Initial coding
(Routine contained in inms_compare_utc.pro)
NAME:
inms_compute_density - Simplified density calculation (depreciated)
pro inms_compute_density, axL1A, $ ;; (i) input level 1 data
anDensity, $ ;; (o) array of densities (m^-3)
anDensErr ;; (o) array of density errors
PURPOSE:
compute the atmospheric density at titan without de-convolution
This routine has been depreciated - do not use in new work
ARGUMENTS:
axL1A - an array of INMS level 1A data
anDensity - an array of density values in units of
number per meter cubed.
The array is the same length as the array of
level 1A data, axL1A. Values are inserted into this array
for each axL1A record with mass 16 or 28.
All other values are zero.
METHOD:
the counter 1 count is divided by the sensitivity and integration period
for any IP with mass 16 or 28. If the measurement is closed source, the
result is further divided by the ram enhancement factor to yield the
ambient density.
to add aditional species, add the mass and sensitity values
then add block to perform the computation. Use the N2 or CH4 computations
as a template
CHANGES:
08-Oct-2004 DAG Initial coding (based on computation in
countstodensity
26-Oct-2004 DAG handle counter roll-over for TA data
27-Oct-2004 DAG omit non-csn data from output
11-Nov-2004 DAG Add calculation of density errors
16-Nov-2004 DAG Add calculation based on osnb counting
15-Feb-2005 DAG Correct calculation of angle by normalizing
velocity vector
14-Nov-2005 DAG Changed value for nC2gain to 4459.6 from analysis in
"Determination of counter Response Ratio from Flight
Data" INMS file 089-0065
4 Dec 2004 DAG Depreciated
(Routine contained in inms_compute_density.pro)
NAME:
inms_compute_mean_spectra - computes the mean of a collection of spectra
pro inms_compute_mean_spectra, axSpectra, $ ;; (i) array of spectra structures
xMeanSpectra, $ ;; (o) mean spectra
poisson=poisson, $ ;; (i) set if statistics assumed Poisson,
debug=debug ;; debug switch, set to enable
PURPOSE:
Computes the mean and standard deviation of the collection of spectra
provided in the array of structures axSpectra,
ARGUMENTS:
axSpectra an array of at least two spectra structures
xMeanSpectra a spectra structure containing the mean spectra
spectra definition in file inms_define_xSpecRec.pro
METHOD:
CHANGES
02-AUG-2004 DAG initial coding
17-Sep-2004 DAG changed method to straight average and sigma calculation
change counts to float, permitting averages
add type code to record
7-Oct-2004 DAG corrected spectra field name sType to comply with standard
3-Nov-2004 DAG if only one input spectra copy to output, add number of spectr
to type string
7-Jan-2005 DAG compute error as sqrt(number of counts)/no of samples
26-Jan-2005 DAG improve comment readablility
20-Sep-2006 DAG Use error handler and inms_post_message
17-Nov-2006 DAG Fixed error in handling the debug switch
21-Nov-2006 DAG Compute midpoint geometric quantities by interpolation
27-Nov-2006 DAG Correct interpolation method selection
04-Dec-2006 DAG Added velocity components to spectra structure
18-Dec-2006 DAG Ensure backwards compatiblity
(Routine contained in inms_compute_mean_spectra.pro)
NAME:
inms_compute_summed_spectra - sums spectra contained in a collection
pro inms_compute_summed_spectra, axSpectra, $ ;; (i) array of spectra structures
xSummedSpectra, $ ;; (o) sum of spectra
debug=debug ;; debug switch, set to enable
PURPOSE:
Sums a collection of spectra provided in the array of structures axSpectra
and determines the Poison standard deviation
ARGUMENTS:
axSpectra an array of at least two spectra structures
xSummedSpectra a spectra structure containing the result
see file inms_define_xSpecRec.pro for contents
CHANGES:
10-Sep-2004 DAG initial coding, based on compute_mean_spectra
17-Sep-2004 DAG removed loop, use dimension argument to ensure counts in channel summed
change counts to float, permitting averages
add type code to record
6-Oct-2004 DAG If the input array of spectras aXspectra has one element,
return it as the summed spectra.
7-Oct-2004 DAG corrected field name sType to comply with standard
29-Dec-2004 DAG added number of spectra to type string
20-Sep-2006 DAG Use error handler and inms_post_message
21-Nov-2006 DAG Compute midpoint geometric quantities by interpolation
27-Nov-2006 DAG Correct interpolation method selection
04-Dec-2006 DAG Added velocity components to spectra struture
18-Dec-2006 DAG Ensure backwards compatibility
(Routine contained in inms_compute_summed_spectra.pro)
NAME:
inms_create_l1a_template - creates template used in reading L1A files (Obsolete)
PRO inms_create_l1a_template, xTemplate, file=file, debug=debug
PURPOSE:
creates template for the L1Archives files to be used by inms_get_data
ARGUMENTS:
sTemplate the template structure
KEYWORDS:
file supplies the name of the file for which a template is
requested, defaults to last file read
/debug set to produce additional error data
CHANGES:
7-June-4 NAB procedure born
28 June 04 jkp changed name to create_ion_template
26-Jul-04 DAG changed name to inms_create_l1a_template
24-Aug-2004 dag added additional fields, sc_vel_scx, sc_vel_scz, and
sc_vel_scz. Replaced alt_s with distance_s. prepared
header for doc_lib use.
7-Jan-2005 dag new version, reads format file
17-Mar-2005 dag insure that both ASCII_INT and ASCII_INTEGER are
properly interpreted.
22-Jun-2005 DAG add handling for PDS TIME data type (treat as character)
24-Jun-2005 DAG insure that both ASCII_FLOAT and ASCII_REAL are
properly interpreted
26-Oct-2005 DAG Correct error which prevented short integers from being
properly initialized
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_create_l1a_template.pro)
NAME:
inms_deconvolve - extracts species abundances by mass deconvolution
pro inms_deconvolve, axResult, $ ;;(o) resulting densities and std deviation
xSpectra, $ ;;(i) a spectra
axCal, $ ;;(i) calibration data
species=species, $ ;;(i) list of species
c2factor=c2factor, $ ;;(i) ratio of c1 counts to c2
critfreq=critfreq, $ ;;(i) C1 maximum linear frequency
tempCS=tempCS, $ ;;(i) The antechamber wall temperature
plot=plot, $ ;;(i) set to plot the histogram and fit
annotate=annotate, $ ;;(i) controls annotation
noannotate=noannotate, $ ;;(i) set to disable annotations
chisqr=chisqr, $ ;;(o) optional chisqr output
model=model, $ ;;(o) optional reconstructed spectra
residual=residual, $ ;;(o) and residual
kernel=kernel, $ ;;(o) and kernel
debug=debug, $ ;;(i) set for debuging
verbose=verbose, $ ;;(i) set for verbose output
_extra=extra
PURPOSE:
performs a linear-least square retrieval of the species abundances from a
spectra
METHOD: See memo Gell, D.A. "Deconvolution of INMS Mass Spectra", 13 Jan 2005
ARGUMENTS:
OUTPUTS:
axResult - an array of structures containing the retrieved density and
mole fractions. Each element of the array has the form
xResult = {sSpecies: 'xx', $ ;; the name of the species
nAlt: 0.0, $ ;; altitude of the data
nDensity: 0.0, $ ;; number per cubic centimeter
nSigma: 0.0, $ ;; standard deviation of above
nMoleFcn: 0.0, $ ;; mole fraction, N / (total(Ni)
nMoleSig: 0.0, $ ;; standard deviation of above
nSingValue:0.0} ;; singular value associated with this species
INPUTS:
xSpectra - A spectra record, as formed by inms_get_spectra containing the
mass spectra to deconvolve
axCal - The calibration data in the form returned by inms_read_cal. This
structure contains a filed for each column in the calibration
spreadsheet designed by Wayne Kasprzak
KEYWORDS:
species - a string vector containing a list of species to retrieve
if absent, defaults to ['N2','CH4']
c2factor - the ratio of counter 1 counts to counter 2 counts
if absent, defaults to 6727
critfreq - the maximum frequency at which counter 1 is linear
if absent, no replacement of the c1 counter valuea by scaled
c2 counter values is performed,
specifying /critfreq results in a default value of 1.75 MHz
tempCS - the temperature of the closed ion source antechamber in
degrees Kelvin.
plot - if set produce a plot of the input spectra, synthetic spectra
and residuals annotated with measurement conditions and results
noannotate- if plot is set, noannotate omits annotations from the plot
annotate - a list of options specifing which annotations are
to be added to the plot. The choices are:
"None" is equavalent to /noannotate
"Residual" adds a lower panel displaying the scaled fit residual
"Deconvolution" adds the table of species density
"Observation" adds the observation conditions
"Isotopes" adds the table of isotope ratios, if any isotopic
specieswere included in the species list.
Each option may be abbreviated by its first letter.
chisqr - set to a named variable to receive the reduced chi-squared value
model - set to a named variable to receive the reconstructed spectra.
the model is a one-dimensional array with each element containing
the counts per ip in the corresponding mass bin
residual - set to a named variable to receive the difference between the
reconstruction and the input mass spectra. The residual is a
one-dimensional array with each element containing
the residual in counts per ip in the corresponding mass bin
kernel - set to a named variable to contain the kernel structure. The
structure is of the following form
xKernel={anKernel: fltarr(nMassCount,nSpeciesCount),$
anMass: intarr(nMassCount)}
where nMassCount is the number of mass bins in the spectra and
nSpeciesCount is the number of species in the species list.
verbose - set to provide additional output messages tracing program execution
debug - set to provide additional debuging features
CHANGES:
26-Jan-2005 D. A. Gell, release as used to analyze data for the Science Paper
08-Mar-2005 D.A. GELL, added altitude to results structure.
return reduced chi-square value
14-Mar-2005 D.A. Gell, Correct test for overflow, accounting for number of IPs
co-added during spectra formation
31-Mar-2005 D. A. Gell, added capability to ignore mass 28,
additional annotations
26-Apr-2005 D. A. Gell, increased critical frequency to 1.5MHz from 1.0 MHz
08-Jun-2005 D.A. Gell make critical frequency a keyword
22-Jul-2005 D.A. Gell permit selection of annotation elements
02-Sep-2005 D.A. Gell deleted unneeded keyword calfactor, added keyword
annotate.
Now returns chi-square not reduced chi-squared
Now use inms_select_cal and sprl_error_plot in place
of add-hoc code. Correct error creating isotope
output structure when only one of the isotopes
present
13-Sep-2005 D.A. Gell Character size setting considers value of !p.charsize
27-Sep-2005 D.A. Gell Reports the reduced chi-square value
Annotation includes chi-square, reduced chi-squared value
Degrees of freadom, and Q statistic
Displays both density and mole fraction - deleted mole keyword
18-Oct-2005 D.A. Gell Replaced ad-hoc code for annotation with calls to
inms_put_annotation where appropriate
14-Nov-2005 D.A. Gell Changed value for nC2mult to 4459.6 from analysis in
"Determination of counter Response Ratio from Flight
Data" INMS file 089-0065
13-Dec-2005 D.A. Gell Moved definition of result and ratio structures to prolog
to comply with coding standard
06-Feb-2006 D.A. Gell If open source cal data is unavailable, used closed
Add keyword to set the closed ion source antechamber
temperature
20-Sep-2006 DAG Use error handler and inms_post_message
04-Oct-2006 D.A. Gell Change default value of C1 critical frequency to 1.25 Mhz
Change default value of C1/C2 ratio to 5840.7 (ex 4459.6)
09-Oct-2006 D.A. Gell Include name of species in error message when cal info cannot be
found.
Fix error in calculation of kernel matrix. Masses now floats in
call data, need to be rounded, not truncated when used to
calculate indices into kernel matrix.
30-Nov-2006 D.A. Gell Omit computation of isotopic ratio, no14 and no28 options
(Routine contained in inms_deconvolve.pro)
NAME:
inms_define_xSpecRec.pro - defines the contents of a spectra record
useage: @inmd_define_xSpecRec.pro
changes:
26-Aug-2005 D.A. Gell extracted from inms_get_spectra, adding lat, lon, lst and sza to
structure
29-Aug-2005 D.A. Gell added target name to structure
4-Dec-2006 D.A. Gell add components of spacecraft velocity to structure
4-Jan-2007 D.A. Gell add sequence and cycle table to structure to support
determination of correct ion sensitivity paramters
10 Apr 2007 D.A. Gell add time from closest approach to spectra record
--------------------------------------------------------------------------
;; create a spectra record
spectra record definitions
xSpecRec = { sType: 'Data', $ ;; type indicator
sFirstDOYtime: '2000-100T00:00:00', $ ;; start time of spectra UTC
sFinalDOYtime: '2000-100T00:00:00', $ ;; final time of spectra UTC
sTarget: 'titan', $ ;; name of the target body
nUTtime: 0L, $ ;; time of (mid-point) spectra ms
nTimeCA: 0L, $ ;; time from closest approach ms
nLat_t: 0.0, $ ;; latitude of spacecraft wrt target deg
nWlon_t: 0.0, $ ;; west longitude of spacecraft wrt target deg
nSza_t: 0.0, $ ;; solar zenith angle of subsatellite point deg
nLst_t: 0.0, $ ;; local solar time of subsatellite point hr
nAlt_t: 0.0, $ ;; altitude of spacecraft wrt target km
nSpeed: 0.0, $ ;; speed wrt target km/sec
nAngle: 0.0, $ ;; angle of boresight wrt velocity deg
nVelX: 0.0, $ ;; x-component of s/c velocity wrt target km/sec
nVelY: 0.0, $ ;; y-component in the s/c frame km/sec
nVelZ: 0.0, $ ;; z-component km/sec
nIntPeriod: 0.031, $ ;; duration of the integration period sec
nCoAddCnt: 0, $ ;; number of IPS coadded
sSource: 'osnb', $ ;; source name
nSeqTable: 0, $ ;; sequence table ID number
nCycTable: 0, $ ;; cycle table ID number
anMassTables: massTableID, $ ;; list of mass tables
anMassBins: anMassList, $ ;; actual masses of bin
anC1Counts: fltarr(nMassCount), $ ;; C1 Counts per IP
anC1Error: fltarr(nMassCount), $ ;; standard deviation
anC1Samples: lonarr(nMassCount), $ ;; number of samples
anC2counts: fltarr(nMassCount), $ ;; C2 Counts per IP
anC2Error: fltarr(nMassCount), $ ;; standard deviation
anC2Samples: lonarr(nMassCount) $ ;; number of samples
}
spectra type field may be Data - data extracted from packets,
Mean - averages spectra
Summed - Summed spectra
Ion - ion abundances
Gridded - time interpolated to
uniform time intervals
Created - created by user input
(Routine contained in inms_define_xSpecRec.pro)
NAME:
inms_doy2date - converts a day of year numeric date to a calendar date string
function inms_doy2date,doy
PURPOSE:
converts day-of-year (yyyy-ddd) to calendar date dd-mon-19yy
ARGUMENT:
An array of strings containing the dates to convert
RETURN VALUE:
an array of strings containing the converted date strings
EXAMPE:
aSresult = inms_doy2date(['2004-001','2004-031'])
print,asResult
01-Jan-2004 31-Jan-2004
adapted from version used by tidi
note that the conversion is valid only between 1901 and 2999
due to leap year check
changes
8-Jul-2004 DAG adapted from version used by tidi
29-Nov-2004 DAG changed name to inms_doy2date
(Routine contained in inms_doy2date.pro)
NAME:
inms_doy2julian - converts calendar strings to Julian dates
function inms_doy2julian, asDoyTimes, mjd=mjd
PURPOSE:
convert strings in the form yyyy-doyThh:mm:ss.sss to a Julian date
RETURNS:
Julian Date, JD for the specified
Gregorian Dates. If the input is an array
the output is an array of the same shape
ARGUMENTS:
asDoyTimes - an array of strings containing PDS compliant
doy time strings.
/MJD Set if input is a modified Julian date
METHOD:
The input calendar dates are converted to ordinal dates,
where the date is the year*1000+day-of-year and the time
is the time of day in milliseconds. The routine
sprl_cvt_odate_jdate performs the conversion to Julian Date.
CHANGES:
09-Nov-2005 D.A. Gell Initial Coding
(Routine contained in inms_doy2julian.pro)
NAME:
inms_doy2utc - converts calendar strings to UTC time structure
function inms_doy2utc, asDoyTimes, debug=debug
PURPOSE: convert strings in the form yyyy-doyThh:mm:ss.sss
to a structure {nDate: yyyydoyL, nMSecs: ssss}
USEAGE:
CHANGES:
28-Feb-2005 DAG Initial Coding
20-Sep-2006 DAG Use error handler and inms_post_message
27-Apr-2007 DAG Corrected variable name in post_message statement
(Routine contained in inms_doy2utc.pro)
NAME:
inms_dump_structure - Creates a CSV file filled with data from a structure
Created by David A. Gell on 2007-04-17.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
pro inms_dump_structure, axStruct, $
file=file, $
note=note, $
debug=debug
PURPOSE:
Fills a file with the contents of a structure
RETURNS;
ARGUMENTS:
axStruct - the structure array to be dumpted to a file
KEYWORD PARAMETERS:
file - the name of the file, created if needed
note - An optional parameter supplying a descriptive note
inserted in the file
RESTRICTIONS:
METHOD:
The existance of the file is checked. If it exists, the
user is asked for permission to overwrite it. If it doesn't
exist, it is created.
The file creation date and note are put in the file
A label row is written, each label is the name of a structure field
The data is written, one row per structure array element, comma separated
EXAMPLE:
MODIFICATION HISTORY:
date by description
17 Apr 2007 DA Gell initial coding
(Routine contained in inms_dump_structure.pro)
NAME:
inms_file_format - obtains the file format for a specified file type
function inms_file_format, sFileType, debug=debug
PURPOSE: obtain the format for the specified file type
USEAGE:
axFmt=inms_file_format(sFileType)
RETURN VALUE:
A structure containing the information obtained from
the PDS structure file for the specified type
ARGUMENTS:
sFileType - a string specifying the file type for which
the format is desired, L1A, HKG, or CAL
Default value is L1A
KEYWORDS:
/debug set to provide diagnostic info
RESTRICTION:
inms_read_file_fmt must have been executed previously.
inms_get_data calls inms_read_file_fmt for you.
CHANGES:
1-Jun-2005 DAG initial coding, adapted from inms_l1a_labels
23-Aug-2005 DAG test for existance of format stack prior to
dereferencing pointer to it. If no stack exists,
call inms_read_fmt_file to get a format.
08-Nov-2005 DAG Add CAL to list of valid types, for calibration system
data.
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_file_format.pro)
NAME:
inms_format_time - converts time of day in milliseconds to hours, minutes, seconds
function inms_format_time, anUTtime, format=format
PURPOSE:
Converts a time of day expressed in milliseconds to an hours-minutes
seconds string.
RETURN VALUE:
a string or array of strings containing the resultant times
the shape of the array is the same as the shape of the input argument
ARGUMENTS:
anUTtime - the time in milliseconds to be converted. This argument
may be a scalar or an array of arbitrary shape. In the
first case a string is returned, in the second an array
of strings with the same shape as this argument is returned
CHANGES:
26-Jan-2005 D.A. Gell Augment program prolog documentation
(Routine contained in inms_format_time.pro)
NAME:
inms_format_time_tick - a callback function to format time axis tick labels
function inms_format_time_tick, axis, index, value
PURPOSE:
callback function used to format time tick labels
ARGUMENTS:
axis - axis number: 0 for X axis, 1 for Y axis, 2 for Z axis.
index - tick mark index (indices start at 0).
value - the value assigned to the tick mark, time is ms
CHANGES:
20-August-2004 NAB altered function to support times that aren't perfectly
on the hour
25-August-2004 NAB created format_time_ticks.pro so as to be used
by other procedures
28-Jan-2005 DAG Renamed inms_format_time_tick to comply
with conventions
18-Nov-2005 DAG Added seconds to string
(Routine contained in inms_format_time_tick.pro)
NAME:
inms_get_data - reads a Level 1A INMS data file
pro inms_get_data, axData, $ ;;(o) structure containing l1A data
path=path, $ ;;(i) path to data files,
;;; default: current working directory
files=files, $ ;;(i) optional list of files
trange=trange, $ ;;(i) two element vector with time range
;;; in yyyy-doyThh:mm:ss format
yeardir=yeardir, $ ;;(i) if set files are located in path/YYYY
doydir=doydir, $ ;;(i) if set files are located in path/YYYY/doy
type=type, $ ;;(i) specifies file type to read
debug=debug ;;(i) set to add debug output
PURPOSE:
Read INMS Level 1A archive data for a specific time range from the .CSV files
ARGUMENTS
axData a named variable to receive the data structure. Fields in the
structure are named as defined in the L1A or HKG Data definition
spreadsheets (and do not follow the IDL coding standard conventions)
path a keyword argument to supply the path to the data files
defaults to the current working directory
files a keyword argument asigned to the list of input files as a
vector of strings. Data from the start of the first file
to the end of the final file will be provided.
trange a keyword argument asigned to a two element string vector
containing the initial and final times. The data will
at the first data point with time greater than or equal
to trange[0] and end at the last data point with time
less than or equal to trange[1]. Supply the times in the
yyyy-doyThh:mm:ss format
type a keyword argument to supply the type of file to read
when the trange argument is specified, values are L1A, HKG
Defaults to L1A
yeardir keyword arguments that control the search for files within
the specified timerange. If neither are present,
doydir files for the specified time range are to be found in the directory
directory specified by the path keyword. If yeardir is
present the files are organized in subdirectories by year
within the directory specified by the path keyword argument.
If doydir is present the files are orgainized by
year and day-of-year subdirectories within the specified directory.
if neither doydir nor yeardir is present the following structure
is assumed
path/specified/by/pathKeyword -+--- 2003_180_L1A_00_00_00_1.CSV
+--- 2003_181_L1A_00_00_00_1.CSV
+--- 2004_181_L1A_00_00_00_1.CSV
+--- 2004_182_L1A_00_00_00_1.CSV
if the yeardir keyword is present, the files are expected to be
in year subdirectories
path/specified/by/path +---- 2003 +--- 2003_180_L1A_00_00_00_1.CSV
| +--- 2003_180_L1A_01_00_00_1.CSV
| +--- 2003_181_L1A_01_00_00_1.CSV
| +--- 2003_181_L1A_01_00_00_1.CSV
+---- 2004 +--- 2004_180_L1A_00_00_00_1.CSV
| +--- 2004_182_L1A_01_00_00_1.CSV
| +--- 2004_183_L1A_01_00_00_1.CSV
| +--- 2004_184_L1A_01_00_00_1.CSV
+---- 2005
if the doydir keyword is present the file, the files are expected
to be in year and day directories
path/specified/by/path +---- 2003 +---+---- 180 +--- 2003_180_L1A_00_00_00_1.CSV
| | +--- 2003_180_L1A_01_00_00_1.CSV
| +---- 181 +--- 2003_181_L1A_01_00_00_1.CSV
| | +--- 2003_182_L1A_01_00_00_1.CSV
| +---- 182 +---
+---- 2004 +---+---- 180 +--- 2004_180_L1A_00_00_00_1.CSV
| +---- 181
| +---- 182
+---- 2005 +---
supply either the files keyword or the trange keyword, not both. If neather
are supplied, a file selection dialog is presented
EXAMPLE
#1
inms_get_data, axL1Data, asPaths, path='~/Desktop/inmsData', $
trange=['2004-185T01:15:00','2004-185T05:46:59']
#2
inms_get_data, axL1Data, files=['2004-185T09.00.00.CSV', $
'2004-185T10.00.00.CSV', $
'2004-185T11.00.00.CSV', $
'2004-185T12.00.00.CSV']
reads all data in the files specified. The data is returned in the
axL1Data structure.
ROUTINES NEEDED
- inms_parse_file_name
- inms_is_image
- inms_l1a_files_read
- inms_make_scalar
- inms_parse_l1a_name
- inms_parse_time
- inms_post_message
- inms_purge_fmt_file
- inms_read_label
- inms_remove_quotes
- inms_validate_time
FILES USED:
In addition to the data file, the routine inms_create_l1a_template requires a
PDS structure file. The name of this file is obtained from the PDS label
associated with the data file. PDS specifies that the structure file be located
in the same directory as the data file. If the file is not located
there, the routines in this package check the data file directory's
parent directory. If not there, a dialog is presented to the user so
that the structure file may be located.
CHANGE HISTORY
26-Jul-2004 DAG initial coding
23-Aug-2004 DAG adapted to archive version 2 data file names and directory structure
31-Aug-2004 DAG Corrected error when selecting multiple files with the dialog box
1-Sep-2004 DAG Corrected error when selecting files based on time.
The file containing the first time (if not an even hour) was
not read.
1-Sep-2004 DAG Trim leading and trailing blanks from input record fields prior
to assignment to structure field (for handling R. Yelle's
simulated data). Updated list of required routines.
15-Sep-2004 DAG Change test for end of PDS label and header records, add debugging
output when searching for files
6-Oct-2004 DAG Ensure that all string data is lower case to insure string comparisions
always work
22-Oct-2004 DAG Change to convert all data except sclk time to lowercase.
sclk (field 0) must be uppercase for comparision with file names
23-Oct-2004 DAG Correct error introduced when correcting a typo in the test for
a blank line. The test was unneeded, correcting the typo prevented
successful reading of muliple file data sets.
29-Nov-2004 DAG Update list of required routines,
replaced create_table_list with sprl_create_list
make_scalar with inms_make_scalar
7-Jan-2005 DAG Read format file and header to obtain structure information
19-Jan-2005 DAG Added additional debug output when /debug set. Added note about
format file.
26-Jan-2005 DAG Improved readablilty of file prolog. Removed dead code.
01-Feb-2005 DAG deleted asFilesRead argument and labels keyword, providing accessor
routines instead
01-Mar-2005 DAG Modified to support detached files
02-Mar-2005 DAG Set file delimiter based on OS family, / for unix \ for windows
04-Mar-2005 DAG Ensure day-of-year directories have leading zeros
04-Apr-2005 DAG Purge format cache before reading file label and format.
Update list of functions called
07-Jun-2005 DAG Added file type keyword to permit location of HKG files by time
Changed time range code to support daily files for types not L1A
Added index to locate time tag in various file types
10-Jun-2005 DAG Allow time ranges to cross day and year boundaries
17-Jun-2005 DAG file format structure changed,
21-Jun-2005 DAG use file type to limit selection in filters.
27-Jun-2005 DAG change message to information when no data present
02-Dec-2005 DAG Sort filenames returned by dialog_pickfile - Windows
returns names in arbitrary order
20-Sep-2006 DAG Use error handler and inms_post_message
27-Sep-2006 DAG Confirm validity of label after call to inms_read_label
08-May-2007 DAG Eliminate use of inms_create_l1_template. Using
inms_read_fmt_file instead
(Routine contained in inms_get_data.pro)
NAME:
inms_get_series - extracts a subset of data from a Level 1A data structure
pro inms_get_series, axData, $ ;; (i) a structure containing INMS level 1 data
axSeries, $ ;; (0) a structure containing the selected data
;;; in the same form as the input
silent=silent, $;; (i) set to inhibit error messages
debug=debug, $ ;; (i) set to provide additional debug diagnostics
_extra=extra ;; (i) a series of keywords the define the selection
;;; criteria
PURPOSE:
extract a series of data records from the level 1A data structure
ARGUMENTS:
axData a Level 1A data structure containing the data from which the series
is to be extracted
axSeries a named variable to receive the selected data in the form of a
Level 1A data structure
KEYWORDS:
silent if set, only error messages are produced
debug if set, diagnostic information is produced
extra A series of keyword expressions where the keyword name is an
INMS level 1A data item and the value is either a scalar or a 1 dimensional
element vector. In the first case the keyword expression
KEYWORD=VALUE
routine adds a clause of the form
AND SSTRUCTNAME.KEYWORD EQ VALUE
to the selection criteria. If the vector has two elements as follows
KEYWORD=[MIN, MAX]
then the a clause of the form
AND SSTRUCTNAME.KEYWORD GE VALUE[0] AND SSTRUCTNAME.KEYWORD LE VALUE[1]
is added to the selection criteria. If the vector has more than two elements
KEYWORD=[V1, V2,...VN-1]
then a clause of the form
AND (SSTRUCTNAME.KEYWORD EQ VALUE[0] OR SSTRUCTNAME.KEYWORD EQ VALUE[1]
OR SSTRUCTNAME.KEYWORD EQ VALUE[2] ...
OR SSTRUCTNAME.KEYWORD EQ VALUE[N-1] )
is added to the selection criteria
ROUTINES REQUIRED:
inms_build_locator
CHANGES:
28-Jul-2004 DAG Initial coding
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_get_series.pro)
NAME:
inms_get_spectra - Extracts one or more spectra from Level 1A data
pro inms_get_spectra, axData, $ ;; (i) L1A data Structure
axSpectra, $ ;; (o) Spectra Data Structure
MassTableID=MassTableID, $ ;; (i) list of mass tables that
coaddCnt=coaddCnt, $ ;; (i) value of coadd to use
source=source, $ ;; (i) source to use 'osnb','osnt','osi','csn'
hires=hires, $ ;; (i) set to process 1/8 AMU scans
debug=debug, $ ;; (i) set to provide additional tracing
_extra=extra ;; (i) selector keywords
PURPOSE:
Extract a collection of spectra meeting user supplied criteria from
the L1A data supplied in the array axData
ARGUMENTS:
axData structure of level 1 data as retrieved by inms_get_data
axSpectra array of one or more spectra structures. A scalar zero is
returned if no spectra were found. To test for successful
spectra formation, use
if size(aXspectra,/n_dimensions) gt 0 then ;;success
MassTableID keyword parameter which defines the mass tables tha
make up the mass spectra. For example, a unity mass scan
is mass table 1, but the 1/8 amu scan requires tables
2 through 13, inclusive
coaddCnt keyword parameter which specifies the coadd count used to select
data for the spectra, defaults to 1
source keyword parameter which specifies the ion source to select, defaults to osi
extra a series of keyword expressions where the keyword name is an
INMS level 1A data item and the value is either a scalar or a 1 dimensional
element vector. In the first case the routine adds a clause of the
form
AND SSTRUCTNAME.KEYWORD EQ VALUE
to the selection criteria. If the vector has two elements then the a clause of
the form
AND SSTRUCTNAME.KEYWORD GE VALUE[0] AND SSTRUCTNAME.KEYWORD LE VALUE[1]
is added to the selection criteria. If the vector has more than two elements
a clause of the form
AND (SSTRUCTNAME.KEYWORD EQ VALUE[0] OR SSTRUCTNAME.KEYWORD EQ VALUE[1]
OR SSTRUCTNAME.KEYWORD EQ VALUE[2] ...
OR SSTRUCTNAME.KEYWORD EQ VALUE[N-1] )
is added to the selection criteria
In the event that the user specifies two level 1A data items that IDL believe
are ambiguous, like MASS and MASS_TABLE, IDL will report an error. To resolve
this adorn or, but not both, of the variable names with a leading underscore,
thusly _MASS. IDL will nolonger believe that the names are ambiguous and
the data will be selected.
The keywords /ingress and /egress may also be used as selectors. /ingress selects
data for which the altitude is decreasing, while /egress selects increasing altitude
axSpectra consists of a 1 dimensional array of spectra records. See inms_define_xSpecRec.pro
for definition.
EXAMPLE:
;; read some data
;; a file selection dialog appears
inms_get_data, axData
;; get spectra between 1250 and 1300 km above the target
inms_get_data, axData, axSpec, alt_t=[1250,1300], massTableID=[16,17]
;; confirm successful spectra formation
if size(axSpec, /n_dimensions) gt 0 then begin
;; process spectra here
endif else begin
;; handle error here
endelse
EXAMPLE:
;; get ion spectra on inbound leg
inms_ge_data, axData, axIn, source='osi', massTableID=[40,41], /ingress
CHANGES:
28-Jul-2004 DAG Initial coding
02-Aug-2004 DAG add computation of anC1Error and anC2Error
04-Aug-2004 DAG add specific keywords for coadd count and ion source
26-Aug-2004 DAG add detail to documentation
3-Sep-2004 DAG correct error in producing summary record
17-Sep-2004 DAG change counts to float, permitting averages
add type code to record
4-Oct-2004 DAG fixed error message when no spectra found
6-Oct-2004 DAG changed spectra selection to two step process
First, all spectra with specified mass table, source
and coadd are selected
Second, contiguous time ranges in which the additional
selection criteria are satisfied are found.
Spectra with midpoints within those time ranges
are returned to the caller.
Made computations more robust avoiding division by zero.
These should not occur with quality data.
Added additional output when debug switch present.
Insure invalid result supplied when an error occurs.
7-Oct-2004 DAG improved documentation.
7-Oct-2004 DAG corrected spectra field name sType to comply with standard
8-Nov-2004 DAG corrected formatting for no spectra found alerts
10-Nov-2004 DAG added altitude to spectra record, midpoint altitude
29-Nov-2004 DAG replaced create_table_list with sprl_create_list
06-Dec-2004 DAg added line of sight relative speed and direction to structure
for use in calculating ram enhancement factor
26-Jan-2005 DAG Corrected description of xSpectra record in prolog.
18-Apr-2005 DAG added /hires keyword to form 1/8 AMU spectra
26-Aug-2005 DAG definition of spectra record moved to include file
store lat, wlon, sza, lst in spectra structure
29-Aug-2005 DAG store value of target name in spectra structures
13-Dec-2005 DAG Ensure extra element in the spectra array removed when
the data ends with a partial spectra, moved creation
of spectra array to follow adjustment of number of spectra
20-Sep-2006 DAG Use error handler and inms_post_message
11-Oct-2006 DAG Skip spectra which have too few IPs
30-Nov-2006 DAG Ensure that only valid spectra are included in output
11-Dec-2006 DAG Make target Saturn if not otherwise specified
14-Dec-2006 DAG Fix pathological case that occurs if final data point
is selected by additional criteria
7-Jan-2006 DAG Store sequence and cycle table id numbers
10 Apr 2007 DAG Store time from closest approach
(Routine contained in inms_get_spectra.pro)
NAME:
inms_get_spice_kernels - reads a spice furnish text kernel and gets missing files
Created by David A. Gell on 2007-05-18.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
pro inms_get_spice_kernels, sFile, $ ;; kernel.txt file to read
verbose=verbose, $ ;; set to report list of files
debug=debug, $ ;; set to enable debug options
noFTP=noFTP, $ ;; disables ftp transfer for testing
_extra=extra ;; used to pass path symbol,value pairs
PURPOSE:
Obtains spice kernel files directly from the NAIF ftp server
ARGUMENTS:
sFile - the name of a SPICE kernels.txt file
KEYWORD PARAMETERS:
/VERBOSE -
symbol=path - superceed the PATH_SYMBOL,PATH_VALUE pairs in the file
/DEBUG - set to provide additional debuging information
METHOD:
After validating arguments, the extra keyword parameters are checked. If
present, the keyword names are taken to be PATH_SYMBOL values and the
keyword values are takend to be PATH_VALUE values.
The specified kernel list file, in SPICE text kernel format is read and parsed.
Any PATH_SYMBOLS in the filenames are replaced by the corresponding
PATH_VALUES.
The resulting file descriptions are tested for existance only. The names of those
that do not exist with the PATH_SYMBOLS replaced by the PATH_VALUE tokens are
obtained by ftp from the following NAIF server and directories.
sNaifServer='naif.jpl.nasa.gov' ;; address of NAIF server
sNaifGen ='/pub/naif/CASSINI/kernels' ;; path to generic kernels
sNaifCas ='/pub/naif/CASSINI/kernels' ;; path to Cassini specific kernels
Once the ftp transfer attempt is complete, the files are again tested for existance
to confirm successful transfer.
RESTRICTIONS:
The INMS Operations Network repository of spice kernel files renamed the following
files:
$GEN/lsk/naif.tls,
$GEN/pck/pck.tpc,
$CAS/sclk/cas.tsc,
$CAS/fk/cas.tf
Each of these files, on ION, is a link (alias) to a file with a name containing
a version number. ION always links these names to the file with the greatest
version number. These files need to be manually obtained either from ION or
by ftp from the NAIF ftp site.
EXAMPLE:
MODIFICATION HISTORY:
date by description
22 May 2007 D.A. Gell Initial coding
(Routine contained in inms_get_spice_kernels.pro)
NAME:
inms_grid_spectra - interpolates mass spectra to uniform time grid
pro inms_grid_spectra, $
axData, $ ;; (i) L1A data Structure
axSpectra, $ ;; (o) Spectra Data Structure
MassTableID=MassTableID, $ ;; (i) list of mass tables that
coaddCnt=coaddCnt, $ ;; (i) value of coadd to use
source=source, $ ;; (i) source to use 'osnb','osnt','osi','csn'
;;; form the spectra of interest
stride=stride, $ ;; (i) spacing (sec) between returned spectra
span=span, $ ;; (i) length (sec) of data arc to be fit
order=order, $ ;; (i) order of chebyshev polynomials
exclimit=exclimit, $ ;; (i) exclude points which deviate from
;;; fit by this value defaults to 3 sigma
debug=debug, $ ;; (i) set to provide additional tracing
diagnostic=diagnostic, $ ;; (o) if set contains the chisqr and sigma
verbose=verbose, $ ;; (i) set to provide additional output
_extra=extra ;; (i) selector keywords
PURPOSE:
Extract a collection of spectra meeting user supplied criteria from
the L1A data supplied in the array axData, interpolated to uniform
time grid.
ARGUMENTS:
axData structure of level 1 data as retrieved by inms_get_data
axSpectra array of one or more spectra structures. A scalar zero is
returned if no spectra were found. To test for successful
spectra formation, use
if size(aXspectra,/n_dimensions) gt 0 then ;;success
see file inms_define_xSpect.pro for the contents of a spectra
structure.
KEYWORDS:
MassTableID keyword parameter which defines the mass tables tha
make up the mass spectra. For example, a unity mass scan
is mass table 1, but the 1/8 amu scan requires tables
2 through 13, inclusive
coaddCnt keyword parameter which specifies the coadd count used to
select data for the spectra, defaults to 1
source keyword parameter which specifies the ion source to select,
defaults to osi
stride keyword parameter specifing the time between returned
spectra (sec), defaults to 10 sec
span keyword parameter specifying the time span about the point
of interest used in the fit. Defaults to 6 * stride. Each
data point is the result of a fit to data from t-span/2 to
t+span/2 where t is t0+n*stride
order if present sets the maximum order of the polynomial used to fit
the data, defaults to 3
exclimit supplies the deviation from the fit beyond which a data point
is deemed an outlier. It is supplied in units of std deviation.
Default value is 3 sigma
debug if set, error handling is modified to halt in this routine
on error. Also, breaks occur after fits of
mass 1, 16, and 28 to permit detailed examination
of the state of the routine
diagnostic If a variable name is supplied, a diagnostic information
structure is returned as the named variable.
The structure contains the status of the fit, the mass,
the resulting parameters and there std deviation, the reduced
chi-square and the iterations requiried for convergance
for each mass.
verbose controls additional status information.
If absent (or set to zero) no additional output provided.
If 1, a message is produced for each mass bin with
insufficient data for fitting. If 2, the results of the
fit are displayed. If 4, the points omitted for exceeding
the exclude limit are displayed
extra a series of keyword expressions where the keyword name is an
INMS level 1A data item and the value is either a scalar or
a 1 dimensional vector. In the first case the routine adds
a clause of the form
AND SSTRUCTNAME.KEYWORD EQ VALUE
to the selection criteria. If the vector has two elements
then the a clause of the form
AND SSTRUCTNAME.KEYWORD GE VALUE[0] $
AND SSTRUCTNAME.KEYWORD LE VALUE[1]
is added to the selection criteria. If the vector has
more than two elements a clause of the form
AND (SSTRUCTNAME.KEYWORD EQ VALUE[0] $
OR SSTRUCTNAME.KEYWORD EQ VALUE[1] $
OR SSTRUCTNAME.KEYWORD EQ VALUE[2] ... $
OR SSTRUCTNAME.KEYWORD EQ VALUE[N-1] )
is added to the selection criteria
In the event that the user specifies two level 1A data items
that IDL believes are ambiguous, like MASS and MASS_TABLE,$
IDL will report an error. To resolve this problem
adorn one, but not both, of the variable names with a leading
underscore, thusly: _MASS. IDL will nolonger believe that the
names are ambiguous and the data will be selected.
axSpectra consists of a 1 dimensional array of spectra records. See inms_define_xSpecRec.pro
for definition.
EXAMPLE:
;; read some data
;; a file selection dialog appears
inms_get_data, axData
;; get spectra between 1250 and 1300 km above the target
inms_grid_spectra, axData, axSpec, alt_t=[1250,1300], $
massTableID=[16,17]
;; confirm successful spectra formation
if size(axSpec, /n_dimensions) gt 0 then begin
;; process spectra here
endif else begin
;; handle error here
endelse
CHANGES:
28-Jul-2004 DAG Initial coding
02-Aug-2004 DAG add computation of anC1Error and anC2Error
04-Aug-2004 DAG add specific keywords for coadd count and ion source
26-Aug-2004 DAG add detail to documentation
3-Sep-2004 DAG correct error in producing summary record
17-Sep-2004 DAG change counts to float, permitting averages
add type code to record
4-Oct-2004 DAG fixed error message when no spectra found
6-Oct-2004 DAG changed spectra selection to two step process
*First, all spectra with specified mass table,
source and coadd are selected
*Second, contiguous time ranges in which the additional
selection criteria are satisfied are found. Spectra
with midpoints within those time ranges are returned to
the caller.
*Made computations more robust avoiding division by zero.
These should not occur with quality data. Added
additional output when debug switch present.
*Insure invalid result supplied when an error occurs.
7-Oct-2004 DAG improved documentation.
7-Oct-2004 DAG corrected spectra field name sType to comply with standard
8-Nov-2004 DAG corrected formatting for no spectra found alerts
10-Nov-2004 DAG added altitude to spectra record, midpoint altitude
29-Nov-2004 DAG replaced create_table_list with sprl_create_list
06-Dec-2004 DAg added line of sight relative speed and direction to
structure for use in calculating ram enhancement factor
-------------------
17-Dec-2004 DAG INITIAL CODING OF INMS_GRID_SPECTRA
ADAPTED FROM INMS_GET_SPECTRA
27-Dec-2004 DAG Added diagnositic output structure,
added counter 2 processing
28-Dec-2004 DAG Added background removal, enhanced documentation
29-Mar-2005 DAG Removed unneeded parameter, changed default source to "CSN"
28-Apr-2005 DAG Added code to omit outliers, deleted background removal code
26-Aug-2005 DAG Definition of spectra record moved to include file
29-Aug-2005 DAG store value of target name in spectra structures
03-Oct-2005 DAG Correct initialization of ion source in spectra structure
20-Sep-2006 DAG Use error handler and inms_post_message
06-Oct-2006 DAG Extracted inms_chebyshev for use in other routines
7-Jan-2006 DAG Store sequence and cycle table id numbers
(Routine contained in inms_grid_spectra.pro)
NAME:
inms_hkg_labels - provides list of axis labels for housekeeping data
function inms_hkg_labels, debug=debug
PURPOSE: obtain a list of labels for housekeeping data
USEAGE:
asLabels=inms_hkg_labels()
KEYWORDS:
debug if set, diagnostic information is produced
RESTRICTION:
inms_read_file_fmt must have been executed previously.
inms_get_data calls inms_read_file_fmt for you.
CHANGES:
1-Jun-2005 DAG initial coding, adapted from inms_l1a_labels
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_hkg_labels.pro)
NAME:
inms_idl_type - determines IDL type based on PDS type name and value range
Created by David A. Gell on 2007-05-08.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
function inms_idl_type, xItem
PURPOSE:
Determines the idl type for a data item based on the PDS item definition
from the structure file.
RETURNS;
idl type number
ARGUMENTS:
xItem - (i) the PDS item description structure created by inms_read_fmt_file
KEYWORD PARAMETERS:
RESTRICTIONS:
METHOD:
EXAMPLE:
MODIFICATION HISTORY:
date by description
08-May-2007 D.A. Gell initial coding, extracted from inms_create_l1a_template
(Routine contained in inms_idl_type.pro)
NAME:
inms_init_ss_position - initializes the spice toolkit for use by inms_ss_position (depreciated)
pro inms_init_ss_position, sFilePath
PURPOSE:
initialize spice package
Depreciated, values computed are now included in L1A files
ARGUMENTS
sFilePath - path to a "furnish" kernel, a text file
containing paths to the required SPICE data files(kernels)
CHANGE HISTORY
1-NOV-2004 DAG initial coding
1-Dec-2004 DAG documentation improvements
complete handling of missing data file
8-Feb-2005 DAG specified that the default furnish kernel
location is the current working directory
2-Mar-2005 DAG File is now checked for both regularity and readability
corrected year in above change item
31-Mar-2005 DAG Changed lighttime correction to "lt+s" to match
archive production code
4 Dec 2004 DAG Depreciated
(Routine contained in inms_ss_position.pro)
NAME:
inms_ion_sensitivity - Computes INMS ion sensitivity
function inms_ion_sensitivity, nMass, nSpeed, sDate, $
debug=debug, $
escan=escan, $
shift=shift, $
width=width, $
test=test
RETURN VALUE:
The sensitivity of INMS to an ion of the specified mass and velocity
with errors in the Quad Lens (QL3) voltage set point considered. The
returned value is a vector of the same size and shape as nMass and nSpeed
ARGUMENTS:
nMass The mass of the peak of interest
nSpeed The speed of the incident ions with respect to the instrument
if absent, 6.0 km/s is assumed
sDate The date the data was collected, used to select coefficients
if absent, defaults to the result of the most recent in-flight
QL scan.
KEYWORDS:
shift Supplies a two element array for the linear model of
line shift vs KE
width Supplies a two element array for the linear model of
line width parameter vs KE
/escan When set, the parameters are set to those of T5
specify this setting for ion data collection interspersed
in the energy scans of T17.
/test When set routine returns unadjusted sensitivity
/debug When set additional traceback info produced on errors
The nMass and nSpeed arguments may be either scalars or arrays.
If one argument is an array the other must be either a scalar
or an array of conformable shape where nMass is m x n and nSpeed
is n x 1.
METHOD:
Use the width parameter to compute a Gaussian. Find the height of
the Gaussian at distance shift from center. The sensitivity is the
nominal sensitivity multiplied by the height.
Note that during the T23 energy scans, the switching table values
for the OSI science measurements interspersed with quad lens scans
where based on the same parameters as the inflight velocity compensation
calculations.
CHANGES:
14 Sep 2006 D. A. Gell Initial coding
29 Sep 2006 D. A. Gell Changed parameters based on re-analysis
of gausian fits.
2 Oct 2006 D. A. Gell Caller can supply values for the shift
and width linear model
Compute sensitivity directly
3 Oct 2006 D. A. Gell Add parameters for pre-t17 data
10 Nov 2006 D. A. Gell Added alternate method and keyword
to choose between methods
4 Dec 2006 D. A. Gell Eliminate alternative method
21 Dec 2006 D. A. Gell Permit nMass to be a two dimensional array
and nSpeed to be a vector
4 Jan 2007 D. A. Gell Use correct coeffiecients for T17
ion measurements interspersed with
energy scans.
15 Jan 2007 D. A. Gell Add parameters based on T23 scans
27 Feb 2007 D. A. Gell Add parameters based on T25 scans
13 Apr 2007 D. A. Gell Add parameters based on T28 scans
03 May 2007 D. A. Gell Add parameters based on T29 scans
parameter analysis excluded masses 17
and 91 due to low signal levels
19 Jun 2007 D. A. Gell Add parameeters basedd on T32 scans
parameter analysis excluded mass 17
due to low signal levels
(Routine contained in inms_ion_sensitivity.pro)
NAME:
inms_ion_transmission - computes the effect of angle on transmission
function inms_ion_transmission, nMass, nVelX, nVelY, nVelZ, debug=debug
ARGUMENTS:
nMass: The atomic mass of the ion species in DA
nVelX: The component of the ion velocity in the boresight direction
nVelY: The component of the velocity in the Y axis direction
nVelZ: The component of the velocity in the Z axis direction
KEYWORDS:
/debug Set to enable debugging
RETURN VALUE:
The reduction in transmission due to angle of attack,
T(a) = F * T(0)
T is transmission, F is the value returned.
In the event of an error a value of -1 is returned
CHANGES:
28 July 2006 D.Gell Initial coding based on W. Kasprzak routine
Open_Source_Ion_Angle
20-Sep-2006 DAG Use error handler and inms_post_message
CONSTANTS:
nConvert = 5.1824E-03 ;; kenetic energy conversion
nZoffset = 0.0 ;; z direction response model
nZ0 = 3.873E-04
nZ1 = 4.218E-01
nYoffset = 0.0 ;; y direction response model
nY0 = 2.534E-03
nY1 = 1.049E-01
(Routine contained in inms_ion_transmission.pro)
NAME:
inms_is_image - indicates whether an image file is being created
function inms_is_image, set=set, clear=clear
PURPOSE: indicates if image file creation is in progress
USEAGE:
to set the image flag, use the set option.
to clear the image flag, use the clear option
to test, call with now arguments.
User code that needs to make choices based on this switch
tests this function
if inms_is_image() then begin
;; do stuff for image creation
endif else begin
;; do normal stuff
endelse
CHANGES:
1-Mar-2005 DA Gell Initial coding
(Routine contained in inms_is_image.pro)
NAME:
inms_is_publication - returns publication quality output flag
function inms_is_publication, set=set, clear=clear
PURPOSE: indicates if publication quality output is desired
USAGE:
To set the publication quality flag, use the set option.
Nominally this is done in inms_prepare_plot, and not in
other user code:
dummy=inms_is_publication(/set)
User code that needs to make choices based on output quality
tests this function
if inms_is_publication() then begin
;; do stuff for publication output
endif else begin
;; do normal stuff
endelse
to turn off the switch:
dummy=inms_is_publication(/clear)
CHANGES:
1-Feb-2005 DA Gell Initial coding to replace use of
inms specific system variable
(Routine contained in inms_is_publication.pro)
NAME:
inms_kernel_list - produces a list of SPICE kernels present or missing
pro inms_kernel_list, sFile, $ ;; kernel.txt file to read
present=present, $ ;; set to list found kernels
absent=absent, $ ;; set to list missing kernels
verbose=verbose, $ ;; set to report list of files
debug=debug, $ ;; set to enable debug options
_extra=extra ;; used to pass path symbol,value
;; pairs
RETURN VALUE:
A string array containin a list of the kernel files present or absent on
the local machine. A null string indicates no kernel files meeting the critera
were found or that an error occurred.
ARGUMENTS:
sFile - the name of a SPICE kernels.txt file
KEYWORDS:
/PRESENT - set to list files listed in the kernels.txt file which exist
if set to a named variable, the list of files is returned in that variable
/ABSENT - set to list files listed in the kernels.txt file which do not exist
if set to a named variable, the list of files is returned in that variable
/VERBOSE - set to report absent or present files. If missing just the number is reported
symbol=path - superceed the PATH_SYMBOL,PATH_VALUE pairs in the file
/DEBUG - set to provide additional debuging information
METHOD:
After validating arguments, the extra keyword parameters are checked. If
present, the keyword names are taken to be PATH_SYMBOL values and the
keyword values are takend to be PATH_VALUE values.
The specified kernel list file, in SPICE text kernel format is read and parsed.
Any PATH_SYMBOLS in the filenames are replaced by the corresponding
PATH_VALUES.
The resulting file descriptions are tested for existance only. The names of those
that do not exist with the PATH_SYMBOLS replaced are counted and listed if the /ABSENT keyword
(or neither that keyword or the /PRESENT keyword is specified). If the /PRESENT
keyword is specified, the file names that exist are returned.
CHANGES:
4 Jan 2006 D.A. Gell Initial coding
20-Sep-2006 DAG Use error handler and inms_post_message
22-Feb-2007 D.A. Gell Corrected indexing when replacing path symbols with
path values
6-Apr-2007 D.A. Gell Converted from function to procedure which prints list of
files and optionally returns list via keyword parameter
18-May-2007 D.A. Gell Remove trailing / if needed from path values
22-May-2007 D.A. Gell Validate path symbols provided via extra keyword
(Routine contained in inms_kernel_list.pro)
NAME:
inms_l1A_files_read - provides list of Level 1A files last read by inms_get_data
function inms_l1a_files_read, asFiles, save=save
PURPOSE: saves and access list of files read by inms_get_data
USEAGE:
called by inms_get_data with the save keyword specified to
store the files.
called by user routines with no keyword set to obtain the list
CHANGES:
1-Feb-2005 DAG Initial coding
(Routine contained in inms_l1a_files_read.pro)
NAME:
inms_l1a_labels - provides list of axis labels for l1A data
function inms_l1a_labels, debug=debug ;; (i) set to provide additional debug diagnostics
PURPOSE: obtain a list of labels for l1A data
USEAGE:
asLabels=inms_l1a_labels()
RETURNS:
Returns an array of strings containing the labels for the L1A data.
In the event of an error it returns the null string
KEYWORDS:
debug if set, diagnostic information is produced
RESTRICTION:
inms_read_file_fmt must have been executed previously.
inms_get_data calls inms_read_file_fmt for you.
CHANGES:
1-Feb-2005 DAG Initial coding
1-Jun-2005 DAG Use labels from format file
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_l1a_labels.pro)
NAME:
inms_label_ticks - produces formatted time strings for use as tick labels
function inms_label_ticks, nAxis, nIndex, nValue, nLevel, $
format=format
USAGE
The function is called once prior to any plotting to specify
the format desired, then the name of the routine is supplied to
the plot procedure via the tickformat keyword.
ARGUMENTS:
nAxis the axis number 0(X-axis) 1(Y-axis) 2(Z-axis)
nIndex the tick mark index, 0 is least tick value
nValue the value to be formatted specified in Julian Dates (JD)
KEYWORDS:
format supplies the format to be applied to the Julian Date
available choices:
CAL 2-line Calendar Date
dd-Mon-yyyy
hh:mm:ss
JD Julian Date
dddddddd.fffff
where ddd is the Julian Day Number
and fffff is the fractional day
resolution is approximately 1 second
DOY 2-line Day-of-Year date
ddd-yyyy
hh:mm:ss
TOD: 1-line time of day
hh:mm:ss
EXAMPLE:
nDummy=inms_label_ticks(format='CAL')
plot, anJD, anY, xtickformat='inms_label_ticks'
CHANGES:
06-Jun-2005 D. Gell Initial coding
(Routine contained in inms_label_ticks.pro)
NAME:
inms_list_cal_species - lists species contained in calibration data structure
pro inms_list_cal_species, axCal, debug=debug
PURPOSE:
list the species for which calibration data is available
USAGE:
inms_list_cal_species, axCal
ARGUMENTS:
axCal - a calibration structure returned by inms_read_cal
KEYWORDS:
debug if set, diagnostic information is produced
CHANGES
08-FEB-2005 DAG Initial Coding
17-AUG-2005 DAG Add molecular mass to output
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_list_cal_species.pro)
NAME:
inms_list_files - annotates a plot with a list of names
pro inms_list_files, nXposIn, $ ;; (i) x coordinate at which to start display
nYposIn, $ ;; (i) Y coordinate
asFilesRead ;; (i) list of files
PURPOSE:
annotate a plot with a list of file names
ARGUMENTS:
nXposIn, nYposeIn - the location of the annotation in
normal units
asFilesRead - an array of strings containing the list of files
to be placed in the annotation
CHANGES:
25-August-2004 NAB made inms_list_files.pro to facilitate calls
from other procedures
(Routine contained in inms_list_files.pro)
NAME:
inms_make_pds_label - make a pds label file
Created by David A. Gell on 2007-02-08.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
pro inms_make_pds_label, sPDSfile, $ ;; (i) file to be labeled
sTemplate, $ ;; (i) label template filename
hdrlen=hdrlen, $ ;; (i) number of rows of file header
note=note, $ ;; (i) note string
debug=debug
PURPOSE:
create a pds label file from a template
ARGUMENTS:
sPDSfile - the file for which a label is needed
sTemplate - the name of a template file
KEYWORD PARAMETERS:
hdrlen - supplies value for the length of data file header in rows
note - supplies a string value to replace the !<note>! token
the text can be of any length IDL supports. It is parsed
into lines which are placed in the text.
/debug - if present additional diagnostics provided
RESTRICTIONS:
METHOD:
copies the template file to the pds label file, replacing
tokens surrounded by !<>! with actual values
supported tokens:
file - name of pds spreasheet file
records- number of records in the file
MD5 - MD5 checksum
rows - number of rows in spread sheet
hdrlen - number of rows in header, defaults to 1
note - defaults to empty
startbyte - the starting byte of the spreadsheet
createdate - file creation date
EXAMPLE:
inms_make_pds_label, 2007030_L1A.CSV, L1ATEMPLATE.TXT, hdrLen=3
MODIFICATION HISTORY:
date by description
8-Feb-2007 D. A. Gell initial coding
12-Feb-2007 D. A. Gell added note template token
14-Feb-2007 D. A. Gell added startbyte token
(Routine contained in inms_make_pds_label.pro)
NAME:
inms_make_profiles - computes density profiles by deconvolution
pro inms_make_profiles, axSpectra, $ ; (i) array of spectra
axCal, $ ; (i) calibration value
axResult, $ ; (o) array of retrieved densities
anChisqr, $ ; (o) reduced chi square
anResidual, $ ; (o) residuals
anFit, $ ; (o) reconstructred spectra
species=species, $ ; (i) list of species to retrieve
_extra=extra, $ ; (i) additional keywords
print=print, $ ; (i) set to tablulate results
file=file, $ ; (i) name of file to hold results
debug=debug
PURPOSE:
repeated calls inms_deconvolve to retrieve a altitude profiles of species densities
METHOD: See memo Gell, D.A. "Deconvolution of INMS Mass Spectra", 13 Jan 2005
ARGUMENTS:
OUTPUTS:
axResult - A two dimentsional array of structures containing the
retrieved density and mole fraction profiles.
Each element of the array has the form:
xResult = {sSpecies: 'xx', $ ;; the name of the species
nAlt: 0.0, $ ;; the altitude of the data
nDensity: 0.0, $ ;; number per cubic centimeter
nSigma: 0.0, $ ;; standard deviation of above
nMoleFcn: 0.0, $ ;; mole fraction, N / (total(Ni)
nMoleSig: 0.0} ;; standard deviation of above
axResult[0,*] contains the profile for the first species
axResult[N,*] contains the profile for the n-th species
anChisqr - A vector containing the chi-square value for each fit in
the profile
anResidual - a two dimensional array containing the difference
between the measured spectra and the fit from the deconvolution
anResidual[N,*] is the residual for the Nth profile
anFit - a two dimensional array containing the reconstructed
spectra based on the species densities found by deconvolution
anFit[N,*] is the reconstruction of the Nth profile
INPUTS:
axSpectra - A spectra record array, as formed by inms_get_spectra
or inms_grid_spectra containing the mass spectra to deconvolve
axCal - The calibration data in the form returned by inms_read_cal. This
structure contains a filed for each column in the calibration
spreadsheet designed by Wayne Kasprzak
KEYWORDS:
species - a string vector containing a list of species to retrieve
if absent, defaults to ['N2','CH4']
/print - if present, the altitude profile is tabulated
file - specifies the name of a file to contain a profile.
File is a comma separated text file (CSV)
c2factor - the ratio of counter 1 counts to counter 2 counts
if absent, defaults to 6727
critfreq - the maximum frequency at which counter 1 is linear
if absent, no replacement of the c1 counter valuea by scaled
c2 counter values is performed,
specifying /critfreq results in a default value of 1.75 MHz
plot - if set produce a plot of each input spectra, synthetic spectra
and residuals annotated with measurement conditions and results
noannotate- if plot is set, noannotate omits annotations from the plot
annotate - a list of options specifing which annotations are
to be added to the plot. The choices are:
"None" is equavalent to /noannotate
"Residual" adds a lower panel displaying the scaled fit residual
"Deconvolution" adds the table of species density
"Isotopes" adds the table of isotope ratios, if any isotopic ;
species were included in the species list.
Each option may be abbreviated by its first letter.
mole - if plot is set, results listed in annotation are provides as
mole fractions rather than abundances. No effect if noannotate is
set.
chisqr - set to a named variable to receive the chi-squared value
no28 - set to omit mass 28 from consideration
verbose - set to provide additional output messages tracing
deconvolution procedure execution
debug - set to provide additional debuging features
CHANGES:
07-Jul-2005 DA Gell initial coding
31-Aug-2005 DA Gell add code to write results in file
20-Sep-2006 DAG Use error handler and inms_post_message
30-Nov-2006 DA Gell Omit isotope ratio computation
(Routine contained in inms_make_profiles.pro)
NAME:
inms_make_scalar - returns an initialized scalar of a specified type
function inms_make_scalar, nType, $ ;;(i) type code as returned by SIZE
nInitial ;;(i) optional initial value
purpose: return a scalar of the specified type
numerical types are initialized with zero,
or the optional value specified by nInitial
arguments:
nType - IDL type code of the scalar to create
nInitial - an optional initial value for numerical types
string types are initialized to the null string
pointer types are initialized to an allocated heap variable
change history
26-Jul-2004 DAG initial coding
14-Sep-2004 DAG add optional value
29-Nov-2004 DAG changed name to inms_make_scalar
(Routine contained in inms_make_scalar.pro)
NAME:
inms_make_window - creates a new X window for graphics
pro inms_make_window, sTitle, bSameWindow, animate=animate, $
winset=winset, winsize=winsize, winpos=winpos, portrait=portrait
PURPOSE:
If the current plot device is a windowing device ('X', 'WIN')
Makes a new window with the specified title
Otherwise does nothing
ARGUMENTS:
sTitle - A string containing the title to place in
the window border.
bSameWindow = 0, create new window
1, reuse current window
KEYWORDS:
/animate if present, inhibits redrawing the window to change
the title. Usefull in animating plots
/winset Set to supply values for size and position of windows
winsize Set to supply the width of the window as a fraction of full
width. Default of 0.7 of the window size with the aspect ratio
of a landscape 8.5 x 11 page
winpos A four element vector specifying the region of the display
to use in the style of the position graphics keyword.
[x0,y0,x1,y1] x0,y0 is the lower left, x1,y1 is the upper
right. Defaults to the entire visible region.
/portrait If set the window will be in portrait orientation. This keyword
is ignored unless /winset is present or when the first window is
created
CHANGES:
18-JAN-2005 DAG Initial Coding
20-Jan-2005 DAG Made bSameWindow optional,
if absent create window
Made sTitle optional, default is "IDL"
18-Feb-2005 DAG Limit number of columns so windows don't clip
24-Feb-2005 DAG Add animate keyword, changes behavior of
routine when bSameWindow is set
01-Mar-2005 DAG Use function inms_is_image to decide if
a new window is to be made
26-Jul-2005 DAG Add support for MS Windows
17-Mar-2006 DAG Add small horizontal offset between windows in
a column
31-Sep-2006 DAG Provide method to specify size and location of windows.
07-Dec-2006 DAG Correct window positioning for MS Windows Platform
16 May 2006 DAG Add /portrait keyword
(Routine contained in inms_make_window.pro)
NAME:
inms_mdy2doy - converts a date from YYYYMMDD to YYYYDDD
function inms_mdy2doy, anDates
PURPOSE:
converts a date YYYYMMDD to day-of-year, YYYYdoy
ARGUMENTS:
anDates - an array of integer dates
RETURN VALUE:
an array of the same shape and size as the input containing
the converted numerical dates
NOTE:
leap year correction valid from 1901 throught 2399
CHANGES:
22 March 2006 DA Gell Initial Coding
(Routine contained in inms_mdy2doy.pro)
NAME:
inms_neat_ticks - determines values for tick labeling plot keywords
function inms_neat_ticks, anRange, $ ;; time range, julian day
tickinterval=tickinterval, $ ;; unit of ticks,
debug=debug
ARGUMENTS:
anRange - a two element vector containing the range of Julian Dates
KEYWORDS:
tickinterval - specifies the tick interval to be used,
choices are YEAR, MONTH, DAY, HOUR, QUARTER, MINUTE
the value may be abreviated to 2 characters.
debug - if set, diagnostic information is produced
RETURN VALUE:
A structure containing the axis formatting values
{anRange: anAdjust, $ ;; a two element vector with the
adjusted Julian Dates for the axis
anTickv: anTickv, $ ;; an array tick mark locations
nTicks: n_elements(anTickv)-1, $ ;; the number of tick intervals
nMinor: nMinor} ;; the number of minor ticks between major
In the event of an error the scalar 0 is returned.
EXAMPLE:
The following code fragment illustrates the use of this routine and
inms_label_ticks.
;; convert times to Julian Dates
;; first PDS compiant times to UTC format
;; then UTC to Julian dates
;;
axOrdDate = inms_doy2utc(strupcase(axHkg.sclktime))
anJulDate = sprl_cvt_odate_jdate(axOrdDate.nDate, axOrdDate.nMsecs)
;; determine axis formatting values
;; Ticks are to be on the hour
;;
xTickDef = inms_neat_ticks([anJulDate[0], anJulDate[nPoints-1]],$
tick='Hour')
;; specify the format for the tick labels
nDummy = inms_label_ticks(format='DOY')
;; create a plot
;; using the fields in the xTickDef as values for the
;; corresponding plot keyword
;;
plot, anJulDate, anY,$
position=anPlotPos, $
xrange=xTickDef.anRange, $ ;; obtained from inms_neat_ticks
xtickv=xTickDef.anTickv, $ ;;
xminor=xTickDef.nMinor, $ ;;
xticks=xTickDef.nTicks, $ ;;
xtitle='!Ctime', $
xtickformat='inms_label_ticks', $
yrange=[nYmin, nYmax], $
ytitle=asLabels[anContIdx[0]], $
_extra=extra
CHANGES:
2-Jun-2005 D. Gell Initial Coding
16-Jun-2005 D. Gell Adjust tick mark location determination
17-Jun-2005 D. Gell Correct adjustment of range for even day
increments
09-Nov-2005 D. Gell Added quarter hour major ticks
20-Sep-2006 DAG Use error handler and inms_post_message
02-Jan-2006 DAG Correct calculation of major ticks for quarter hours
(Routine contained in inms_neat_ticks.pro)
NAME:
inms_parse_file_name - extracts constituent fields from INMS archive file names
function inms_parse_file_name, asFileNames, debug=debug
PURPOSE:
Divide one or more INMS archive file names
into it constituent fields
RETURN VALUE:
an array of structures containing one structure for each
file in the list of files
xParsedName = {nYear: 0, $ ;; date fields
nDay: 0, $ ;;
sType: ' ', $ ;; type, L1A, HKG...
nHour: 0, $ ;; time fields
nMin: 0, $ ;;
nSec: 0, $ ;;
nRev: 0, $ ;; revision number
sExt: ' '} ;; extension, always CSV
invalid names are indicated by an uninitialized structure
(a copy of xParsedName) An invalid name is any name without
8 fields or with any non-numeric values in the numeric fields.
ARGUMENTS:
asFileNames an array of file name strings to be parsed
KEYWORDS:
debug if set, diagnostic information is produced
CHANGES:
23-Aug-2004 DAG Initial Coding
29-Nov-2004 DAG replaced isnumeric with sprl_isnumeric
added call to on_error,2
02-Mar-2005 DAG updated to handle new file nameing convention
Parses either name format
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_parse_file_name.pro)
NAME:
inms_parse_l1A_name - extracts constituent fields from L1A file names
function inms_parse_l1a_name, asFileNames
PURPOSE:
Divide a L1A Name into it constituent fields
RETURN VALUE:
an array of structures containing one structure for each
file in the list of files
xParsedName = {nYear: 0, $
nDay: 0, $
sType: ' ', $
nHour: 0, $
nMin: 0, $
nSec: 0, $
nRev: 0, $
sExt: ' '}
invalid names are indicated by an uninitialized structure
(a copy of xParsedName) An invalid name is any name without
8 fields or with any non-numeric values in the numeric fields.
ARGUMENTS:
asFileNames an array of file name strings to be parsed
CHANGES:
23-Aug-2004 DAG Initial Coding
29-Nov-2004 DAG replaced isnumeric with sprl_isnumeric
added call to on_error,2
02-Mar-2005 DAG updated to handle new file nameing convention
Parses either name format
02-Jun-2005 DAG superceeded by inms_parse_file_name
(Routine contained in inms_parse_l1a_name.pro)
NAME:
inms_parse_time - extracts fields from date/time strings
function inms_parse_time, asTimes, debug=debug
PURPOSE:
Divide a time strings into constutient fields
RETURN VALUE:
an array of structures containing one structure for each
file in the list of files
xParsedTime = {nYear: 0, $
nDay: 0, $
nHour: 0, $
nMin: 0, $
nSec: 0.0}
invalid times are indicated by an uninitialized structure
(a copy of xParsedTime)
ARGUMENTS:
astimes an array of file name strings to be parsed
KEYWORDS:
debug if set, diagnostic information is produced
;
CHANGES:
23-Aug-2004 DAG Initial Coding
09-Feb-2005 DAG Allow fractional seconds
13-Jun-2005 DAG Change loop counter to long
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_parse_time.pro)
NAME:
inms_plot_cal_ptrn - plots calibration cracking patterns curves
pro inms_plot_cal_ptrn, axCal, $ ;; (i) calibration data structure
asSpecies, $ ;; (i) list of species to plot
em=em, $ ;; (i) set for engineering model
reu=reu, $ ;; (i) set for refurbished EM
nist=nist, $ ;; (i) set for nist
fm=fm, $ ;; (i) set for flight model
filament=filament, $ ;; (i) 'primary' | 'secondary'
energy=energy, $ ;; (i) electron energy
source=source, $ ;; (i) 'OS' | 'CS'
title=title, $ ;; (i) supply title to plot
multiple=multiple, $ ;; (i) set to display all matches
columns=columns, $ ;; (i) set for two columns
debug=debug, $ ;; (i) controls additional debug diagnostics
samewindow=samewindow, $ ;; (i) set to reuse current open window
_extra=extra
PURPOSE:
Plot calibration curves
ARGUMENTS:
axCal - an array of calibration data structures as returned
by inms_read_cal
asSpecies- a string array containing the list of species to display,
defaults to all species in the structure
/EM - set to display only engineering model data
/REU - set to display only refurbished engineering model data
/FM - set to display only flight model data
/NIST - set to display only NIST orginated data
if neither /EM, /FM nor /NIST is set, display from all
filament - set to 'PRIMARY' or 'SECONDARY' to select ion source
filament data to display, Defaults to 'PRIMARY'
energy - set to the ion source electron energy to display,
Defaults to 70.0
source - set to 'OS' or 'CS' to select the ion source
Defaults to 'OS'
title - a string to be used as the plot title, defaults to "Cracking Patterns"
/columns - if set the plots are placed in two columns of 8 rows
if absent the plots are placed in one column of 4 rows
/debug if set, diagnostic information is produced
/SAMEWINDOW - if set reuse current plot window for display
EXAMPLE
inms_read_cal,axCal
asSpecies=['n2','n2(iso)','ch4','ch4(iso)']
inms_plot_cal, axCal, asSpecies,
CHANGES:
13-Jan-2004 DA Gell Initial coding
18-Jan-2004 DA Gell replace inline code with inms_make_window
20-Jan-2004 DA Gell added overplot of log(relative response)
26-Jan-2004 DA Gell enhanced program prolog. Implemented model
selection
01-Feb-2004 DA Gell Adjusted size of axis labels,
Adjusted location and size of legends
18-Aug-2004 DA Gell Replaced ad-hoc test of axCal validity with
function INMS_VALIDATE_CAL_DATA.
Make asSpecies optional, defaults to all
02-Aug-2006 DA Gell Added support for Refurbished EM data
Added call to inms_prepare_plot,/next after
page is compete for multiple PNG plots
08-Aug-2006 DA Gell Renamed to better describe function
20-Sep-2006 DAG Use error handler and inms_post_message
9-Oct-2006 DAG Round floating pt mass values when creating indicies
31-Oct-2006 DAG Adjust annotation text size, considering number of
columns
28-Nov-2006 DAG Adjust location of annotation based on x-axis
length
2-Mar-2007 DA Gell Added title to plots
(Routine contained in inms_plot_cal_ptrn.pro)
NAME:
inms_plot_cal_sens - plots sensitivities as function of species
pro inms_plot_cal_sens, axCal1, axCal2, $ ;; (i) calibration data structure
species=Species, $ ;; (i) list of species to plot
em=em, $ ;; (i) set for engineering model
reu=reu, $ ;; (i) set for refurbished EM
nist=nist, $ ;; (i) set for nist
fm=fm, $ ;; (i) set for flight model
filament=filament, $ ;; (i) 'primary' | 'secondary'
energy=energy, $ ;; (i) electron energy
source=source, $ ;; (i) 'OS' | 'CS'
multiple=multiple, $ ;; (i) set to display all matches
nodates=nodates, $ ;; (i) inhibits label component
title=title, $ ;; (i) Title for plot
subtitle=subtitle, $ ;; (i) string to add to title
debug=debug, $ ;; (i) controls debug diagnostics
samewindow=samewindow, $ ;; (i) set to reuse current window
_extra=extra
PURPOSE:
Plot bar charts of sensitivities
ARGUMENTS:
axCal1 - an array of calibration data structures as returned
by inms_read_cal
axCal2 - an optional array of calibration data structures, plotted
for comparision with the values in axCal1
asSpecies- a string array containing the list of species to display,
defaults to all species in the structure
/EM - set to display only engineering model data
/REU - set to display only refurbished engineering model data
/FM - set to display only flight model data
/NIST - set to display only NIST orginated data
if neither /EM, /FM nor /NIST is set, display from all
/multiple- set to display all data for a species
/nodates - set to inhibit date or run number annotation for each gas
filament - set to 'PRIMARY' or 'SECONDARY' to select ion source
filament data to display, Defaults to 'PRIMARY'
energy - set to the ion source electron energy to display,
Defaults to 70.0
source - set to 'OS' or 'CS' to select the ion source
Defaults to 'OS'
title - Set to the main title, defaults to 'Instrument Sensitivity'
subtitle - Set to a string to add as the second line of the title
debug - if set, diagnostic information is produced
/SAMEWINDOW - if set reuse current plot window for display
EXAMPLE
inms_read_cal,axCal1
asSpecies=['n2','n2(iso)','ch4','ch4(iso)']
inms_plot_cal_sensitivity, axCal1, asSpecies,
CHANGES:
30-AUG-2006 DA Gell Initial coding
03-Nov-2006 DA Gell Added /nodates keyword for format control
Corrected error in sorting runs
07-Dec-2006 DA Gell Correct error in gas label positioning when
more than 25 species are to be plotted
30-Jan-2007 DA Gell Ensure that all data bars fall between x axis
limits
12-Feb-2007 DA Gell Correct regular expression used to parse run
number from calibration data file name
(Routine contained in inms_plot_cal_sens.pro)
NAME:
inms_plot_compare - plots count rate time series from Level 1A data and spectra
pro inms_plot_compare, axData, $ ;; (i) L1A data array
axSpectra, $ ;; (i) Spectra to be overplotted
mass=mass, $ ;; (i) the mass to plot
xrange=xrange, $ ;; (i) time range for x axis
noaux=noaux, $ ;; (i) set to inhibit auxilliary axis
subtitle=subtitle, $ ;; (i) string to add to title
c2counts=c2counts, $ ;; (i) set to plot counter 2 data
samewindow=samewindow,$ ;; (i) set to inhibit new x window
target=target, $ ;; (i) selected target for aux axis
errorbar=errorbar, $ ;; (i) set to draw error bars
debug=debug, $ ;; (i) set for additional debugging control
_extra=extra ;; (i) extra plotting keywords pass through
DESCRIPTION: This procedure produces plots the count rate time history for
one or more mass bins.
ARGUMENTS
axData data structure produced by inms_get_data
axSpectra data structure produced by inms_get_spectra or inms_grid_spectra
KEYWORDS
mass supplies the mass to display
xrange set to two element time string vector, specifying x-axis range
noaux refrains from showing auxilliary axes
subtitle supplies an additional title line, following standard title
c2counts switches to c2counts
errorbar set to display error bars on plot
samewindow set to plot in same window ('X' or 'WIN' devices only)
target a keyword which specifies whether additional axis contain
s/c position wrt Saturn or wrt the current target body
debug set to produced additional diagnostic outputs
and additional plot keywords
REVISIONS:
23-Aug-2004 NAB initial coding, with generous pasting from browse products
(DAG)
30-Aug-2004 NAB subtracted previously added keywords /png, /path,
altered matters such that path and image plots are
called before and after with inms_prepare_plot
added noaux keyword. added checks for correct arguments
31-Aug-2004 NAB one of the headers was erased, call examples written in
header, unnecesary comments removed, added keyword for
using C2 counts
09-Sept-2004 NAB added _extra keyword, modified plot range, added checks
13-Oct-2004 DAG added target keyword, formatting, corrected description
corrected occasional array bounds error in code determining scales
Simplified X window selection. Set window title
replaced ad-hoc code with file_basename IDL procedure
set error handling to return to caller (on_error,2)
02-Nov-2004 DAG remove call to load_colors, now executed by inms_prepare_plot
11-Nov-2004 DAG removed call to date_plotted, now executed by inms_prepare_plot
29-Nov-2004 DAG replaced draw_flag with sprl_draw_flag, doy2date with inms_doy2date
find_color_index with sprl_find_color, plot_sym with sprl_plot_sym
create_table_list with sprl_create_list
18-Jan-2005 DAG replaced inline window create code with inms_make_window
27-jan-2005 DAG changed name of format_time_tick to inms_format_time_tick
added call to sprl_date_plotted
1-Feb-2005 DAG use inms_l1a_files_read to get list of files
removed dependance on prior knowledge of the axData layout.
21-Feb-2005 DAG Added source keyword like inms_plot_mt_spectra
Corrected code to place no data point alert in plot
Added subtitle keyword
25-Feb-2005 DAG Made list of colors for data points identical
to inms_plot_mass_history
Added error bars every 25 points
01-Mar-2005 DAG Corrected problem that caused png files to be monochrome
25-mar-2005 DAG Insure color table re-loaded after changing to catagorical colors
29-mar-2005 DAG Made ion source labels more ledgible
------------------------
04-May-2006 DAG Adapted from inms_plot_mt_line to overplot data from spectra
08-Jul-2006 DAG Pass _extra keywords through to all plotting routines
10-Nov-2006 DAG Reduced spacing between aux axes for publication plots
5-Apr-2007 DAG Add time from closest approach to aux axis, adjust plot location
23-May-2007 DAG Display sequence start flags only within time range
(Routine contained in inms_plot_compare.pro)
NAME:
inms_plot_density_profiles - plots one or more density profiles with altitude
pro inms_plot_density_profiles, $
axProfiles, $ ;; array of density structures
asSpecies, $ ;; list of species to plot
molefraction=molefraction, $ ;; set to plot mole fraction
samewindow=samewindow, $ ;; set to re-use window
subtitle=subtitle, $ ;; subtitle
debug=debug, $ ;; controls additional debug diagnostics
_extra=extra
PURPOSE:
plots the density profiles produced by inms_make_profiles
ARGUMENTS:
axProfiles - an array of density structures containing the data to plot
asSpecies - a list of species to plot, specified as the formula.
Note, capitolization is used in forming legend.
Specify Ar, not AR to insure proper atomic symbols
KEYWORDS:
/molefraction - if present the mole-fraction is plotted
in place of the number density
/samewindow - if present the current window is re-draw,
if absent the plot is place
in a new window
subtitle - supplies a string to be added to the title
/debug - if set, diagnostic information is produced
_extra - any additional plotting keywords
CHANGES:
30-Aug-2005 D.A. Gell - initial coding
13-Sep-2005 D.A. Gell Character size setting considers value of !p.charsize
20-Sep-2006 DAG Use error handler and inms_post_message
30-Nov-2006 DA Gell form species label from formula using inms_idl_species_label
(Routine contained in inms_plot_density_profiles.pro)
NAME:
inms_plot_geom - plots geometric quantities as function of time
Created by David A. Gell on 2007-03-21.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
pro inms_plot_geom, axData, $ ;; L1A data structure
saturn=saturn, $ ;; controls ref. for aux axes
subtitle=subtitle, $ ;; subtitle to add to title
samewindow=samewindow, $ ;; set to re-use window
debug=debug, $ ;; set to enable debugging
_extra=extra ;; additional plotting options
PURPOSE: Plots latitude, longitude, ram angle, local solar time as function of
time and time from closest approach
ARGUMENTS:
axData - (i) array of level 1 data records
KEYWORD PARAMETERS:
/saturn if present, the auxilliary axes display the position w.r.t Saturn.
If absent, the s/c is position wrt the target body
subtitle supplies additional title information to follow the main title
/samewindow if present, reuse the current IDL display window
('X' or 'WIN' devices only, ignored otherwise)
/debug if present, additional debugging features are enabled
and additional plotting keywords accepted by the IDL PLOTS and PLOT
procedures
RESTRICTIONS:
METHOD:
EXAMPLE:
MODIFICATION HISTORY:
date by description
21-Mar-2007 D.A. Gell Initial Coding
16-Apr-2007 D.A. Gell Simplified logic, made target-relative plots the default
Added hour scale for local solar time, plot west longitude
from -180 to 180 deg.
22-May-2007 D.A. Gell Improve spacing of anciliary data on figure
(Routine contained in inms_plot_geom.pro)
NAME:
inms_plot_histogram - plots a mass spectra histogram
pro inms_plot_histogram, xSpectra, $ ;; histogram
hires=hires, $ ;; set to display 1/8 amu scans
C2counts=C2counts, $ ;; set to plot C2, default C1
noylog=noylog, $ ;; set to inhibit log plot
noip=noip, $ ;; set to inhibit plot IP count
errorbar=errorbar, $ ;; set to plot errros
scale=scale, $ ;; ratio of c1 counts to c2
replace=replace, $ ;; controls replacement
refspec=refspec, $ ;; reference spectra to overplot
nogrid = nogrid, $ ;; if set inhibit grid
position=position, $ ;; set postion of plot
subtitle=subtitle, $ ;; value added to title
samewindow=samewindow, $ ;; set to inhibit new x window
debug=debug, $
_extra=extra
PURPOSE:
Plot a single spectra as a histogram
ARGUMENTS:
xSpectra a structure containing the spectra to plot
KEYWORDS:
/hires set to plot data collected during 1/8 amu scans
/C2counts set to plot the output of counter 2 rather than 1 (the default)
/noylog set to plot the counts linearly, rather than the log of counts
/noip set to disable plot of Integration periods accumulated
/errorbar set to plot error bars
scale supplies the ratio of c1/c2 counts, defaults to 5840.6
/replace set to replace values of c1 counts with scaled c2 counts
refspec supplies an optional reference spectra to overplot
/grid set to disable grid at major tick marks
position supplies a 4 element vector specifying the location of the
plot in normal units
subtitle a string to be added to the plot title
/debug if set, diagnostic information is produced
/samewindow set to inhibit new x window
additionaly, any graphics keywords accepted by plot
EXAMPLES:
to plot the Counter 1 count rate on a log scale, with no error bars
inms_plot_histogram, xSpectra
as above, with error bars
inms_plot_histogram, xSpectra, /errorbar
Plot counter 2 values
inms_plot_histogram, xSpectra, /C2, /err
note that keywords may be abbrieviated by the keywords shortest non-ambiguous substring
CHANGES:
2-AUG-2004 DAG Initial Coding
31-Aug-2004 DAG remove font settings, allow user to set
13-Oct-2004 DAG set error handling to return to caller (on_error,2)
14-Oct-2004 DAG corrected error in determining mass bins when mass step
is less than 1.0. Correct formatting of plot title when
mass table list is longer than 10 entries
11-Nov-2004 DAG removed call to date_plotted, now executed by
inms_prepare_plot
15-Nov-2004 DAG add noIP switch to disable auxilliary y axis
added consideration of !inms_pub global switch
30-Nov-2004 DAG replaced find_color_index with sprl_find_color
21-Dec-2004 DAG changed case statement for setting ytitle to if
10-Jan-2005 DAG made annotations on plot optional
17-Jan-2005 DAG ensure points with no data fall below x axis,
recognize the /samewindow keyword
27-jan-2005 DAG changed name of format_time_tick to inms_format_time_tick
added call to sprl_date_plotted
1-feb-2005 DAG replaced test of !inms_pub with call to inms_is_publication
4-feb-2005 DAG corrected ambiguous keyword pair c2 & c2factor
made roll over replacement optional
28-Feb-2005 DAG changed error bar keyword to errorbar from errSw for
consistancy with other routines
01-Mar-2005 DAG set color table in this routine, can't depend on it
remaining as set by inms_prepare_plot,
validate xSpectra argument and refspec keyword
Simplify creation of mass table list for title
12-Mar-2005 DAG Increase critical frequency to 1.5MHz
correct test for rollover when mass bins are co-added
25-Mar-2005 DAG Add altitude to title of plot
18-Apr-2005 DAG Added keywords hires and position to produce 1/8 AMU
resolution plots and to permit relocation of plot
22-Jun-2005 DAG Made keyword names consistant with other plotting routines
07-Sep-2005 DAG Confirm that the input is a single spectra, not an array
27-Sep-2005 DAG Reduced title character size
Changed subtitle to be handled same as other library procs
14-Nov-2005 DAG Changed value for nC2mult to 4459.6 from analysis in
"Determination of counter Response Ratio from Flight
Data" INMS file 089-0065
24-Jul-2006 DAG Changed reference spectra line type to solid, from dash-dot
25-Jul-2006 DAG Support ION abundance spectra
10-Sep-2006 DAG Corrected spectra type determination so summed spectra
are correctly labeled
04-Oct-2006 DAG Changed default critical frequency to 1.25 MHz
approximately 38000 c/ip
Changed default C1/C2 ratio to 5840.7 ex (4459.6)
04-Dec-2006 DAG Improved main title, removing redundant words
11-Dec-2006 DAG Added target to title
19-Dec-2006 DAG Added grid at major divisions
(Routine contained in inms_plot_histogram.pro)
NAME:
inms_plot_hkg - plots one or more housekeeping data items
pro inms_plot_hkg, axHkg, $ ;; housekeeping data
asItems, $ ;; list of variables to plot
subtitle=subtitle, $ ;; set to add to title
samewindow=samewindow, $ ;; set to inhibit new X window
_extra=extra, $ ;; additional plotting keywords
debug=debug ;; set for debugging
PURPOSE;
Plots trends of housekeeping data. Discretes, that is items whose
value is either 0 or 1 are plotted as color bars, with green for zero
and red for one. All other houskeeping items are plotted as continuous
valued functions
ARGUMENTS:
axHKG - (i) The housekeeping data to plot
asItems - (i) A vector of strings containing the list of
items to plot.
KEYWORDS:
subtitle a string to be added to the plot title
samewindow if set, the plot is produced in the currently open plot window
applicable only to the X plot device
debug set for additional debugging output
extra allows further user specification of plot keyword expressions
CHANGES:
02-June-2005 D. Gell initial coding
20-Jul-2005 D. Gell Added date plotted to figure
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_plot_hkg.pro)
NAME:
inms_plot_mass_history - plots count rate time series from spectra arrays
pro inms_plot_mass_history, $
axSpectra, $ ;; (i) an array of spectra
anMassList, $ ;; (i) a vector of masses to plot
rate=rate, $ ;; (i) set to plot count rate
C2counts=C2counts, $ ;; (i) set to plot counter 2
subtitle=subtitle, $ ;; (i) set to add to title
errorbar=errorbar, $ ;; (i) set to add error bars
wlong=wlong, $ ;; (i) set to display west longitude,
samewindow=samewindow, $ ;; (i) set to inhibit new x window
debug=debug, $ ;; (i) set for verbose output
_extra=extra ;; (i) placeholder for additional
;;; plot keyword
PURPOSE:
plots a time history of the signal in one or more mass bins
ARGUMENTS:
axSpectra an array of spectra produced by inms_get_spectra
or inms_grid_spectra
anMassList an array containing mass values to include on the plot
KEYWORDS:
subtitle a string to be added to the plot title
/rate set to display count rate, not total counts
/wlong set to display west longitude in place of local solar time
/c2counts set to plot counter 2, the low sensitivity counter
/errorbar set to display error bars on plotted points
/samewindow if set, the plot is produced in the currently open
plot window
applicable only to the X plot device
/debug set for additional debugging output
extra allows further user specification of plot keyword expressions
USEAGE:
inms_plot_mass_history, axSpectra
CHANGES:
02-Nov-2004 DAG remove call to load_colors, now executed by
inms_prepare_plot
29-Nov-2004 DAG replaced find_color_index with sprl_find_color,
plot_sym with sprl_plot_sym
3-Jan-2005 DAG Added samewindow keyword processing
18-Jan-2005 DAG replace inline window create code with inms_make_window
21-Feb-2005 DAG Added Subtitle keyword
25-Feb-2005 DAG Made list of colors for data points identical
to inms_plot_mt_line
01-Mar-2005 DAG set color table in this routine, can't depend on it
remaining as set by inms_prepare_plot,
15-Mar-2005 DAG Added auxilliary x-axis showing altitudes
03-May-2005 DAG Plot out of range values along upper or lower frame
22-Jun-2005 DAG made keyword names consistant with other
plotting routines
28-Jun-2005 DAG replaced ad-hoc code to plot error bars with
sprl_plot_error
1-Jul-2005 DAG increased width of altitude tick mark label field
18-Jul-2005 DAG add option to plot count rates
20-Sep-2006 DAG Use error handler and inms_post_message
15-Nov-2006 DAG Reduce spacing between auxilliary axis
11-Dec-2006 DAG Change altitude label when saturn is target
12-Apr-2006 DAG Replaced ad-hoc code for aux axis with inms_add_aux_axes
Show time from closest approach aux axis.
(Routine contained in inms_plot_mass_history.pro)
NAME:
inms_plot_mass_profile - plots signal altitude profiles from spectra
pro inms_plot_mass_profile, $
axSpectra, $ ;; (i) an array of spectra
anMassList, $ ;; (i) a vector of masses to plot
rate=rate, $ ;; (i) set to plot count rate
C2counts=C2counts, $ ;; (i) set to plot counter 2
subtitle=subtitle, $ ;; (i) set to add to title
errorbar=errorbar, $ ;; (i) set to add error bars
connect=connect, $ ;; (i) set to draw lines between pt
samewindow=samewindow, $ ;; (i) set to inhibit new x window
debug=debug, $ ;; (i) set for verbose output
_extra=extra ;; (i) placeholder for additional
;; plot keyword
PURPOSE:
plots an altitude profile of the signal in one or more mass bins
ARGUMENTS:
axSpectra an array of spectra produced by inms_get_spectra
or inms_grid_spectra
anMassList an array containing mass values to include on the plot
KEYWORDS:
subtitle a string to be added to the plot title
/rate set to display count rate, not total counts
/c2counts set to plot counter 2, the low sensitivity counter
/errorbar set to display error bars on plotted points
/connect set to conect data points with line
/samewindow if set, the plot is produced in the currently open
plot window
applicable only to the X plot device
/debug set for additional debugging output
extra allows further user specification of plot keyword expressions
USEAGE:
inms_plot_mass_profile, axSpectra
CHANGES:
09-Sep-2006 DAG Initial coding, adapted from inms_plot_mass_history
20-Sep-2006 DAG Use error handler and inms_post_message
30-Nov-2006 DAG Changed name for consistancy with inms_plot_mass_history
11-Dec-2006 DAG Labels altitude axis differently when target is saturn
14-Dec-2006 DAG Added /CONNECT keyword
(Routine contained in inms_plot_mass_profile.pro)
NAME:
inms_plot_mt_line - plots count rate time series from Level 1A data
pro inms_plot_mt_line, axData, $ ;; (i) data
anMassList, $ ;; (i) list of masses
xrange=xrange, $ ;; (i) time range for x axis
source=source, $ ;; (i) list of sources to display
rate=rate, $ ;;(i) set to plot count rate
files=files, $ ;; (i) set to display list of l1a files
noaux=noaux, $ ;; (i) set to inhibit auxilliary axis
subtitle=subtitle, $ ;; (i) string to add to title
c2counts=c2counts, $ ;; (i) set to plot counter 2 data
samewindow=samewindow, $ ;; (i) set to inhibit new x window
target=target, $ ;; (i) selected target for aux axis
errorbar=errorbar, $ ;; (i) set to draw error bars
debug=debug, $ ;; (i) set for added debugging control
_extra=extra ;; (i) extra plotting keywords
DESCRIPTION: This procedure produces plots the count rate time history for
one or more mass bins.
ARGUMENTS
axData data structure produced by inms_get_data
anMassList list of masses to include
KEYWORDS
xrange set to two element time string vector,
specifying x-axis range
source set to list of sources to display,
defaults to ['csn', 'osi', 'osnb']
/rate plot count rate rather than summed counts per sample period
/files set to show l1a files
/noaux refrains from showing auxilliary axes
subtitle supplies an additional title line, following standard title
/c2counts switches to c2counts
/errorbar set to display error bars on plot
/samewindow set to plot in same window ('X' or 'WIN' devices only)
/target a keyword which specifies whether additional axis contain
s/c position wrt Saturn or wrt the current target body
and additional plot keywords
EXAMPLE:
first one needs to get the data structure using inms_get_data and set
device with inms_prepare_plot. The whole show may be similar to:
inms_get_data, DATA, path = '/home/KingBorggren/data/', /doydir, $
trange = ['2004-183T07:22:08', '2004-183T09:16:21']
inms_prepare_plot, init= 'ps'
inms_plot_mt_LINE, DATA, [16, 28, 32], /files, /noaux, /c2counts
inms_prepare_plot, /done
REVISIONS:
23-Aug-2004 NAB initial coding, with generous pasting from browse products
(DAG)
30-Aug-2004 NAB subtracted previously added keywords /png, /path,
altered matters such that path and image plots are
called before and after with inms_prepare_plot
added noaux keyword. added checks for correct arguments
31-Aug-2004 NAB one of the headers was erased, call examples written in
header, unnecesary comments removed, added keyword for
using C2 counts
09-Sept-2004 NAB added _extra keyword, modified plot range, added checks
13-Oct-2004 DAG added target keyword, formatting, corrected description
corrected occasional array bounds error in code
determining scales
Simplified X window selection. Set window title
replaced ad-hoc code with file_basename IDL procedure
set error handling to return to caller (on_error,2)
02-Nov-2004 DAG remove call to load_colors, now executed by
inms_prepare_plot
11-Nov-2004 DAG removed call to date_plotted, now executed by
inms_prepare_plot
29-Nov-2004 DAG replaced draw_flag with sprl_draw_flag,
doy2date with inms_doy2date
find_color_index with sprl_find_color,
plot_sym with sprl_plot_sym
create_table_list with sprl_create_list
18-Jan-2005 DAG replaced inline window create code with inms_make_window
27-jan-2005 DAG changed name of format_time_tick to inms_format_time_tick
added call to sprl_date_plotted
1-Feb-2005 DAG use inms_l1a_files_read to get list of files
removed dependance on prior knowledge of the axData layout.
21-Feb-2005 DAG Added source keyword like inms_plot_mt_spectra
Corrected code to place no data point alert in plot
Added subtitle keyword
25-Feb-2005 DAG Made list of colors for data points identical
to inms_plot_mass_history
Added error bars every 25 points
01-Mar-2005 DAG Corrected problem that caused png files to be monochrome
25-mar-2005 DAG Insure color table re-loaded after changing to
catagorical colors
29-mar-2005 DAG Made ion source labels more ledgible
25-May-2005 DAG Adjust fonts and spacing, add gutter between plots
1-Jul-2005 DAG Support for MS windows
17-Nov-2005 DAG Add option to plot count rate, improve y-axis scale
13-Sep-2006 DAG Fix location of aux axis, size of x axis labels
20-Sep-2006 DAG Use error handler and inms_post_message
21-Sep-2006 DAG Added "esm" source to list of valid sources
10-Nov-2006 DAG Reduce aux axis spacing when inms_publication set
30-Mar-2007 DAG Add time from closest approach axis when /target specified
Adjust plot position to avoid clipping vertical axis title
23-May-2007 DAG Display sequence start flags only within time range of plot
(Routine contained in inms_plot_mt_line.pro)
NAME:
inms_plot_mt_spectra - plots mass time spectra from Level 1A data
pro inms_plot_mt_spectra, axData, $ ;;(i) Data Structure
xrange=xrange, $ ;;(i) Two element vector of times
subtitle=subtitle, $ ;;(i) additional title line
rate=rate, $ ;;(i) set to plot count rate
noaux=noaux, $ ;;(i) set to disable auxilliary axes
noseq=noseq, $ ;;(i) set to disable sequence start flags
noion=noion, $ ;;(i) set to disable ion source flags
source=source, $ ;;(i) list of sources
tres=tres, $ ;;(i) time resolution seconds
c2counts=c2counts, $ ;;(i) set to plot counter 2 data
samewindow=samewindow, $ ;;(i) set to inhibit new x window
target=target, $ ;;(i) select target for aux axis
_extra=extra, $ ;;(i) extra plotting keywords pass through
debug=debug
DESCRIPTION:
This procedure produces the mass-time spectrum plot, in which
the vertical axis is mass bin, the horizontal axis is time and
the color code indicates the counts per sample period.
ARGUMENTS:
axL1aData data structure produced by inms_get_data
KEYWORDS:
xrange=[min,max] time range to plot, supplied as a two element string vector
using the year, day-of-year format: yyyy-dddThh:mm:ss
subtitle supplies an additional line to add to the standard title
/rate plot count rate rather than summed counts per sample period
/noaux refrains from putting auxilliary axes on plot
/source a vector of strings containing the ion sources to include
in the plot
tres=value sets the size of the pixels in the time direction,
default is 15 s
/c2counts makes plot using c2counts rather than c1counts
/samewindow if you want plot to go to the same window rather
then opening a new one. of use only with 'X' or 'WIN'
devices
/target a keyword which specifies whether additional axis contain
s/c position wrt Saturn or wrt the current target body
_extra=extra allows furthur user specifications
EXAMPLE: first one needs to get the data structure using inms_get_data and set
device with inms_prepare_plot. The whole show may be similar to:
inms_get_data, DATA, files, path = '/home/KingBorggren/data/', /doydir, $
trange = ['2004-183T07:22:08', '2004-183T09:16:21']
inms_prepare_plot, init= 'ps'
inms_plot_mt_spectra, DATA, /noaux, /c2counts
inms_prepare_plot, /done
inms_plot_mt_spectra,DATA,/noaux,tres=2.0,source=['osi','osnb', 'csn']
Revisions:
30-July-04 NAB Procedure is born. Code is liberally utilized from
bp_make_plots (DAG)
13-August-04 NAB
17-August-04 NAB Switched arguments from sStartTime, sFinalTime, and sPath
to simply axL1AData. rid procedure of afung-shui @bp line.
20-August-04 NAB made asFilesRead an optional argument, generalized
format_time_tick
23-August-04 NAB removed /test keyword and added /png keyword
24-August-04 NAB added path keyword for where to store plots defaults
to current directory.
27-August-2004 NAB subtracted previously added keywords /png, /path,
altered matters such that path and image plots are
called before and after with inms_prepare_plot
added noaux keyword. added checks for correct arguments
31-August-2004 NAB one of the headers was erased, call examples written in
header, unnecesary comments removed, added keyword for
using C2 counts
09-September-04 NAB added _extra keyword, modified plot range, added checks
13-October-2004 DAG added target keyword, formatting, corrected description
fixed indexing error in pixel array. Simplified X window selection
Set window title
replaced ad-hoc code with file_basename IDL procedure
set error handling to return to caller (on_error,2)
20-October-2004 DAG added code to permit changing of time resolution and
plotting spectra for individual sources. Fixed problem
handling files that extend into the next day. Fixed X window
selection. Removed the file option.
02-Nov-2004 DAG remove call to load_colors, now executed by inms_prepare_plot
11-Nov-2004 DAG removed call to date_plotted, now executed by inms_prepare_plot
15-Nov-2004 DAG recognize the !inms_pub keyword, add switches to control sequence
flags and source bar
29-Nov-2004 DAG replaced draw_flag with sprl_draw_flag, doy2date with inms_doy2date
colorplot with sprl_colorplot, find_color_index with sprl_find_color,
create_table_list with sprl_create_list
30-Nov-2004 DAG corrected handling of color for pseudo color device, established
error handler to insure colors restored if required
18-Jan-2005 DAG replaced inline window create code with inms_make_window
27-jan-2005 DAG changed name of format_time_tick to inms_format_time_tick
added call to sprl_date_plotted
1-feb-2005 DAG replaced test of !inms_pub with call to inms_is_publication
removed dependance on prior knowledge of the layout of axData
9-feb-2005 DAG adding adjustable time range to support browse product use
21-Feb-2005 DAG added subtitle keyword
28-Feb-2005 DAG Added notation on plot when no data present
1-Mar-2005 DAG replaced call to sprl_load_categorical_colors
with sprl_load_colors,/categorical
24-mar-2005 DAG Delete calls to sprl_load_colors, executed by inms_prepare_plot
and inms_write_image changed to read pixel map not Z-buffer
25-May-2005 DAG Adjust character sizes
13-Sep-2005 DAG Consider value of !p.charsize in setting character sizes
31-Oct-2005 DAG Added option to plot count rate, permit time resolution less than
one second
20-Sep-2006 DAG Use error handler and inms_post_message
10-Nov-2006 DAG Reduce aux axis spacing when inms_publication set
30-Apr-2007 DAG Add time from closest approach axis when /target specified
Adjust plot position to avoid clipping vertical axis title
23-May-2007 DAG Display sequence start flags only within time range
(Routine contained in inms_plot_mt_spectra.pro)
NAME:
inms_plot_series - plots one or more housekeeping data items
pro inms_plot_series, axData, $ ;; housekeeping data
asItems, $ ;; list of variables to plot
aux=aux, $ ;; set to show aux axis
target=target, $ ;; set for target relative aux values
subtitle=subtitle, $ ;; set to add to title
samewindow=samewindow, $ ;; set to inhibit new X window
_extra=extra, $ ;; additional plotting keywords
debug=debug ;; set for debugging
PURPOSE;
Plots trends of housekeeping data. Discretes, that is items whose
value is either 0 or 1 are plotted as color bars, with green for zero
and red for one. All other houskeeping items are plotted as continuous
valued functions
ARGUMENTS:
axData - (i) The housekeeping data to plot
asItems - (i) A vector of strings containing the list of
items to plot.
KEYWORDS:
subtitle a string to be added to the plot title
samewindow if set, the plot is produced in the currently open plot window
applicable only to the X plot device
debug set for additional debugging output
extra allows further user specification of plot keyword expressions
CHANGES:
02-June-2005 D. Gell initial coding, based on earlier version
revised to correct limited color
palete and permit plot including only
discrete items
12-Sep-2005 D. Gell added date plotted to bottom of plot, corrected
format of legend used for discretes.
13-Sep-2006 DA Gell Fix size of x axis labels
20-Sep-2006 DA Gell Use error handler and inms_post_message
25-Oct-2006 DA Gell Correct use of subtitle keyword in forming title
10-Nov-2006 DAG Reduce aux axis spacing when inms_publication set
(Routine contained in inms_plot_series.pro)
NAME:
inms_plot_stacked_spectra - plots a collection of spectra as a color coded mass/time spectra
pro inms_plot_stacked_spectra, axSpectra, $ ;;(i) spectra to plot
rate=rate, $ ;;(i) set to display counts/sec
subtitle=subtitle, $ ;;(i) additional title info
wlong=wlong, $ ;;(i) set to display west longitude, not lst
ramangle=ramangle, $ ;;(i) set to overplot ram angle
c2counts=c2counts, $ ;;(i) set to plot low sens counter
samewindow=samewindow, $ ;;(i) set to inhibit new x window
debug=debug, $
_ref_extra=extra
PURPOSE:
Plots a series of histograms as color stripes. The vertical axis is mass
and the horizontal axis is time. The color code indicates the signal
ARGUMENTS:
axSpectra an array of spectra produced by inms_get_spectra or inms_grid_spectra
/rate if set, plot is of count rate rather than counts per sample
subtitle a string to be added to the plot title
/wlong set to display west longitude inplace of local solar time
/ramangle set to plot ram angle in degrees over the color plot
/c2counts set to plot counter 2, the low sensitivity counter
/samewindow if set, the plot is produced in the currently open plot window
applicable only to the X plot device
/debug set for additional debugging output
extra allows further user specification of plot keyword expressions
CHANGES:
25-FEB-2005 DAG Initial Coding
4-Apr-2005 DAG Change plot title to include the spectra type
22-Jun-2005 DAG Made keyword names consistant with other plotting routines
06-Jul-2005 DAG handle date strings with and without enclosing quotes
30-Aug-2005 DAG Added auxilliary axes, lat and wLon or sza
4-Nov-2005 DAG Added count rate switch
18-Nov-2005 DAG Identify the counter being displayed
20-Sep-2006 DAG Use error handler and inms_post_message
15-Jan-2007 DAG Add overplot of ram angle to aid diagnosis of
ion spectra
Properly title ion abundance spectra
17-Apr-2007 DAG Replace ad-hoc code for auxiliary axes with
inms_add_aux_axes routine
(Routine contained in inms_plot_stacked_spectra.pro)
NAME:
inms_plot_state - Plots mass, cycle, or sequence table transitions
pro inms_plot_state, axData, $ ;; L1A data structure
table=table, $ ;; controls the table to display,
target=target, $ ;; controls ref. for aux axes
noaux=noaux, $ ;; set to inhibit auxilliary axis
ramangle=ramangle, $ ;; set to overplot with ram angle
subtitle=subtitle, $ ;; subtitle to add to title
samewindow=samewindow, $ ;; set to re-use window
debug=debug, $ ;; set to enable debugging
_extra=extra ;; additional plotting options
PURPOSE:
Creates a plot showing the times at which tables of the selected type
are invoked by the flight software.
ARGUMENTS:
axData An array of L1A data structures containing the data to plot
KEYWORDS:
table Set to the table type to plot, values may be MT, CT, or ST
for mass, cycle or sequence table respectively. If absent,
the mass table data is displayed.
/target if present, the auxilliary axes display the position w.r.t the
target body. If absent, the s/c is position wrt Saturn
/noaux if present, the auxilliary axes are omitted.
/ramangle if present, the ram angle is plotted over the figure
subtitle supplies additional title information to follow the main title
/samewindow if present, reuse the current IDL display window
('X' or 'WIN' devices only)
/debug if present, additional debugging features are enabled
and additional plotting keywords accepted by the IDL PLOTS and PLOT
procedures
EXAMPLE:
inms_get_data, axData ;; get data to display
inms_plot_state, axData, /target, subtitle='S24 Actual'
REVISIONS:
21-Aug-2006 D. Gell Initial coding
23-Aug-2006 D. Gell Added prolog, additional inline documentation
and improved error handling
08-Sep-2006 D. Gell Added sequence table indicator to mass table plot
13-Sep-2006 D. Gell increased columns of tables to 4.
10-Oct-2006 D. Gell Change plot symbol to vertical bar
16-Mar-2007 D. Gell Add time to closest approach axis
12-Apr-2007 D. Gell Add vertical line at ca time when /ca
(Routine contained in inms_plot_state.pro)
NAME:
inms_post_message - Posts a message as a dialog if possible
pro inms_post_message, sMessage, $ ;; the message to display
console=console, $ ;; set to report in cmd buffer only
traceback=traceback, $ ;; set to make traceback
error=error, $ ;; sets type of message, error
warning=warning, $ ;; warning
information=information ;; or info
PURPOSE:
displays an error or informational message as a dialog if possible
or to the standard output if not
ARGUMENTS;
sMessage A string or string array containing the message to post
defaults to the last message created by the MESSAGE procedure.
If an array is passed each array element is written as a
separate line
KEYWORDS:
/console if set, output is to the standard IDL output
if absent, and widgets are supported a dialog is posted
/traceback if set, a traceback of the calling path is displayed
/error if set, an error message is posted
/information if set, an informational message is posted
/warning if set, a warning message is posted
USEAGE:
This routine may be used in two ways. First, it may be called directly
to post an informational message,
inms_post_message,asTheMessage,/info
Secondly, it may be called within an error handler
on_error,2 ;; return to caller on error
catch,nErrCode ;; establish an error handler
if nErrCode then begin
catch,/cancel ;; prevent infinte error loops
inms_post_message,/traceback ;; post message with traceback
return ;; return to caller
endif
The return is needed because the condition that threw the exception,
either an error that IDL detected or a user invoked MESSAGE statement,
has now been handled and without the return statement execution continues
within the routine containing the exception
CHANGES:
02 Feb 2006 D.A. Gell initial coding
03 May 2006 D.A. Gell Handle traceback correctly when error message
is multi-lined
help,/last_message
returns the error message followed by the
traceback
12 May 2006 D.A. Gell simplify the extraction of message and traceback
information
06 Sep 2006 D.A. Gell Make sure the supplied message is used when available
21 Sep 2006 D.A. Gell Change format of message at console
(Routine contained in inms_post_message.pro)
NAME:
inms_prepare_plot - initializes plotting for X, PS or PNG
pro inms_prepare_plot, init=init, $
black=black, $
white=white, $
publication=publication, $
resolution=resolution, $
portrait=portrait, $
path=path, $
file=file, $
next=next, $
done=done, $
spool=spool, $
sequential=sequential, $
divergant=divergant
PURPOSE:
Initialize plotting device
KEYWORDS
init set to initialize plotting for X, WIN, PS, IMAGE, PNG, TIFF, JPEG, or NULL
X sets the plot device to the X window
WIN sets the plot device to the Microsoft Windows device
PS sets the plot device to a postscript file
IMAGE sets the plot device to an X pixel map in
preparation for making an image PNG file
PNG, TIFF, JPEG set the plot device to an X pixel map in
preparation for making an image file of the specified type
NULL disables graphical output
/white set if plot with white background and black lines is
desired.
/black set if plot with black background and white lines is desired
NOTE: keywords BLACK and WHITE are disregarded for PS
/publication set if plot is to be publication quality
resolution is a two element vector containing the horizontal and
vertical resolution in pixels for images other than PS
path is an optional parameter specifying the directory into which
the image or postscript file will be placed.
initial value is ./, subsiquent values are retained.
The directory is created if required
file is the name of the file to contain the postscript or image
portrait optional keyword to make plot portrait style rather than
landscape style for images
sequential chooses a sequential color table.
/SEQUENTIAL, a smooth variation from light blue to dark blue (default)
it may also be set to one of the following string values
SEQUENTIAL='BLUE' - a smooth variation from light blue to dark blue
SEQUENTIAL='RED' - a smooth variation from black to red
SEQUENTIAL='SPECTRUM' - colors of the spectrum from red to violet
divergent if present, select the divergant color table,
a smooth variation from blue to white to dark red
next set on subsequent call to save image (PNG, TIFF, or JPEG)
file and prepare another
done set on subsequent call to save file
spool set on subsequent call to save file and spool to printer
EXAMPLES
#1 - CREATE A POST SCRIPT FILE
inms_prepare_plot, init='ps'
(plotting code)
inms_prepare_plot, /done
a file named INMSplotnnnnnnnnnn.PS is created in the
current working directory
#2 - create an image with black background
inms_prepare_plot,image='IMAGE', path='/etc/data/ion',/black
(plotting code)
inms_prepare_plot,/done
a file named INMSplotnnnnnnnnnn.PNG is created in the /etc/data/ion
directory. The plot will be on a black background
NOTE TO PROGRAMMERS
To insure that annotation text is properly scaled,
use keyword charsize=nSize*!p.charsize in calls to xyouts
when !p.charsize is not zero, or use the function inms_set_charsize
example: xyouts, xpos, ypos,'message',charsize=2.0*!p.charsize
will create a double size text string on any of the devices
setup by this procedure
The keyword PUBLICATION sets the state variable returned by
inms_is_publication to 1 (one). The value may be tested by
plotting routines to adjust formatting for publications.
The class of graphics device can be determined using the
inms_is_image() function. It returns zero if the output device
is a windows server (X or WIN) and 1 if the output is being
directed to the PS device or to a buffer for a PNG file.
CHANGES:
27-Jul-2004 DAG Initial coding
25-Aug-2004 DAG set graphics device attributes appropriate to selected
device - primarily character sizes
2-Sep-2004 DAG retain plot destination path between initialization
calls.
5-Oct-2004 DAG when initializing X device, initially set device to
NULL, then use xyouts to set screen font. Avoids
bringing up X window before a plot.
29-Nov-2004 DAG addapted to avoid calls to find_color_index, now
replaced by sprl_find_color.
18-Jan-2005 DAG Added spool keyword as alternate to /done
27-Jan-2005 DAG removed date_plotted call, when doing ps the file can
contain more than 1 plot, so only the last one would
be dated. The date_plotted capability is put back in
the plotters
01-Feb-2005 DAG Replaced use of !inms_pub system variable with use
of inms_is_publication
04-Feb-2005 DAG supplied correct function name for setting publication bit
21-Feb-2005 DAG Corrected error message posted when /init, /done or
/spool missing
29-Feb-2005 DAG Corrected error when setting device to null
25-May-2005 DAG Handle file extensions identically for image and
postscript files
20-Jun-2005 DAG Close Pixel map between images, use specific window index
not in the range used by the window,/free option
07-Jul-2005 DAG add next option to close a PNG file and start another
20-Jul-2005 DAG Correct file name when spooling PS file
27-Jul-2005 DAG Add MS Windows support
30-Sep-2005 DAG Corrected initialization of previous device
28-Oct-2005 DAG Choose file path delimeter correctly for MS Windows
20-Dec-2005 DAG Correct message reporting name of PS file produced
10-Jan-2006 DAG Increase character sizes for X device
09-Sep-2006 DAG Reduce character sizes for Xdevice
28-Sep-2006 DAG Set inms_is_image when doing postscript output
29-Sep-2006 DAG Create output directory if required
27-Oct-2006 DAG Add TIFF & JPEG to available image types
10-Nov-2006 DAG All images now acknowledge publication switch
12-Nov-2006 DAG Increased all line thicknesses - publication switch
just sets the flag for other routines to check
15-Jan-2007 DAG Adjust line widths for X and WIN devices
30-Mar-2007 DAG Update program prolog, change color table only
when explicitly specified by SEQ or DIV keywords
(Routine contained in inms_prepare_plot.pro)
NAME:
inms_put_annotations - writes annotations on plot in specified location
pro inms_put_annotations, nXpos, nYpos, axItems, debug=debug
ARGUMENTS:
nXpos - the x position of the annotation in normal units
nYpos - the y position of the annotation in normal units
if the actual nXpos or nYpos parameter is a variable,
it is updated with the starting position for the next
annotation line
/debug - if set, diagnostic information is produced
axItems - an array of anonymous structures containing
the following fields:
sLabel; a string containing the label to preceed the value
nValue: the numerical value to display, optional included when nSel=1
sValue: the string value to display, optional included when nSel=2
nError: the error on the value, optional included when nSel=4
sUnits: the units,optional included when nSel=8
sFmt: the format to use to display nValue when nSel=1
use a blank for default
nSize: the size of the characters, 1 normal size
nSel: the selector, sum of values for optional fields
1, display numeric value in field nValue
2, display string value in field sValue
4, add error to display as value +/- error
8, add units to display
16, use sLabel as header, don't include in
label width calculation
Each element in the array results in a string as follows:
sLabel: nValue sValue +/- nError sUnits
with characters nSize times the standard character size
The selectors nSel=1 and nSel=2 should not both be assigned. The string
output to the plot will be incorrect
The numerical fields, nValue, nError and nSize may be of any numerical
type when the first structure array element is created, but additional
items must conform to the type of the initial instance of the item defintion.
In the example below, the fields nValue and nError were initialized in
the first entry, creating the table heading, as floats. In subsequent
data items the double precision values anDensity, anDenSig, anMoleFcn
and anMoleSig must be explicity convert to single precision floats.
EXAMPLE:
;; create an item to use as a table heading
axItems = {sLabel:'Deconvolution Results', nValue:0.0, sValue:'', $
nError:0.0, sUnits:'', sFmt:'', nSize: 1.1, nSel:16}
;; add items to use as column headings, using a string value
;; note the use of embedded formatting commands
axItems = {axItems, $
sLabel:'Species', nValue:0.0, sValue:'Density (cm!U-3!N)!', $
nError:0.0, sUnits:'', sFmt:'', nSize: 1.0, nSel:2}
axItems = [axItems, $
{sLabel:'', nValue:0.0, sValue:'Mole Fraction', $
nError:0.0, sUnits:'', sFmt:'', nSize: 1.0, nSel:2}]
;; add data items
for nI=0, nSpeciesCount-1 do begin
axItems = [axItems, $
{sLabel:asLabels[nI], nValue:float(anDensity[nI]),
sValue:'', nError:float(anDenSig[nI]), sUnits:'', $
sFmt:'E9.2', nSize: 0.9, nSel:5}]
axItems = [axItems, $
{sLabel:'', nValue:float(anMoleFcn[nI]), sValue:'', $
nError:float(anMoleSig[nI]), sUnits:'', $
sFmt:'F9.4', nSize: 0.9, nSel:5}]
endfor
;; display annotation
inms_put_annotations, nXpos, nYpos, axItems
The following item definition may be used to insert a blank line
{sLabel:'', nValue:0.0, sValue:'', nError:0.0,$
sUnits:'', sFmt:'', nSize: 1.0, nSel:16}]
CHANGES:
11 OCT 2005 DA Gell Initial coding
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_put_annotations.pro)
NAME:
inms_query_l1a - Extracts configuration data from a Level 1A data structure
pro inms_query_l1a, axData, $ ;; (i) level 1 data structure
debug=debug ;; (i) set for debugging
PURPOSE:
create a table indicating unique values for
target, table_set_id, coadd_cnt, seq_table, cyc_table, mass_table
and velocity_comp
USAGE:
inms_query_l1a, axData
ARGUMENTS:
axData - the level 1A data structure to be examined
KEYWORDS:
/debug - if set, diagnostic information is produced
CHANGES:
29-Nov-2004 DAG Replaced create_table_list with sprl_create_list
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_query_l1a.pro)
NAME:
inms_ram_angle - computes the ram angle (Depreciated use inms_auxiliary_value)
function inms_ram_angle, axL1A
PURPOSE:
computes the angle between the INMS boresight and the
spacecraft velocity
ARGUMENTS:
axL1A - an array of L1A data records
RETURN VALUE
a vector of boresight angles (radians)
METHOD:
computes the dot product of the unit vector in the direction of the
velocity with the unit boresight vector. The angle is the arccos of
the result
CHANGES:
07-NOV-2006 D.A. Gell Initial coding
(Routine contained in inms_ram_angle.pro)
NAME:
inms_ram_coefficient - computes density enhancement in closed source due to velocity
function inms_ram_coefficient, speed, $ ;; speed w.r.t instrument km/s
theta, $ ;; angle between ram & boresight (rad)
mass, $ ;; mass of species (amu)
Tambient=Tambient, $ ;; ambient temp
Tsource=Tsource ;; source temp
PURPOSE:
Compute the ram enhancement factor
AUTHOR:
John Parejko
USAGE:
value=inms_ram_coefficient(speed, theta, mass)
RETURN VALUE:
the ram enhancment factor for the specified mass
at the speed and angle with respect to the instrument
apature and outward normal.
The return value has the same shape as the input.
ARGUMENTS:
Speed - Speed in km/s of the incident gas relative to the
the instrument
theta - angle in radians between the incident gas and the outward
normal of the instrument
mass - the mass of the species of interest.
arguments may be arrays, but must be the same shape or a scalar
KEYWORDS:
Tambient - the ambient atmospheric temperature in Kelvins
defaults to 273 K
Tsource - the gas temperature within the closed source
defaults to 300 K
Changes:
11 Oct 2004 - Extracted from counts2density and renamed
13-Jul-2005 DA Gell made temperatures arguments
(Routine contained in inms_ram_coefficient.pro)
NAME:
inms_read_cal - reads a calibration data spreadsheet
pro inms_read_cal, axCal, $ ;; (o)the calibration data
file=file, $ ;; (i)the file to read
debug=debug
PURPOSE: read a calibration data spreadsheet file
ARGUMENTS;
axCal - a structure array containing the calibration data
one element per row of the spreadsheet
KEYWORDS:
file - supplies the name of the file to be read,
if omitted, a file selection dialog is presented
/debug - set to provided additional debugging output
CALIBRATION STRUCTURE FORMAT:
xCal = { $
sUnit: 'xx', $ ;; flight(FM), engineering(EM) or NIST(NT)
sFile: 'xx', $ ;; cal data file from which data extracted
sSource: 'xx', $ ;; source, OS, CS
sGas: 'xx', $ ;; name of calibration gas
sLabel: 'xx', $ ;; IDL label string with imbedded formating
sFormula: 'xx', $ ;; Molecular formula of calibration gas
nMolWt: 0.0, $ ;; Molecular weight of calibration gas
sFilament: 'xx', $ ;; filament, Primary, Secondary
nElecEnergy: 0, $ ;; electron energy
nMajorPeak: 0, $ ;; mass of major peak
nSensitivity: 0.0, $ ;; sensitivity at major peak
nSigmaSens: 0.0, $ ;; standard deviation in sensitivity
nPeakCount: 0, $ ;; number of fragment peaks
anFracMass: fltarr(50), $ ;; mass of fragment
anFraction: fltarr(50) $ ;; sensitivity of fragment, major=1
}
CHANGES:
06-DEC-2004 DAG Initial coding, based on wkt_callib.pro
11-Jan-2005 DAG Added column to spreadsheet with IDL label string
21-Jun-2005 DAG Reads either PDS compliant spreadsheet or
original format calibration spreadsheet
5-Jul-2005 DAG ensure that arrays in calibration structure
are zero'd out prior to use.
17-Nov-2005 DAG Update to handle cal summary plots with NIST derived
dissociation fractions (0-999) in addition to
FU/EU values of 0-1.0
07-Feb-2006 DAG Corrected test to determine whether dissociation
fractions were NIST values (changed test from
"value gt 1" to "value ge 1"
18-Jul-2006 DAG Corrected parsing of input lines to retain null
fields, allow 50 mass peaks (for complex cal gasses)
18-Aug-2006 DAG Changed type of mass anFracMass to float (ex integer)
because masses started being off by one. This fixed
the problem, for no apparent reason.
29-Aug-2006 DAG Added calibration data file name to the structure to
permit date of calibration determination
07-Sep-2006 DAG Determination of NIST cracking pattern fails if
principal mass peak is first.
20-Sep-2006 DAG Use error handler and inms_post_message
06-Oct-2006 DAG Remove quotations from PDS compliant strings
17-Oct-2006 DAG Return molecular weight as a float
31-Oct-2006 DAG Add standard deviation of sensitivity to cal data
structure
02-Feb-2007 DAG Increased size of spectra to 50 masses
05-Feb-2007 DAG Increase size of mass fraction arrays for Toluene
(Routine contained in inms_read_cal.pro)
NAME:
inms_read_fmt_file - Reads PDS compiant structure file
pro inms_read_fmt_file, axFormat, $
file=file, $
debug=debug, $
verbose=verbose
PURPOSE;
read a spreadsheet file format and compile into
an array of item definitions
ARGUMENTS:
axFormat: an array of item definition structures
file: name of the format file to read
CHANGES:
01-DEC-2004 DAG Initial Coding
07-Jan-2005 DAG Added code to handle comments
Added code to check parent directory for
format file if the file is not present
at the specified path
24-Jan-2005 DAG Cache format and use if file name unchanged
from last call
03-Feb-2005 DAG If the specified file is not found, use a
default located in the directory containing
the IDL source
17-Mar-2005 DAG Added format keyword to set
Made nBytes field an integer to match name
29-mar-2005 DAG Added verbose keyword to control cache messages
1-Jun-2005 DAG Placed common block definition into include file
Use heap variables to build format directory in
paxSavedFmt
16-Jun-2005 DAG Removed test for unexpected PDS keyword so that
keywords in the object that are not required will]
be silently ignored.
17-Jun-2005 DAG Changed default format file to latest version
07-Sep-2005 DAG Changed reading loop from repeat ... until EOF to
while ~EOF do ... endwhile so the format file need
not have a trailing blank line
08-Dec-2005 DAG Handle input lines of one or more blanks as null line
12-Dec-2005 DAG Test type of path keyword value before using it.
16-Mar-2006 DAG Fixed error that left NKEYID undefined if a non-comment
string was encountered prior to the first OBJECT=
statement.
08-Mar-2007 DAG Add idl type code and plot label to item structure
permitting retirement of inms_create_l1a_template
sDefaultFmtFile = 'L1A_STRUCT_05.FMT'
(Routine contained in inms_read_fmt_file.pro)
NAME:
inms_read_jcamp - reads mass spectrometer data in the JCAMP/DX format
pro inms_read_jcamp, axData, sFile, debug=debug
ARGUMENTS:
axData A named variable to contain the data structure holding
the input data. Each named record in the JCAMP-DX file
becomes a field in the structure. Fields are named with
the name of the record, spaces in the name are replaced
with underscores"_". The peak table is a two dimensional
array with axData.peak_table[0,*] containing the masses
and axData.peak_table[1,*] relative signal.
sFile The name of the input data file. If not supplied, a file
selection dialog is posted. If a directory is supplied
a file selection dialog is posted, using the supplied
path as the initial directory
KEYWORDS:
/debug Set to enable additional output. If set, errors are
written to the command console, (stdout) if not, errors
dialogs are posted.
RESTRICTION:
Only handles data as discrete points
recognizes data list types (XY..XY) (XYZ..XYZ),
not (X++Y..Y)
Also, it does not process $DATA_CLASS=NTUPPLE
METHOD:
Each line in the file is read. Blank lines and full line
comments are ignored are ignored.
In-line comments are stripped off
Lines beginning with ## are parsed
If the value is preceeded by (XY..XY) the values are
saved and formed into an array of the appropriate size
CHANGES:
03 May 2006 D. Gell Initial coding
(Routine contained in inms_read_jcamp.pro)
NAME:
inms_read_label - reads a PDS compliant label
pro inms_read_label, xLabel, $ ;; (o) structure containing label items
file=file, $ ;; (i) path to file with label
debug=debug ;; (i) controls additional debug diagnostics
PURPOSE:
read the PDS label within the file specified in the sPath argument
ARGUMENTS:
xLabel a structure containing the label fields. The first field
"FILE" contains the name of the file whose label was extracted.
Each item in label is stored in a field named
after the data item
eg: FILE_RECORDS = 2883
is stored in xLabel.file_records
All fields are strings
file if this keyword is present, the specified file is read
if absent or a directory, a file selection dialog is presented
CHANGES:
2-Sept-2004 DAG Initial coding
3-Nov-2004 DAG change file path from argument to keyword
7-Jan-2005 DAG Added code to handle comments
1-Mar-2005 DAG Added code to handle detached labels
17-Jun-2005 DAG Handle multiline values
Handle multiple arguments
20-Sept-2006 DAG Add error handler use
27-Sept-2006 DAG Ensure that missing/invalid labels are reported
(Routine contained in inms_read_label.pro)
NAME:
inms_reduce_qb_scan - reduce quad bias scan data
pro inms_reduce_qb_scan, axData, $
cyc_table=cyc_table, $
mass_tables=mass_tables, $
plot_only=plot_only, diagnostic=diagnostic
PURPOSE:
Reduce quad-bias scan data to determine the quad bias voltage at which the
signal level is reduced by a factor of 2 as a function of ion energy.
METHOD:
After selecting the data for each mass (kinetic energy), the data for each
quad bias scan is fit to a sigmoid (logistical) function.
S = A1 + (A0 - A1) / [1.0 + A2*exp{A3*(V-P4)/p5}]
using an amoeba search to minimumize the functional
V = total ( (anY - S(X, A))^2) / N
where anY are the measurements, X are the corresponding voltages, S is the
sigmoid evaluated at each X, A is the vector of parameters and N is the number
of measurements.
The quad bias voltage at half amplitude is found by numerically deterimining the
root of S - (A1+A0)/2 = 0
The value of the optimum quad-bias voltage (the target voltage) is evaluated by
subtracting 1.5 volts from the half-amplitude quad-bias voltage. A linear fit of the
target to the kinetic energy is performed, to parameterize the tracking curve.
Other diagnostic fits are performed.
CHANGES:
07-May-2007 D. A. Gell initial release coded
(Routine contained in inms_reduce_qb_scan.pro)
NAME:
inms_reduce_ql_scan - performs analysis of quad lens scan
Created by David A. Gell on 2007-01-16.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
pro inms_reduce_ql_scan, axData, $
anMass=anMass, $
anOpPt=anOpPt, $
anMTable=anMtable, $
use=use, $
debug=debug, $
_extra=extra
PURPOSE:
Performs the analysis of quadrupole switching lens scans collected
in flight to obtain the parameters needed to adjust ion sensitivity
for the actual switching lens tuning.
ARGUMENTS:
axData - a L1A data structure array containing the scan data
KEYWORD PARAMETERS:
anMass - supplies the masses for each scan in the data set
anOpPt - supplies the nominal QL3 voltage for each mass
anMTable- supplies the mass table ids used
use - set to a vector the same length as anMass. Zero entries
are excluded from analysis
the keyword parameter values default to those appropriate to
T23 if absent
The vectors supplied by these keywords must be of the same length
METHOD:
for each mass in the anMass argument
obtain the quadrupole lens data
fit data to Gaussian as a function of ql3 voltage
save the parameters in an array
plot the data and the resulting fit
add fwhm and operating point to plot
endfor
fit the voltage, shift, and width to line
plot peak signal voltage as function of KE
plot fit parameters as function of KE
plot fwhh
plot throughput
MODIFICATION HISTORY:
date by description
16-Jan-2006 D.A. Gell initial coding
07-May-2007 D.A. Gell corrected computation of FWHM, error in
indexing parameter array
(Routine contained in inms_reduce_ql_scan.pro)
NAME:
inms_remove_quotes - removes enclosing quotation marks
function inms_remove_quotes, sString
PURPOSE:
remove leading and trailing quotation marks from
pds compliant strings
RETURN VALUE:
string stripped of surrounding quotation marks
ARGUMENT:
sString - the string to be trimmed
CHANGES
26-Jul-2004 DAG initial coding
3-Dec-2004 DAG handle short strings
(Routine contained in inms_remove_quotes.pro)
NAME:
inms_saturn_latitude - computes the latitude w.r.t Saturn (Depreciated use inms_auxiliary_value)
function inms_saturn_latitude, axData ;;(i) level 1A data structure
PURPOSE:
calculate the planetocentric latitude of the spacecraft in the IAU_saturn
frame
RETURN VALUE:
A vector of latitudes in degrees
ARGUMENTS
axData level1A data structure
Changes
25-Aug-2004 DAG Initial coding
(Routine contained in inms_saturn_latitude.pro)
NAME:
inms_saturn_wlongitude - computes the west longitude w.r.t. Saturn (Depreciated use inms_auxiliary_value)
function inms_saturn_wlongitude, axData ;;(i) level 1A data structure
PURPOSE:
calculate the west longitude of the spacecraft in the IAU_saturn
frame
RETURN VALUE:
A vector of west longitudes in degrees
ARGUMENTS
axData level1A data structure
Changes
25-Aug-2004 DAG Initial coding
(Routine contained in inms_saturn_wlongitude.pro)
NAME:
inms_select_cal - selects a calibration record from the calibrtion structure
function inms_select_cal, axCal, $ ;; an array of calibration records
species=species, $ ;; the species
unit=unit, $ ;; unit (FM, EM, REU, or NT)
source=source, $ ;; source (CS OS)
energy=energy, $ ;; electron energy
filament=filament, $ ;; and filament (PRI, SEC) of interest
multiple=multiple, $ ;; set to return multiple matches
silent=silent ;; set to inhibit messages
ARGUMENTS:
axCal - the calibration structure to be examined for a match
KEYWORDS:
species - specifies the formula of the species of interest
unit - specifies the instrument unit
FM (flight), EM(engineering), REU(Refurbished EM), NT(nist), *(any)
source - specifies the ion source, CS(closed), OS (open)
energy - specifies the electron energy, defaults to 70
filament - specifies the filament of interest, defaults to PRImary
/multiple - set to return multiple matches when a specific unit is selected
/silent - set to operate silently
CHANGES:
15 July 2005 D. Gell Initial Coding
06-Feb-2006 D. Gell set error handling option to 2, return to caller
did not properly initialize xSelected
25-Aug-2006 D. Gell add Refurbed EM to list
add /MULTIPLE keyword
01-Sep-2006 D. Gell validate species keyword and axCal argument before use
04-Oct-2006 D. Gell validate unit, source and filament keyword values
(Routine contained in inms_select_cal.pro)
NAME: inms_set_charsize - returns scaled character size function inms_set_charsize, nSize RETURN VALUE: scaled character size ARGUMENT: nSize nominal character size PURPOSE use to supply scaled character size to IDL routines such as XYOUTS that do not apply the !p.charsize scaling METHOD: if !p.charsize not set, return the argument unchanged otherwise multiply the argument by !p.charsize and return CHANGE HISTORY 26 May 2005 D. Gell Initial Coding
(Routine contained in inms_set_charsize.pro)
NAME:
inms_spectra_aux_values - determines values of ancilliary data
pro inms_spectra_aux_values, axSpectra, $ ;; (i/o) spectra array
axSeries, $ ;; (i) l1A data series
anTimeValues ;; (i) times for interpolation
ARGUMENTS:
axSpectra - the spectra array to be filled with aux values
axSeries - the data series from which the spectra were formed
anTimeValues - an array of times corresponding to eh spectra
CHANGES:
18-NOV-2005 D. A. Gell Add program prolog and ensure that
no math exceptions are reported
04-Dec-2006 D. A. Gell Add velocity components to structure, replaced
interpolation cals with equivalent interpol call (simplification)
11-Dec-2006 D. A. Gell Compute Saturn relative positions for non-targeted periods
05-Jan-2007 D. A. Gell Use correct velocity components, velocity w.r.t target in
spacecraft frame (ex target frame)
08-Jan-2007 D. A. Gell Correct computation of ram angle, velocity components
are w.r.t. spacecraft when targeted
and w.r.t. saturn when not.
10-Jan-2007 D. A. Gell Ram angle w.r.t. saturn was overwritten with bad value
(Routine contained in inms_spectra_aux_values.pro)
NAME:
inms_spectra_calculations - performs arithmetic with spectra
function inms_spectra_calculations, axSpectra, $ ;; (i) an array of 1 or more spectra
xOperand, $ ;; (i) the spectra (or number) to modify with
add=add, $ ;; (i) add xOperand or number to axSpectra
subtract=subtract, $ ;; (i) subtract
multiply=multiply, $ ;; (i) multiply
divide=divide, $ ;; (i) divide
Sigma0_M=Sigma0_M, $ ;; (i) uses a variance of zero for the minuend structure(s)
Sigma0_S=Sigma0_S ;; (i) uses a variance of zero for the operand
PURPOSE:
subtracts one spectra from an array of one or more spectra
to remove the background
RETURN VALUE;
an array of spectra the same size as the axSpectra containing
the result of subtracting xBackground from each record in axSpectra
ARGUMENTS:
axSpectra the array of minuend spectra
xOperand the subtrahend spectra
add, subtract, multiply, divide operation to perform
CHANGES
16 Sep 2004 NAB begat coding
27 Sep 2004 NAB changed from l1a data structure to spectra structure
(see inms_get_spectra for struct. def.)
28 Sep 2004 NAB added error calculations. added Sigma0_* keywords.
10 Oct 2004 NAB replaced 0 with O and O with 0 in confused variable
definitions
3-Jan-2005 DAG enhanced check of spectra structure validity, no longer
relies on length (subject to change). Instead uses field
names.
(Routine contained in inms_spectra_calculations.pro)
NAME:
inms_ss_position - computes the position of the subsolar point (depreciated)
function inms_ss_position, sTime, $ ;; time in string format
sTarget ;; name of target body
PURPOSE:
Compute the planeto-centric position of the sub-solar point on TITAN
Depreciated, values computed are now included in L1A files
RETURNS:
an anonymous structure defined as follows:
xRet={anState: fltarr(3), $ ;; cartesian position of subsolar point
nLat: 0.0, $ ;; latitude of subsolar point
nLon: 0.0 } ;; west longitude of subsolar point
CHANGES
23-June-2004 DA Gell Completed file prolog
4 Dec 2004 DA Gell Depreciated
(Routine contained in inms_ss_position.pro)
NAME:
inms_subtract_background - performs background removal
function inms_subtract_background, $
axSpectra, $ ;; (i) an array of 1 or more spectra
xBackground, $ ;; (i) the background to be subtracted
debug=debug
PURPOSE:
subtracts one spectra from an array of one or more spectra
to remove the background
RETURN VALUE;
an array of spectra the same size as the axSpectra containing
the result of subtracting xBackground from each record in axSpectra
ARGUMENTS:
axSpectra the array of minuend spectra
axBackground the subtrahend spectra
KEYWORDS:
/debug if set, diagnostic information is produced
CHANGES
4 Aug 2004 DAG Initial coding
3 Jan 2005 DAG Added computation of std deviation
7 Jan 2005 DAG Added basic error detection
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_subtract_background.pro)
NAME:
inms_svd_solve - Solves aX=b using Singular Value Decomposition
pro inms_svd_solve, anX, $ ;;(o) solution vector
anMatrix, $ ;;(i) kernel matrix
anB, $ ;;(i) measurements
anMeasureErrors, $ ;;(i) measurement errors
status=status, $ ;;(o) error status
sigma=sigma, $ ;;(o) 1-sigma solution uncertainty
chisqr=chisqr, $ ;;(o) chi square goodness of fit
svalues=svalues, $ ;;(o) edited singular values
silent=silent, $ ;;(i) set to inhibit message
debug=debug
PURPOSE:
Solves the matrix equation, aX=b in a least squares sense,
using singular value decomposition. If measurement errors are supplied,
the weighted least square solution is obtained
ARGUMENTS:
anX; The N element solution vector example: fltarr(N)
anMatrix: The M row by N column matrix example: fltarr(M,N)
anB: The M element (measurement) vector example: fltarr(M)
anMeasureErrors: an M element vector of measurement errors
If absent, the unweighted solution is determined
Specify as sqrt(anB) for Poisson distribution of errors
Specify as standard deviation of anB for Gaussian error
distribution
KEYWORDS:
status: status value: 0, no error;
-1, incompatable dimensions
-2, insufficient arguments supplied
-3, non-writable keyword supplied
for status, sigma, or svalues
>0, number of singular values
sigma: Supplies the name of a variable to contain the
1-sigma uncertainties is anX
svalues: Supplies the name of a variable to contain the edited
singular values. Small values deleted from the solution will
be replaced by zero
METHOD:
The matrix A can be decomposed into three vectors,
b=Ax becomes b=UWtranspose(V)x by applying the singular value
decomposition to A. The matrix U is an MxM colomn-orthogonal matrix,
W is a NxN diagonal matrix and V is an NxN orthogonal matrix.
The orthogonality condition provide that
transpose(U)U = tranpose(V)V = I
Using the conditions result in
x=V inverse(W) tranpose(U)b
Since W is diagonal its inverse is the diagonal matrix whose
elements are 1/W[i,i]
The standard deviation is (v inverse(W))
For more details see
Press, W.H, et.al., Numerical Recipies,Cambridge University Press,
1986
CHANGE HISTORY
21-Feb-2004 DA Gell Initial coding, extracted from inms_deconvolve.pro
added argument validation
(Routine contained in inms_svd_solve.pro)
NAME:
inms_tabulate_spectra - Writes the contents of the spectra record
Created by David A. Gell on 2007-01-02.
Copyright (c) 2007 __Southwest Research Institute__. All rights reserved.
pro inms_tabulate_spectra, xSpectra, anMasses, file=file, title=title, debug=debug
PURPOSE:
Display contents of a spectra structure in text form.
ARGUMENTS:
xSpectra - The spectra to display
anMasses - A list of masses whose signal levels are to be listed
if absent, only the ancilliary data will be displayed
KEYWORD PARAMETERS:
/debug - if present, diagnostics displayed on console with
traceback
RESTRICTIONS:
none
METHOD:
extracts fields from structure and prints
MODIFICATION HISTORY:
date by description
02-Jan-2006 DA Gell Initial coding
(Routine contained in inms_tabulate_spectra.pro)
NAME:
inms_test - executes a sequence of routines to verify installation
USAGE:
.run inms_test
REQUIREMENTS:
requires the data file for 2004-300T15:00:00, the TA closest approach
EVALUATION:
Compare the plots produced with the plots in the file INMS_TEST_RESULTS.PS
CHANGES:
25-MAR-2005 D. A. Gell Initial coding
25-May-2005 D. A. Gell Added code to avoid re-reading L1A file when
executed repeatedly
24-Jun-2005 D. A. Gell Added tests of housekeeping data access
12-Sep-2005 D. A. Gell Added code to exercise inms_make_profiles and
the associated plotting routine
30-Sep-2006 D. A. Gell Added code to exercise inms_plot_state
17-Nov-2006 D. A. Gell Changed example data to that of 2006-282 (T18)
so that example ION data plots can be made
4-Dec-2006 D.A. Gell Anounces version
5-Jan-2007 D.A. Gell Update version number
17-Jan-2007 D.A. Gell Update version number to 2007018
Add display of ion spectra w/ram angle
Change order of plots to match user guide
(Routine contained in inms_test.pro)
NAME:
inms_utc2date - converts a UTC time to a calendar date string
function inms_utc2date, axUTCtime
PURPOSE:
Converts a UTC time structure to a time string
ARGUMENTS:
axUTCtime a structure or array of structures containing the utc time
{nDate: yyyyddd, nMSecs: sssss.sss}
RETURN VALUE
an array of strings containg the converted times in the form
yyyy-doyThh:mm:ss.fff
CHANGES:
28-FEB-2005 D.A. Gell Initial coding, adapted from tidi code
(Routine contained in inms_utc2date.pro)
NAME:
inms_utc_increment - increments a UTC time by a specified amount
function inms_utc_increment, axUTCtime, nIncrement
PURPOSE:
Adds an increment, in seconds to a UTC time structure
utc time structure is defined as {nDate: 0L, nMsec:0L}
where nDate is the ordinal date 1000 * year + day of year
and nMsec is the time of day in milliseconds. Day and Year
boundaries are handled.
ARGUMENTS:
axUTCtime - an array of time structures
nIncrement - a time increment in seconds
the increment may be positive to increase UTC time
or negative to decrease it.
RETURN Value
an array of the same shape as axUTC with the updated times
CHANGES:
28-Feb-2005 DAG Initial Coding
20-Sep-2006 DAG Use error handler and inms_post_message
(Routine contained in inms_utc_increment.pro)
NAME:
inms_validate_cal_data - confirms a structure is a calibration data structure
function inms_validate_cal_data, axData
PURPOSE:
Tests a structure to see if it appears to be a
valid calibration data structure
METHOD:
Tests that the argument is a structure
If it is, then checks to see if it has
appropriately named fields
RETURNS:
1 if structure appears valid
0 if it is not
CHANGES:
27-JAN-2004 DA GELL Initial coding
(Routine contained in inms_validate_cal_data.pro)
NAME:
inms_validate_hkg_data - confirms validity of housekeeping data structures
function inms_validate_hkg_data, axData
PURPOSE:
Tests a structure to see if it appears to be a
valid l1a data structure
METHOD:
Tests that the argument is a structure
If it is, then checks to see if it has
appropriately named fields
RETURNS:
1 if structure appears valid
0 if it is not
CHANGES:
02-Jun-2004 DA GELL Initial coding, adapted from inms_validate_l1a_data
(Routine contained in inms_validate_hkg_data.pro)
NAME:
inms_validate_l1a_data - confirms a structure is a valid Level 1A data structure
function inms_validate_l1a_data, axData
PURPOSE:
Tests a structure to see if it appears to be a
valid l1a data structure
METHOD:
Tests that the argument is a structure
If it is, then checks to see if it has
appropriately named fields
RETURNS:
1 if structure appears valid
0 if it is not
CHANGES:
27-JAN-2004 DA GELL Initial coding
(Routine contained in inms_validate_l1a_data.pro)
NAME:
inms_validate_spectra_data - confirms a structure is a spectra data structure
function inms_validate_spectra_data, axData
PURPOSE:
Tests a structure to see if it appears to be a
valid spectra data structure
METHOD:
Tests that the argument is a structure
If it is, then checks to see if it has
appropriately named fields
RETURNS:
1 if structure appears valid
0 if it is not
CHANGES:
08-Feb-2005 DA GELL Initial coding
(Routine contained in inms_validate_spectra_data.pro)
NAME:
inms_validate_time - confirms that a string is a properly formated date/time
function inms_validate_time, sTime
PURPOSE:
ensure that sTime argument is a valid time in the form yyyy-doyT00:00:00
RETURN VALUE:
1, time is valid
0, time is invalid
METHOD:
Parses input calendar time string. Confirms that all required delimiters
are present, then verifies that each field contains valid values.
if the input argument is an array, all elements must be valid times
CHANGES
28-Jul-2004 DAG Initial Coding
09-Feb-2005 DAG Added test for optional millisecond field
14-Feb-2005 DAG Corrected logic to ignore millisecond test when
decimal point absent
14-Jun-2005 DAG Changed loop counter to Long
(Routine contained in inms_validate_time.pro)
NAME:
inms_weighted_mean - computes the estimate of the mean & std deviation
Created by David A. Gell on 2006-10-31.
Copyright (c) 2006 __Southwest Research Institute__. All rights reserved.
function inms_weighted_mean, anMean, anSigma
PURPOSE:
Uses the propogation of error to estimate the population
mean from a set of means and standard deviations
RETURNS;
A two element vector, the first element of which is the
mean and the second is the standard deviation
ARGUMENTS:
anMean - an vector of values to be averaged togather
anSigma - an vector of corresponding standard deviations
KEYWORD PARAMETERS:
RESTRICTIONS:
The length of the arguments must be the same
METHOD:
Bevington & Robinson, "Data Reduction and Error Analysis",
third edition, pp 56,57
EXAMPLE:
MODIFICATION HISTORY:
date by description
31-Oct-2006 D.A. Gell Initial Coding
(Routine contained in inms_weighted_mean.pro)
NAME:
inms_write_image - transfers an image from an pixel map and saves to a file
pro inms_write_image, sFilePath, type=type, _extra=extra
PURPOSE:
capture a x pixel map or window and save to file
ARGUMENTS:
sFilePath - path, excluding extension of the output file
KEYWORDS:
type - the type of output file to create
choices are PNG, TIFF, JPEG, default: PNG
RESTRICTIONS:
The x device must have had the backing store defined with
device,retain=2 if capturing a window. Not required if
capturing an Xwindow pixel map.
USEAGE:
set_plot,'x'
device,retain=2
; plotting commands here
inms_write_image,sFilePath, type='PNG'
CHANGE HISTORY
11 Sept 2002 DAG Initial coding
based on printwindow example from IDL
contributed code repository
12 Sept 2002 DAG test for pixel map prior to reading display
change output device to ps from printer
22 Jul 2003 DAG save and restore color table - PS should have
ramp color tables so pixel values will be
passed unchanged.
01-mar-2005 DAG adapted from ps_window for use in inms analysis
library by omitting postscript creation and adding
image writing routines
20-Sep-2006 DAG Use error handler and inms_post_message
27-Oct-2006 DAG Ensure that TIFF image is organized properly without
requiring that the orientation property be set, some
TIFF display programs ignore that keyword
(Routine contained in inms_write_image.pro)
NAME:
l_getdim - transforms the results of where() to dimensions
PURPOSE:
translates a one-dimensional index (like given by where() function)
into a multidimensional one (i.e. the array indices according to
the multidimensional array)
PARAMETERS:
a the array
ix the one dimensional index (or array of indices)
if ix is omitted, the dimensions of a are returned
KEYWORDS:
MINDIM if set, only the number of dimensions of a is returned,
else 8 dimensions (what is better in some degenerated
cases, i.e the calling program can rely on that there is
always a second(third...) dimension given)
returns a 8 by n_elements(ix) array
example:
IDL> a=intarr(23,24,27,33)
IDL> a[13,19,2,11]=1
IDL> ix=where(a)
IDL> print,l_getdim(a,ix)
13 19 2 11 0 0 0 0
IDL> print,l_getdim(a)
23 24 27 33 1 1 1 1
MODIFICATION HISTORY:
Marc Schellens 01.2002
(Routine contained in l_getdim.pro)
NAME:
sprl_color_triad - returns the a 3 element byte array corresponding to the named color
function sprl_color_triad, sName
PURPOSE:
Returns the color triad [nRed,nGreen,nBlue] for the named color
If the color name is invalid, the tria for black [0,0,0] is returned
USEAGE:
anColorTriad=sprl_color_triad(name)
ARGUMENTS
name = a string containing the namee of the color for which
the index is desired. If not argument is specified a
list of color names is produced.
RETURN VALUE:
a 3 element byte vector containing the red, green and blue values
for the named color. If no argument is supplied, [0,0,0] is returned
CHANGES:
23-Mar-2005 DAG initial coding based on sprl_find_color
(Routine contained in sprl_color_triad.pro)
NAME:
sprl_colorplot - plots a function of two variables in color
pro sprl_colorplot, anZ, $ ; 2 dimensional array to plot
anXin, anYin, $ ; x, y axis values, optional
zrange=zrange, $ ; range of data
ztitle=ztitle, $ ; title for color scale
region=region, $ ; position of plot window, normal coords
margins=margins, $ ; 4 element vector [lf, lw, rt, up]
;;; of margins
gutter=gutter, $ ; specify space between plot and scale
barwidth=barwidth, $ ; specifies the width of the color scale,
;;; default 0.075
logsw=logsw, $ ; set if log plot desired
xwrap=xwrap, $ ; when smoothing assume periodic in x
ywrap=ywrap, $ ; when smoothing assume periodic in y
missing=missing, $ ; value of anZ used to indicate missing value
noerase=noerase, $ ; set if screen is not to be erased
smooth=smooth, $ ; set if smoothed plot desired
contour=contour, $ ; set if countours are to be overplotted
_ref_extra=extra ; keywords to be passed to plot and contour
ARGUMENTS:
anZ - input 2 dimensional array, Z(xi,yi)
anXin - x coordinate of inputs, if omitted it is the x coordinate is the x index
to specify just the range, supply a two element vector [xmin,xmax]
anYin - y coordinate of inputs, if omitted it is the y coordinate is the y index
to specify just the range, supply a two element vector [ymin,ymax]
zrange- a two element vector containing the range of the independant variable
when contouring, values outside of the specified range are ignored
values < zrange[0] are plotted with the minimum color and
values > zrange[1] are plotted with the maximum color
ztitle- the title to apply to the color scale
logsw - set if log of anZ is to be plotted
xwrap - set to extend the x dimension to make it periodic
ywrap - set to extend the y direction to make it period
noerase-set to prevent erasing the window before plotting
smooth - a two element vector set if anZ is to be smoothed,
smooth[0] is number of elements in x direction and
smooth[1] is number of elements in y direction used
for the boxcar smoothing. A value of zero disables
smoothing in that direction.
ex. to smooth in x but not y use smooth=[10,0]
contour- set if contours of anZ are to be overplotted
best contour results obtained when the smooth keyword is also set
missing- value of z used to indicate a missing value
must be outside of zrange
any plot procedure keywords, xtitle, ytitle, ...
any contour procedure keywords, xtitle, ytitle, c_annotate,c_levels,...
region, margins,gutter,barwidth
The plot position is specified by the region keyword, in the same form as the
!p.region system variable.
It specifies the entire plot regions, encompassing the color plot, the scale, and
the titles. The keyword margin specifes the margins between the left side of the
color plot and the plot region, the lower margin, the upper margin, and the margin on
the right between the color bar and the right edge of the plot regions. The
keyword gutter specifies the spacing between the color plot and the color bar.
Margin and gutter are specified as fractions of the plot region given by region.
example, setting region=[0.,0.,1.,1.]
margin=[0.05, 0.05, 0.05, 0.05]
gutter=0.05
results in the plot region filling the entire window
and margins of 5% of the window between the edges of the
graphics and the edges of the window, with 5% of the window between
the plot and the color scale.
default values: region = [0.125, 0.1125, 0.85, 0.95]
margin = [0.075, 0.075, 0.075, 0.075]
gutter = 0.025
barwidth=0.075
ROUTINES USED:
sprl_draw_scale
l_getdim
NOTES:
After the plot is produced, one may use OPLOT, PLOTS, and XYOUTS, with data coordinates
to add additional annotations.
CHANGES:
17 June 2004 DAG Initial coding, intended to be a 24 bit friendly version
of color_plot
08 July 2004 DAG changed keyword inheritance to by reference, permitting use
of [xyz]tick_get
keywords
09 July 2004 DAG made degree of smoothing adjustable
14 July 2004 DAG replaced ad-hoc and inefficent smoothing with IDL SMOOTH routine,
which performs boxcar smoothing. Changed syntax of smooth keyword to
provide for independent smoothing in x and y
24 Nov 2004 DAG Change the color scaling to use only indicies 1 through 253
so that color zero (normally black), color 255 (normally white)
and color 254 (reserved) are not used in the scaled color image
(Routine contained in sprl_colorplot.pro)
NAME:
sprl_create_list - forms a list of unique elements in an array
function sprl_create_list, tables
PURPOSE:
form a list of the unique values
found in the tables argument
replaces the inefficient IDL
result=uniq(tables[sort(tables)])
USEAGE:
result=sprl_create_list(tables)
ARGUMENTS:
tables - an array to be examined
returns:
an vector containing each unique value found
in the argument tables
changes:
20-jan-2003 DAG initial coding
8-Jul-2004 DAG modified to handle non-numeric types
29-Nov-2004 DAG changed name to sprl_create_list
(Routine contained in sprl_create_list.pro)
NAME:
sprl_cvt_jdate_mdy - converts the specified Julian date to the month, day and year
function sprl_cvt_jdate_mdy, anJdate, $ ;; array of julian dates
mjd=mjd ;; set if modified julian dates supplied
METHOD:
Seidelmann, P.K, ed, Explanatory Supplement to the Astronomical Almanac
RESTRICTION:
argument anJdate should be either a long or a double.
CHANGES:
2-Jun-2005 D. Gell Initial coding
(Routine contained in sprl_cvt_jdate_mdy.pro)
NAME:
sprl_cvt_jdate_odate - converts a Julian day number to an ordinal date
function sprl_cvt_jdate_odate, nJDate, mjd=mjd
PURPOSE:
Computes the ordinal date at midnight UTC
on the specified Julian Date
The inverse of sprl_cvt_odate_jdate
RETURN VALUE:
The date corresponding to midnight UTC on
Julian day number nJD, in the form YYYYDDD, that is
year*1000 + day-of-year. The return value has the
same shape as the input
ARGUMENTS:
nJDate Julian date (or dates)
/MJD Set if input is a modified Julian date
METHOD
The number of days since the refernce epoch
JD 1721118.5 is computed. The centuries since
the epoch is determined by noting a Julian century
is exactly 36525 days long.
The year within the Century is computed is computed
by dividing the remainder by 365
Since the epoch is day 60 (March 1) of year 0
The day of year calculated as the difference between
the Julian date and the start of the year, as calculated
above may be greater that 365. The year and day-of-year
are adjusted. Finally, if the prior year is a leap year
adjust the day of year by 1.
RESTRICTION:
Valid for Julian days greater than 1721118.5 (1 March 0000)
CHANGES
10-Feb-2005 DAG Initial Coding
22-Mar-2005 DAG Correct algorithm to fix an off by one error
04-Apr-2005 DAG handle centenial year leap years
13-Jul-2005 DAG Correct logic for centenial year, subtract one
day from length if (year mod 400) equals 0
02-Sep-2005 DAG Corrected off-by-one error in computation of NDOY
(Routine contained in sprl_cvt_jdate_odate.pro)
NAME:
sprl_cvt_jtime_tod - converts the fractional part of a Julian date to time
function sprl_cvt_jtime_tod, nJD, seconds=seconds
ARGUMENTS:
nJD the Julian Date or Dates to convert.
KEYWORDS:
/seconds when present returns a vector of seconds
when absent returns an array with hours,
minutes and seconds
RETURNS
A vector of seconds or an array of hours minutes and seconds
with [*,0] containing the hours
[*,1] containing the minutes
[*,2] containing the seconds
CHANGES:
7-Jun-2005 D. Gell Initial Coding
(Routine contained in sprl_cvt_jtime_tod.pro)
NAME:
sprl_cvt_odate_jdate - converts an ordinal date/time to a Julian date
function sprl_cvt_odate_jdate, nOrdDate, $ ;; Dates
nTimeMS, $ ;; Time of day
mjd=mjd ;; set for modified Julian day
PURPOSE:
Computes the Julian Date
given an ordinal day in the Gregorian Calendar
The inverse of sprl_cvt_jdate_odate
RETURNS:
Julian Date, JD for the specified
Gregorian Dates. If the input is an array
the output is an array of the same shape
ARGUMENTS:
nOrdDate a date or array of dates in the
YYYYDDD format, where YYYY is the year
and DDD is the day of year (ordinal date)
NTimeMS time of day in milliseconds, if an array it
must be the same shape as nOrdDate.
/MJD if set the modified Julian day is returned
METHOD:
Compute the number of years since 0000-060 (march 1, 1BCE)
compute length of that number of years in days by formula
365*nyears + nYears/4L - nYears/100L + nYears/400L
Add the Julian Day Number corresponding to March 1, 1BCE
Add the number of days in the current year since 1 March
If the MJD flag is set, the offset 2400000.5 is subtracted
from the result.
This method effectively makes the start of the year 1 March
and the leap-year day if present is the last day of the year
Algorithm Reference: http://vsg.cape.com/~pbaum/date0.htm
Peter Baum
Aesir Research
P.O. Box 1255
3 Prospect Avenue
Onset, MA 02558-1255
CHANGES:
10-Feb-2004 DAG Initial Coding
02-Aug-2004 DAG Correct of-by-one error during leap years
following day 58.
(Routine contained in sprl_cvt_odate_jdate.pro)
NAME:
sprl_date_plotted - annotates a plot with the current date
pro sprl_date_plotted, left=left
PURPOSE: prints current date at exteme lower corner of plot
ARGUMENTS: none
KEYWORDS:
/left when present display is at extreme left corner
when absent display is at extreme right corner
AUTHOR: D.A. Gell
METHOD: parses current date from string in !stime variable
and prints
CHANGE HISTORY:
date by description
16-May-1994 DAG added header for use in library
3-Aug-2004 DAG get file name from fstat rather
than depending on a common block
27-Jan-2005 DAG renamed sprl_date_plotted
20-Mar-2006 DAG added /left keyword
(Routine contained in sprl_date_plotted.pro)
NAME:
sprl_discrete_color_list.pro - Definitions of discrete colors
PURPOSE:
specifies names and formulae for 88 discrete colors
USEAGE;
intended to be used as an include file in other programs
@sprl_discrete_color_list.pro
CHANGES:
30-NOV-2004 DAG Initial coding - extracted from sprl_find_colors
30-Nov-2004 DAG Reordered colors so that they may be loaded as a
color table, index 0 is black, index(max) is white
(Routine contained in sprl_discrete_color_list.pro)
NAME:
sprl_draw_flag - draws a flag at a specified location
pro sprl_draw_flag, nX, $ ;; x location of flag
nY, $ ;; y location of flag
sKey, $ ;; character key written in flag
SIZE=SIZE, $ ;; size of flag
DATA=DATA, $ ;; set if nx and ny are data coordinates
;;; otherwise they are in normal coordinates
_REF_EXTRA=EXTRA
PURPOSE:
draws a flag at the specified position.
The flag is shaped like a P, and may optionally
have a single character key in the circular part.
The location of the flag is in normal coordinates
unless the DATA keyword is set.
The size of the flag is 1/50 of the width of the display
times the value supplied by the SIZE keyword. If the
SIZE keyword is absent, the multiplier is one
The COLOR keyword may be used to set the color of
the flag and character. The CHARSIZE and CHARTHICK
keywords may be used to override the default character
specifications
changes:
26-Sep-2004 DAG Initial coding
29-Nov-2004 DAG renamaed from draw_flag.pro to sprl_draw_flag.pro
(Routine contained in sprl_draw_flag.pro)
NAME:
sprl_draw_scale - draws a color bar scale at the specified location
pro sprl_draw_scale, position=position, $ ;; vector specifing position
zrange=zrange, $ ;; vector specifing data range
ztitle=ztitle, $ ;; axis label for scale
horizontal=horizontal, $ ;; set if horizontal scale desired
zlog=zlog, $ ;; set if logscale desired
inside=inside, $ ;; controls annotation position
_extra=extra
KEYWORDS:
position - supplies the position and size of the bar in normalized coordinates
as a 4 element vector in the format of the position keyword to PLOT
zrange - a 2 element vector specifying the data range [min,max]
ztitle - the title for the axis
/zlog - set for logrithmic scale
/horizontal- set to make the scale horizontal
/inside - set if annotation is to be left (below) the
vertical (horizontal) color bar
note: the inside keyword is based on having the color bar to the right or above the
plot window
change history:
15 Jun 2004 DAG Initial coding
29 Nov 2004 DAG Changed name from draw_color_scale to sprl_draw_scale
14 Nov 2006 DAG Changed tick marks to cross the axis bar
(Routine contained in sprl_draw_scale.pro)
NAME:
sprl_error_plot - Plots data points with x & y error bars
pro sprl_error_plot, anX, anY, $
anError1, anError2, $
xerrorbar=xerrorbar, $ ;;set if drawing x bars
yerrorbar=yerrorbar, $ ;;set if drawing y bars
showclipped=showclipped, $ ;; set to show clipped values at limit
psym=psym, $
debug=debug, $
_extra=extra
ARGUMENTS:
anX An array of abscissae
anY An Array of ordinates
anXerror An array of abscissae errors
anYerror An array of ordinate errors
CHANGES:
9 March 2005 D. Gell Initial coding, based on the method in errplot.pro
routine distributed with IDL
18 March 2005 D. Gell Corrected test for size of yerror array when
/yerrorbar is set
5 May 2005 D. Gell ensure that log calculations have valid arguments
add out-of-limit control. Correctly display
both x and y error bars.
23 Jun 2005 D. Gell Moved computation of limitting values for
error bars outside of loop to correct floating
exceptions
30 Aug 2005 D. Gell Extensive modifications to simplify code and
insure that tick marks at end of error bars
are constant size in logrithmic plots
(Routine contained in sprl_error_plot.pro)
NAME:
sprl_find_color - returns the numerical value corresponding to the named color
function sprl_find_color, sName, $ ;; name of color
index=index, $ ;; set to return index of psuedo color
swatch=swatch ;; set to view swatches
PURPOSE:
searches color table for index of color that most closely matches
one of the specified names. If using decomposed color, then
it returns the 24 bit color value. If the color name is invalid,
the index 0 (usually black) is returned
USEAGE:
nColIdx=find_color_index(name)
ARGUMENTS
name = a string containing the namee of the color for which
the index is desired. If not argument is specified a
list of color names is produced.
swatch Set this keyword to view a swatch of colors
index If set and if the current device is a pseudo color device
the index of the color table entry closest to the color
is returned.
If the index keyword is absent, then the specified
color is loaded to index 254 of the color table and
that value is returned
Keyword is ignored for true-color devices
RETURN VALUE:
the 8 or 24 bit index of the color nearest the named color
if a swatch or list of names is produced, the function returns
-1
NOTE:
Depending on the color table in use, the index returned for psuedo-color
devices (PS) may not accurately produce the desired color. This is because
the only colors that can be displayed are the 256 colors defined by the color
tables. For example, if a grey scale color table is loaded, the only available
colors are different intensities of grey and the index returned by this routine
will be one of the greys.
CHANGES:
22-June-2004 DAG inital coding based on define_colors.pro
23-Nov-2004 DAG added more colors taken from an IDL user library routine
added swatch output
30-Nov-2004 DAG made an include file out of the color list
added /index keyword
(Routine contained in sprl_find_color.pro)
NAME:
sprl_is_decomposed - indicates if a true color display is in use
function sprl_is_decomposed
PURPOSE:
Determines if the display is True Color
USAGE
if sprl_is_decomposed() then begin
;; code for true color display
endif else begin
;; code for non true color displays
endelse
RETURN VALUE:
1 if true color (decomposed display)
0 otherwise
(Routine contained in sprl_is_decomposed.pro)
NAME:
sprl_isnumeric - Tests if a string represents a valid number
function sprl_isnumeric, string
PURPOSE:
tests a string to determine if it is a number
RETURN value:
1 if all characters are numeric with an optional leading
sign (+-) and one optional decimal point
0 otherwise
changes:
29-Nov-2004 DAG changed name to sprl_isnumeric
(Routine contained in sprl_isnumeric.pro)
NAME:
sprl_load_blue_sequential - loads the blue sequential color table
pro sprl_load_blue_sequential
PURPOSE: loads the red sequential color table
METHOD:
The 10 step blue sequential color definition from the
http://geography.uoregon.edu/datagraphics/color_scales.htm
is converted to a 256 step color table by interpolation
resulting in a smooth color scale;
The resulting values for red, green and blue color tables are loaded.
entry zero is black, entry 255 is white
CHANGES:
19-Nov-2004 DAG Initial coding
(Routine contained in sprl_load_colors.pro)
NAME: sprl_load_catagorical_colors - loads the discrete colors defined in SPRL_DISCRETE_COLOR_LIST.PRO pro sprl_load_categorical_colors PURPOSE: loads the categorical color table CHANGES: 19-Nov-2004 DAG Initial coding
(Routine contained in sprl_load_colors.pro)
NAME:
sprl_load_colors - interface to set of color table loading routines
pro sprl_load_colors, sequential=sequential, $
divergent=divergent, $
categorical=categorical
PURPOSE:
Supplies a user interface to routines that load color tables.
The keywords specify type:
sequential - a smooth variation from light blue to dark blue (default)
sequential=BLUE - a smooth variation from light blue to dark blue
sequential=RED - a smooth variation from black to red
sequential=SPECTRUM - colors of the spectrum from red to violet
divergent - a smooth variation from blue to white to dark red
categorical - 12 discrete color steps choosen to be legible even for
those with red-green color blindness
USAGE:
sprl_load_colors, /type
/type = /[seqential | divergent | categorical ]
REFERENCE:
general -
http://geography.uoregon.edu/datagraphics
color table definitions by C. A. Brewer
http://www.personal.psu.edu/~cab38
changes:
16 Nov 2004, DAG inital coding
(Routine contained in sprl_load_colors.pro)
NAME:
sprl_load_divergent_colors - loads a divergent color table (blue)
pro sprl_load_divergent_colors
PURPOSE: loads the red-blue divergent color table
METHOD:
The 18 step blue to dark red color definition from the
http://geography.uoregon.edu/datagraphics/color_scales.htm
is converted to a 256 step color table by interpolation
resulting in a smooth color scale
CHANGES:
19-Nov-2004 DAG Initial coding
(Routine contained in sprl_load_colors.pro)
NAME:
sprl_load_red_sequential - loads the red sequential color table
pro sprl_load_red_sequential
PURPOSE: loads the red sequential color table
METHOD:
values for red, green and blue color tables are computed
as follows: Red is bi-linear with a break at the table midpoint
Green is zero for the lower half of the table,
then linear thereafter
Blue has the same shape as green but leads by 10 steps
entry zero is black, entry 255 is white
CHANGES:
19-Nov-2004 DAG Initial coding
24-Nov-2004 DAG Replaced the blue sequential with the red sequential
color table
(Routine contained in sprl_load_colors.pro)
NAME:
sprl_load_spectrum_sequential - loads the spectrum sequential color table
pro sprl_load_spectrum_sequential
PURPOSE: loads the spectrum sequential color table
METHOD:
The spectra table obtained from the IDL distribution (table named
(rainbow + white") is loaded into the color table using tvlct.
indicies 0 and 255 are black and white respectively.
CHANGES:
19-Nov-2004 DAG Initial coding
27-Jul-2005 DAG Replaced "lumpy" table with smoother one from IDL distribution
(Routine contained in sprl_load_colors.pro)
NAME:
sprl_plot_sym - generated user defined plot symbols
PRO SPRL_PLOT_SYM, SIZE=SIZE, $
FILL=FILL, $
NOFILL=NOFILL, $
CIRCLE=CIRCLE, $
THICK=THICK, $
SQUARE=SQUARE, $
DIAMOND=DIAMOND, $
TRIANGLE=TRIANGLE, $
TRIDOWN=TRIDOWN, $
PENTAGON=PENTAGON
This routine generates a user defined plot symbol which is used by the PLOT
command by setting PSYM = 8. The default symbol is a filled circle.
SIZE - Size of plot symbols (default 1.0).
SQUARE - Set this keyword if you want square plot symbols (default circles)
DIAMOND - Set this keyword if you want square plot symbols
TRIANGLE - Set this keyword if you want triangle plot symbols,
point up
TRIDOWN - Set this keyword if you want triangle plot symbols,
point down
NOFILL - Set this keyword if you don't want the symbols filled
THICK - Line thickness of plot symbols (default 1).
Example: IDL> PLOT_SYM, SIZE=1.2, /SQUARE, /NOFILL - gives open squares of
size 1.2
(Routine contained in sprl_plot_sym.pro)