Last update:
2009-06-18 04:10 PM
Contents:
1. Making images using visibilities
2. Visibility Options
Editing
Combination
Normalization
3. Storing bags of
visibilities in FITS files
4. Using visibility FITS
files as input
5. Accessing
visibilities
6. Using
the visibility object directly
7. Visibility object parameters
This document assumes that you understand the command-line level of the IDL RHESSI software.
All of the capabilities described here are also available through the RHESSI GUI (hessi command).
Note these changes in the current visibility object compared to before May 2009:
1. vis_time_interval parameter no longer exists. Use
im_time_interval for images and visibilities.
2. vis_normalize parameter is new and is enabled by default.
3. vis_combine parameter is renamed to vis_conjugate.
4. vis_conjugate is enabled by default (previously, vis_combine was disabled by
default)
To make images based on visibilities, specify one of the two visibility-based imaging algorithms available, mem_njit or vis_fwdfit.
o = hsi_image()
o->set, im_time_interval = '2002/02/20 ' + ['11:05', '11:15']
o->set, im_energy_binning = [10,20]
o->set, image_algorithm = '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 algorithm.
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'], $
im_energy_binning = [6,12,25], image_alg = 'vis_fwdfit', pixel_size = 1 )
o->panel_display
Once the visibilities have been created for a given set of times and energies, they can be reused to make different images, instead of starting from the telemetry level-0 data.
By default, visibilities are edited to remove those with inadequate phase coverage or bad fits.
To turn off editing functions, set vis_edit to zero:
o->set, vis_edit = 0
You can customize a limit for the allowed valued of reduced chi2 via the control parameter chi2lim (default is 1.e9):
o->set, vis_chi2lim = 5
vis = o->GetData( )
will remove visibilities with chi2 > 5.
The editing functions are implemented in the function hsi_vis_edit.
By default, visibilities with negative v values will be converted to their conjugate values (i.e. the visibilities for each pair of half rotations are combined), and then in the resulting visibilities, similar uv points are combined. To turn off this feature, set vis_conjugate to zero:
o->set, vis_conjugate = 0
The combination functions are implemented in the function hsi_vis_combine.
Note: This control parameter was called vis_combine
By default, visibilities are normalized and detectors out of range are rejected. To disable normalization, set vis_normalize to zero:
o->set, vis_normalize = 0
To control the value used to reject detectors, set vis_max_corr. vis_max_corr is the maximum allowable fractional difference of one detector's total flux from the average. (Default = 0.25)
o->set, vis_max_corr = .5
To see the correction factors applied to the visibilities for each detector, and which detectors were rejected in the normalization:
print, o->get(/vis_corr_factors)
print, o->get(/vis_det_index_mask_used)
A bag of visibilities is a data structure that contains visibilities for several energy and time intervals. Bags of visibilities can be stored in a FITS file for reuse.
In the GUI, the option to write the visibility bag to an output file is available through the 'Set visibility params' button.
From the command line, you just need to set a filename in the vis_out_filename parameter:
o->set, vis_out_filename = 'yourvisfile.fits'
Now the file will be written as soon as a new getdata() command is issued (thus reprocessing the whole bag of visibilities).
If you don't want to save visibilities into a file, just leave the filename blank (or set to a null string if it was previously set, i.e. o->set, vis_out_filename='')
An existing visibility file can be used as input to avoid having to read the raw telemetry files again.
In the GUI, set the 'Select Input' droplist widget to 'Visibility FITS file'.
From the command line, set parameter vis_input_fits instead of specifying image parameters:
o = hsi_image( vis_input_fits = 'yourvisfile.fits' )
o->set, image_alg = 'fwd'
o->panel_display
You need to set the imaging algorithm you want to use. All of the other parameters (control and info) were stored in the visibility FITS file, and will be set into the object as they were when you created the visibility file. Although these parameters are not necessary in principle to generate images once the visibilities have been generated, they are needed by the software for consistency. In fact, as long as vis_input_fits is set to a file, you are blocked from setting any parameters that are not consistent with the information in the visibility bag. In the GUI, you will notice that most of the 'Change' buttons are not sensitive. You can set any imaging algorithm, including the algorithms that do not use visibilities such as clean and pixon. If you set an algorithm that is not visibility-based, the image generator will switch to the annular sector method and switch back to accessing the telemetry packets again. Note however, that the control and info parameters read from the visibility file, will have been set in the object as defaults.
To revert to using the telemetry files instead of the visibility file, set vis_input_fits to a null string:
o->set,vis_input_fits=''
Visibility bags can be retrieved as follows:
vis = o->getdata( class = 'hsi_visibility' )
help, vis, /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]
When the visibility bag covers several time or energy intervals, the command above will retrieve only those items associated with the first time and first energy interval. Items in other intervals are retrieved using the indices tb_index and eb_index:
vis = o->getdata( class = 'hsi_visibility', tb_index = 0, eb_index = 1 )
The visibilities returned have been edited, combined, and normalized if requested, and are only for the detectors selected by det_index_mask.
To sort the visibilities by increasing position angle of grids, and optionally return the position angle (in degrees) of the visibilities:
vis = o -> getdata( class = 'hsi_visibility', /sortpa, paout = paout)
You can also get all visibilities at once, in a single bag by using the /all keyword. Note that when you use /all, however, the edit, combine, and normalize functions and detector selection are bypassed - all of the visibilities in the bag are returned.
all_vis = o->getdata(class='hsi_visibility', /all )
All of the discussion above assumes that you are working with an image object. The visibility object is created as part of the object chain when you select a visibility-based image algorithm (mem_njit or vis_fwdfit). You can also create a visibility object directly by typing
vis_obj = hsi_visibility()
All of the operations above can performed using this visibility object directly, just omit the class = 'hsi_visibility' keyword. For example:
vis_obj -> set, im_time_int =
'2002/02/20 ' + ['11:06', '11:08', '11:10']
vis_obj -> set, im_energy_binning = [6,12,25]
vis = vis_obj -> getdata(tb_index = 0, eb_index = 1)
All of the control and info parameters specific to the visibility object can be found in the Image Object Parameters table. Look for the parameters that start with 'vis_'. In addition, any control or info parameter in an object below the visibility object in the chain of objects (calib_eventlist, eventlist, stacked eventlist, aspect, spectrogram, etc.) can be set or retrieved from the visibility object. Thus, for example, im_time_interval and im_energy_binning control visibility selection even though they are control parameters of the calib_eventlist and binned eventlist objects respectively.
Note that previously (before May 2009), there was a separate control parameter called vis_time_interval to select the visibility time interval(s). The vis_time_interval parameter no longer exists. Time selection for the visibility object is controlled by the im_time_interval parameter.