Using the RHESSI Software from the IDL Command Line
The RHESSI data analysis software is based on the concept of object-oriented programming. The software uses object classes to stepwise reconstruct images, spectra and light curves from raw data. Each step of the construction is associated with an object class.
An object class is a software construct that describes a data type and the methods (i.e., procedures and functions) to access and handle it. Objects make it easier to control the large collection of data products and processes that are needed to produce a final product; the final and all intermediate products, the settings used to create them, and the current state of each level (processed or in need of updating) are stored within a single entity that a user can refer to by a simple variable name, e.g. 'o' .
On this page: | External Links:
|
RHESSI Object Basics
RHESSI users normally interact with the three high-level object classes - those for images, spectra, and quicklook data, shown in the following table.
| Object Class | Object Creation | Object Purpose |
|---|---|---|
| hsi_image | o=hsi_image() | Generate single images or cubes of images at multiple times and/or energies |
| hsi_spectrum | o=hsi_spectrum() | Generate spectra and lightcurves for arbitrary time and energy binning |
| hsi_obs_summary | o=hsi_obs_summary() | Accumulate quicklook products from the observing summary files |
Users control the data generation process by setting options (called Control Parameters) such as the time interval or energy binning, and by calling methods to get or display the data. Informational parameters (called Info Parameters) that provide information about the data product can be retrieved. These methods are shown in the following table.
| Method | Syntax | Purpose |
|---|---|---|
| set | o->set,param=value | Set a control parameter |
| get | value=o->get(/param) | Retrieve the value of a control or info parameter |
| getdata | data=o->getdata() | Generate the data (image, spectrum, whatever) |
| plot or plotman | o->plot or o->plotman | Plot the data in a simple window or a plotman interface |
Each object keeps track of its state. For example, if you change a control parameter and then request a plot, the object knows that it needs to redo some part of its chain of processing in order to display the updated final product. You don't need to call getdata first. Each object has additional methods that are not typically called by users, or are object-specific, and are documented in the description for that object.
All of the control and info parameters available to SET and GET in the RHESSI objects are listed in the RHESSI Object Parameter Tables. All control parameters are initialized to default values when the object is created. You only need to set the parameters that you want to be different from the default. To see the default value of any parameter, use the GET method, e.g. to see the default image algorithm, type
print, o -> get(/image_algorithm)
A simple example follows, showing how to use the basic methods above to reconstruct and display a RHESSI image. We create an image object, set a time interval, energy band, and image reconstruction algorithm, and request the image to be reconstructed and plotted. We also retrieve the image array.
o = hsi_image()
o -> set, im_time_interval= ['12-Aug-2002 02:19:19.776', '12-Aug-2002 02:19:36.224']
o -> set, im_energy_binning= [6., 12.]
o -> set, image_algorithm= 'clean'
o->plotman
image = o -> getdata()
See the RHESSI Snippets for more examples of using the objects from the CLI.
RHESSI Object Chain
In fact, each of the high-level objects is comprised of a chain of objects (>100!) that handle every operation needed to go from the raw data to the final product (view an object tree diagram). Normally users set control parameters in the high-level object, and it passes the information down the chain until the particular object that handles that option is reached. Similarly, info parameters can be requested from the high-level object, which will request the information from the appropriate underlying object. Each level object generates its own data product which is used in the next higher level object, all contributing to the final product of the top level object.
All of the RHESSI object classes are similar in structure, i.e. they all have control and info parameters, and common methods for setting and retrieving them (GET and SET), as well as for requesting and displaying the final data product (GETDATA, PLOT, and PLOTMAN, if plotting is appropriate).
For many operations, users need not be concerned with the chain of underlying objects. However, it is possible to
- extract data from one of the lower-level objects,
- extract a lower-level object and work with it directly, or to
- create a stand-alone instance of any of the underlying objects.
For example, in order to reconstruct an image, the image object needs pointing and roll angle information which it gets from an underlying aspect solution object. If you wanted to retrieve the aspect data yourself, you could type (assuming o is your image object):
aspect = o -> getdata(class='hsi_aspect_solution')
or, the equivalent
aspect_obj = o -> get(/obj, class='hsi_aspect_solution')
aspect_data = aspect_obj -> getdata()
or to create a stand-alone aspect solution object:
aspect_obj = hsi_aspect_solution()
aspect_obj -> set, obs_time_interval=['12-Aug-2002 02:19:19.776', '12-Aug-2002 02:19:36.224'])
aspect_data = aspect_obj -> getdata()
Special GET calls
In addition to simply getting the value of a control or info parameter, you can also do the following:
params = o -> get() ; returns a structure containing all control and info parameters
control = o -> get(/control) ; returns a structure containing all control parameters
info = o -> get(/info) ; returns a structure containing all info parameters
obj = o -> get(/obj, class='hsi_xxx') ; returns the lower-level object called hsi_xxx
Defaults
The RHESSI objects are initialized with default values for all control parameters. Occasionally the software developers change some of the default values. You can force using the old defaults. You can also override the defaults with your personal choices.
Old Defaults
If you want to use defaults prior a change date, you can either set an environment variable or specify a keyword when initializing the object or starting the hessi GUI.
pre_apr2007 - use defaults in effect prior to April 2007
pre_apr2011 - use defaults in effect prior to April 2011
Examples;
setenv,'pre_apr2007=1'
o = hsi_image(/pre_apr2007)
hessi, /pre_apr2011
Note: to see what the defaults before a change date were, look in the routine hsi_old_defaults.pro.
User Defaults
If you want to override the defaults with your own, you can create a text file containing parameter=value pairs, one per line. To use the file during object initialization, you can do one of the following (and this is the order of precedence):
1. Pass in keyword argument def_file
2. Set environment variable HSI_DEFAULTS_FILE to point to file
3. Name the file hsi_defaults.txt and put it one of the three locations below.
If the file specified in one of those three ways is a relative path, it is searched for in this order:
1. current directory
2. home directory
3. $SSW/site/setup directory
For example, you could put the following lines into a file called my_defaults.txt:
image_alg='clean'
clean_niter=500
use_phz_stacker=1
modpat_skip=8
sp_energy_binning=11
and use it by doing one of the following:
o=hsi_image(def_file='my_defaults.txt')
hessi,def_file='my_defaults.txt'
setenv,'HSI_DEFAULTS_FILE=my_defaults.txt'
Or, if you named the file hsi_defaults.txt and put it in one of the three locations specified above, you don't need to do anything special.
