**[2-Dimensional Spectrograms:]{.underline}**

**Introduction:**

2-dimensional spectrograms display either energy on the vertical axis
and spin angle on the short horizontal axis or vice versa. The major
horizontal axis is time. The panels can be either ion mass for a
specific polar channel or polar channels for a specific mass.

Each count if converted to flux. Any flux value below the user-requested
minimum flux value is set to the minimum and any flux over the maximum
is set to the maximum. The color table index is calculated by dividing
the flux value by the flux difference (flux maximum minus flux minimum)
and multiplying by 221 and adding five. This gives a color table index
between 5 and 225.

**Plot description:**

The output plot filename has the standard format:
**tyymmddh1m1_h2m2.ext2.ext1.ptype** where **t** stand for TIDE,
**yymmdd** is the 2-digit year, month, and day-of-month of the plot
start time, **h1m1** are the start hour and minute, **h2m2** are the
stop hour and minute, **ext2** is an optional file extension used to
distinguish plots processed differently but with the same start/stop
times, **ext1** is the Spectrogram extension, and **ptype** is the plot
type. If **h2m2** is smaller than **h1m1**, the plot crosses a day
boundary.

There are five types of 2-D spectrograms. For the first four types the
file extension **ext1** lists the horizontal dimension first, the
vertical dimension second, the panel dimension third, and the page
dimension fourth. You will get a plot page for every mass or channel
requested. Because these plots require both masses and polar angle
channels they should not be used to display Stops data. The fifth type
(esse) was set up for Stops data. polar channel is **p**, spin angle is
**s**, and energy is **e**.

**espm** energy on horizontal axis, spin angle on vertical axis, the
panels are polar angle

channels, one mass per page

**esmp** energy on horizontal axis, spin angle on vertical axis, the
panels are masses,

one polar angle channel per page

**sepm** spin angle on horizontal axis, energy on vertical axis, the
panels are polar angle

channels, one mass per page

**semp** spin angle on horizontal axis, energy on vertical axis, the
panels are masses,

one polar angle channel per page

**esse** energy/spin and spin/energy panels for one mass and one channel
plus orbit

plots or text labels

Samples of each type of htr spectrogram are in
/archive/tide_docs/ProcFiles/Spect2d/Plots or
<http://satyr.msfc.nasa.gov/archive/tide_docs/ProcFiles/Spect2d/Plots/>.

IDL creates gif (**.gif**) and postscript (**.ps**) plot types
(**ptype**). A pdf (**.pdf**) file was created from the postscript file
because the .pdf file is much smaller but provides the same resolution.
Thumbnail jpeg (**.jpg**) were created from the .gif files.

As with most TIDE plots, there is some documentation at the bottom of
the plot that includes the processing software version number; date the
plot was created; plot filename; whether or not the minimum count was
subtracted; the names for the sector sensitivity, calibration, and mass
calibration files used in processing; source or value of the spacecraft
potential used; and the names of the mask, attitude, orbit, and
level-zero files used in the processing.

Above these are the time axis labels including time (hh:mm), Re,
L-Shell, magnetic local time (mlt), magnetic (mlat) and invariant
(invlat) latitude. In addition to the orbit text labels, **esse** plots
have the option to plot the orbit data. The orbit plots include Re,
L-Shell, mlt, mlat, and invlat as a function of time and 3 GSM Polar
orbit plots: Z versus X, Z versus Y, and Y versus X.

At the top left of the plot, the standard labeling includes the title
line (POLAR TIDE/PSI), the start and stop times of the plot, the number
of spins averaged, the data collapse option (see the TIDE Flight
Software Requirements Document, page 10-13 for collapse option details
http://satyr.msfc.nasa.gov/archive/tide_docs/old_docs/TIDEFlightSoftwareRequirements.pdf
), and a plotted indication of the operational status (operational,
standby, off, or mirror stepping) of both TIDE and PSI. The flux color
bar is on the upper right. In the top center is the ranges over which
the flux sum or average was created. This is almost always the full
range but it doesn't have to be.

On panels with spin angle as the vertical axis, an **\*** is used on the
axis to indicate the location of the sun pulse. The ram (**x**) and
positive (**+**) and negative (**-**) magnetic field directions are
indicated on the panel image in white.

The time axis is set up to display as much data as possible. The time
axis is made up of a series of spin-averaged sets of data. Each spin is
six seconds long. The number of spins average for each set of data on
the plot depends on the user-specified length of time for the total plot
and the dimension displayed on the horizontal axis. The start and stop
times of the plot and the number of spins averaged for each set of data
appears at the top left of a plot. There can be up to 30 sets of spin
averaged data per plot.

**Color Tables:** The IDL version of the software allows the user to
pick from several color tables. Usually only the first one is selected.
The web only allows the use of the first color table. The color table
text files are available in /archive/tide_docs/ProcFiles/DataFiles. The
tables are blue-cyan-green-yellow-red (bcgyr.tbl, original/default),
black-red-orange-yellow-white (broyw.tbl),
black-blue-green-orange-pink-white (bbgopw.tbl), black-gray-white
(black_white.tbl), and white-gray-black (white_black.tbl). In all cases
the table has 226 colors. The first 5 colors are used just for plot
labeling. The remaining 221 colors are used to create the spectrograms.
All 226 appear in the color bar at the top of each spectrogram plot. The
archive directory also has pdf plots of the color tables.

**lz-parm command files and tide_lz input files:**

All processing is controlled from the parameter file created using
**lz_parm**. See ParameterFileCreation.doc or
<http://satyr.msfc.nasa.gov/TIDE/Documentation/ProcessingSoftware/ParmFileSpect.html>
for details on creating the spectrogram parameter file from **lz_parm**.
**lz_parm** can be run from a UNIX shell script that makes **lz_parm**
easier to use. Sample command files, those used to create the parameter
files that were used to create the sample plots are in
/archive/tide_docs/ProcFiles/Spect2d/ParmCmd
(<http://satyr.msfc.nasa.gov/archive/tide_docs/ProcFiles/Spect2d/ParmCmd/>).
Sample **tide_lz** input files (list of start and stop time and
associated input files) are in /archive/tide_docs/ProcFiles/InputFiles
(<http://satyr.msfc.nasa.gov/archive/tide_docs/ProcFiles/InputFiles/>).

**web-interface:**

2-D spectrograms can be created using the TIDE Custom Plot
web-interface. The first four 2-D spectrogram types (**espm, esmp, sepm,
semp**) are created using the Spectrogram Plots webpage
(http://satyr.msfc.nasa.gov/TIDE/lz_spectrograms.shtml). **esse** plots
are created using the Energy-Spin/Spin-Energy Plots webpage
(http://satyr.msfc.nasa.gov/TIDE/lz_esse.shtml).

All of the prompts are designed to get the input used to create the
lz_parm parameter file and the tide_lz list file that contains the start
and stop times and a list of input files associated with that time
range. The webpage is filled in with some defaults that you can change.

The first menu items for all five types asks for the start and stop date
range of the data to be processed. The date can be enter as
year/day-of-year (**yyyydoy**) or year/month/day-of-month
(**yyyymmdd**). The year must be four digits. Time is entered in
hour/minute/second (**hhmmss**). Seconds must be included even if they
are **00**. Do not use any spaces. Use the tab key or the mouse to move
from one date/time field to the next.

For **esse** plots, select the mass and polar angle channel to plot. For
Stops, the polar angle channel is always 4. Stops data have been summed
over all channels. The resulting sum in reported in channel 4 data
products. If the mass is Stops, you need to enter the mass-to-charge
ratio of the ion used in the flux calculation. For the other plots, you
select the dimension used for each panel (either channel or mass), the
dimension on the horizontal axis (energy or spin angle), and each of the
masses and the channels to be plotted as panels and pages.

For all five plot types the remainder of the menu asked what flux unit
(usually energy flux) to use, the minimum and maximum flux values to use
on the colorbar, what mask to use, whether or not to correct the mask
subtraction (See TIDE\\documentation\\new\\DatafileFormat\\mask.doc for
details), whether or not to use the sector sensitivity correction (See
InstrCalibration.doc), and whether or not to subtract the minimum count
(See MinimumCountSubtraction.doc for details). For **esse** plots, there
is one final menu item that asks how to display the orbit data, as the
standard test labels or as plots.

Once you have made all the changes you want to the default plot settings
'**Submit request**'. To clear the form '**Reset Form**'. Once you
'**Submit request**', the web server queries the File Location Table to
get a list of the input files needed for the processing and where they
are stored. This information is used to create the **tide_lz** list
file. The information provided via the menu is used to create the
parameter file via **lz_parm**. The web server uses the parameter and
list files as input to the idl version of **tide_lz** (@**run_tide**).
Once the processing is completed and the postscript, gif, and pdf files
are created, the gif images are returned as a webpages. For the 1996 ion
data and plot types **espm, esmp, sepm, semp**, if you requested more
than one mass or channel, there will be a plot and a webpage for each
mass or channel. There are arrows at the top of each gif webpage that
let you navigate between the plots. The plot files can be downloaded
from these webpages. The plot files remain in a staging area
(<http://satyr.msfc.nasa.gov/stage/>) for three days. They can also be
downloaded from the staging area. The web uses the job process id as the
optional **ext2** filename extension.