Sondrestrom Radar Visualization Tool (ver 4.0) 1. Background This document is a brief user's guide to the batch mode of the Sondrestrom radar visualization tool (SRVT). The SRVT has been developed with support from NASA's ISTP program to enable the visualization and analysis of ground-based data from the Sondrestrom incoherent scatter radar facility (66.99 N Lat., 50.95 W Lon.). The main difference between v. 4.0 and prior versions of the SRVT is the ability to process a large number of radar scans in a batch mode. Note, the batch mode works only on scan data, that is, elevation, azimuth, or composite scans. Before we describe specific SRVT v 4.0 functions a few general comments are in order: ** Required Platform. The SRVT has been written with IDL v 3.5 and has been tested on laptop, PC and UNIX machines. The `True Batch' feature (described below) invokes the UNIX `at' command and will thus only work on a UNIX platform. Most likely SRVT v 4.0 will run on earlier versions of IDL as the widgets are simple and we avoid calls to exotic IDL functions. The SRVT requires the host machine to be capable of rendering eight-bit color images with a resolution no smaller than 680 by 530 PIXELs, as such small displays severely distort the on-screen fonts. At least 32 Mbytes of RAM are recommended. ** Hardcopy Requirements. The SRVT code requires that a PostScript compatible laser printer is available for making black and white or color hardcopies. In order to correctly specify the print command and path to your local printer, two procedures must be customized: `goprint.pro' (interactive printing) and `batprint.pro' (batch printing). In procedure `goprint.pro', the exact syntax required to access your local printer should be inserted at lines 18 and 26. These two lines define strings of the form: printcom_BW = 'lp' + psname, printcom_COL = 'lpr -P' + psname, which assume that the laser printer can be accessed with the regular UNIX lp and lpr commands. Simply replace these commands with the appropriate command for your system. Likewise the procedure `batprint.pro' should be modified at lines 32, 41, and 49 for the correct your system's specific print syntax. This procedure, which allows batch print jobs to be submitted, has additional strings defined (lines 35, 44, and 52) which override the protection of temporary print filenames as required for spooling. VMS users should modify these lines using the correct DCL syntax required to read/write unprotect the temporary files. Windows users should simply comment out lines 37, 45, and 53 as file protection has no meaning in a DOS environment. Note that the batch mode does not archive PostScript files to the hard disk as does the interactive mode. Thus if you want to save a black and white or color PostScript version to hard disk, you must use the interactive mode. ** Required Input files. The SRVT requires XDR (external data representation) files, which represent single scans or a series of fixed-position up B dwells, for data input. These files contain date, time and pointing direction, as well as relevant plasma parameters including raw electron density (Ne), electron temperature (Te), ion temperature (Ti), line-of-sight ion velocity (VLOS), and fitted electron density. Version 4.0 of the SRVT displays: (1) elevation scan data, in which the antenna moves from one elevation angle to another through the zenith (at a fixed azimuth angle), (2) composite scans, in which the antenna moves in both elevation and azimuth angle (not necessarily through the zenith), (3) azimuth scans, in which the antenna moves in azimuth at a fixed elevation angle, and (4) fixed-position dwells looking up the local magnetic field line. Requests for Sondrestrom radar XDR files should be directed to: Dr. John Kelly SRI International Geoscience and Engineering Center 333 Ravenswood Avenue G-282 Menlo Park, CA 94025 (415) 859-3749. A small (but growing) on-line archive radar XDR files is available via anonymous FTP connection to 128.18.44.72. Upon successful FTP login, change directories to pub/radar_data. Here you will find dated directories for all archive holdings. Simply go to the year in question, and then to the specific day in question. All archived XDR files are UNIX compressed tar files. Remember to use a binary transfer mode. To restore individual XDR files upon successful transfer simply execute the following: uncompress tar xvf Please remember that this archive grows only when radar users submit a request for XDR files from specific intervals during which the radar was operated. If you fail to see data from your experiment, please contact Dr. John Kelly and request appropriate XDR files. Directions to obtain the IDL code appear later in Section 3 of this document. 2. General Description The Sondrestrom radar visualization tool is a collection of widgetized IDL modules that allow the display of 2-dimensional radar data as pseudo-color images. For elevation scans, the displayed images are rendered on grids of ground distance (X-axis) versus altitude (or range on the Y-axis), and for azimuth scans, the displayed images are rendered on polar grids with east-west ground distance on the X-axis and north-south ground distance on the Y-axis. For up B radar dwells, Ne, Te, Ti, and VLOS altitude profiles are displayed as 2-dimensional arrays with time displayed on the X-axis and range up B displayed on the Y-axis. SRVT version 4.0 displays four panels of radar scan data which can be assigned to a single XDR file, which is useful for the detailed analysis of a single radar scan, or, conversely, four consecutive XDR files, which is useful for the analysis of the temporal development of various ionospheric phenomena. Dwell data are assigned to a single XDR file. Raw electron density, electron temperature, ion temperature, and fitted electron density data are range splined and rendered as byte scaled images on the aforementioned display grids. A default color look-up table is provided with the SRVT to aid the visual discrimination of features embedded in these data. Further color mapping of these grayscale images is possible by the use of a native IDL color table manipulation routine (xloadct.pro). The line-of-sight ion velocity is displayed as a field of vectors, which has been color coded to help discriminate positive doppler velocity (red vectors) from negative doppler velocity (blue vectors). JPEG examples of 4-panel plots for elevation scan, azimuth scan, and dwell modes can be found on the SRI Sondrestrom Facility World Wide Web homepage: http://chaos.sri.com/iono/issdatas.html 3. Getting Started A compressed TAR file containing the SRVT version 4.0 can be obtained by anonymous FTP to 128.18.44.72 in directory pub/radar_vistool. You will need to binary FTP files called srvt40.tar.Z and PRINTME.ps in order to implement the tool. Once the file srvt40.tar.Z has been uncompressed and restored, a module named `setpath.pro' should be modified to indicate the complete path to the SRVT resident directory. This `setpath.pro' module and the `srvt4.pro' module are the only two files which are required to run the visualization tool. Simply move these two files to a directory containing radar XDR files, or operate the code locally with the sample XDR files contained in the current release. The SRVT is invoked by simply entering IDL and typing @SRVT4. 4. Interactive Widget Description The initial SRVT window immediately forces the user to choose amongst inter- active or batch operation. If you are unfamiliar with the tool, we suggest that you run in the interactive mode first in order to better understand the impact of various file, format, and range selections. The following section describes selections available for interactive operation. Once the INTERACTIVE button has been selected, a new window appears to force a selection between scans or dwells. This selection helps the tool establish an internal format for setting up subsequent commands and helps the tool search for appropriate XDR files. Once either SCANS or DWELLS are selected, a third window appears. Unlike the two prior windows which simply force a decision, this window gives access to meaningful commands for the interactive mode SRVT. This window has been designed so that required selections flow logically from top to bottom and from left to right. The buttons labeled Panel Format, Select Files, Filter Data and Scale Data control the data selection and layout of the four panel display. The button Run invokes procedures which filter, scale, spline, and smooth density and temperature data, create the ion velocity field vectors, and display the resultant four panel display in an IDL window on the local workstation. The buttons Color & Font and Save Options enable manipulation of the displayed color and font tables, and allow selection of options for saving grayscale PostScript, color PostScript, byte array, TIFF, and GIF versions of the 4-panel display to hard disk. The Save Option button also allows individual panels to be saved as floating point arrays for subsequent data analysis. The Print function spools previously saved PostScript files to the appropriate printer. Each of these functions is reviewed in detail as follows. 4.1 Panel Format The Panel Format button creates a small pull-down window that allows the selection of panels 1 through 4 and a summary. Panels are numbered 1 through 4 from left to right and top to bottom. Upon the selection of a specific panel from this pull-down window, a second window opens up to allow the selection of specific key parameters assigned to this panel. Input XDR files are selected with the Select Files button (Section 4.2). The SRVT defaults to a four-panel display wherein panel 1 is set to raw density, panel 2 is set to electron temperature, panel 3 is set to ion temperature, and panel 4 is set to ion velocity. Any changes to this default pattern must be made by individually selecting key parameters from the four Panel windows. When all panels have assigned key parameters and XDR files, a summary window can be viewed. Just click on the Panel Format button and select Summary from the pull-down menu. One should note that this window is for review purposes only as no panel changes are accepted from it. 4.2 Select Files Once the plot choices (key parameters) have been selected, one must choose specific input radar data. The Select Files function allows the selection of input XDR files for the 4-panel display. For dwells experiments, a single XDR file is assigned to all four panels in order to avoid confusion in the labeling of the time axis for multiple experiments. Dwell XDR files are named with a format, MMDDhhmm.dYY, where MM is month, DD is day, hhmm is the UT time corresponding to the beginning of the dwell period, d is the code letter for dwell files, and YY is the year of the experiment. Elevation and composite scans follow the same format except that `x' is used as a code letter and azimuth scans use an `a' as the code letter. The file selection window allows the user to specify the specific path to the XDR file. This path field is a convenient feature for input data residing in a remote directory location. Note: the SRVT does not allow the user to mix elevation/composite scans with azimuth scans or dwells on a single 4-panel display. For scan experiments, XDR files may be individually assigned to specific panels by means for a small pull-down menu. When used in conjunction with the Panel Format function, the operator can set up a number of interesting combinations for comparative analysis. For example, fitted electron density and electron temperature data can be compared for two sequential scans periods, or ion velocity can be displayed over the period spanned by four scans. On the assumption that no other XDR files have been selected, the user can assign a single XDR file to all four panels by selecting the panel 1 XDR file. This is useful for examining the behavior of an individual radar scan. A `clear files' feature allows the user to initialize the selection process with new assignments. 4.3 Filter Data This button serves two functions: (1) to select the maximum uncertainty that will be allowed for the display of electron/ion temperature data, ion velocity data, and fitted electron density data, and (2) to select the desired range resolution of the display (2 km high resolution - 50 km low resolution). A small pull-down window prompts the user to filter the data based on either (1) `Uncertainties' or (2) `Resolution'. The uncertainty in temperature, velocity and density is an indication of how well the nonlinear data fitter was able to match raw autocorrelation functions (ACFs) with analytically modeled ACFs. Note: the selection of high resolution mode will significantly increase the time required to create the four panel display. This mode is intended for detailed analysis, rather than data browsing. The low resolution mode creates super PIXELs in the displayed image and is more efficient. For example, a typical elevation scan at low resolution requires about four minutes to process into an image (SGI Indigo2 or SUN Sparc20). The same rendering at high resolution requires approximately eight minutes. 4.4 Scale Data This button allows the user to set the dynamic range over which all key parameters will be displayed. For electron density, this is the minimum and maximum density in CGS units that will be shown in the final image. The temperature dynamic range is input in degrees Kelvin. The velocity scale allows the user to select the maximum velocity (in meters per second) that will be displayed in the final image. For the analysis of dwell data, the Scale Data button allows access to a subsidiary widget for setting the time scale over which the displayed data will be rendered. This Select Time Window function uses widget sliders to select the beginning and ending UT for the period of interest. 4.5 Run This button tells the program to create the four panel display based on all selections made previously. This procedure filters the data for the required uncertainty limits, splines the data across missing values, and interpolates if required for high-resolution plots. This procedure maps scan data onto vertical and horizontal grids as required. Velocity data is not splined and is therefore processed much more rapidly. For example, four panels that have all been set to display ion velocity data will typically complete processing in a couple of minutes. As mentioned previously, the time required to complete this process for densities and temperatures is greatly dependant on selection of low or high resolution under the Filter function. When the plot function approaches completion, a large IDL window will be opened for display. In order to leave room for the console window and control widgets, the SRVT program senses the size of the current graphics device and creates a window that is somewhat smaller than the maximum screen size. Upon completion of the Run function, the user may choose to change the dynamic range originally selected by the Scale Data function. This is accomplished by clicking the Scale Data button and altering the displayed scales. When the changes have been made, the user simply selects the Run button again. 4.6 Color & Font This button gives access to the IDL function xloadct.pro which allows slider control of mapping of the default color table, and allows selection of alternate color tables. This function is very useful in analyzing density and temperature data within the dynamic range specified by the Scale Data function. This button also allows the user to modify the default size used to display on-screen fonts. This feature is useful as the physical size for vector drawn fonts (using the xyouts function) is platform dependent. A refresh feature is also included in the `Color & Font' pull-down menu in order to redraw the entire four panel display. This function is useful for platforms without an enabled backing store function. 4.7 Save Options This button provides the user with options for saving PostScript, binary array, TIFF, and GIF versions of the displayed data to the local hard disk directory. Individual radar panels can also be saved as floating point arrays. This feature is useful for in-depth analysis of specific data features and offers the user an opportunity to create a custom display. The pull-down menu for the Save Options button allow the user to choose between save options for the 4-panel display, and a floating point save for individual radar panels. The user can save three type of PostScript files: (1) black and white grayscale Postscript files, (2) color Postscript files on a black background, and (3) color Postscript files on a white background. Once the user has selected the type of file to be saved to hard disk, a second window opens up to give the user the option of changing the saved filename. When the user accepts the filename by clicking the Ok button, the program searches for duplicate filenames, to avoid unintentionally overwriting existing files. Headerless binary arrays (1150 by 900 PIXELs) are written to hard disk when the Binary array button is selected. These files are useful for rapid perusal of large volumes of radar scans. 4.8 Print This button directs black and white and color PostScript images to the printer specified in module `goprint.pro' (lines 18 and 26). If no color PostScript printer is available, then the user may choose to modify goprint.pro to pass out an announcement such as, ``file has been written to hard disk.'' 4.9 Quit This button terminates the program. 5. Batch Widget Description The SRVT batch mode has been designed for users who want to peruse a large number of radar scans. This mode assumes that the user has prior knowledge of appropriate dynamic ranges and spatial scales for displaying various radar parameters. The batch mode will apply a single set of selected parameters to a list of individual XDR files. This mode processes individual XDR files in the same manner as for the interactive mode, except that resultant 4-panel images are immediately spooled to the printer. We now assume that the user has selected the BATCH button on the initial SRVT window. Recall that the batch mode works only on scan data. Once the BATCH button has been selected, a new window appears to force a selection between elevation/composite scans and azimuth scans. This selection helps the tool avoid the problem of displaying elevation type scans intermixed with azimuth type scans. Once either ELEVATION/COMPOSITE or AZIMUTH are selected, a third window appears. Unlike the two prior windows which simply force a decision, this window gives access to meaningful commands for the batch mode SRVT. This window has been designed so that required selections flow logically from top to bottom and from left to right. The buttons labeled Select Files, Format, Filter Data and Scale Data control the data selection and layout of the four panel display. The buttons Color & Font and Save Options enable manipulation of the displayed color and font tables, allow selection of options for spooling grayscale and color PostScript output to the printer, and allow the archive of a large file containing a series of 1150 by 900 headerless binary images corresponding to the selected radar data period. This file of binary images is useful for creating a playback movie of scan data using the IDL intrinsic procedure `xinteranimate.pro'. The button Run invokes procedures which filter, scale, spline, and smooth density and temperature data, create the ion velocity field vectors, and spool the resultant 4-panel PostScript file to the printer. With the exception of some minor differences detailed below, these buttons operate in the same manner as for the interactive mode. Each of these functions is reviewed in detail as follows. 5.1 Select Files The Select Files function allows the selection of input XDR files for the 4-panel display. Elevation/composite scan files are named with the format MMDDhhmm.xYY, where MM is month, DD is day, hhmm is the UT time corresponding to the beginning of the dwell period, d is the code letter for dwell files, and YY is the year of the experiment. Azimuth scans follow the same format except that an `a' replaces `x' as the code letter. This widget assumes that all required XDR files reside in the current local directory. Simply click on all desired files. 5.2 Format The Format button for the batch mode differs somewhat from the interactive mode. It is assumed that XDR files will be arranged in chronological order from the list created by the SELECT FILES button. The only real choice is whether all four parameters (Ne, Te, Ti, and VLOS) will be examined (the so-called FOUR PARAMETER choice), or whether a single plasma parameter (the so-called SINGLE PARAMETER choice) will be examined. For the SINGLE PARAMETER choice, a small widget will appear to ask the user to select between Ne, Te, Ti, or VLOS parameters. Once this selection is made, the SRVT will arrange a series of 4-panel plots that show only the single parameter for all XDR files in chronological order, left to right, and top to bottom. This mode is useful for examining the temporal development of ionospheric features. In contrast, the FOUR PARAMETER choice sets up a single 4-panel image of Ne, Te, Ti, and VLOS, for each XDR file. When all panel format selections have been completed, a summary window can be viewed. Just click on the Panel Format button and select Summary from the pull-down menu. 5.3 Filter Data This button functions exactly as described for interactive mode operation. 5.4 Scale Data This button functions exactly as described for interactive mode operation. Note that dynamic range and spatial scale selections will be applied to all XDR files selected, regardless of changing geophysical conditions. Users are advised to examine a small sample of individual scans with the interactive mode SRVT so that reasonable scale choices can be made with this function. 5.5 Color & Font This button functions exactly as described for interactive mode operation. 5.6 Save Options This button functions in a similar, albeit abreviated, manner as described for interactive mode operation. The first three choices enable options for spooling output as grayscale PostScript, color PostScript on a black background, or color PostScript on a white background to the printer. This function will default to grayscale PostScript prints only. The last two choices allow the user to save 1150 by 900 headerless binary images to the hard disk on either a black (color = 0) or a white (color = 255) background. For UNIX systems, a composite image file is formed as a UNIX compressed TAR file with the form: DDMMMYYimg.tar.Z. This file contains a series of binary images corresponding to the input from the Select Files function. When this file is uncompressed and restored, individual images will have filenames of the form: [b,w]MMDDHHmm.[a,x]img, where b and w indicate the color of the background, and a and x differentiate between azimuth and elevation/composite scans. For Windows and VAX operating systems, individual image arrays are written to hard disk without the formation of a compressed TAR file. The user is encouraged to create an interactive movie base on saved images with the intrinsic IDL function `xinteranimate.pro'. Future releases of the SRVT will incorporate a widget based movie option. 5.7 Run This program launches the batch process which creates a series of four panel displays based on all selections made previously. This procedure filters the data for the required uncertainty limits, splines the data across missing values, and interpolates if required for high-resolution plots. This procedure maps scan data onto vertical and horizontal grids as required. Upon selection of this button, the user has the option of entering a `windowed batch' mode or a `true batch' mode. The windowed batch mode continues to update the current IDL window with the status of various SRVT modules and is useful for gauging the progress of a batch job. This mode will also let the user abort the batch job with a CNTRL-C command. The true batch mode spawns a UNIX `at' type command and is useful for times when the user prefers to log out of the workstation. The true batch mode will only work for UNIX operating systems. 5.8 Quit This button terminates the program. 6. Disclaimer The SRVT is provided with no expressed or implied minimum performance criteria. Therefore, the efficiency of this code may not be up to commonly accepted commercial standards. Windows based systems will most likely require some fine tuning and we anticipate suggesting specific CPU/RAM/memory management schemes in the near future. 7. Known Problems If we had more time we would probably like to have fixed the following: Select Files: For the interactive mode, the program will bomb if a bad filename is entered manually. Scale Data: The program will bomb if range larger than 850 km is requested. Font Size: Windows version does not respond to font size changes. Color Manipulation: The widget window called by `xloadct.pro' comes up in the background behind the main control window. For UNIX installations, just drag the control window out of the way. PCs often cannot display all 256 colors from the palette. To fix this problem, just drag the upper end of the color range down a bit so that the lettering changes from magenta to white. Restart: If you wish to abort after the `Run' button has been pressed, you must enter a command, exit IDL, restart IDL, and type @SRVT4. Date Label: The current version labels the entire 4-panel plot with the date corresponding to the data in panel 1. Scan Modes: Azimuth and elevation data types cannot be mixed. ****** Good Luck ****** Dr. Richard A. Doe SRI International Geoscience and Engineering Center 333 Ravenswood Avenue G-278 Menlo Park, CA 94062 (415) 859 2165 voice (415) 322 2318 fax doe@spica.bu.edu June 07, 1996