vanna Documentation

vanna - User interface to the ASU vanilla application
vanna is an ISIS interface to the ASU (TES) vanilla database tool used
to process the Mars Global Surveyor Thermal Emission Spectrometer (TES)
data.  Vanilla has a command line interface.  vanna provides perhaps a
more convenient method to construct and execute vanilla commands.

vanna has a very TES oriented inmplementation but is not limited to
the this data set.  Virtually any data that is stored in vanilla format
or is supported by vanilla should work with vanna.

The defaults provided for vanna are a minimal set for the TES data.
vanna provides additional parameters for vanilla "fields" and "select"
options.  Vanilla "fields" are those that are selected for output of the
database search.  "select" fields are used to limit the "fields" by
putting constraints on fields that exist in the vanilla data sets.  The
"select" fields need not be specified in the "fields" parameter.  And
the opposite is also true - "fields" need not be specified in the
"select" parameter.

The "UFIELDS" parameter is provided so the user can choose additional
"fields" to be selected for printing in the output record (line) of
each data entry that passes the "select" constraints.  These fields are
appended to those specified in the "FIELDS" parameter.  The "USELECT"
parameter provides the user with additional selection criteria that
is added to the ones that already exist in the "SELECT" parameter.  Any
one of the default "FIELDS" or "SELECT" values can be nulled (via the
TAE "--" designation) if none are desireable.  Both these parameters can
be used at the discretion of the user as well.  They are only suggested
defaults.

vanna takes all the user input and constructs a vanilla command.  vanna
echos the constructed command, and has the ability to write the command
to a file for later execution and execute the command for you directly.
vanilla has the ability to write the search results as text, which is
its default, or 4-byte or 8-byte "cooked" floating point.  vanna allows
the user to select any of these output options via the "MODE" parameter.

Some things need to be considered when executing vanilla commands with
vanna.  If you do not specify an output file in the "TO" parameter, the
run results will be written to screen.  This is almost always an ill-
advised way to have vanna execute a vanilla command.  More times than
not, vanilla runs generate a great deal of output as the output is a
function of the number of records that are specified in the data base
and the number and length of the "fields" selected.  If you execute
a vanilla run with vanna within TAE, it is difficult to stop or even
suppress the output unless you specify an output file.  For this reason,
the default for vanna is EXECUTE="NO".  It is advisable to always
specify an output "TO" file for any run you intend to have vanna
execute.  Furthermore, vanna uses the C "system()" function to execute
the constructed vanilla command.  This will execute the vanilla command
using the Bash (Linux) or Bourne (Solaris and others) shell.  When
selecting "TEXT" output, the results of the vanilla run is "redirected"
to the output file specified in the "TO" parameter using shell
redirection.  This is a bit tricky especially if this is not your
default user shell (e.g., you may use the C or T shell by default).  The
problem with this is there is very little control over the "TEXT" output
mode.  For example, if the file already exists, then the command will
fail with normal redirection techniques.  Data must be either appended,
which is probably not the right thing to do since a header is produced
for each run, or the file must be deleted.  vanna does not make these
decisions for the user.  vanna tests for the existance of the output
file and will not execute the command if it exits.  It will always
generate the command, however.  Therefore, it is recommend that you
do not use vanna to execute the command directly but use it to construct
the command and write it to a script file or run it from a command
prompt.  These methods provides the user with more control of vanilla
output and testing.

vanna was orignally written to process MGS TES data but it can be used
for any vanilla data set.  Below is a table of potential TES data fields
that can be used for both the "fields" and "select" parameters in vanna
and vanilla.  Note that all fields are scalar (single values) unless
otherwise indicated.  Some are variable size array fields are indicated
as such:


PDS  Column  Name                  Team  Alias
AEROSOL_DOWNWELLING_FLUX           (aerosol_dw_flux)
AEROSOL_OPACITY_PROFILE_LIMB       (opacity_profile)
AEROSOL_OPACITY_SPECTRUM_LIMB      (opacity_spectrum)
AEROSOL_SNG_SCAT_ALB_SPECTRUM      (ss_albedo)
AEROSOL_SNG_SCAT_PRES_LEVEL_IND    (ss_pressure)
ATMOSPHERIC_CALIBRATION_ID         (version_id)
AUXILIARY_DIAGNOSTIC_TEMPS         (aux_temps)
BOLOMETER_CALIBRATION_ID           (bol.version_id)
BOLOMETRIC_BRIGHTNESS_TEMP         (brightness_temp_bol)
BOLOMETRIC_THERMAL_INERTIA         (ti_bol)
CALIBRATED_RADIANCE                (cal_rad)
CALIBRATED_VISUAL_BOLOMETER        (cal_vbol)
CO2_CONTINUUM_TEMP                 (co2_cont_temp)
CO2_DOWNWELLING_FLUX               (co2_dw_flux)
COMPRESSION_MODE                   (cmode)
DATA_PACKET_TYPE                   (pckt_type)
DETECTOR_MASK                      (det_mask)
DETECTOR_NUMBER                    (bol.detector)
DETECTOR_NUMBER                    (cmp.detector)
DETECTOR_NUMBER                    (geo.detector)
DETECTOR_NUMBER                    (ifg.detector)
DETECTOR_NUMBER                    (rad.detector)
DETECTOR_TEMPERATURE               (tdet)
DIAGNOSTIC_TELEMETRY_1             (v1)
DIAGNOSTIC_TELEMETRY_2             (v2)
DIAGNOSTIC_TELEMETRY_3             (v3)
DIAGNOSTIC_TELEMETRY_4             (v4)
DIAGNOSTIC_TELEMETRY_5             (v5)
DIAGNOSTIC_TELEMETRY_6             (v6)
DIAGNOSTIC_TELEMETRY_7             (v7)
DIAGNOSTIC_TELEMETRY_8             (v8)
DIAGNOSTIC_TELEMETRY_9             (v9)
DIAGNOSTIC_TELEMETRY_10            (v10)
DIAGNOSTIC_TELEMETRY_11            (v11)
DIAGNOSTIC_TELEMETRY_12            (v12)
DIAGNOSTIC_TELEMETRY_13            (v13)
DIAGNOSTIC_TELEMETRY_14            (v14)
DIAGNOSTIC_TELEMETRY_15            (v15)
DIAGNOSTIC_TELEMETRY_16            (v16)
DIAGNOSTIC_TELEMETRY_17            (v17)
DIAGNOSTIC_TELEMETRY_18            (v18)
DIAGNOSTIC_TELEMETRY_19            (v19)
DIAGNOSTIC_TELEMETRY_20            (v20)
EMISSION_ANGLE                     (emission)
EPHEMERIS_TIME                     (et)
FFT_COMPLEX_DATA                   (complex)
FFT_START_INDEX                    (ffti)
GEOMETRY_CALIBRATION_ID            (geo.version_id)
IMC_COUNT                          (pnt_imc)
INCIDENCE_ANGLE                    (incidence)
INSTRUMENT_TIME_COUNT              (ick)
INTERFEROGRAM_DATA                 (ifgm)
INTERFEROGRAM_END                  (ifgm_end)
INTERFEROGRAM_MAXIMUM              (ifgm_max)
INTERFEROGRAM_MINIMUM              (ifgm_min)
INTERFEROGRAM_ZPD                  (ifgm_zpd)
LAMBERT_ALBEDO                     (lambert_alb)
LATITUDE                           (latitude)
LIMB_PARAMETERS_QUALITY            (lmb_quality)
LIMB_TEMPERATURE_PROFILE           (limb_pt)
LOCAL_TIME                         (local_time)
LONGITUDE                          (longitude)
MIRROR_POINTING_ANGLE              (pnt_angle)
NADIR_TEMPERATURE_PROFILE          (nadir_pt)
NADIR_OPACITY                      (best_fit_opacities)
NADIR_OPACITY_RESIDUAL             (rms_opacities)
NEON_AMPLITUDE                     (neon_amp)
NEON_GAIN                          (neon_gain)
NEON_LAMP                          (neon_lamp)
NEON_ZPD                           (neon_zpd)
OBSERVATION_CLASSIFICATION         (class)
OBSERVATION_CLASSIFICATION:        (class:class_value)
  CLASSIFICATION_VALUE
OBSERVATION_CLASSIFICATION:        (class:type)
  INTENDED_TARGET

OBSERVATION_CLASSIFICATION:        (class:phase)
  MISSION_PHASE
OBSERVATION_CLASSIFICATION:        (class:lamp_status)
  NEON_LAMP_STATUS
OBSERVATION_CLASSIFICATION:SPARE   (class:spare)
OBSERVATION_CLASSIFICATION:        (class:sequence)
  TES_SEQUENCE
OBSERVATION_CLASSIFICATION:        (class:timing)
  TIMING_ACCURACY
OBSERVATION_TYPE                   (pnt_view)
ONBOARD_PROCESSING_EVENT_LOG       (dsp_log)
ORBIT_COUNTER_KEEPER               (ock)
ORBIT_NUMBER                       (orbit)
PHASE_ANGLE                        (phase)
PLANETARY_ANGULAR_RADIUS           (angular_semidiameter)
PLANETARY_PHASE_ANGLE              (planetary_phase)
POSITION_SOURCE_ID                 (id)
PREPROCESSOR_DETECTOR_NUMBER       (comp_pp)
PRIMARY_DIAGNOSTIC_TEMPERATURES    (temps)
QUALITY                            (atm.quality)
QUALITY                            (obs.quality)
QUALITY                            (rad.quality)
QUALITY:ALGOR_PATCH                (quality:algor_patch)
QUALITY:ALGOR_RISK                 (quality:algor_risk)
QUALITY:ATMOSPHERIC_OPACITY_       (quality:atm_opacity_
  RATING                              rating)
QUALITY:CALIBRATION_QUALITY        (quality:calib_quality)
QUALITY:EQUALIZATION_TABLE         (quality:equal_tab)
QUALITY:HGA_MOTION                 (quality:hga_motion)
QUALITY:IMC_PATCH                  (quality:imc_patch)
QUALITY:MAJOR_PHASE_INVERSION      (quality:phase_inversion)
QUALITY:MOMENTUM_DESATURATION      (quality:moment)
QUALITY:SOLAR_PANEL_MOTION         (quality:pnl_motion)
QUALITY:SPECTROMETER_NOISE         (quality:spect_noise)
QUALITY:TEMPERATURE_PROFILE_       (quality:atm_pt_rating)
  RATING
RADIANCE_CALIBRATION_ID            (rad.version_id)
RAW_RADIANCE                       (raw_rad)
RAW_THERMAL_BOLOMETER              (tbol)
RAW_VISUAL_BOLOMETER               (vbol)
SCAN_LENGTH                        (scan_len)
SCHEDULE_TYPE                      (schedule_type)
SOLAR_DISTANCE                     (solar_distance)
SOLAR_LONGITUDE                    (heliocentric_lon)
SPACECRAFT_ALTITUDE                (altitude)
SPACECRAFT_CLOCK_START_COUNT       (atm.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (bol.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (cmp.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (geo.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (ifg.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (lmb.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (obs.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (pos.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (rad.sclk_time)
SPACECRAFT_CLOCK_START_COUNT       (tlm.sclk_time)
SPACECRAFT_POSITION                (pos)
SPACECRAFT_QUATERNION              (quat)
SPECTRAL_MASK                      (spectral_mask)
SPECTRAL_SURFACE_TEMPERATURE       (srf_temp_est)
SPECTRAL_THERMAL_INERTIA           (ti_spc)
SPECTROMETER_GAIN                  (spc_gain)
SUB_SOLAR_LATITUDE                 (sub_solar_lat)
SUB_SOLAR_LONGITUDE                (sub_solar_lon)
SUB_SPACECRAFT_LATITUDE            (sub_sc_lat)
SUB_SPACECRAFT_LONGITUDE           (sub_sc_lon)
SUN_POSITION                       (sun)
SURFACE_PRESSURE                   (srf_pressure)
SURFACE_RADIANCE                   (srf_radiance)
SURFACE_RAD_SPECTRUM_              (srf_uncertainty)
  UNCERTAINTY
TARGET_ALTITUDE                    (height)
TARGET_DISTANCE                    (target_distance)
TARGET_TEMPERATURE                 (target_temp)
TEMPERATURE_PROFILE_RESIDUAL       (rms_pt)
TEMPORAL_AVERAGE_COUNT             (tic)
TEMPORAL_INTEGRATION_SCAN_         (tic_count)
  NUMBER
THERMAL_BOLOMETER_GAIN             (tbol_gain)
VISUAL_BOLOMETER_GAIN              (vbol_gain)


There is a decent reference for the vanilla software found at
http://software.la.asu.edu/vanilla/.

PROGRAMMER: Kris Becker, USGS, Flagstaff, Az

Output file to be created by
vanilla.

--

Path to vanilla application.
Default is OK if its in your
path.

"vanilla"

Directory specification for
vanilla data

"./"

vanilla output file mode:
TEXT - output text fields
BIN4 - output 4-byte cooked
       float
BIN8 - output 8-byte cooked
       double

"TEXT"

Specifies to execute the
resulting vanilla command
YES or NO

"NO"

Specifes the name of a file
to append the vanilla command

--

Name of all the colunms in the
vanilla data base to write out
to specified target (file)

                "orbit",                "ock",                "bol.detector",                "bol.sclk_time",                "latitude",                "longitude",                "phase",                "emission",                "incidence",                "heliocentric_lon",                "altitude",                "target_temp",                "cal_rad[]",                "lambert_alb",                "ti_spc"

User may specify output fields
independant of default FIELDS
columns

--

Vanilla default selection
criteria to apply to each
record data

                "latitude  -90 90",                "longitude 0 360",                "scan_len 1 1",                "height 0 0"

User may add selection criteria
independany of default SELECT
columns

--

ADDITIONAL NOTES:

Parm	Description
TO	Name of the output file generated by the vanilla run. This parameter is used for all output MODEs. If the file already exists and the EXECUTE="YES", this is an error. vanna will not append to or replace an existing file.
VANILLA	Specifies, if necessary, the absolute path to the vanilla executable program. If the path to the vanilla executable does not exist in the users' PATH variable, then you must specify the complete path in this parameter so it can be invoked directly. The default assumes that the executable is in the path. (BTW, this can be verified by issuing the 'which vanilla' command at the prompt. If it comes back with a path to the vanilla program, then the default will suffice.)
DATA	This parameter specifies the location of the vanilla database. Accessing vanilla data can be done in several ways. Generally, you provide a directory that contains a file named "DATASET", case sensitive. The contents of the DATASET file is either a list of data set types or a list of other directories containing DATASET files.
MODE	This parameter tells vanna how to vanilla should output the resulting data. The default setting is to write the result to the screen in TEXT node. Other options are "BIN4", 4-byte "cooked" floating point and "BIN8", 8-byte "cooked" double floating point values. The output will be written to the file specified in the "TO" parameter.
EXECUTE	Tells vanna to execute the vanilla command directly. If EXECUTE="YES", the C "system(command)" function is invoked with the resulting vanna-constructed vanilla run command. The "system" command always invokes the Bash (Linux) or Bourne (Solaris and others) shells to execute the command. Specifically, it uses /bin/sh. Text output is written to a file using shell redirection syntax so the command may need to be altered if you defer execution to some other environment. This requires a certain understanding of other output redirection methods for other shells.
SCRIPT	This optional parameter is the name of a file where the constructed vanilla command is written to so that it can be executed at a later time. The command is always appended to the end of this file so if it exists, it is assumed to contain other Bourne shell commands. It it does not exist, it will be created and the command will be written to it.
FIELDS	This parameter contains the default values for the vanilla "fields" option. The "fields" option to vanilla selects which data fields contained in the vanilla data set will be written to the specified output file. See also "UFIELDS" which allows the user to add to the fields provided here for output. This parameter contains addition information about proper specification of these values.
UFIELDS	This parameter is optional and allows the user to select more vanilla output values in addition to the defaults in the "FIELDS" parameter. These values are appended to the default "FIELDS" in the output file. The form of vanilla "fields" is: "field_name[[low:high]]" where "[low:high]" is only applicable to array fields, fields with more than one value. "low" specifies the starting index and "high" specifies the ending index. Other valid forms are "field_name" which selects the entire field whether it be a scalar (single) value or an array, "field_name[]" which also selects the entire array field, or "field_name[index]" which selects a single value at the given "index" in the array. vanilla indexes range from 1 to N where N is the number of elements in the field. See also "FIELDS".
SELECT	This parameter contains all the default vanilla "select" fields used to limit the data selected for writting to the output TO file. The user should provide the name of an existing vanilla data field with a "low" and "high" range of inclusive values. All records that satisfy this criteria for all "SELECT" entries will be written to the output file. Those that do not are excluded from the output file. See also "USELECT" which allows the user to add to the default criteria specified in this parameter. The "USELECT" help section contains information on proper specification of these values.
USELECT	This optional parameter provides a convenient way for the user to add additional vanilla data selection criteria to data records. The values specified here is added to the defaults specified in the "SELECT" parameter. The form of a vanilla selection field is: "field_name[[index]] low high" "[index]" is required if "field_name" is an array. It is not needed for scalar or single valued fields.