Contents:
1. Making images using visibilities
2. Visibility Options
Edit
Combine
Normalize
3. Accessing visibilities
4.
Storing bags of visibilities in FITS files
5.
Using visibility FITS files as input
6.
Using the visibility object directly
7. Visibility object
parameters
8.
Regularized visibility spectra (new October 2012)
9. Visibility FITS files helper routines
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 visibility-based imaging algorithms, currently mem_njit, vis_fwdfit, or uv_smooth.
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 visibility-based algorithms turn off the annular sector engine (used by non-visibility-based algorithms such as clean and pixon), switch on the visibility engine, create visibilities, and apply the image algorithm 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.
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 vis_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 prior to May 2009.
By default, visibility amplitudes are normalized to compensate for presumed relative detector calibration errors. Normalization is based on the expectation that the average values of TOTFLUX will be the same for all detectors. The correction factors are the ratio of the detector-associated values of TOTFLUX to the average (detectors that deviate by more than vis_max_corr from the average are not used in the average)
To disable normalization, set vis_normalize to zero:
o->set, vis_normalize = 0
To control the value used to reject detectors for use in calculating the average, 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 for use in calculating the average:
print, o->get(/vis_corr_factors)
print, o->get(/vis_det_index_mask_used)
Visibility bags are sets of visibility structures with different energy bins, time intervals, and sub-collimator indices. Normally a visibility bag is from a single flare with a common xyoffset. 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]
After October 2102, the following additional fields will be in the vis structure.
TYPE STRING ''
UNITS STRING ''
ATTEN_STATE INT 0
COUNT FLOAT 0.000000
With the October 2012 changes to the software, you can continue to use old visibility files FITS files that have the old structure or new files which will have the new structure.
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 filtered (edited, combined, and/or normalized) if requested, are for the detectors selected by det_index_mask and are of the type specified by vis_type..
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 of the normal photon visibilities at once, in a single bag by using the /all keyword. Note that when you use /all, the edit, combine, and normalize functions and detector selection are still filtering the visibilities:
all_vis = o->getdata(class='hsi_visibility', /all )
To get all of the unfiltered normal photon visibilities, do:
really_all_vis = o->getdata( /dump )
To retrieve all of the normal photon, regularized electron and regularized photon visibilities, use the get_vis_reg method with the visibility object (not the image object) as follows:
vis_obj = o->get(/obj,
class='hsi_visibility')
vis = vis_obj->get_vis_reg()
help,vis
VIS POINTER = Array[4]
This returns a pointer array, where
*vis[0] contains the filtered (edited, combined, and normalized ) normal photon visibilities
*vis[1] contains the regularized electron visibilities
*vis[2] contains the regularized photon visibilities
*vis[3] contains the normal unfiltered photon visibilities
Bags of visibilities can be stored in a FITS file for reuse. The FITS files contain the visibility bags as well as the control and info parameters in effect in the visibility object at the time they were created.
In the GUI, the option to write the visibility bag to an output file is available through the Write Fits File-> pull-down button.
From the command line, you must call the write method from the visibility object:
vis_obj = o->get(/obj,
class='hsi_visibility')
vis_obj->write ; to autoname file
or
vis_obj->write, vis_out_filename = 'yourvisfile.fits' ; to
specify an output file name
NOTE: Prior to October 2102, once the vis_out_filename parameter was set to a non-blank string, the next getdata() command would automatically write the visibilities in the output file. After October 2012, you must explicitly call the write method.
An existing visibility file can be used as input to avoid having to read and process the raw telemetry files again.
In the GUI, set the 'Select Input' droplist widget to 'Visibility FITS file' and browse to select a file.
From the command line, set parameter vis_input_fits:
o = hsi_image( vis_input_fits =
'yourvisfile.fits' )
o->set, image_alg = 'mem njit'
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 (i.e. any parameters that control the creation of the visibilities such as energy, time, position). For this reason, in the GUI you will notice that most of the 'Change' buttons are not sensitive. You can still set image creation parameters such as image dimension, pixel size, and imaging algorithm. If you select an algorithm that is not visibility based, such as clean and pixon, the image generator will switch to the annular sector method and switch back to accessing the raw 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.
When the visibility file is read, the structures are grouped into sets with common energy and time bins. These sets are loaded into the data property of the visibility object for subsequent use by setting the energy bin or time bin. The regularized visibilities are not written to the visibility FITS file, but instead are recomputed as needed.
NOTE: When using the FITS files the user is forced to use imaging energy bins that are consistent with the visibility im_energy_binning used to construct the photon visibilities. Therefore, the im_energy_binning will be set according to those bins and vis_type when the visibility FITS file is read.
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=''
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) and can be extracted from the image object chain via this command:
vis_obj = o->get(/obj, class='hsi_visibility')
You can also create a visibility object directly by typing
vis_obj = hsi_visibility()
All of the operations above can be 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)
Below are a few more operations (discussed above using the image object) that can be performed on the visibility object (unfiltered means that the edit, combine, and normalize actions have not been taken):
really_all_ph_vis = vis_obj->getdata( /dump ) ; returns all of the unfiltered normal photon visibilities
all_ph_vis = vis_obj->getdata( /all ) ;returns filtered normal photon visibilities for all times/energies
all_vis = vis_obj->get_vis_reg() ; returns all filtered and unfiltered photon vis, reg elec, and reg phot vis
vis_obj->set,vis_input_fits='yourvisfile.fits'
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 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.
After October 2012, there is a new control parameter to select the type of visibility called vis_type (see the Regularized visibility spectra section below).
In October, 2012, we implemented the capability of computing and using regularized electron flux visibilities directly within the RHESSI object framework. We also added the capability of using these electron flux visibilities to compute regularized photon visibilities. These regularization procedures can be accessed through the hsi_image object or the hsi_visibility object using the command line interface or the hessi image GUI. To accommodate the new functionality, there are two changes to the existing visibility software: there are some new fields in the visibility data structure, and writing and reading visibility FITS files has changed.
Prior to October 2012, creating regularized electron flux visibility maps could only be done by scripting a chain of procedures. Now it is possible by setting a few basic object parameters in the CLI or GUI.
See Regularized Electron Flux Visibility Spectra (pdf) for details on regularization and the relationship between the electron flux visibilities and photon visibilities. Regularized photon visibility spectra can be computed directly from a spectrum of regularized electron flux visibilities by integrating over the bremsstrahlung cross-section for all energies greater than the photon energy. The regularization enforces consistency with the bremsstrahlung cross-section across energy bands. This results in more smoothly varying images and better image quality at all energies. Another consideration is that the images are no longer independent in energy when extracting spectra from image cubes. However, even for an image constructed at a single energy there can be cross-talk between different regions. So as before, only simulation can properly evaluate the robustness of any extracted spectrum.
Visibility structures created after October 2012 have the following additional fields: ATTEN_STATE, TYPE, UNITS, COUNT. The functions that work with vis structures will work with the new structure containing the additional fields as well as with the old structure (e.g. from an old visibility FITS file).
There is a new control parameter, vis_type which can be set to the following values:
'PHOTON'
'REGULARIZED ELECTRON'
'REGULARIZED PHOTON'
'PHOTON' (normal photon visibilities) is the default. Prior to October 2012, this was the only type of visibility available. Select your vis_type preference the same way you normally set parameters in the image or visibility object via
o->set, vis_type='photon'
You may also set vis_type using
a shorthand, e.g. 'PHO', 'reg el', or 'reg pho'. You can call
hsi_vis_type(option) to check whether your input is sufficient to obtain
the desired vis_type:
IDL> print, hsi_vis_type('reg el')
reg_electron
IDL> print, hsi_vis_type('reg el',/full)
regularized electron
IDL> vis_obj->set, vis_type = 'PHO'
IDL> print, vis_obj->Get(/vis_type)
photon
For regularized electron visibilities, we have the following energy binning requirements.
1. Minimum energy: Integer >= 10 keV
2. Bin width: Integer between 2 and 6 keV
3. Number of bins: Even number of bins, minimum of 10 bins
For regularized photon visibilities, we have the following energy binning requirements.
1. Minimum energy: Integer >=
10 keV
2. Bin width: Integer between 2 and 6 keV
3. Number of bins: minimum of 5 bins
(They're the same, except for photon visibilities, the minimum number of bins is 5 and there's no requirement for an even number of bins.)
When making the electron flux energy bins from regularization, half as many raw photon visibility energy bins are used, with the same bin width and the same starting energy. These requirements come from the regularization procedure as implemented but are not fundamental to regularization. The regularized photon visibilities are produced in the same procedure and don't require a separate step. The regularized visibilities are reused on subsequent requests from the object provided the originating set of visibilities haven't changed.
Any of the available visibility-based image algorithms can be used with any of the three visibility types (selected by setting the vis_type parameter). The only restriction is that for the two regularized visibility types, the energy binning must conform to the requirements listed above.
As mentioned above, regularized visibilities are not written to the visibility FITS file. The normal photon visibilities are written and read, and the regularized visibilities are computed as requested (by setting vis_type) and saved for reuse (stored in the object). They will be reused if the same normal photon visibilities are used as input.
When using the FITS files the user is forced to use imaging bins that are consistent with the visibility im_energy_binning used to construct the photon visibilities. Therefore, when the visibility FITS file is read, the im_energy_binning will be set to values consistent with the visibilities in the file and the current selection of the vis_type parameter. You may choose any vis_type at this point. If a change in the vis_type parameter forces a change in the energy binning, the following message will be displayed:
Changing im_energy_binning to be compatible with vis_type and sp_energy_binning
hsi_vis_erange(filename) returns the energy bins in the
visibility structure in the FITS file specified by filename (full path
descriptor). For example,
IDL> print,
hsi_vis_erange('vis_test_12-52.fits')
FITSGEN::GETDATA: reading ext 3
MRDFITS: Binary table. 15 columns by 4000 rows.
12.0000 16.0000
16.0000 20.0000
20.0000 24.0000
24.0000 28.0000
28.0000 32.0000
32.0000 36.0000
36.0000 40.0000
40.0000 44.0000
44.0000 48.0000
48.0000 52.0000
hsi_fits_param(filename, type=type) returns CONTROL or INFO
structures from the FITS file specified by filename. Set type to
'control' or 'info'. For example,
IDL> control =
hsi_fits_param('vis_test_12-52.fits',type='control')
FITSGEN::GETDATA: reading ext 0
MRDFITS: Null image, NAXIS=0
FITSGEN::GETDATA: reading ext 1
MRDFITS: Binary table. 120 columns by 1 rows.
IDL> help, control
<Expression> STRUCT = -> <Anonymous> Array[1]
IDL> info =
hsi_fits_param('vis_test_12-52.fits',type='info')
FITSGEN::GETDATA: reading ext 0
MRDFITS: Null image, NAXIS=0
FITSGEN::GETDATA: reading ext 2
MRDFITS: Binary table. 68 columns by 1 rows.
IDL> help,info
<Expression> STRUCT = -> <Anonymous> Array[1]
By examining the CONTROL and INFO structures and the energy
bins returned by hsi_vis erange, you can determine if an existing
visibility FITS file is suitable for your task.
andre.csillaghy@fhnw.ch,
kim.tolbert@nasa.gov, richard.schwartz@nasa.gov
Last Modified: June 8, 2017