tbl2isl Documentation

tbl2isl - Put Table file spectrum into an Instrument Spectral Library
"tbl2isl" reads a spectrum from an ISIS binary Table file and inserts
it into an Instrument Spectral Library (ISL).  It will either create
a new ISL file or update an existing ISL file.


ISL CREATION OR UPDATE

When a new ISL file is being created there are two ways for determining
the wavelengths in the new ISL.  The WAVEFILE parameter can specify
the name of an ISIS binary Table file that contains the wavelengths
and associated full widths at half maximum.  (This Table file can be
generated by the "bandtab" program, which extracts the information from
an existing cube file.)  These values are stored in the BAND_BIN_CENTER
and BAND_BIN_WIDTH label keywords in the BAND_BIN Group of the new ISL.
If the WAVEFILE parameter is not specified, then the wavelengths are
obtained from the input spectrum Table file.  (In this case, there
will be no full widths at half maximum information stored in the new
ISL.)

When an existing ISL file is being updated, the list of ISL wavelengths
and full widths at half maximum (if available) are obtained from
keywords in the ISL label.

When a new ISL file is being created there are two ways for determining
the structure of the spectrum header to be associated with each
spectrum in the ISL.  If the input spectrum Table file contains the
optional SPECTRAL_HEADER_DEFINITION Group of keywords, then the keywords
in this Group specify the header structure.  If the Group does not
exist, then "tbl2isl" will use a default spectrum header structure.


INPUT SPECTRUM WAVELENGTHS AND DATA

The spectrum data are obtained from the input spectrum Table file
specified by the SPECFILE parameter. This file must contain at least
two columns that specify the wavelengths and spectrum data values.
The names of these columns are specified by the WAVECOL and SDATACOL
parameters.


ISL SPECTRUM HEADER

The ISL spectrum header values for the spectrum are obtained from
label keywords in the optional SPECTRAL_HEADER_DATA Group in the
input spectrum file.  These keywords can be set or updated by the
"hdrkeys" program.  The only required fields in the spectrum header are
the SPECTRUM_NAME and SPECTRUM_TYPE_ID, which are specified by the
SPECNAME and SPECTYPE parameters in "hdrkeys".  These fields can also be
specified by the SPECNAME and SPECTYPE parameters in "tbl2isl".  If
the values for these fields are specified by "tbl2isl", then they
override the values (if any) contained in the label of the input
spectrum Table file.  Thus, specifying these values in "tbl2isl" will
eliminate the need to run "hdrkeys" on the input spectrum file.


SECONDARY DATA ARRAYS

If the input spectrum Table file contains more than two columns, then
columns numbered 3-N can be inserted into the ISL as secondary data
arrays associated with the primary spectrum.  These can contain data
for the min, max, standard deviation or valid pixel count of an
average spectrum, spectrum uncertainty, or imaginary part of a complex
spectrum.  (These columns are located by column index number rather
than column name.)  The types of data contained in the secondary
arrays are specified by the array of values in the SPECTRUM_TYPE_ID
label keyword in the SECONDARY_HEADER_DATA Group in the input spectrum
file.  This can be set or updated by running "hdrkeys" and specifying
the type codes with the SECTYPE parameter.


SPECTRUM FAMILY MEMBERSHIP

If the input spectrum file contains the FAMILY_NAME keyword, then
the value of the keyword is an array of spectrum family names with
which the input spectrum is to be associated.  This keyword can be
set or updated by running "hdrkeys" and specifying the families with
the FAMNAME parameter.


CONVOLUTION TO ISL WAVELENGTHS

The input spectrum is optionally convolved to the set of wavelengths in
the ISL file.  The convolution can be omitted only if the number of
bands and the wavelengths in the input spectrum match the number of
bands and wavelengths in the ISL file.  Convolution can only be done
when the full width at half maximum information is available (either
specified by the WAVEFILE parameter when creating a new ISL or contained
in the ISL when updating an existing ISL.)  If convolution is selected,
then the secondary data arrays (if any) that are associated with the
primary spectrum are also convolved to the ISL wavelengths.


SOURCES OF INPUT SPECTRUM TABLE FILES

The following are some of the ways that the input spectrum Table file
can be produced:

  1. Run "asc2tbl" to convert an ASCII text file to an ISIS binary
     Table file.  Optionally run "hdrkeys" to set ISL spectrum header
     values, secondary data array types, and/or family names.
  2. Run "cubespec" to compute an average spectrum for a rectangular
     region of a cube file.  The region is selected by SFROM, which
     can also select a single spectrum.  Optionally run "hdrkeys".
  3. Run "cv" and interactively save an average spectrum in a table
     file.  The average can be for a single spectrum, a rectangular
     region, or an arbitrary Region of Interest.  Optionally run
     "hdrkeys".
  4. Run "isl2tbl" to extract a spectrum from an ISL and write it
     to a table file.  Optionally run "hdrkeys".

Programmer:  Tracie Stoewe & Jim Torson, U.S.G.S., Flagstaff

Input spectrum Table file
  (Default extension is .tbl)

NONE

TABLE OBJECT in SPECFILE that
  contains input spectrum

"TABLE"

Column name in SPECOBJ that
  contains spectrum wavelengths

"WAVELN"

Column name in SPECOBJ that
  contains spectrum data values

"SPECTRUM"

Spectrum name
  (40 characters)

--

Spectrum Type ID
  (1-11)

--

Input wavelength Table file
  (Default extension is .tbl)

--

TABLE OBJECT in WAVEFILE that
  contains input wavelengths

"TABLE"

Output ISL file
  (Default extension is .isl)

NONE

Output file mode (NEW or UPDATE)

"NEW"

Whether to convolve the spectrum
  (YES or NO)

NO

Whether to replace existing
  spectrum in ISL  (YES or NO)

NO

User comment

" "

ADDITIONAL NOTES:

Parm	Description
SPECFILE	Name of ISIS binary Table file that contains the input spectrum data and wavelengths. Must contain at least two columns whose names are specified by WAVECOL and SDATACOL If the file extension is omitted, then ".tbl" will be assumed.
SPECOBJ	Name of TABLE OBJECT in SPECFILE that contains the input spectrum data.
WAVECOL	Name of the column in SPECOBJ in SPECFILE that contains the input spectrum wavelengths.
SDATACOL	Name of the column in SPECOBJ in SPECFILE that contains the input spectrum data values.
SPECNAME	The name to be given to the input spectrum when written to the ISL. If specified, this name overrides the value of the SPECTRUM_NAME keyword in the SPECTRAL_HEADER_DATA Group in the input spectrum file. If not specified, the SPECTRUM_NAME keyword value is used. The spectrum name must be unique for each primary spectrum in an ISL and is stored in the SPECTRUM_NAME field of the ISL spectrum header. The maximum length of the spectrum name is 40 characters.
SPECTYPE	Specifies the type of data in the primary spectrum when written to the ISL. Primary spectra type codes have positive values while secondary data type codes have negative values. Valid values are: 0 = reserved for system usage 1 = real part of complex index of refraction 2 = radiance 3 = reflectance 4 = reflectance*solar spectrum 5 = transmission 6 = transmission*solar spectrum 7 = absorption 8 = absorption coefficient 9 = emissivity 10 = instrument noise spectrum 11 = unclassifiable
WAVEFILE	When a new ISL is being created, this optionally specifies the name of a Table file that contains a list of wavelengths and full widths at half maximum for the new ISL. (This file can be produced by the "bandtab" program, which extracts the information from an existing cube file.) If not specified, then the wavelengths will be obtained from the input spectrum Table file and no full widths at half maximum will be recorded in the new ISL. If the file extension is omitted, then ".tbl" will be assumed.
WAVEOBJ	Name of TABLE OBJECT in WAVEFILE that contains the input wavelength and full widths at half maximum for a new ISL.
ISLTO	Name of the output ISL file into which the input spectrum data will inserted. This can either be an existing ISL or the name of a new ISL to be created. If the file extension is omitted, then ".isl" will be assumed.
OMODE	Indicates whether TO is the name of an existing ISL file or a new ISL file to be created. Valid values are NEW or UPDATE.
CONVOLVE	Whether to convolve (YES or NO) the input spectrum data and secondary data arrays (if any) to the wavelengths of the ISL file.
REPLACE	Indicates whether the spectrum will be permitted (YES or NO) to replace an existing spectrum in the ISL that has the same SPECTRUM_NAME.
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and in the History entry that is put into the Hisory object of the output file.