Using visibility objects in the RHESSI software Last update: 2007-10-18 11:57 AM
This memo assumes that you understand the command-line level of the IDL RHESSI software.
1. A first example: making images using visibilites
To make images based on visibilities, specify one of the two visibility-based imaging algorithms available, mem_njit or vis_fwdfit. Thus
o = hsi_image()
; set the observing time interval
o->set, im_time_int = '2002/02/20 ' + ['11:05', '11:15']
o->set, energy_band = [10,20]
o->set, image_alg = 'njit'
o->plot
plots an image of the 20th February 2002 flare using the MEM NJIT image algorithm.
o->set, image_alg = 'vis_fwdfit'
o->plot
plots an image of the same flare using the visibility forward fit agorithm.
In the background, these two algorithms turn off the annular sector engine used by e.g. clean and pixon, switch on the visibility engine, create visibilities from the level-0 files and apply one of the two visibility algorithms to generate the image.
These methods can also be applied to create image cubes:
o = hsi_image( im_time_int = '2002/02/20 ' + ['11:06', '11:08', '11:10'], $
energy_band = [6,12,25], image_alg = 'vis_fwdfit', pixel_size = 1 )
o->panel_display
2. Software Overview
The visibility software is integrated into the RHESSI framework as a set of objects. The main visibility object is called hsi_visibility. An instance of the visibility object is created by:
o = hsi_visibility(); (1)
This object integrates the "user shell" functions provided by Gordon Hurford & Ed Schmahl. Shell functions are described in the Visibility Guide and the MEM NJIT tutorial. The visibility object allows calculation and editing of visibilities. The object also allows some visibility displays. Image generation based on these visibilities is delegated to the RHESSI image object as shown in the example above.
A comparison between the shell functions and the object functions is shown in Figure 1. The typical sequence with shell functions is shown on the right of the Figure. First, visibilities, contained in an array called a visibility bag, are calculated using hsi_vis_usershell, then saved, displayed, edited, or combined, and finallyinterpreted. For the evaluation of spectral and temporal differences, the process must be repeated with a script.
Figure 1: Comparison between the RHESSI objects (left) and the shell functions
The same sequence using the visibility object is illustrated on the left of Figure 1. The visibility object is created either directly with the command (1), or through an image object. Parameters defining the visibility bag are set on the object, such as time interval, energy range, and list of sub-collimators. The visibility bag is managed within the object. This means that the calculation is not explicitely started by the user, but will be automatically when needed. Here an example:
o->set, vis_time_interval = '2002/02/20 ' + ['11:06', '11:10']
o->set, energy_band = [6,50]
o->set, det_index_mask = [0,0,1,1,1,1,1,1,0]
; the calculation of the visibilities will be started automatically when GetData() is called:
vis = o->GetData()
The conceptual difference between the object approach and the user shell approach is that the former is data-centric, while the latter is function-centric. In other words, the shell functions correspond to methods of the visibility object. Thus, hsi_vis_display corresponds to o->plot, hsi_vis_edit corresponds to o->edit, and so on. The main advantage of the data centric approach is that the user does not have to take care of the data management. He or she only has to specify parameters. A second advantage is that the need of editing hsi_vis_usershell falls out, as the visibility bag is defined by the parameters set on the object. A third advantage is that the object allows tu set multiple time and energy intervals, so no scripting is needed.
The transition from the visibility object to the user shell function is straightforward. Visibilities can be grabbed out of the object with GetData(). The array of visibility structures that comes out of the object is fully compatible with the shell functions.
One additional feature of the object is that it can save visibilities in FITS files (see below). One can still save the visibilities in IDL ".sav" files by using Getdata() and then saving the variable. The advantage of FITS files is that they are system and IDL independent.
3. Visibility object tutorial
Object Creation
An instance of the visibility objectis created as follows:
oo = hsi_visibility( )
help, o
The visibility object can also be accessed from the image object:
oo = o->get( class = 'hsi_visibility', /object_reference )
help, oo
Parameter Setting
Parameters accepted by a visibility object are all those of the calibrated event list and below, plus those specific to the visibility object.
oo->set, vis_time_int = '20-feb-02 11:' + ['06:00', '06:21', '06:31']
oo->set, im_energy_binning=[6,12, 25]
Note that here vis_time_int is used to specify time intervals instead of im_time_int with the imaging software.
Retrieval
Visibility bags can be retrieved by individual time intervals and energy intervals
vis1 = oo->getdata( tb_index = 0, eb_index = 0 )
help, vis1, /str
** Structure <85a090c>, 11 tags, length=64, data length=64, refs=2:
ISC INT 3
HARM INT 1
ERANGE FLOAT Array[2]
TRANGE DOUBLE Array[2]
U FLOAT 0.0424057
V FLOAT 0.00205242
OBSVIS COMPLEX ( 2817.70, 739.822)
TOTFLUX FLOAT 6687.36
SIGAMP FLOAT 521.994
CHI2 FLOAT 1.11308
XYOFFSET FLOAT Array[2]
IDL>
Note that this will generate visibilities for both energy intervals ([6,12] and [12, 25]), but it will pass back in vis1 only those associated with the first energy interval.
vis2= oo->getdata( tb_index = 0, eb_index = 1 )
The line above will now execute very fast because the visibilities for the second energy interval are already generated.
vis3= oo->getdata( tb_index = 1, eb_index = 0 )
The line above will take now more time to execute as it will generate all visibilities for the second time interval.
You can also get all visibilities at the same time, in a single bag. For this you need to change the mode used to get them:
o->set, vis_get_mode = 1
all_vis = o->getdata()
In the former example, vis_get_mode was set to 0 (the default). To get all visibilities for a specific time interval, use vis_get_mode = 2:
o->set, vis_get_mode = 2
all_vis = o->getdata( tb_index = 1)
To get all visibilities for a specific energy interval, use vis_get_mode = 3:
o->set, vis_get_mode = 3
all_vis = o->getdata( eb_index = 1)
Selection
To select subset of visibilities:
vis = o->getdata( this_a2d = [0,0,1,1,0,1,0,0,0] )
retrieves data from the 3rd, 4th and 6th sub-collimators.
vis = o->getdata( this_a2d = [0,0,1,1,0,1,0,0,0], paout = paout, /sortpa )
retrieves data from the 3rd, 4th and 6th sub-collimators, sorting the visibilities according to incresead position angle of grids. paout is an optional output of the position angle (deg) of the selected visibilities.
Editing
To use the editing functions, set vis_edit to a nonzero value:
o->set, vis_edit = 1
In the editing mode, bad visibility points are removed according to the value in the chi2 tag of the visibility structure. By default, negative chi2 values are removed. This will be done every time vis=o->GetData() is called.
o->set, vis_ch2lim = 5
vis = o->GetData( )
will not only eliminate negative chi2 values, but also values with chi2 > 5.
Combination
To combine visibilities, set vis_combine to a nonzero value:
o->set, vis_combine = 1
This will convert visibilities with negative chi2 value to their conjugate value. More options will be added soon.
4. Visibility files
To store visibilities in a FITS file, set the vis_out parameter to a file name
o->set, vis_out = 'yourvisfile.fits'
now the file will be written as soon as a new getdata() command is issued (thus reprocessing the whole bag of visibilities).
To use an existing visibility file, set the parameter vis_filename instead of specifying image parameters:
o = hsi_image( vis_file = 'yourvisfile.fits' )
o->set, image_alg = 'njit'
o->panel_display
or do the same with the visibility object:
o = hsi_visibility()
vis = o->getdata( vis_filename = 'yourvisfile.fits' )
You need to set the imaging algorithm you want to use. You can set any imaging algorithm. However, if you set an algorithm that is not visibility-based, the image generator will switch to the annular sector method and access the telemetry packets.
An alternative way to write visibility files is to retrieve the visibility object and generate the file using the write command:
(o->get( class = 'hsi_visibility', /object_reference ))->write, vis_out = 'yourvisfile.fits'
also creates a file containing the visibilities.
Note that the visibility FITS file stores also the values of the control and info parameters. Although these parameters are in principle not necessary to generate images, they are needed by the software for consistency. As a side effect,the software can reuse these values to generate images using other algorithms (getting back to the telemetry files).
---
André Csillaghy andre.csillaghy@fhnw.ch