tesemiss Documentation

tesemiss - Retrieve TES Emissivity data from vanilla database
"tesemiss" extracts data for a user-specified geographic region on Mars
from the emissivity field in the PDS TES orbital data.  In addition to
specifying latitude and longitude coordinates, the user can also
select TES data at either 10 wavenumber (the default) or 5
wavenumber.  A daytime observation sequence is assumed for calculation
of emissivity data, but the user may also choose to select either
TES EPF (emission phase function) or MOSAIC files.  A Lambert Albedo
can be readily specifed to restrict searches to relatively low-albedo
regions (e.g., albedo < 0.24) that are more likely to be less
contaminated with dust than high-albedo regions.  The user may also
limit data selection using the heliocentric longitude parameter to pick
a favored L-subS (or season) on Mars to avoid times of dust storms or
water clouds (e.g., Smith, M.D. et al., JGR 106, 23929-23945).
Alternatively, the user can impose limits directly on dust and ice
cloud opacity when those quantities are present in the database.
This program is optimized for use with Mapping Phase data from TES.


"tesemiss" program uses the "vanilla" program released by the TES
mission and found on all TES data volumes.  "vanilla" is a command-line
program that reads the binary TES TSDR (Time Sequential Data Records)
file format, correlates and extracts data from various fields, and
outputs data as a table of ascii values.  TES TSDR Standard Data
Products contain raw and calibrated thermal IR radiance spectra, visual
and bolometric radiance measurements, and atmospheric and surface
properties derived from these data.  Also included in each TSDR file
are the parameters that describe each observation, some downlinked
diagnostic information, and pointing and positional information
derived from the project's SPICE kernels.  It is suggested that users
review the vanilla documentation on the TES data volumes (see below).

Several changes to the TES data tables occured during the mission which
affect a users ability to use all mission CDs as a single set.  The
following are sets of CDs that have similar data structures.  If a user
attempts to use CDs from different sets of incompatability problems can
occur and will be flagged with "odd file size" messages from vanilla.

Aerobraking    MGST_0001 to MGST_0061  ("original" structure)
Mapping        MGST_0100 to MGST_0161  (new class/quality fields)
Mapping        MGST_0162 to MGST_0187  (new/changed fields)
Mapping        MGST_0188 to .........  (new atmospheric table)


This application calls the the ISIS "vanna" program to construct
the vanilla command and then executes it.  The ascii output is written
to the TO file if specified, otherwise the number of "hits" (or TES
orbits) are counted and reported.  The user can thus run this program to
refine input parameters, identify the number of TES orbits available
for a specific area, etc. before actually extracting those data.

The emissivity data field is referred to as a "faked field" in
vanilla.  The emissivity data are not actually stored in the TSDR
but are derived from data in other fields, and they are written
out as ascii or text data.  To calculate emissivity, calibrated
planetary radiance is divided by the Planck function value at the
kinetic temperature at the surface.  In practice, the surface kinetic
temperature is approximated by deriving the brightness temperature from
TES calibrated radiance at each wavenumber and setting the kinetic
temperature equal to the maximum brightness temperature within a wave
number internal from 300 to 1350-cm-1 (e.g., see Christensen et al.,
2001, JGR, 106, pp.  23873-23885 and references therein).  This method
assumes that the surface materials have unit emissivity at the point of
maximum brightness temperature within the TES spectral range.

Here are the user-selectable criteria used by vanilla to select
valid instrument and imaging parameters so that emissivity can be
calculated from the TSDRs.  The values shown are defaults; although
they can be modified by the user, this should be done with caution
because these values correspond to the best advised parameters for
calculation of emissivity for most regions on Mars.

incidence 0 80 - TES incidence angle.  Restricts selection to the range
                of 0 to 80 degrees to restrict to daytime observations.

target_temp 255 350 - Target temperature.  Use of these values
		ensure a high signal-to-noise ratio.

height 0 0 - Observation height.  This selection restricts
             	data to surface (rather than limb) observations.

pnt_imc 0 0 - This selection indicates whether the image motion
              compensation was in use or not.  Because IMC use caused
              noise in the TES data, it should bot be used (i.e., 0 0).

quality:algor_patch 1 1 - "algor flight software patch onboard TES"
		This software path was added during TES operation
		to correct problems in calculation of spectra. Better
		TES data are generally produced when the patch was
		onboard.

quality:algor_risk 0 0 - This selection identifies the TES data
		that are thought to be at low risk for algor phase
		inversions.  These are due to low temperature contrast
		between the sensor and the target.

quality:phase_inversion 0 0 - Phase inversions are major problems in
		the calculation of the TES spectra due to lost bits,
		excessive ringing, incorrect ZPD determinations, etc.
		This selection identifies TES data without major phase
		inversions.

quality:hga_motion 1 1 - High-gain antenna motion.  The HGA was deployed
		after the Aerobraking Phase and its movement state
		(which varies for different OCKs) was recorded as noise
		in the TES data.  This selection identifies data
		collected when the HGA was not moving.

quality:pnl_motion 1 1 - Solar panel motion.  As for the HGA, the
		use of the solar panels causes noise in the TES data.
		Solar panels were used nearly constantly early in the
		Mapping Phase, but a "move and hold" pattern was adopted
		at OCK 3589.  This selection identifies data acquired
		when the solar panel(s) were not moving.

quality:moment 0 0 - Periodic bursts from thrusters were used to
		adjust the angular momentum of the MGS spacecraft.  This
		selection identifies TES data acquired when these
		adjustments were not being made.

spectral_mask 0 0 - This selection identifies TES data in which all
                channels are used and there is no masking or coadding.
                Note that the default here is to also return data in
                which none of the 6 TES detectors have been coadded or
                masked (vanilla field "det_mask 7 7").

More detailed information on the vanilla program, the TES dataset, and
analysis techniques used by the TES team can be found at
http://software.la.asu.edu/vanilla/vanilla2.html, and in the Mars
Global Surveyor special issue of Journal of Geophysical Research,
volume 106, Number E10, 2001.

NOTE:  To create an emissivity image for a specific region, the user
must use the ascii data and the accompanying configuration file
created by "tesemiss" as input to the "lev2raster" program in ISIS.

See also documentation for the ISIS application "vanna" that actually
constructs the vanilla command and executes it on behalf of this
application.

PROGRAMMER: Kris Becker, USGS, Flagstaff, AZ

Name of output file for
TES emissivity data

--

Path to vanilla executable
program if not in your
current path

"vanilla"

Path to vanilla database or
"DATASET" file

"./"

Select 5- or 10-wavenumber
TES data

10

Select specific range of
latitudes (e.g., low to high,
or southern value then
northern)

--

Select specific range of
longitudes (e.g., low to high,
0 to 360, or eastern to western)

--

Select desired observation
sequence:  DAYTIME for
emissivity data, EPF, or MOSAIC

"DAYTIME"

Select specific range
of albedo

--

Select specific range
of heliocentric longitude
to limit dusty periods

--

Select desired range of
dust opacity

--

Select desired range of
water ice cloud opacity

--

ADDITIONAL NOTES:

Parm	Description
TO	Name of the the output file generated by vanilla for the selected data. This file is always a text file. It will have three fields: latitiude, longitude, and emissivity (which will be an array of values). See the general help section for more detail about the output generated in this file. If a TO file is not specified, only a count of the number of records ("hits") will be reported (by vanna).
VANILLA	This parameter allows the user to select the complete path to the vanilla executable. The default of simply "vanilla" is sufficient if and only if your shell PATH environment variable contains the path to the executable. Otherwise you will need to provide a complete path. Example: /usr/local/bin/vanilla
DATA	Specify the path of the vanilla database you wish to extract data from for the parameters selected. There must be a file named "DATASET" (case sensitive) in this directory that the vanilla application will attempt to read. This file may have a list of other directories that contain a DATASET file or a directory that contains a list of data products. Refer to the vanilla documentation for more information on the required format of a DATASET file
WAVESET	This allows the user to select the desired spectral resolution of the TES data. The default 10 wavenumber data have 143 spectral channels, and the 5 wavenumber data have 286 spectral channels. The user must pick one or the other; variable length records in the two file formats make it unwise to mix the two datasets if you intend to rasterize them. If both types of data are desired, then it is best to do this in two runs of this program.
LATITUDE	The default mode of operation (null value) will select all data in the complete latitude range (-90 to +90). This can produce a very large output file. The user can also identify a desired range of latitudes, and data outside this range will be excluded from the output file. Values must be entered north to south (or low to high) in the following formats: -5 40; -20 0; 80 90; etc. This parameter can be left as null to exclude it from the selection criteria.
LONGITUDE	The default mode of operation (null value) will select all data in the complete longitude range (0 to 360). This can produce a very large output file. The user can also identify a desired range of longitudes, and data outside this range will be excluded from the output file. Values must be entered east to west (low to high): 45 55; 350 10; 68 88; etc. This parameter can be left as null to exclude it from the selection criteria.
SEQUENCE	This parameter identifies TES data acquired during specific times or under certain conditions. The options are "DAYTIME", "MOSAIC" and "EPF". "DAYTIME" data must be selected for calculation of emissivity; this is implied for selection of "EPF" or emission phase function data or for "MOSAIC" TES files. "DAYTIME" will select data that are collected on the DAY side of MARS. "MOSAIC" data use the rotation of Mars to provide continuous ground coverage. These data are acquired by viewing a specific region of the surface of Mars in the forward, nadir, and aft directions along the MGS ground track. "EPF" (Emission Phase Function) data are acquired by viewing a specific region of the surface of Mars at variable emission angles in the forward and aft directions. Two types of EPF data were acquired: limited angle (7 to 9 emission angles) and continual tracking (340 observations) EPF data.
ALBEDO	This parameter allows the user to select and/or restrict the TES data selection on the basis of measured lambertian albedo of the surface. This selection is typically used to restrict searches to relatively dark areas free of high albedo dust covers. Typical values are 0 to 0.24. The user must exercise caution in the manipulation of this parameter. This parameter can be left as null values to exclude it from the selection criteria.
HELIOLON	Heliocentric longitude is used to select and/or restrict searches to a particular Martian season. It is useful for limiting data to relatively dust-free periods. Typical values are 0 150. The user must exercise caution in the manipulation of this parameter. See also DUST and ICE parameters. This parameter can be left as null to exclude it from the selection criteria.
DUST	This parameter may be used to further restrict searches to dust-free periods when measurements of nadir dust opacities are low. See also HELIOLON and ICE parameters. This parameter can be left as null values to exclude it from the selection criteria.
ICE	This parameter refers to nadir ice water cloud measurements and can be used to restrict searches to relatively cloud-free and/or dust-free periods. See also HELIOLON and DUST parameters. This parameter can be left as null to exclude it from the selection criteria.