Scan Angle

written by Carrie A. Gonzalez
cgonzalez@swri.org

Overview
Plot Format
Getting Started
1. Time Button
2. Data Source
Saving the Definitions
Changing the plot...

Overview

ScanAngle is a program which performs the plotting of spectral quantities for each angle range, azimuthal or polar, at each of the bin partitions utilized by the scanning dimension for the selected IDFS data set. The data is displayed in three dimensions: angle (x-axis), scan variable (y-axis) and intensity (z-variable). The z-axis or intensity variable can be any of the available units defined for the data parameter selected.

The ScanAngle program can be invoked in one of two modes: (1) interactive mode or (2) batch mode. In interactive mode, the program utilizes a GUI-based definition session to define the data parameters to be presented. The definition phase of the ScanAngle program has many options so that the user can tailor the displays to meet their individual needs. Once the definition session has been completed, the selected data parameters can then be displayed for the selected time range. To invoke the program in interactive mode, type ScanAngle at the command line. When the user is accessing the ScanAngle program from within the SDDAS viewer, the program is always invoked in interactive mode.

In batch mode, the interactive GUI-based definition session is bypassed and the data requested is immediately displayed based upon information contained in the named layout file. To invoke the program in batch mode, type ScanAngle -FName filename at the command line. The argument filename is the name of the layout file that is to be utilized during the current display session. Note that the name of the layout file does not include the .SA extension. If the named layout file does not exist, an error is displayed and processing terminates. In addition, batch mode can only be used for non-interactive graphics devices, which result in the generation of meta files that can later be printed. If the output device selection contained in the layout file is an interactive device, an error is displayed to the screen and processing terminates. However, the output device that is specified in the layout file can be overridden by specifying the device to be utilized as an argument on the command line. For a complete list of arguments that can be utilized in batch mode, the user is referred to the SDDAS Applications Batch Interface document.

Plot Format

The format that is used for plotting the data is selectable by the user, using a row and column specification. The maximum number of rows is set to ten. The maximum number of columns is dependent upon the variable selected to be plotted against the x-axis. If the x-axis parameter is polar angle, the maximum number of columns is set to six. If the x-axis parameter is azimuthal angle, the maximum number of columns is set to either the number of sensors defined for the selected IDFS data source or six, whichever is smallest.

For azimuthal plots, each row increases in time and each column represents sensor data to be displayed. The data is plotted one row at a time. Note that if the user selects the same sensor more than once (more than one column is to display the selected sensor), the data is merely duplicated since time increases according to row, not according to column. Annotation is displayed along the top row for each column, specifying which sensor is being plotted for that column. In the upper right-hand corner of the page, TIME is displayed for the first and last row of data. TIME is the start time for the data in the format hours:minutes:seconds. If there is only one row of data, both the start time and the end time for the data is displayed.

For polar plots, time increases from plot to plot, starting at the top of the page, displaying data column to column before proceeding to the next row of data. Unlike azimuthal plots, TIME is not displayed in the upper right-hand corner of the page; instead, the start time for the data is displayed along the top of each plot in the format hours:minutes:seconds.

For both types of plots, the year and day for the current plot is displayed in the upper-left hand corner of the page. A heading at the top center of the page is always displayed. This heading indicates the name of the satellite and the virtual instrument being processed and the spectral quantity being displayed. In addition, a label which specifies the units being processed is displayed along the top of the color bar. This label is defaulted, but can be changed by the user.

Getting Started

To commence the display of the ScanAngle program, a time range for which the data is to be acquired must be specified. This is achieved by selecting the "Time" button. Next, an IDFS source must be selected. This is achieved by selecting the "Data Source" button. Once a valid IDFS source has been selected, the "Attributes", "Data Binning" and "Scaling" buttons becomes visible. At this point, a plot can be displayed, since all other information is defaulted based upon information found in the PIDF file for the selected IDFS source. To plot the first page of data, select the pull-down Action menu from the main menubar and select the Draw option. Upon activation, the local database is checked to see if the requested data files are online. If data for the requested time range is not online, the ScanAngle program will ask the user if they wish to retrieve the requested data before the plotting of the data is enacted. If the user answers yes, the data will be promoted to the local disk before an attempt is made to display the data. If the user answers no, the ScanAngle program continues and tries to display the data, but the page layout will remain empty since the data is not available for processing.

The plots will be displayed on the output device selected by the user. The default selection is the XWindows device. If the user is accessing the ScanAngle program from within the SDDAS viewer, the plot will be displayed in the box area defined on the grid. If the user is running the ScanAngle program from the command line, the plot will be displayed in an area designated as the output area for the window being utilized. If the output device selected is a bus hard-copy device, the plotting of the data will be done concurrently by another process, with the results being sent to a meta file.

Based upon the time range specified by the user, the ScanAngle program may generate more than one page of data. In order to proceed to the next page of data, the Draw option must be utilized. A full page of data is always displayed to the user for each "Draw" activation. Data will continue to be plotted until the user-requested end time has been reached or until an error condition is raised. When an error condition is encountered, a message is displayed and processing terminates. If the user- requested end time is reached before all rows are processed for the current page, rows that exceed the end time are cleared and left blank so that data from the previous page and the current page are not mixed together.

Saving the Definition

Once all the information has been defined, the information may be saved to a layout file for future retrieval. This is achieved by selecting the pull-down File menu and selecting the Save As option. The information defined is not saved by the program unless the user explicitly does so. Note that when providing the name of the layout file, do not specify the .SA extension. The ScanAngle program automatically appends the .SA extension to the name of the layout file upon creation of the file.

Changing the plot...

The remainder of this document gives an in-depth explanation of the options that appear on the various GUIs utilized by the ScanAngle program.

Graphics Options

Color Bar - specifies the color table used to display the data.

Value Color Table

Grayshade

Color

Earth Tones

Double Color
Output Device - specifies the device on which the plots are to be displayed.
This option is not presented when the user is accessing the ScanAngle program from within the SDDAS viewer. The default value is XWindows. The other devices listed are hardcopy devices which are currently supported. If an output device other than XWindows is selected, the plots will be sent to a meta file, which must be manually sent to the appropriate device upon completion. The name of the meta file is composed of a prefix that identifies the device and the process id of the program that generated the meta file.

Value	Color Table
Grayshade
Color
Earth Tones
Double Color

Attributes

The Infer button is used to default all options based upon information found in the PIDF file for the selected IDFS data source.

Lower Cutoff - value that represents the smallest data value that is to be included when collecting the data. The value should be entered in terms of the Data Unit being processed. The Lower Cutoff value must be less than the Upper Cutoff value. The default value represents the smallest data value that is recognized by the IDFS data access routines.
Upper Cutoff - value that represents the largest data value that is to be included when collecting the data. The value should be entered in terms of the Data Unit being processed. The Upper Cutoff value must be greater than the Lower Cutoff value. The default value represents the largest data value that is recognized by the IDFS data access routines.
X-Axis Parameter - indicates the variable to be plotted against the x-axis. This option will be defaulted based upon information retrieved from the PIDF file for the IDFS data source selected. If the IDFS data source acquires both azimuthal and polar angle information, the user may alter the variable being plotted against the x-axis; otherwise, the user may not change this option.
- Azimuthal - plots the azimuthal angles against the x-axis.
- Polar - plots the polar angles against the x-axis.
Phi Width - the angular span each data bin must encompass when processing is done according to the azimuthal angle associated with each data point. This option is pertinent only to those IDFS data sources which return azimuthal angle information.
Location Of Zero - specifies where the zero degree value is to be located along the x-axis. This option is pertinent only to azimuthal plots.
- Left - zero degree value is located at the left-most end of the x-axis scale (0 to 360).
- Center - zero degree value is located in the middle of the x-axis scale (-180 to 180).
Avg Method - the scheme to use in order to reduce the dimensionality of the data for polar plots. This option is only pertinent to polar plots which access data sets that return azimuthal data.
- Straight Average - the simplest of the three data reduction methods. This method is a simple average of the data between the range specified by the Start Range and Stop Range options and is represented by the equation
- Straight Integration - the data is reduced by integrating over the range specified by the Start Range and Stop Range options using the format
- Spherical Integration - identical to the straight integration reduction scheme except for the integration over sensors which is of the form
  
  This integration scheme may be appropriate when the sensors represent discrete angular ranges.
Int Method - the formalism by which the integral is taken.
- Point - a trapezoidal integration using the center of each bin as the integration parameter.
- Band - the bin widths of each bin are used as the integration widths in a rectangular or block integration.
Normalize Data - indication if the data is to be normalized after the integration (Straight or Spherical) is performed.
Start Range - the starting angle value used to collapse the data over the PHI dimension. This option is pertinent only to those IDFS data sources which return azimuthal angle information and for which a polar plot has been selected.
Stop Range - the ending angle value used to collapse the data over the PHI dimension. This option is pertinent only to those IDFS data sources which return azimuthal angle information and for which a polar plot has been selected.
Data Accumulation - indicates if the data is to be acquired in terms of individual spectras (sweeps) or in terms of spins.
No. Of Data Sets - the number of data sets that are to be acquired and processed for the retrieval of data (value between 1 and 1000).
Data Units - the level of data processing to be applied to the selected IDFS data source; that is, the unit in which the data is to be displayed.
This option reflects the intensity (z-axis) which is represented by the color bar. When this option is changed, the scaling factors for the color bar are updated to reflect the range covered by the selected unit. The Data Units option is defaulted to the last data unit defined for the selected data parameter.
Scan Units - the unit for the scanning dimension.
This option is represented along the y-axis. When this option is changed, the scaling factors for the y-axis are updated to reflect the range covered by the selected unit. The Scan Units option is defaulted to the last scan unit defined for the selected data parameter.
Number Of Rows - the number of rows to be displayed.
The rows reflect time advancement for azimuthal plots.
Number Of Columns - the number of columns to be displayed.
The column value determines the number of data parameters (sensors) to be processed for azimuthal plots. The maximum number of columns is set to either the number of sensors defined for the selected IDFS data source or six, whichever is smallest. The value is defaulted using this same criteria.
Select Azimuthal Sensors - button which activates the "Azimuthal Sensors" GUI which is used to define the sensors that are to be displayed in the columns defined for azimuthal plots.
This button is hidden for polar plots since sensor selection is not applicable; that is, all sensors are needed in order to produce polar plots.

Data Binning

Once the IDFS data source has been selected, binning information must be provided. The binning information is defaulted based upon information contained in the PIDF file for the selected data source. For the ScanAngle application, all sensors are binned using the same binning scheme; therefore, PIDF sensor zero is used to define the binning scheme that will be used by all sensors. The user need not concern themselves with this information unless a change in binning schemes is desired, which can be achieved by selecting the "Data Binning" button.

Scaling

The Infer button is used to default all options based upon information found in the PIDF file for the selected IDFS data source. For color bar information, the information retrieved from the PIDF file is based upon the selected Data Unit. For the y-axis information, the information retrieved from the PIDF file is based upon the selected Scan Unit. For the x-axis information, the min/max range is set based upon the selections for the X-Axis Parameter and Location Of Zero options. For polar plots, the range is set from 0 to 180. For azimuthal plots with a left location of zero, the range is set from 0 to 360. For azimuthal plots with a center location of zero, the range is set from -180 to 180.

Color Bar Scaling - the scaling for the color bar.
- Linear - scale the color bar linearly.
- Log - scale the color bar logarithmically.
Color Bar Min - the minimum value for the color bar.
The color bar min value must be less than the color bar max value.
Color Bar Max - the maximum value for the color bar.
The color bar max value must be greater than the color bar min value.
Color Bar Label - label indicating the units represented by the color bar.
The color bar label may be changed to any eleven-character alphanumeric label. If the label is longer than eleven characters, the user will be asked to truncate the label.
Y-Axis Scaling - the scaling for the y-axis.
- Linear - scale the y-axis linearly.
- Log - scale the y-axis logarithmically.
Y-Axis Min - the minimum value for the y-axis.
The y-axis min value must be less than the y-axis max value.
Y-Axis Max - the maximum value for the y-axis.
The y-axis max value must be greater than the y-axis min value.
X-Axis Scaling - the scaling for the x-axis.
- Linear - scale the x-axis linearly.
- Log - scale the x-axis logarithmically.
X-Axis Min - the minimum value for the x-axis.
The x-axis min value must be less than the x-axis max value.
X-Axis Max - the maximum value for the x-axis.
The x-axis max value must be greater than the x-axis min value.

Azimuthal Sensors

An IDFS sensor is defined as a primary data source returned by the IDFS data source in question. The primary data sources returned by the selected IDFS source are presented in two lists entitled Sensor Group and Sensor. The PIDF file utilizes these two groupings to allow an additional level of subdivision within the primary data sources. This scheme is useful when the IDFS source contains a large number of primary data sources representing a diverse set of measurements.

The user must select one IDFS sensor for each column requested. There can be a maximum of six columns. If the IDFS data source selected has fewer than six sensors defined, the maximum number of columns is equal to the number of defined sensors. The sensor selection is defaulted once the IDFS data source is selected, starting with the first sensor defined (sensor zero) and ending with the last sensor defined or sensor five, depending upon the number of columns selected. In addition to selecting the sensor to be displayed, a label must be defined. This label is displayed at the top of the column.

The Infer button is used to default all options based upon information found in the PIDF file for the selected IDFS data source. When enacted, the sensors are selected sequentially, from the first sensor to the number of sensors defined for the data source until all columns are specified. The following is a brief explanation of the three options associated with each column.

Sensor Group - the available sensor groups defined in the PIDF file for the selected IDFS data source. Sensor groups represent data subsets within the data source.
Sensor - the available sensor components associated with the sensor group selected. Sensor components are data subsets of sensor groups and are defined in the PIDF file for the data source selected.
Label - the label to be displayed along the top row of the layout for the column being defined. The label is defaulted based upon the sensor selected but may be changed to any eleven-character alphanumeric label. If the label is longer than eleven characters, the user will be asked to truncate the label.

Time

In order to set the time values, enter the values in the boxes that appear next to the time component being set or use the sliders. The stop time must be greater than the start time. The time is initially set to the current time. By Julian convention, January 1 is day 1.

Data Source

The user must select a project, satellite, experiment, instrument and virtual instrument from which data is to be acquired and displayed in the ScanAngle graphics presentation. To change any of the selected options, click on the buttons on the right hand side. Note that all lineage information under the branch being changed is no longer applicable and must be re-selected. When the IDFS data source is changed, all GUI options are reset based upon information in the PIDF file for the newly selected source.

File Button

New - clears current definition for re-start
Open - loads a pre-existing layout file (.SA) into memory
Save - saves the current definition into a layout file
Save As - saves the current definition to a new file name
Delete - deletes a layout file
Print - create the graphics image in the selected format
Quit - terminates the program

Action

Displays the selected IDFS data parameters for the selected time range in a ScanAngle presentation. Once the first page has been displayed, this button serves as a page advancement button.

Scan Angle

Table Of Contents