12/13/02

Lisa Gaddis

Before using these programs:

1. Please read through this entire TES "cookbook" before you start processing TES data in ISIS.
2. Create an online database of TES data according to instructions in the VANILLA MANUAL, http://software.la.asu.edu/vanilla/vanilla2.html. This is *FAR* easier than extracting TES data one orbit at a time from the CDROMS!
3. Obtain the appropriate vanilla binary (executable) software for your system from the ASU Web site or from any TES data CDROM. Put the executable file in your working directory (or you can point to the appropriate directory in "vanna" below).
4. Create a DATASET file that contains a list of directory/file pointers to the online TES data. Put this in your working directory, or link to it directly. (You will need to update this list each time you update the TES database.)

1. Extract TES emissivity data for a given region

1. Use "tesemiss" in ISIS as an interface to TES "vanilla" (via the ISIS program "vanna") to extract TES emissivity data from an existing on-disk database of TES data. (Type "help tesemiss" at the tae prompt or read the tesemiss.pdf to see detailed notes for this program.) The appropriate vanilla command line will be echoed to the screen and print files for review and documentation, the number of files found are also echoed, and the output data file will be in ascii format.

   The user can also choose not to run vanna/vanilla but simply to create the command line script, which can then be edited and used directly in vanilla to create images of other measured TES data, such as ick, ock, phase and/or emission angle, lambert albedo, etc.

   Note that the user can provide a few parameters to specify the observing and/or instrument conditions under which the TES data were obtained. For example, the sequence parameter can be used to extract nadir emissivity data (emission 0 to 10 degrees). Or, to extract data with little dust one could specify the maximum level of dust opacity (e.g., dust=0.3 or ice=0.04). Note that dust opacity values in the TES literature (e.g., Smith et al., 2001, JGRP, 23929-23945) are often reported as scaled values, so it may be best to use the direct ice opacity values. Scaled dust opacities (at 1075 cm-1) vary from 0.0 to 0.5 and ice opacities (at 825 cm-1) vary from 0.0 to 0.15.

   • example 1.1 (with DUST constraint):

     tae>tesemiss to=valmar_emiss.van vanilla=vanilla data=./ waveset=10 + latitude(1)=-10.0 latitude(2)=-2.0 longitude(1)=68.0 + longitude(2)=78.0 sequence=daytime albedo=(null) heliolon=(null) + dust=0.3 ice=(null)

     Note1.1: This example takes ~15 minutes to run.

2. The ISIS program "vanna" has more flexibility and can be used directly to extract TES data with specific characteristics or to extract other types of measured TES data, including lambert albedo, phase angle, etc. The program can be used once to extract several datasets as a single database, or repeatedly to extract datasets one at a time. Latitude and longitude are always extracted for image data; TES data have latitudes increasing from prime meridian (0 degrees longitude) to the West.
   • example 1.2 (to extract EMISSIVITY data only):

     tae>vanna to=valmar_orbits.van vanilla=vanilla data="./" + mode=text execute=yes script=(null) + fields(1)=latitude +
     fields(2)=longitude +
     fields(3)=emissivity +
     select(1)="latitude -10 -2" +
     select(2)="longitude 68 78" +
     select(3)="scan_len 1 1" +
     select(4)="height 0 0" +
     select(5)="emission 0 10" +
     select(6)="incidence 0 80" +
     select(7)="target_temp 255 350" +
     select(8)="pnt_imc 0 0" +
     select(9)="quality:algor_patch 1 1" + select(10)= "quality:algor_risk 0 0" + select(11)= "quality:phase_inversion 0 0" + select(12)= "quality:hga_motion 1 1" + select(13)= "quality:pnl_motion 1 1" + select(14)= "quality:moment 0 0") + select(15)= "det_mask 7 7" +
     select(16)= "spectral_mask 0 0" +

     Note1.2: Most of these parameters are defaults (see "help" for vanna for details), but the user *must* change latitude and longitude values for each geographic region. This example takes ~10 minutes to run.

     Note1.3: These are "conservative" default selection parameters. If you prefer to find more (possibly lower quality) TES data for your area, you may want to relax these constraints a bit. For example, you may want to remove the "quality:hga_motion 1 1" and "quality:pnl_motion 1 1" constraints to increase your TES pixel population for a given area. If you do this, your data may suffer from the results of these motions in certain TES channels or at certain latitudes. Be careful!

     Note 1.4: You may want to extract TES data in "layers", perhaps related to albedo or temperature. If you create sorted TES datasets with vanna, you can overlay them sequentially when you create the TES image cube so that, for example, pixels with higher temperatures are on top. You can also do this by simply sorting the text output of vanna so that higher-temperature data are on the bottom.

   • example 1.2 (to extract LAMBERT ALBEDO data only):

     tae>vanna to=valmar_orbits.van vanilla=vanilla data="./" +

     mode=text execute=yes script=(null) + fields(1)=latitude +
     fields(2)=longitude +
     fields(3)=lambert_alb +
     select(1)="latitude -10 -2" +
     select(2)="longitude 68 78" +
     select(3)="scan_len 1 1" +
     select(4)="height 0 0" +
     select(5)="emission 0 10" +
     select(6)="incidence 0 80" +
     select(7)="target_temp 255 350" +
     select(8)="pnt_imc 0 0" +
     select(9)="quality:algor_patch 1 1" + select(10)= "quality:algor_risk 0 0" + select(11)= "quality:phase_inversion 0 0" + select(12)= "quality:hga_motion 1 1" + select(13)= "quality:pnl_motion 1 1" + select(14)= "quality:moment 0 0") + select(15)= "det_mask 7 7" +
     select(16)= "spectral_mask 0 0" +

     Note1.3: This example takes ~10 minutes to run.

2. Create a TES emissivity image for a specific geographic region.

1. Use the "lev2raster" program in ISIS, which requires the ascii data from tesemiss/vanna and the configuration file "emissivity_tes.conf" (see below) as input. See lev2raster.pdf for extensive detail on this program.

2. ***BEFORE*** using "emissvity_tes.conf", copy it to new file for a given area and/or dataset and change the filename of ^RASTER = "??". Also, adjust COLUMN_NUMBER as needed (this data file is optimized for TES emissivity, COLUMN_NUMBER = 9, to allow for skipping over the first 6 channels of bad or missing TES data). The result will be an ISIS image cube with 137 channels or bands (stored in band-interleaved-by-pixel or BIP format) and "level-2" geometry.

   emissivity_tes.conf

3. Use "lev2raster" to create an emissivity image. A report will be generated describing the geometric characteristics of the image and will be displayed on the screen and echoed in the print.prt file.

   Note2.1: The ISIS TES cube will have "ocentric" latitudes with positive latitude direction East (see below). This is the preferred orientation for Mars data in ISIS. This means that the West coordinates used to extract raw TES data in tesemiss/vanna above must be converted to East coordinates for input to lev2raster. [Because the configuration file refers to the extracted (original) TES coordinates, leave the "LONDIR" in the configuration file as "WEST".]

   • example 2.1:
     tae>lev2raster to=valmar_emiss.cub initfrom=(null) mode=init + update=average config=emissivity_tes_valmar.conf targdef=mars + mappars=simp:287,ocentric latrange(1)=-10.0 latrange(2)=-2.0 + lonrange(1)=282.0 lonrange(2)=292.0 km=3.15 latsys=ocentric + lonsys=360 pmeroff=-0.1795

     Note2.2: Coordinate systems for Mars data vary with respect to their positive longitude direction ("londir" in ISIS) and their latitude measurement systems. LONDIR=East means longitude increases from 0 to 360 in the right or east direction from the prime meridian. LONDIR=West means longitude increases to the left or west. Latitudes are either measured from the equatorial plane through a point at the center of the planet ("planetocentric") or as an angle from a local vertical to the equatorial plane ("planetographic"). TES, MOLA, and THEMIS data are in East/Ocentric format, MOC data are in West/Ographic format, MDIM 1.0 and 2.0 are in West/Ographic format, and MDIM 2.1 and 3.0 products are in East/Ocentric format. These parameters are defined for ISIS in the mars.def.n files; the current file is "mars.def.4" (found in $ISISDATA/target).

       East(degrees):  180       270       360/0       90       180
       West(degrees):  180       90        0/360       270      180
       

     to convert from west to east: 360 - west_lon
     to convert from east to west: 360 - east_lon

     Note2.3: The parameter "pmeroff" refers to the value needed to adjust the offsets in prime meridian (longitude) values among the different datasets for Mars that are now commonly in use. TES uses IAU 1994 prime meridian values of 176.901. MOC data use IAU 2000 prime meridian values of 176.7215. To compare TES data with MOC data would require an adjustment or "pmeroff" to match the two, so pmeroff=(176.7215 - 176.901) -0.1795. ( If not matched, offsets at the equator would measure ~4 km.) Different offsets are needed to match TES data with other datasets, such as MOLA. If coregistration with other Mars data is not necessary, or if those datasets have already been adjusted to coincide (e.g., all > are coincident with MOLA geometry) then pmeroff=-- (null).

     Note2.4: This example takes about 10 minutes to run.

4. "lev2raster" can also be used to create an emissivity image that matches an existing image file with ISIS "level-2" geometry. This requires that a level-2 projected ISIS image be available for a given area. If this is the case, the level-2 image can be used to create a corresponding TES emissivity image with matching map parameters. In addition to specifying a TO file in lev2raster, the user must include an INITFROM level2 file. Also, for TES data a resolution of KM=3.15 *must* be used.

5. A matching photographic or albedo image will help the user to ensure that the emissivity data cover the desired area. Unfortunately, only the MGS data are currently available in the required "level-2" projected formats. Future MDIM versions will be in this format, but are not yet available. One photographic dataset that can easily be converted to the level-2 format is the MOC Wide-Angle Map of Mars, available as MDIM-like quads on the Web at http://www.msss.com/mars_images/moc/moc_atlas. These image quads can be converted to ISIS cubes using the following instructions:
   • Convert MSSS Atlas to ISIS.zip. Go to the following FTP site and read convert_to_ISIS_README.txt.
   • ftp://webgis.wr.usgs.gov/mars/moc

6. Once ISIS cubes are available in level-2 format, they can be used to extract subscenes for creating geometrically matching TES data. To do this, use "lev2tolev2" to create a tfile for a given geographic region, then use "geom" to extract the desired portion of the data from the level2 cube. This cube file can then be used as INITFROM in lev2raster. The "lev2tolev2" program can be used to reproject an image or to specify a desired geographic region to be extracted from the MOC quad, and to adjust pixel resolution (scale) or map projection parameters such as center longitude. See lev2tolev2.pdf for details.
   • example 2.2(to extract MOC data from an ISIS cube for a desired region):

     tae>lev2tolev2 from=cvm_simp.cub mappars="simp:73" +

     latrange(1)=-9.0 latrange(2)=-4.0 lonrange(1)=73.0 lonrange(2)=78.0 + latsys=ocentric lonsys=360

     Note2.2: The "km" parameter must match

7. A note on TES pixels in ISIS. TES pixels are square, 3.15 km/pixel in (default) size, and they are mapped into an image cube one detector per pixel. Up to 6 TES pixels/detectors from a single instrument observation ("ick") can be present, and each of these is mapped into the image cube individually. If pixels from different orbits are spatially coincident, the "update" parameter in lev2raster allows you to select how these will be mapped into the image. You can average coincident pixels (update=average), replace them with later pixels (e.g., if you want to create a TES cube with different layers; update=replace), or preserve them (update=preserve) so that the first pixel into the image remains unmodified by subsequent pixels. In the examples above, update=average is the default. This creates a TES cube in which some pixels are "multiple" pixels with possibly better signal-to-noise than adjacent pixels. An alternative is to use the mode=add and update=replace parameters in lev2raster, and to augment a single TES cube with sequentially higher-temperature pixels (i.e., from multiple runs of vanna as described above).

3. Create a TES lambert albedo image for a specific geographic region

1. If an INITFROM file is not available or desired, a TES albedo image will help users to ensure that they are working in the correct area. Hopefully recognizable features will be displayed in the albedo image.

2. Use the "lev2raster" program in ISIS, which requires the ascii data from vanna (see example 1b(2) above) and the configuration file "lambert_alb_tes.conf" (see below) as input.

3. ***BEFORE*** using "lambert_alb_tes.conf", copy it to new file for a given area and/or dataset and change the filename of ^RASTER = "??". Also, adjust COLUMN_NUMBER *if* needed (this data file is optimized for TES lambert albedo, COLUMN_NUMBER = 3). The result will be an ISIS image cube with 1 channels or band and "level-2" geometry.

   lambert_alb_tes.conf

4. Use "lev2raster" to create a a lambert albedo image. A report will be generated describing the geometric characteristics of the image and will be displayed on the screen and echoed in the print.prt file.
   • example 3.1:
     tae>lev2raster to=valmar_albedo.cub initfrom=(null) mode=init + update=average config=albedo_tes_valmar.conf targdef=mars + mappars=simp:287,ocentric latrange(1)=-10.0 latrange(2)=-2.0 + lonrange(1)=282.0 lonrange(2)=292.0 km=3.15 latsys=ocentric lonsys=360 + pmeroff=-0.1795

   • Note3.1: This example takes about 1 minute to run.

4. View TES image cubes in ISIS

1. If an emissivity image in BIP format has been created, it is necessary to transpose the image to band-sequential or BSQ format to view it and to extract spectra in ISIS. Note that a TES emissivity image cube typically consists of multiple orbits with null-valued pixels between them.
   • example 4.1:

     tae>transpose from=valmar_emiss.cub to=valmar_emiss_bsq.cub

     Note4.1: This example takes about 4 minutes to run.

2. If an albedo image (with only a single band) has been created from TES data, it is not necessary to transpose the image.

3. Use the ISIS programs "qview" or "cv" to view the images. "cv" will allow extraction of spectra.

5. A note on configuration files