This hypertext documentation is based on original postscript documentation written by Bill Bristow and Kile Baker. It has, however, in places been modified to try to reflect the current reality of the Leicester version of plot_radar. Comments and complaints, written on a ten pound note, should be directed to Tim Yeoman.
Plot_Radar :is an IDL program for plotting SuperDARN radar data. It is a widget program which provides a relatively easy means for viewing the radar data in a variety of formats. In addition, there is some processing available and there is the possibility for including some user defined processing.
The program plots data in the format of RTP plots, PACEMAP style plots, and line plots. Any of the thirty or so parameters derived from the radar data can be plotted. In addition, the various noise levels and transmitted frequency can be plotted.
Plot_Radar was originally written on an HP 9000 workstation, directly interfacing to the library of SuperDARN file reading programs written by Kile Baker. The File reading routines are written in C and are called from IDL using the CALL EXTERNAL facility of IDL. To use Call_External the C routines must be compiled into shared libraries, and various paths must be hard coded in the IDL programs. Therefore, to implement this program on various machines will require the user to make some changes to the program, and to establish the libraries.
In this document the functions of Plot_Radar will be described in detail. Also, the libraries and paths will be described to help the user to install the program on his machine.
The image below is a print of the appearance of the Plot_Radar widget. the widget consists of the graphics window, the push buttons in the lower left hand corner, and the text widgets and buttons along the left hand side. The text widgets allow the user to enter the plot parameters, while the buttons select the type of plot.
We will start this section with a simple example of using Plot_Radar. The example will be followed by a more detailed discussion of the use of the various widgets.
The user must first invoke IDL by entering the command idl at the prompt. If the file startup.pro has been set up correctly (see below) to automatically compile the radar routines you should now be ready to enter the command Plot_Radar.
Most users will have a script plot_radar , which will automatically invoke IDL and launch Plot_radar
The Plot_Radar command will display the plot_radar widget (which is a complex set of widgets). Initially the plotting area will be blank. the user should now enter a file name in the text widget at the top left
Enter the name of a file (for example: 95080620f).
You will notice that several other text windows change immediately after you have entered the file name. The start and end times are determined by the file name. In the example here, the start time is set to 2000 44s and the end time is set to the end of the day 2200 15s . In addition, the default x and y limits have been set according to the station being plotted (which is determined by the last letter in the file name).
You have five options for your coordinate system; (1) geographic, (2) magnetic/rectangular (3) magnetic/sterographic (4) magnetic/polar or (5) range. The initial default system is magnetic/rectangular. In the example given here, the default x and y limits are: 85.0 to 130.0 in longitude and 55.0 to 80.0 in latitude.
You are now ready to plot the data. Move the pointer to the button labelled PaceMap at the bottom left. Click on the button. Whenever you want to plot a new file or a new time period or parameter or coordinate system, you should choose the PaceMap option. Since you are starting to plot a new file you would choose the PaceMap option now.
There are three parameters that are available for you to plot. The default parameter is pwr_1, the backscattered power. the other options are the velocity and the spectral width. We will see how to select different parameters in a moment.
The program will now read the data in the file and plot it. the results of this plot are shown in Figure 1 below.
Suppose you would prefer to use geographic coordinates. Use the mouse to point to the button labelled GRAPHS at the top. Click the button and it will create a pull-down menu. One of the options on that pull down menu is COORD SYSTM. Click on that option and a new pull-down menu appears showing the five coordiante system options. Click on GEOGRAPHIC. Note that the text in the window labelled COORDINATES has changed to geog and the limits have changed to -20.0 to 80.0 longitude and 55.0 85.0 latitude. To replot the data in the new coordinate system again click the option PaceMap . The results are shown in Figure 2 below.
You can now step through a sequence of maps by selecting the next frame ">" button. You can also step backwards by selecting the last frame "<" button.
Let us suppose you now have the map you want and you are ready to get a hard copy print of it. From the Postscript pull-down menu select Pacemap postscript colour. IDL will then create a postscript file with the name idl.ps that contains the plot you see on your screen. You can create a sequence of maps if you wish by alternating between the options > and Pacemap postscript colour.
You are now ready to print out the postscript plots on your color printer. Point to the button labelled Tools at the top and select PrintPS from the pull- down menu. The postscript file will be closed and the print job will be spawned to the default color postscript printer.
The name of the printer is hardwired into the IDL code. Each installation will have to change the IDL code to reflect the names appropriate to their printers.
When you are all done, simply go to the last option in the "OPTIONS" pull down menu, "EXIT". Clicking on the button labelled EXIT will cause the Plot_Radar display to disappear and you will be back at the IDL prompt.
The precise method needed to enter a value in the text widget depends on how the user has the KeyboardFocus policy set. The default focus policy requires the user to use the mouse to position the pointer in the text window and then click the left button. Once the focus has been set to the text widget, the pointer does not have to remain inside the window. However, if the user has set the focus policy to pointer it is not necessary to click the mouse button but it is necessary to make sure the pointer stays in the text window while you are entering data.
The text widgets allow the user to enter text which is communicated to the program running in the background. Widget communication is through events, which are generated when the return key is hit while a widget is selected. To change the text in a widget and generate a widget event, the user must select the desired widget with the mouse, enter the text, and then hit the return key while the widget is still selected. When an event is generated by one of the text widgets, plot_radar prints the event value.
The text widgets and buttons on the left hand side of the plot_radar window are shown below:
DATA FILE: This widget is self explanatory. The name of the data file to be read. The file is entered without extension. Whenever a new file name is entered in this text widget, the start and end times are reset to default values and the x and y plot limits are set according to the station id and the coordinate system that is currently selected.
START TIME: This is the time from which to start reading the data. The format is: hhmm ss. For example: 2200 44s. There must be spaces between the minutes and seconds numbers. Plot radar now counts from the beginning of the datafile, not the beginning of the day, so with a little practice day and year boundaries should not cause any problems.
END TIME: This is the time for the last record read from the file. The format is the same as for start time.
COORDINATES: The type of coordinates to be used in the plots. The five possibilities are: geographic, mag/rect, mag/stereo, mag/polar and range. For geographic stereographic, magnetic rectangular, magnetic stereographic, magnetic polar and range respectively, If you set the coordinate system by using the GRAPHS menu , the x and y limits will be set to the default values for the particular radar being used. You can, however, simply enter the appropriate coordinate value in the text widget in the same way as you enter data into any widget. In that case the x and y plot limits are not changed.
X LIMITS: The plot range for the horizontal axis. In RTP plots and line plots of parameter versus time, this is a time coordinate; in pacemap type plots it is a range or longitude coordinate.
Y LIMITS: The plot range for the vertical axis. This is a range or latitude coordinate.
MIN MAX: The range of values for the color bar. This requires three numbers. First a 0 or 1 as a flag to select default parameter values or to use the values entered here. Then two numbers, the minimum value and the increment between levels (note: if the first value is 0, the remaining two values are ignored.)
MOVIE TIME: the time interval for making a movie. Format hhmm hhmm for start and end time.
FRAME TIME: the time (Format: hhmm ss) for pacemap plots. Entering a value in this widget and then selecting PaceMap will result in a plot of the radar scan that contains the time requested.
BEAM NO: The number of the beam to be used in the RTP type plots, and for the line plots. this value has no effect on the PaceMap plots.
RANGE BIN: The range number to be used in line plots of parameter versus time. This value has no effect on the PaceMap or RTP plots.
SCATTER: The type of scatter to be plotted: 1 selects ground scatter. 2 selects ionospheric scatter. 3 selects both.
SKIP: The number of frames to skip when NEXT FRAME ">" or LAST FRAME "<" is selected from the pacemap menu.
Below the text widgets are the button/menu widgets.
Underneath the button/menu widgets there is a window with three push buttons. These select between the three parameters which have been loaded from the PARAMETERS button above.
At the bottom of the left hand panel there are two output text boxes.
The first of these is used by plot_radar to inform you what is going on, the type of data loaded, etc. It also outputs the value of the selected parameter in the location within the field of view selected by clicking the mouse within the data window.
The lower box is used by plot radar to give you an error message when things go wrong. And lets face it things will go wrong. More detailed error and information text can be found in the idl command window which you originally called plot_radar from
In order to run the Plot_Radar programe you must make sure that IDL compiles all the proper routines. The easiest way to do this, particularly if Plot_Radar is going to be one of the more common IDL programe you will be running, is to include the appropriate .run commands in your IDL startup.pro file. an example of an IDL startup procedure is shown here.
; define the system variable '!default'
; this variable contains information about the user's default
; plotting device.
defsysv,'!default',{defdev, name: 'X', device: '', pcolor: 17, ncolors: 18}
default_device = getenv('IDL_DEFAULT_DEVICE')
if default_device EQ '' then default_device = 'X'
!default.name = default_device
; initialize plot device
set_plot,!default.name
cut_col_tab
if !default.name EQ 'TEK' then begin $
!default.ncolors=2 &$
!default.pcolor=1 &$
endif
if !default.name EQ 'X' then begin $
!default.ncolors= !d.n_colors &$
!default.pcolor=!p.color &$
endif
if !default.name EQ 'PS' then begin $
!default.ncolors = 256 &$
!default.pcolor = 0 &$
endif
.run sd_device_init
.run genlib
.run rawlib
.run fitlib
.run acflib
.run radar
.run wpacemap
.run wmaprti
.run wfread
.run param_vs_coord
.run param_vs_time
.run gusr
.run scan_filter.pro
.run read_file.pro
Once you have started IDL and compiled the plot_radar routines all you need to do is type plot_radar. The widget should appear after a few seconds. If plot_radar has been run previously in the current directory, and the inputs file still exists, the text widgets will show the values that they had when the program was last run. Otherwise new values will be required. the first step is to enter the desired parameters. since the parameters will be different for different types of plots, the following describes operation for each kind of plot.
Enter the file, start time, end time, beam no, etc. X LIMITS in this type of plot is the time coordinate. It requires two numbers, the start and stop times for the plot. In this case the time is given in 24 hour format as an integer between 0000 and 2400.o example, to plot the parameters between 12:30 UT and 16.30 UT the X LIMITS line should read 1230 1630. Y LIMITS depend on the type of coordinates. For range coordinates, the values are kilometers (eg. 0 3000), for geog or mag the numbers are degrees of latitude (eg. -90 -30). If ground scattter (scatt = 1) and range coordinates are selected, then the y-coordinate is the mapped range. That is, the reflection point in the ionosphere assuming a reflection height of 300 km.
The MIN MAX window contains three numbers. For an initial plot, these numbers could be set to 0 0 0, and the default values will be used.
Next, select one of the three parameter buttons from the bottom menu. Finally, to make the plot click the RTI button. On the initial plot, the program will read the file before making the plot, so it will take some time to make the plot (it takes about 30 seconds on an HP 9000 workstation to read 12 hrs of data). making subsequent plots the file will only have to be re- read if changes are made to the three selected parameters. After the initial plot is made, the values in the text windows can be changed and new plots will take a shorter time (less than 10 seconds on an HP 9000).
To make pacemap plots the procedure is very similar to the procedure for making RTI plots. In this case, however, the FRAME TIME must be selected, this is the time in decimal hours (note that this is different from the way time is defined in the X LIMITS widget for RTI plots). the X LIMITS are now range or longitude. For range coordinates the numbers are in kilometers (like -1000 2000), for geog or mag the numbers are degrees longitude, positive going east (for Goose Bay geographic -90 -30 gets the whole field of view, for an interesting view, choose geographic -180 180).
Parameter vs range plots require the same parameters as pacemap plots, frame time and ylimits, in addition the beam number must be selected.
After the initial plot is made, the data may be filtered. To use the built-in filter, select FILTER PARMS from the options menu. this will bring up a window with three buttons and four text windows. Select time and/or range filtering and enter the low and high frequency cutoffs for each. Remember to hit return after entering the text. Then hit the done button. Next, choose FILTER from the TOOLS menu. this applies the standard IDL digital filter to the time series from a single beam and range gate, or to the range series from a single beam and time. To plot the filtered data choose the plot type from the menus. To discard the filtered data and retrieve the original data, either choose a different parameter, or select FILTER PARMS again and hit the done button without hitting either the TIME FILTER or RANGE FILTER buttons. This clears the filter flags, and the original data is retrieved when a plot is made.
For each of these types of plots it is possible to get a postscript file output. Select the parameters as described above and select the postscript menu item. Note that the postscript file remains open until either the IDL session is ended, CLOSE PS is selected from the TOOLS menu, or PRINT PS is selected from the TOOLS menu. After the postscript file is closed, creating any additional postscript plots will over-write the old file.
The noise and frequency plots require the x-limits to be a time coordinate. Also the MIN MAX values should be set for these plots, since there are no default values. For noise plots the range should be something like MIN MAX = 1 0 100; for frequency something like MIN MAX = 1 14400 100: which selects a 1 MHz band starting at 14.4 MHz.
The program, Plot_Radar, is actually a bundle of IDL routines which interface to some fortran and C routines. Most of the IDL routines are included in two files, radar.pro and fitlib.pro. Other necessary files are:
def_pars.dat, lsh_geog.dat, mk_cont.pro, nf_v_t.pro param_vs_coord.pro, param_vs_time.pro, psland.pro, psport.pro, startup.pro, ufilter.pro, wfilter.pro, wfread.pro, wmaprti.pro, wpacemap.pro sd_device_init.pro, genlib.pro, gusr.pro, read_file.pro, cut_col_tab.pro, cut_col_tab.dat, scan_filter.pro rmscript and wpmovie.pro.
The C routines required are listed in the makefile for the libraries.
There is one place in the IDL programs where specific paths are hard wired in:
set_filename.pro:FITPATH='/cutlass'There are many places in the IDL programs where specific paths are referred to by environment variables. the following is a list of the required environment variables and what they point to. There are no longer any hard wired paths in plot_radar.
export IDL_PATH=$IDL_PATH:/people/cutlass/lib/share:/people/yxo/Idle/lib: /people/cutlass/idl/lib:/people/cutlass/idl/plot_radar: /people/cutlass/idl/rawful:/people/cutlass/idl/plot_merge:. # SD_TOP=/people/cutlass; export SD_TOP # # IDL_STARTUP=/people/cutlass/idl/plot_radar/startup.pro; export IDL_STARTUP SD_IDL=/people/cutlass/idl/tables; export SD_IDL IDL_CPRINT=DeskJet; export IDL_CPRINT IDL_BWPRINT=Laser; export IDL_BWPRINT IDL_PLOT_RADAR=/people/cutlass/idl/plot_radar/; export IDL_PLOT_RADAR # SD_LIB_FIT=/people/cutlass/lib/share/libfit.so; export SD_LIB_FIT SD_LIB_GEN=/people/cutlass/lib/share/libgen.so; export SD_LIB_GEN SD_LIB_PGM=/people/cutlass/lib/share/libpgm.so; export SD_LIB_PGM SD_LIB_RAW=/people/cutlass/lib/share/libraw.so; export SD_LIB_RAW SD_LIB_ACF=/people/cutlass/lib/share/libacf.so; export SD_LIB_ACF SD_LIB_MAG=/people/cutlass/lib/share/libmag.so; export SD_LIB_MAG SD_LIB_MRG=/people/cutlass/lib/share/libmrg.so; export SD_LIB_MRG SD_LIB_RBPOS=/people/cutlass/lib/share/librbpos.so; export SD_LIB_RBPOS # SD_TABLES=/people/cutlass/tables; export SD_TABLES SD_MERGE=/cutlass/data/cutlass/merge; export SD_MERGE IDL_PLOT_FILE=idl.ps; export IDL_PLOT_FILE # SD_FITROPEN_PATH=.:/people/cutlass/Data/:/cutlass/finland/incoming/: /cutlass/iceland/incoming/:/cutlass/data/$USER/fit/; export SD_FITROPEN_PATH SD_SMROPEN_PATH=/cutlass/finland/incoming/:.; export SD_SMROPEN_PATH USR_LOCATION=/people/cutlass/prog_files/usr_location; export USR_LOCATION CNV_COORD=/people/cutlass/tables/cnv_coord.dat; export CNV_COORD SD_RAWROPEN_PATH=/people/cutlass/Data/:/cutlass/finland/incoming/: /cutlass/data/$USER/dat/:.; export SD_RAWROPEN_PATH SD_FIT_LAMDA_TABL=/people/cutlass/tables/lamda.dat; export SD_FIT_LAMDA_TABL SD_FIT_SIGMA_TABL=/people/cutlass/tables/sigma.dat; export SD_FIT_SIGMA_TABL SD_FIT_PATH=/people/cutlass/Data/:/cutlass/finland/incoming/:.; export SD_FIT_PATH SD_HARDWARE=/people/cutlass/tables/hardware.dat; export SD_HARDWARE IGRF_PATH=/people/cutlass/tables/; export IGRF_PATH
Hard wired paths have also been removed from the C routines, and building the C and FORTRAN libraries as sharable objects on your system will enable plot_radar to call all the code it needs. Look at the Makefiles to see how this is done for various systems.
In addition there are a few lines in radar.pro which use the spawn command:
gusr.pro:spawn,"whoami",user
radar.pro: SPAWN, '${IDL_PLOT_RADAR}rm_script'
radar.pro: SPAWN, cmnd, result
radar.pro: SPAWN, '${IDL_PLOT_RADAR}rm_script'
sd_device_init.pro: spawn,'lp -d'+que+' idl.'+extension
To install the software, establish an IDL directory somewhere on your system and make sure that the directory is in everyone's IDL path. Put all of the IDL programs in that directory. Make whatever changes are required. Then establish another directory for the shared libraries. The makefile included with the programs has the commands for creating the libraries on the HPs. Other Makefiles can be found in the darn directory of the anonymous ftp archive at ion.le.ac.uk. The main options which we use to compile the library are: ansi C, position independent code, and whatever optimization we could get. If there are problems with getting the C routines to compile, Kile Baker will be more than happy to help you to get them to work; just give him a call. On unix systems you need to establish the environment variables SD_FITROPEN_PATH, IDL_PATH and IDL_STARTUP. SD_FITROPEN_PATH is the path to the data files. IDL_STARUP is the name oof the file IDL should execute on startup, IDL_PATH is the IDL path.
