This HELP text describes the operation of this IDL viewing and analysis program
which allows a user to:

(1) view ISIS-1 or ISIS-2 topside ionogram files retrieved from the National
Space Science Data Center (NSSDC), optimize the displayed frequency and/or
apparent-range scales and apply amplitude thresholding if desired, and print the
resulting ionogram image with world-map information,

(2) perform precise scaling of frequency-mark onset times and produce new
ionogram files with frequencies based on interpolations between these new onset
times,

(3) calculate frequencies of resonances and wave cutoffs based on one selected
resonance or wave cutoff input value,

(4) produce plots including topside electron-density (Ne) profiles from the
ionogram reflection traces and

(5) produce output files that will allow these profiles to be combined to
produce topside Ne contours along the orbital path.

Upon start up, there is a pull-down menu in the upper left corner entitled ISIS
Properties with the following 8 options:
	Load CDF
	Load Binary (.os2bin)
	Load Binary (.bin)
	Traces
	Res/Cutoff
	Line Plot
	Color
	Output
The first three allow a choice of input files, the second-to-last allows the
user to select the desired color for the amplitude-modulated signal intensity
and the last one is used to output the ionogram image. The other three are used
to work with the data.  Descriptions follow:

Load CDF

Row #1 (top): Exit to quit program. Help to read this help text. Amplitude
thresholding: "min" and "max" sets the limits of the relative amplitude scale.
The default value covers the complete relative amplitude range (linear scale)
from 0 to 255. If the values are changed so as to view the ionogram with
different amplitude limits, click the 'ENTER' button.  (If the displayed
amplitude range is acceptable, there is no need to click 'ENTER'.)

Row #2: cursor gives the 5 coordinates of the cursor: 2 on x (sweep time in
seconds & frequency in MHz), 2 on y (delay time in ms & apparent range in km)
and the relative amplitude (linear scale from 0 to 255 which corresponds to
4.5V).

Row #3: Select CDF to start over with the file selection process, i.e., select
the directory containing the ISIS CDF files and then the ISIS CDF file for
scaling.  After selecting a file, click "OK" and the corresponding ionogram is
displayed on the screen.  Previous to go back one ionogram.  Next to go forward
one ionogram.  Filter to clean up ionograms containing many vertical lines
(caused by amplitude vs. delay-time scan lines at a given frequency that usually
only contain a few data samples, called overflow scan lines, which are sometimes
produced during the A/D operation).

Row #4 : min & max time to select desired sweep times. min & max apparent range
to select desired apparent ranges.  Re-size after making previous selections
(can also be used without making previous selections to re-size ionogram to fit
screen display).  Reset to return to full original display.


Color

Row #3: Color contains a pull-down menu with color options for the ionogram
display.
Row #4: Color X & Color Y contains pull-down menus with color options for the
scaled trace points on the ionogram display.


Output

This option is used to output the ionogram image with a file name where the last
two characters have been changed as desired (a-z, 0-9).


Traces

Here the user can interactively scale the ionospheric reflection traces on
ISIS-1 or ISIS-2 topside ionograms and invert them to vertical  Ne profiles from
the satellite altitude down to (or slightly above) the altitude of the Ne peak.
(Propagation conditions, due to antenna orientation and medium characteristics,
determines how close the profile extends to the peak altitude.)  This program is
based on scaling two of the three ionospheric reflection traces that usually
appear on topside ionograms, namely, the extraordinary (X)- and ordinary
(O)-mode traces.  The third trace, due to the slow branch of the X mode, is
known as the Z-mode trace and is not scaled even though it is often more
prominent than the O-mode trace (particularly at mid-to-high latitudes).  The
Z-mode trace has a wave cutoff frequency at the satellite (fZS) which is less
than that of the O-mode trace (fOS) which, in turn, is less than the that of the
X-mode trace (fXS). The Z-mode trace is often helpful in identifying the start
of the O-mode trace since it often reaches its maximum delay time (or apparent
range) near the electron plasma frequency resonance (particularly at mid-to-high
latitudes) which corresponds to fOS.  The calculation of the vertical topside Ne
profile is based on the scaling of the X-mode trace.  The scaling of the O-mode
trace is performed in order to obtain confidence in trace identification,
quality of scaling and validity of the assumptions used in the inversion
program.  This confidence, or lack thereof, is obtained by inspecting the plots
that are available after executing the analysis program.

This analysis program includes a FORTRAN true-height analysis program, based on
the work of John E. Jackson [Proc. IEEE, 57, 960-976, 1969], and FORTRAN
programs to calculate the geographic coordinates of the satellite and the
corresponding magnetic parameters (WORLD-MAP, FIELDG programs; the latter uses
an epoch date of 1965). 

The first two rows under Traces are the same as described for Load CDF above.

Row #3 contains:

Scale Trace contains two options in a pull-down menu:
	Scale X trace to be selected first and
	Scale O trace to be selected after the X-trace scaling is complete.

Jackson contains four options in a pull-down menu:
	Variable Known assumes a variable satellite position and a known FXS
        value,
	Variable Unknown assumes a variable satellite position and an unknown
        FXS,
	Fixed Known assumes a fixed satellite position and a known FXS value,
	Fixed Unknown assumes a fixed satellite position and an unknown FXS.

Save File contains a suggested file name for the output data file for
the scaled X- and O-mode traces.  It contains the directory name, satellite
identification (i1 or i2 for ISIS 1 or 2), the 3-character station code, the
last two digits of the year, the day number, the UT hour minute and second
corresponding to the ionogram frame-sync time and two characters to designate
the version number for the scaled ionogram trace (a-z, 0-9).

Cleanup All Traces to remove "O" & "X" symbols on traces from previous scaling.

Object Plot contains five options in a pull-down menu:
Plot O displays the O-mode trace, calculated from the Ne profile deduced from
the scaled X-mode trace, together with the scaled X-mode points and the scaled
O-mode points for comparison with the calculated O-mode points.  Good agreement
provides a degree of confidence in the assumptions used by the Jackson
true-height analysis program (vertical propagation in a horizontally-stratified
ionosphere) and in the identification of the scaled ionogram traces.
Plot Ne displays the Ne profile deduced from the scaled X-mode trace.
Plot fN displays the electron plasma frequency profile deduced from the scaled
X-mode trace.  Note: [fN (kHz)]**2 � 80.6 [Ne (cm-3)].
Plot 3-Ne allows three Ne profiles to be plotted on one figure (as selected from
a list of three or more Ne files from previously-scaled ionograms).
Plot multi-Ne allows similar plot as above except for more than three Ne
profiles.
Direct Plot same as above except based on a different IDL program option.

Row #4 Re-Load Trace File contains 5 options in a pull-down menu that allows a
previously-scaled X-mode trace (.tra) file to be loaded so that this same .tra
file can be used for one of the other 3 Jackson-program options.  (Note: the
option used to produced the .tra file under investigation is given in the upper
right hand corner of one of the plots described above.)


Row #5 Output to Traces File allows the file name for a trace file, or the files
for the Object or Direct plots, to be changed before selecting Save Traces as
File. It is suggested that changes be made to the last two characters (a-z, 0-9)
to designate new version numbers.

Row #6 (below ionogram display) Output Information contains information
concerning the status of the attempt to run the Jackson true-height analysis
program.

Scaling procedure to follow under Traces:

After selecting Scale X trace under Scale Trace, use the mouse button to enter
up to 50 points (with the frequencies monotonically increasing) along the X-mode
trace.  Next select Scale O trace and scale the O trace in the same manner.
(This scaling is only used to compare with the calculated O-mode trace from the
Jackson program.) After scaling the O-mode trace, select Variable Known under
Jackson.  If the program executes successfully, a message "Jackson program
ran successfully" appear in Output Information below ionogram and graphs will
result from initiating options under Object Plot.  If it doesn't run the message
"Jackson program failed, return to Load CDF to reload ionogram (Select CDF) and
try again" will appear below the ionogram.  The user can (a) re-scale the
ionogram and try the same option under Jackson, (b) re-scale the ionogram and
try a different option, or (c) re-load one of the previously scaled X-mode trace
files for this ionogram, if available, and try one of the other option under
Jackson.



Res/Cutoff calculates resonances and cutoff values after a mouse click is made
on a resonance or cutoff believed to have been correctly identified.

The first two rows under Res/Cutoff are the same as described for Load CDF
above.

Row #3 contains 8 options, from Z cutoff through Qn Resonance; the last 4
contain pull-down menus. Click on the appropriate option after clicking on the
corresponding resonance or cutoff feature.  The results of calculating a large
number of resonance and cutoff values from this input value (and the model value
for fH - or an input value as entered on row #5 below) are given on a separate
screen.  Some of the principal values are given under Output Information below
the ionogram display.

Row #4 Output to Res/cutoff File allows a file name to be selected for the
calculated resonance and cutoff values (the results from several input
selections on one ionogram are all on the same file).  New File saves the file
name given at the left.

Row #5 Input values displays scaled resonance or cutoff values and fH from model
(or from input if input value is entered).

Output Information (below the ionogram image) displays the input scaled
resonance or cutoff value, the input fH value and calculated values of some of
the principal resonances & cutoffs (more values are given on a separate screen).



Line Plot allows detailed scaling of features from an amplitude vs. delay-time
scan corresponding to the location of the cursor click on the ionogram below. 
If it is used to accurately scale frequency-mark onset times, then a new
ionogram file can be produced based on interpolation between the new
frequency-mark onset times.

The first two rows under Line Plot are the same as described for Load CDF above.

Below these two rows a line plot appears after clicking somewhere on the
ionogram displayed below the line-plot window.  The resulting line plot displays
a receiver-amplitude vs. delay-time plot corresponding to the frequency line
selected by the mouse click.  To the right of the line-plot window are 4 control
buttons that allow the selected frequency/delay-time position to be controlled
either frequency-line by frequency-line (Left & Right) or range-bin by range-bin
in delay-time (Up & Down).  Freq Marks contains a pull-down menu with the
sweep-times corresponding to each of the frequency marks as determined during
the auto-detection routine during the A/D operation.  These times (which
correspond to the start of the first frequency line containing a frequency
marker over all delay times) can be replaced by a more accurate scalings of the
frequency-mark onset times based on the line plots.  This replacement is
performed by first positioning the line-plot indicator on the frequency-mark
onset time. Next, select the appropriate frequency marker from the pull-down
menu.  Each time this process is performed, an asterisk is placed in the
appropriate location in the pull-down menu. Use "Write Revised Ionogram File" to
create a new ionogram based on interpolations between these new frequency-mark
onset times.  This capability allows the user to salvage an ionogram for
scaling that originally had negative frequency values (indicating that the A/D
auto-detection routine could not confidently identify the frequency markers).
In order to scale this new ionogram, it is necessary to return to Load CDF
under ISIS Properties and choose Select CDF to find the file just created.
Use "Write Amplitude File" to produce an output A-scan file corresponding to the
displayed amplitude line plot. The default is a file for a single scan line.
If more lines are desired in the file, enter the number in the box below.
The file name, displayed in the window below the ionogram, will include the time
of the A-scan displayed and the number of lines (up to 9999) in the file. 
Note: a typical ionogram contains of the order of 1000 lines.  The file will
contain the sweep time, interpolated frequency of the line scan, the
corresponding AGC voltage and the number of rows of data each containing delay
time, apparent range, amplitude(0-255) and the calculated receiver input power
PI in dBm.  Note: the above coordinates and corresponding amplitude values are
also recorded with each mouse click in the window display below the ionogram.

Between the line-plot & ionogram displays, Displayed circle gives the 5
coordinates of the displayed circle on the ionogram display.  This circle will
persist into later windows selected under ISIS Properties.  It can be removed by
using Reset on the Load CDF display.






The current version of the Jackson true-height analysis program produces one
.tra and 10 .dat output files. The file resulting from the scaling of the X & O
traces has the extension .tra. It has the ionogram information used as the input
to the Jackson true-height analysis program plus additional information
concerning the amplitude of each scaled point.  The first two lines contain
world-map information corresponding to the time of the start of the X-mode
trace.  The next line contains header information with the ionogram frame-sync
time given to the millisecond.  It is followed by the number of points scaled,
and 7 columns of data for each of the scaled traces (X & O).  The first two
columns give the coordinates of the scaled point in terms of apparent range (km)
and frequency (MHz) (the Jackson true-height analysis program use these data as
input), the next two give the coordinates in terms of delay time (ms) and
ionogram time (sec) (relative to the frame-sync time).  The last three columns
give (1) the video amplitude (Ampl) of the scaled point using a linear scale
from 0 to 255 (where 0 corresponds to telemetry zero and 255 corresponds to a
video output of 4.5 V), (2) the automatic gain control voltage in volts (VAGC)
corresponding to the receiver listening scan line (vertical direction on the
ionogram) containing the scaled point, and (3) the calculated receiver input
power (pi) in dBm (decibels relative to 1 mW) based on equations that use Amp
and VAGC [H. G. James, Communications Research Centre, Ottawa, personal
communication, 1999].  

The first line of the first three of the ten .dat files contains header
information with the ionogram frame-sync time given to the millisecond.  On the
next seven files, the time corresponds to the first scaled point on the X-mode
trace.  The 10 .dat files are described below:

1.    x_fhp_SSSYYDOYHHMMSSTn          scaled X-mode trace (frequency (MHz) and
apparent range (km) values) as used by the program (may be different than
x_scal... file because some "offending" input points may have been removed
because the frequency was not monotonically increasing from point-to-point).

2.    x_scal_SSSYYDOYHHMMSSTn          originally scaled X-mode points (apparent
range (km), frequency (MHz), delay time (ms), ionogram time (sec) and amplitude
(linear scale from 0 to 255) of each scaled point).


3.    o_scal_SSSYYDOYHHMMSSTn          scaled O-mode trace (if present)
(apparent range (km), frequency (MHz), delay time (ms), ionogram time (sec) and
amplitude (linear scale from 0 to 255) of each scaled point).

4.    nhout_SSSYYDOYHHMMSSTn           original output file from the Jackson
true-height analysis program.  Information from this file has been used to
produce the files described below.  It is retained here because it may contain
additional useful information.  For example, it contains some parameters for
setting up and plotting contour plots (which the program no longer does - such
plots are now made from information in the appropriate output file using other
software packages).

5.    ne_prof_SSSYYDOYHHMMSSTn         calculated electron-density (Ne) profile
(Ne (cm-3) and true height (km).

6.    plas_freq_SSSYYDOYHHMMSSTn       calculated plasma-frequency (fN) profile
(fN (MHz) and true height (km)).

7.    ne_sel_alt_SSSYYDOYHHMMSSTn      Ne at selected altitudes (true height
(km) and Ne (cm-3)).

8.    alt_sel_ne_SSSYYDOYHHMMSSTn      altitude at selected Ne (true height (km)
and Ne (cm-3)).

9.    o_tra_SSSYYDOYHHMMSSTn           calculated O-mode trace (frequency (MHz)
and apparent range (km)).

10.   wmap_SSSYYDOYHHMMSSTn            world map information corresponding to
the first scaled X-modemode trace point)

   where SSSYYDOYHHMMSSTn is:

    SSS   station id
    YY     year
    DOY   day of year
    HH      hour
    MM     minute
    SS      second
    Tn       version number

    (example: NE_PROF_QUI70108194608T1.DAT)



-- 
Robert F. Benson
Code 692, NASA/Goddard Space Flight Center
Greenbelt, MD 20771
Phone: 301-286-4037
Fax:301-286-1433
email: robert.f.benson@nasa.gov
