XYPlot is a program which performs spectral plotting of data that has been stored in the Instrument Description File System (IDFS) format. The IDFS format is a data storage format that is designed to be general enough to handle the majority of scientific data sets. These data sets include raw telemetry, processed data, simulation data and theoretical data.
In most cases, the data parameters to be displayed are referred to as IDFS sensors. An IDFS sensor is defined as a primary data source returned by the virtual instrument in question. However, in some cases, the data parameters may be SCF output variables. The SCF (Science Computation Formulation) system provides for the creation of new data products from an existing primary data set (IDFS). In some cases, these derived products may be dependent upon values returned from a single instrument; in other cases, the derived products are dependent upon values taken from many instruments. For a more in-depth explanation of the SCF system, the user is referred to the paper entitled "The Science Computation Formulation System".
The XYPlot program has the ability to draw data from multiple sources against a single axis. These sources may be IDFS sensors from the same virtual instrument, IDFS sensors from different virtual instruments, and/or SCF output variables from a single SCF definition file. In any case, the data must be time-rectified; that is, data from all sources must form an equal time measurement increment. For example, IDFS data that is returned at 8 second, 4 second and 2 second rates may be plotted on the same graph, as long as the data is time-synchronized.
IDFS data sources are defined as either scalar instruments or vector instruments. A scalar instrument returns singular data quantities that are dependent only upon time and position. A vector instrument returns one-dimensional data quantities that have a functional dependence on a single variable, which in IDFS terminology is called the scanning variable. The XYPlot program does not allow the selection of scalar instruments or scalar SCF output variables since the data is displayed in two dimensions: data parameter and scan variable. The data parameters can be placed against either the x-axis or the y-axis, as selected by the user. The data parameters can be displayed in any of the available units defined for the selected data source. The IDFS format performs a real-time conversion of telemetry data into physical units as the data is accessed. This allows for the refinement of calibration factors and processing algorithms without having to reprocess the original data set.
The XYPlot program utilizes two schemes to derive the time-rectified spectra for the situation where only IDFS data parameters are selected. The user may either select the IDFS source that will dictate the time periods for which data is to be acquired per spectra or the user may specify the accumulation rate directly. If the user specifies the accumulation rate, the time period for the first spectra is determined by utilizing the start time associated with the first data source selected for the axes pair being processed. This data source is flagged as the "controller". To this start time value, the user-specified accumulation rate is added to define the end time. Each successive time period is calculated by adding the user-defined accumulation rate to the end time of the current time period, resulting in the start/stop time interval for the next spectra. For each spectra that is displayed, data will either need to be retrieved or the previous sample will hold for the current time interval.
If the user chooses to let an IDFS source dictate the time intervals for each spectra, data will first be acquired for the "controller" IDFS source. The time period covered by the data accumulation will dictate the time period that is to be acquired for all other IDFS sources. For the "non-controller" IDFS sources, data will either need to be retrieved or the previous sample will hold for the current time interval.
If the data sources are a mixture of SCF data and IDFS data, the XYPlot program utilizes only one scheme to derive the time-rectified spectra. The user must choose the SCF output variable that will serve as the "controller". The data for the "controller" SCF output variable will first be acquired. The time period covered by the data accumulation will dictate the time period that is to be acquired for all other SCF and/or IDFS sources. For the "non-controller" data sources, data will either need to be retrieved or the previous sample will hold for the current time interval.
Once the data has been acquired, the percentage of the sample to be included for the current time interval is determined. Based upon where the start time of the sample lies with respect to the start time defined for the time interval being processed, the fraction is either calculated with respect to the top edge (start time) or bottom edge (end time) of the time interval. The fraction should normally be between 0.0 (0%) and 1.0 (100%); however, if a gap was encountered by the "controller", the fractional values for the other data sets could be negative, indicating a time-stamp somewhere before the gap or in the gap region. A fractional value could also be negative if a gap was encountered and if the start time of the data is beyond the end time of the current time interval. If the fraction is negative, the data from that data set are not included in the current iteration of the algorithm. For positive fractional values, the data are multiplied by that fraction and the resulting quantities are accumulated for the current time interval. The fractional value is also saved separately and used to re-normalize the final quantity before it is displayed.
The XYPlot 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 XYPlot 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 XYPlot at the command line.
When the user is accessing the XYPlot 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
XYPlot -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 .XY extension. If the named layout file
does not exist, an error is displayed to the screen and processing terminates.
In batch mode, the designated time period for data processing can be modified
by utilizing command line arguments. Unlike other SDDAS applications, XYPlot
can process two separate time periods at the same time. If the designated
layout file defines two axes configurations, the two time periods specified in
the layout file must be identical in order to utilize the time period arguments.
If this is not the case, an error message is displayed to the screen 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.
The user is advised that the XYPlot application does not make use of the
graphics colormap file argument; that is, XYPlot always utilizes the
fcolor graphics colormap file.
The format that is used for plotting the data is selectable by the user. The display area will be segmented into one, two, four or eight regions (plots). The selection of multiple plots per page signifies time advancement of the selected data source(s). The spectra plots will be displayed in a ticked and numerically labeled box, with the x-axis and y-axis labeled to reflect the units selected. A time stamp (year, day and time of day) appears in the upper-left hand corner of the page, representing the start time of the first spectrum plotted and the end time of the last spectrum plotted. The XYPlot program will not display any heading on the page unless the user defines a heading. A heading consists of up to three lines of text to be oriented anywhere on the graph.
In addition to displaying the spectra, the XYPlot program will display a key on the right-hand side of the page. This key contains information about each spectrum. The key contains the symbol of each spectrum, if a symbol was requested, in addition to the name of the virtual instrument and the name of the IDFS sensor or SCF output variable selected. The entry in the key for each spectrum can be identified by the symbol of the spectrum if a symbol is displayed.
To commence the display of the XYPlot program, the configuration of the "graph paper" must first be performed. This is achieved by selecting the "Plot Configuration" button. The graph paper (the display area) has the capability of being segmented into multiple plotting areas, with the same data source(s) being displayed in the various plotting areas. When more than one graph is requested, the individual graphs represent time advancement of the data source(s).
The XYPlot program allows for data to be plotted against two sets of axes: (1) the left-bottom axes pair and (2) the right-top axes pair. The user may choose to plot the data source(s) against either or both sets of axes. The default scenario is to define data against the left-bottom axes pair. The definition of each axes pair is accomplished by selecting the "Configure Axes" button. The user may then define the line color and line style for the spectra, in addition to defining how data for each plotted spectra is to be acquired. A time range for which the data is to be acquired must be specified. This is achieved by selecting the "Time" button.
For each axes pair, the user can determine which axis will be the dependent axis (the data parameters) and which axis will be the independent axis (the scan variable). In order to define the data source(s) to be plotted against the dependent axis, either the "Y-Axis Data" or "X-Axis Data" buttons must be selected. At least one data source must be defined for the dependent axis. When the "Axis Data" button is selected, the Data Sources GUI is displayed. On this GUI resides a list which indicates the data sources to be plotted against the axis being defined. Initially, this list is empty. To add a data parameter to the list, the pull-down Insertion menu is utilized. Once the position for the data parameter to be added has been determined, the actual data parameter must be defined using the "IDFS Sensor Source" GUI. This GUI is automatically invoked when a new item is added to the list.
Once all data source(s) have been selected for the designated axes pair, one final piece of information must be provided IF the data acquisition is instrument-defined; that is, if the user is not specifying the delta-t accumulation period. The user must specify which data parameter will be the source that is used to control the data acquisition period for each plotted spectra. This is done by selecting the data parameter from the list and activating the "Attributes" button. This GUI contains the checkbox option This Source Controls The Timing. When this option is selected, the accumulation period is driven by the data acquisition rate for the identified data source. If more than one data source is flagged as the controller, the code simply uses the first data source on the list that has the checkbox option selected. If the data sources are a mixture of SCF data and IDFS data, the user must choose an SCF output variable to serve as the "controller".
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 data source(s). 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 XYPlot 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 XYPlot 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 XYPlot 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 XYPlot 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 XYPlot 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 graphs are processed for the current page, graphs 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.
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 from the main menubar 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 .XY extension. The XYPlot program automatically appends the .XY extension to the name of the layout file upon creation of the file.
The remainder of this document gives an in-depth explanation of the options that appear on the various GUIs utilized by the XYPlot program.
This GUI is utilized to control the configuration of the plot box. The user may change the scaling of the axes, the ticking of the box and the displaying of numeric and textual labels, to name a few of the controllable graphics issues. The bottom axis is identified as x1. The top axis is identified as x2. The left-hand axis is identified as y1. The right-hand axis is identified as y2.
Auto Scale - the range for the axes will be based upon the data retrieved for the data source(s) selected. The minimum and maximum of all retrieved data source(s) will define the range for the axes. The range is recomputed for each piece of graph paper displayed.
Manual Scale - the range for the axes will be specified by the user. The range remains constant for each piece of graph paper displayed.
This GUI contains options that allow for the definition of a heading to be placed at the top of the display.
Number Of Heading - the number of user-defined lines for the heading.
Label Font - the character font to be used to display all lines in the heading.
Label - the user-specified label to be displayed for the line being defined.
Label Size - the size of the characters to be displayed for the line being defined.
X-Axis Pos - the position along the x-axis for the line being defined.
Y-Axis Pos - the position along the y-axis for the line being defined.
Phi Ang - the azimuthal angle, in degrees, at which the line being defined is to be displayed.
Theta Ang - the elevation angle, in degrees, at which the line being defined is to be displayed.
Rot. Ang - the rotation angle, in degrees, at which the line being defined is to be displayed.
Hv - specifies whether the line being defined will be displayed horizontally or vertically, with the default specifying horizontal output.
Justify - specifies whether the line being defined will be left-justified, centered or right-justified at the given (x,y) location.
Color - the color to be used to display the label for the line being defined.
This GUI contains options that define the layout of the graph paper and the definition of the plot axes.
Plots Per Page - the number of plot boxes displayed for each page of data, with the default being set to one plot per page.
Plot Ordering - displays the time advancement ordering of the plot boxes for the configuration selected.
This GUI contains options that define the data acquisition scheme to be used to acquire the spectra, in addition to how the spectra is to be displayed (color, line style and plot type). In addition, the time range and the data source(s) to be acquired must be defined for the axes pair being defined.
Plot Type - indicates the type of line plot that will be displayed for all data sources plotted against the axes pair.
Log Zeros - indicates how to display a zero data value against a logarithmically scaled axis.
Log Negatives - indicates how to display a negative data value against a logarithmically scaled axis.
Be advised that the processing of negative values for a logarithmically scaled axis will take place prior to the determination of the scaling for auto-scaled plots.
Line Color - the color of the line(s) being plotted against the axes pair.
Line Style - the style of the line connecting points in a graph for data being plotted against the axes pair.
Y-Axis Data - button which activates the "Data Sources For Designated Axis" GUI which is used to specify the data source(s) to be plotted against the y-axis.
X-Axis Data - button which activates the "Data Sources For Designated Axis" GUI which is used to specify the data source(s) to be plotted against the x-axis.
Time - button which activates the "Time" Gui which defines the time range for which the data is to be acquired for the axes pair.
Time Stepping - determines how the time duration for each plotted data value or spectrum is to be derived for the axes pair.
Sweeps - the user specifies the number of sweeps that are to be acquired for each plotted data value or spectrum.
Spins - the user specifies the number of spins that are to be acquired for each plotted data value or spectrum.
In cases where SCF output variables are being displayed, the Delta T and Spins options are not applicable. If either option is selected, an error message is displayed when the user tries to plot the data, informing the user that they must change this option before the plotting can commence.
Resolution - indicates how the Delta T value will be defined.
Instrument-Defined - the time duration is determined using the maximum temporal resolution for a selected data source.
This widget is only displayed if the user selected Delta T as the Time Stepping option.
No. Of Incremental Time Units - a scaling factor to be applied to the maximum temporal resolution for the selected data source to derive the time duration for each plotted data value or spectrum.
Time Units - the amount of time to be used to acquire the data for each plotted spectrum.
This widget is displayed only if the user selected User-Defined as the
Resolution option. The value can be expressed in one of
four time units:
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.
To add a data parameter to the list, the pull-down Insertion menu is utilized. The menu options indicate the position within the list at which the current data parameter definition is to be inserted. These options include:
To delete a data parameter from the list, the pull-down Removal menu is utilized. Currently, this pull-down menu contains just one option
The "Data Source" button invokes the IDFS Sensor Source GUI. The "Attributes" button invokes the Data Attributes GUI. The "Binning" button invokes the Bins GUI. The "Averaging" button invokes the Data Averaging GUI, which is applicable only for IDFS sensors. If the data parameter is an SCF output variable, an error message is displayed when the user tries to access the "Averaging" button.
The user must select the project, satellite, experiment, instrument and virtual instrument from which data is to be extracted, in addition to specifying the sensor(s) to be acquired and displayed in the XYPlot 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 sensor is changed, all GUI options are reset based upon information in the PIDF file for the newly selected sensor.
Once the data parameter has been identified, the lineage for the data parameter is displayed on the list in the position selected. If the data parameter is an SCF output variable, the name of the SCF definition file is displayed after the lineage. This piece of information can be used to help resolve a possible SCF error condition. The XYPlot program has one restriction with respect to the plotting of SCF output variables: all SCF output variables that are to be plotted against the same axes pair must come from the same SCF definition file. If the SCF output variables come from separate SCF definition files, the user must choose which SCF output variables are to be deleted and/or moved to the other axes pair.
The XYPlot program does not allow the selection of a scalar IDFS sensor or a scalar SCF output variable for processing since the scan variable is one of the axis to be plotted. If a scalar IDFS sensor or a scalar SCF output variable is selected, an error message is displayed and the GUI will remain on the screen until a valid vector data source is selected. In addition, the option Data Types may contain several options to choose from, but the XYPlot program only allows the selection of Sensor data. If any other data type is selected, an error message is displayed and the GUI will remain on the screen until the Sensor data type is selected.
The Infer button is used to default all options based upon information found in the PIDF file for the selected data source.
If the IDFS data source selected uses spacecraft potential data in the conversion of the
values selected for the Data Units and / or the Scan Units
options, this menu option will become visible and may be changed from the default value
of "No" by the user.
Once the 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. The user need not concern themselves with this information unless a change in binning schemes is desired, which can be achieved by selecting the "Binning" button.
Some of the vector IDFS data sources return data that has a functional dependence on dimensions other than the scan dimension. The IDFS paradigm handles data that can have additional dependencies on charge, mass, phi angle and theta angle. When one of these IDFS data sources is selected, the data must be reduced to a 1-D quantity that is only dependent upon the scan parameter by averaging the data over the specified ranges for applicable dimensions. By specifying the ranges over which to collapse (reduce) the data, the resultant plot may actually be displaying data from multiple IDFS sensors instead of from the single IDFS sensor selected by the user. For example, if more than one IDFS sensor utilizes the same initial and final aperture elevation angles, the data for those sensors will be combined when collapsing over the specified elevation angle range. To ensure that the plot will only display data for the selected IDFS sensor, the XYPlot program has defaulted menu options such that data reduction is "turned off" (No Average).
The Infer button is used to default all options based upon information found in the PIDF file for the selected IDFS data source. The user should note that the Averaging GUI is not pertinent to SCF output variables.
The selection of this option has one of two possible meanings. Either the data has no dependence on any variables other than time and scan or the other dimensions are to be ignored and the vector data from the single selected IDFS sensor is to be processed.
![[Straight Average Equation]](pics/str_avg.gif)
![[Straight Integration Equation]](pics/noscan_str_int.gif)
where the range is defined by the volume integral, dΘ is the polar angle increment, and dΦ is the azimuthal angle increment. Note that angular measurements are converted to radians when producing the final answer.
![[Spherical Integration Equation]](pics/noscan_sph_int.gif)
where the range is defined by the spherical volume integral, Θ is the polar angle with increment dΘ, and dΦ is the azimuthal angle increment. Note that angular measurements are converted to radians when producing the final answer.
![[Flux Integration Equation]](pics/noscan_flux_int.gif)
where the range is defined by the spherical volume integral, Θ is the polar angle with increment dΘ, and dΦ is the azimuthal angle increment. Note that angular measurements are converted to radians when producing the final answer.
The hemisphere assumption factor is dependent upon the dimension being processed
and the scheme (method) selected in order to reduce the dimensionality of the
data. The hemisphere assumption factor is not selectable by the user. The
hemisphere assumption factors were obtained for each method assuming angular
isotropy. The table below summarizes the values used for assumption factors
during processing:
DIMENSION
STRAIGHT INTEGRATION
SPHERICAL INTEGRATION
FLUX INTEGRATION
CHARGE
n / a
n / a
n / a
MASS
n / a
n / a
n / a
PHI
n / a
2 pi
2 pi
THETA
n / a
1
0.5
Currently, this pull-down menu contains just one option
This option is not presented when the user is accessing the XYPlot program from within the SDDAS viewer. When this program is invoked from within the viewer, the user should go to the box that contains the XYPlot plot, click on the right mouse button and select one of the options presented or use the Action button provided by the viewer.