Appendix 11. HISCALE IDL Display System (IDL_HS)

 

 

Document Reference: James Tappin, July 20, 1994, November 11, 1994.

 

• A11.1 Part One - User's Guide (below)
• A11.2 Part Two - Reference
  • A11.2.1 - Introduction
  • A11.2.2 - Procedures (part 1)
  • A11.2.2 - Procedures (part 2)
  • A11.2.2 - Procedures (part 3)
  • A11.2.2 - Procedures (part 4)
  • A11.2.2 - Procedures (part 5)
  • A11.2.2 - Procedures (part 6)
  • A11.2.3 - Common Blocks
  • A11.2.4 - Structure Tags
  • A11.2.5 - The Xmanager Names

 

 

A11.1 Part One - User's Guide

 

A11.1.1 Introduction

 

IDL_HS is a set of procedures for displaying data from the Ulysses HISCALE instrument in several different forms. The main procedures are listed in the next section.

This system is most usually encountered through its graphical user interface (GUI). This allows you to set options and run programs via a hierarchy of menus. For users with World-Wide-Web access a more detailed help system is available on the URL:

 

http://www.sr.bham.ac.uk/hi-scale_help/index.html

 

There is also a command-line interface for users who don't have access to an X-terminal or who wish to manipulate the data in a more direct manner than is possible via the GUI; the main commands for this are listed in a separate "Reference Card' (section A11.3).

 

A11.1.2 Available Procedures

 

There are 7 main procedures available within IDL_HS.

 

1. PLOT_RATES

   The PLOT_RATES procedure allows plotting of time-series of HISCALE data. Any of the rates and fluxes contained in the ULA files can be selected; in addition, rates and fluxes from the TRK composition files can be plotted.

2. PLOT_SPECT

   The PLOT_SPECT procedure allows the plotting of spectra derived either from the 7 and 8 channel rates data, or from the 32-channel MFSA data.

3. PLOT_PAD

   The PLOT_PAD procedure produces Pitch Angle Distribution plots for selected channels from ULA (or averaged) files into which magnetic field data have been merged.

4. MOVIE

   The MOVIE procedure displays anisotropies in the form of a movie, with optional pitch angle contours.

5. PLOT_CDF

   The PLOT_CDF procedure will plot time-series of selected channels from the Ulysses Common Data File (CDF).

6. PLOT_UDS

   The PLOT_UDS procedure will plot time-series of selected channels from the Ulysses Data System (UDS).

7. PLOT_MAG

   The PLOT_MAG procedure plots magnetic field data from the values merged into HISCALE data files.

 

N.B. Data from the Magnetometer and other Ulysses experiments should not be used in publication without prior consultation with the appropriate P.I.

 

 

A11.1.3 The Widget Interface

 

The GUI to the IDL_HS software is intended to be self-explanatory. But there are a few items which have caused some confusion and this section attempts to clarify those issues.

 

Toggle Buttons

 

Toggle buttons are of two types, known as exclusive and non-exclusive.

 

Exclusive buttons are always grouped into a menu and allow selection between alternatives (for example, the plot device selection menu). The selected option is indicated by either the selection indicator beside the label (motif) or the whole button (openlook) being shaded and depressed. When a different alternative is selected the previous one is deselected. All the exclusive menus in IDL_HS are configured such that clicking on the currently selected button has no effect (even though the button will cease to show the selected state).

Non-exclusive buttons allow the toggling of two-state switches. In version 3.06 and later these have mostly been replaced by arrays of pairs of exclusive buttons to reduce confusion. They still survive in the EXTRACT_SECTORS selection menu for choosing the sectors to be extracted.

 

Filtering

 

In PLOT_RATES and MOVIE there is an optional filter to remove spikes from the data. This appears to cause many users problems in its use.

 

The median filtering option is quite straightforward; it just takes a running median of the specified width and uses that in place of the raw values.

 

The "Spike removal'' option is slightly less intuitive. The procedure used is to take a running median as above and then compare the raw data with that median, and any point which exceeds the median by a factor greater than the threshold is replaced with the median.

When dropout removal is selected, then the same threshold criterion is applied but for points falling below the median. The problem lies in the selection of suitable values for the neighbourhood width and the threshold; the following guidelines may therefore be useful:

 

• Filtering should NOT be used at all on data where there are only of order one count per INPUT accumulation, as the zeros are liable to cause most or all of the data to be removed.
• For ULA files spikes can often extend for a complete data record so you may need to use a width of 21 or more to remove all the spikes.
• For averaged files, this problem does not occur so you will rarely need to change the default width of 7.
• The default threshold of 4 may need to be lowered to clean up averaged data where the spikes have been reduced by averaging in with good values.

 

There is, however, no hard and fast rule. The best option is to plot the raw data, and then experiment, until you have removed as many spikes as possible.

 

N.B. UAF QCA-filtered files should not need further filtering as the QCA algorithm is much better than these algorithms.

 

The filtering in PLOT_CDF uses the same "Spike Removal'' filtering but with a single standard set of parameters.

 

Crashes

 

Although the IDL_HS GUI is fairly robust, there are almost certainly still some holes in the interlocking system which will result in routines being called with unsuitable settings. If this occurs, then it may crash IDL_HS (or even IDL). If the system seems to hang up with the hourglass cursor and/or disabled menus and not be doing anything, then you should check the terminal window from which you ran IDL_HS. If you find an error message and the Hiscale:_ prompt, then you should use the following procedure to restart the GUI:

 

• Kill all the widget windows created by IDL, using the window manager.
• Return to the top level with the RETALL command.
• Clear the widget controller settings by calling the XMANAGER procedure.
• Restart the GUI with the HS_MENU procedure.

 

N.B. While you can follow steps 1-3 above and then work in line-mode this is not recommended as some settings will be left in a state appropriate to widget-mode, so prompts and information messages will continue to be presented in widget windows.

 

 

A11.1.4 Environment Variables (Logical Names)

 

There are a number of environment variables (logical names on VMS) which can be set to modify the default settings on entry to IDL_HS. These are summarized below:

 

Directories

 

IDL_HS defines two directories, one in which to find the data, and the other in which to deposit plot files and other output files from the system. Default values may be set for these using the variables HS_DATA_DIR and HS_PLOT_DIR respectively. They may both be specific settings. If just one of HS_PLOT_DIR and HS_DATA_DIR is set and HS_DIR is not set, then the other directory is set to the current directory.

 

Path

 

In IDL routines are searched for in the directories and libraries (VMS only) specified in the !PATH system variable. This is initially picked up from the IDL_PATH variable or from an internal default value. IDL_HS adds a substantial tree to this; it is generally preferable to leave IDL_PATH unset to avoid possible complications with the user library failing to be accessed properly. If you wish to be able to search other directories of your own, then you can use the HS_EXTRA_PATH to prepend that to the !PATH. For example in unix:

 

setenv HS_EXTRA_PATH +~/idl_etc:~/special/idl 
idl_hs

 

will allow the whole tree from ~/idl_etc and the directory ~/special/idl to be searched automatically. A corresponding command in VMS might be:

define HS_EXTRA_PATH "+DISK$USER1:[SJT.IDL_ETC],DISK$USER1:[SJT.SPECIAL.IDL]"
idl_hs

 

Note: This only works in IDL V3.1.0 or later as that was the release at which EXPAND_PATH appeared.

 

Spool Command

 

A default value of the command to spool plots can be set with the HS_PRINT command. The value is just a suitable print command in your system, but with the filename replaced by a % symbol; e.g., on the Birmingham systems I set up:

setenv HS_PRINT 'lp -c -o nobanner -dps2 %'
define HS_PRINT "print/que=sys_ps/form=post %"

on Unix and VMS respectively.

Instrument Definition

The instrument parameters (energy ranges, geometry factors and backgrounds) are read from the Instrument Definition File. The default is IDF.DAT in the IDL_HS distribution directory. This may be changed by specifying a filename in the HS_IDF variable.

 

Others

 

There are a number of other variables which are of less general use but which are listed here for completeness:

 

• HS_WIDGETS if set to no then start up in line mode even if widgets are available, equivalent to an automatic idl_hs -l.
• HS_DEBUG if set to a non-null value, then start up as for idl_hs -d - i.e., switch information level messages on, and if using widgets, stop on a crash without returning to the top-level.
• HS_PIXMAP Some X-terminals do not support server backing store of windows. If your terminal has this property, set HS_PIXMAP to a non-null value other than no to force IDL to manage the backing store.
• HS_SMALL_FONTS if set to yes then use fonts one size smaller than the defaults in all widgets, useful on a small screen or if you want to be able to see several windows at once.

 

 

Next: A11.2 Part Two - Reference