HESSI Utility Software Reference

This document: (1) Presents the class diagram of the HESSI data analysis Software; (2) Describes the object classes used in run-time configurations of the data analysis software; (3) Describes the object accessor methods available to retrieve data from the objects; (4) Describes control parameters and keywords allowing to modify the contents of the objects; (5) Describes data structures used by the classes. This document needs not to be read for analyzing HESSI data. Instead, users of the data analysis software might want to look at the HESSI Imaging Overview describing the command-line user interface or by using the hessi graphical user interface (type hessi at the prompt). Furthermore, you may also read the utility quick reference guide for an introduction to HESSI object classes. This manual is intended to developers who need to understand all low-level details. It is assumed that you have installed both IDL version 5.3, as well as the Solar Soft Tree with at least the HESSI, SPEX and XRAY branches of the tree.

Contents

• Class diagram
• Class summary
• Method summary
• Parameter summary
• Keyword summary
• Data structure summary
• Class detail
  Framework, Framework_Template, HSI_BProj, HSI_Calib_Eventlist, HSI_Clean, HSI_Eventlist, HSI_Eventlist_Simulation, HSI_Eventlist_Strategy, HSI_Eventlist_Packet, HSI_FITS, HSI_GSE, HSI_Image, HSI_Image_Alg, HSI_ITOS, HSI_Lightcurve, HSI_MEM_Sato, HSI_Modul_Pattern, HSI_Monitor_Rate, HSI_Packet, HSI_PSF, HSI_Simulation, HSI_SMEX, HSI_Spectrogram, HSI_Spectrum, Selection_Manager, Structure_Manager,

Class diagram

See the diagram on your browser or get a printable pdf version of the diagram.

Class summary

Parameter summary

If a parameter has no default value, it is an info parameter (read-only), iterwise it is a control parameter (read/write).

Method summary

The basic implementation of the methods defined below are implented in the abstract class Framework and either extended or overridden in the concrete classes

A procedure method is called by obj->proc_name whereby proc_name is the name of the method. A function method is called by result = obj->func_name whereby result is any IDL variable name and func_name is the name of the method. Methods and functions accept any keyword parameters of type "Set" as defined in the section Keywords below.

Keyword summary

Each name of a control parameter is associated with a keyword that allows to set or get its value using the procedures set and get. Similarly, each name of an infor parameter is associated with a keyword that allows to get its value. Control parameters can be set with any method. Once a control parameter is set, its value is kept in the object, i.e. it does not need to be set for each method call.

Furthermore, some keywords are used to request a specific subset of the data associated with a specific object. These keywords start in general with the prefix THIS_ and are used only with the method GetData. The default value of a keyword is the value used when the keyword is not used.

Object classes: detail

Framework

1. The primary data which needs to be managed;
2. The control parameters;
3. The informational parameters;
4. The administration parameters.

Construction

Only by inheritance in concrete classes.

Methods

• Get() Retrieves ancillary parameters, from control, information, administration and/or source objects. If only one parameter is requested, Get returns the value of this parameter unless /NOSINGLE is set. If more than one parameter are requested, Get returns an anonymous structure that have for tags the parameters requested. For pointer-type variables, Get does an automatic dereferencing, i.e. it returns the variables to which the pointers are pointing rather than the pointers (but see also /NO_DEREFERENCE).
• GetData() Retrieves primary data. When this function is called, the object checks whether the control parameters have changed, using the function Need_Update (see below). If parameters have changed, it assumes that data need to be recomputed and Process is called. Otherwise the object retrieves the contents of its memory, and makes the appropriate selection depending on the keyword parameters. Note that most of the time this procedure is only the generic part of a redefined procedure GetData in the concrete class.
• Set: Sets values to control parameters. Set does not just store the parameter values into a data structure. It first checks if the parameters are the same as those already stored. If they are, it just returns. If they are not, it will set the need_update flag in the administration structure to 1.
• SetData Input primary data into the framework. This is usually called by the procedure Process
• Plot Plots data associated with an object. This generally first calls GetData, and generates a "view" of the data. Often, tough, the data may be strongly summarized. The generic plotting routine is empty.
• Process This procedure is called whenever an object needs to be updated. It reads in the control parameters associated with the class, reads in the data form a source object (or from any other sources), process the source data and stpres the results into the object's memory.
• Print Prints control, information, and administration parameters.
• Need_Update() Returns "1" if the object must call the procedure Process to update its state; otherwise "0."
• Write Write FITS files, usually binary extensions, with the data associated with the object.

HSI_Bproj

Computes the backprojection for a given count rate. The count rate is given either using the parameter vrate, or if vrate is empty (null pointer), the count rate used is the observed count rate.

Construction

obj = Obj_New( 'hsi_bproj' )

Primary data type

Processing method

Control parameters

Control parameters for the back projection are defined in the structure hsi_bproj_control.

flatfield
vrate

Information parameters

HSI_Clean

Provides a wrapper for the clean image algorithm.

Construction

obj = Obj_New( 'hsi_clean' )

Primary data type

Processing method

Control parameters

Control parameters for the clean algorithm are defined in the structure hsi_clean_parameters.

Informational parameters

chi_sq
residual

Acessor methods

No accessor methods are implemented in this class.

Display methods

No display methods are implemented in this class.

HSI_EventList

Provides data structures and methods to build and access an event list.

Construction

• obj = Obj_New( 'hsi_eventlist' )
• obj = hsi_eventlist()

Methods

• result = obj->Get()
  
• result = obj->GetData( /SCORE THIS_A2D_INDEX=BytArr(27) THIS_ENERGY_BAND=DblArr(2) THIS_TIME_RANGE=DblArr(2)
• obj->Plot, THIS_A2D_INDEX=BytArr(27) THIS_ENERGY_BAND=DblArr(2) THIS_TIME_RANGE=DblArr(2)
• obj->Write, THIS_A2D_INDEX=BytArr(27) THIS_ENERGY_BAND=DblArr(2) THIS_TIME_RANGE=DblArr(2)

Control parameters

• a2d_index_mask
  
• energy_band
  
• time_range
  
• time_unit
  
• ut_ref
  

Informational parameters

Data structures

{hsi_event}
{hsi_eventlist_control}
{hsi_eventlist_info}


---

HSI_Image

Provides data structures and methods for HESSI imaging tasks.

Construction:

obj = Obj_New( 'hsi_image' )
obj = hsi_image()

Methods defined or overriden in this class

Get( )
result = obj->GetData( XAXIS=xaxis, YAXIS=yaxis )
obj->Plot

Control parameters defined in this class:

IMAGE_ALGORITHM


Data structures defined in this class:

{hsi_image_control}
{hsi_image_info}

---

HSI_Image_Alg

HESSI IMAGING ALGORITHM ABSTRACT CLASS DEFINITION. This abstract class defines operations common to all imaging algorithms used for HESSI image processing. It leaves up to the subclasses the behavior that can vary. It is inherited by a concrete class that usually has the same name as the algorithm it implements. This class is a realization of the Template Method design pattern.

Construction:

Only through the concrete classes

Methods defined or overriden in this class

Process

The procedure Process loads the control parameters and passes the control to the child class with image_alg_hook. Once it returns from image_alg_hook, it stores the information parameters that may come out of the concrete class into the object. Image_alg_hook must be defined in the concrete class.

Control parameters defined in this class:

Through concrete classes

Data structures defined in this class:

Through concrete classes

Source class

HSI_Modul_Pattern

Known child classes

HSI_Clean, HSI_Forwardfit, HSI_Pixon.

---

HSI_Monitor_Rate

This class implements methods to access monitor rates data.

Construction:

obj = HSI_Monitor_Rate()

Methods

• INIT:
• GetData:
• Process:
and from Framework: CLEANUP, Get, Set, SetData

Control parameters:

• mr_time_range: Dblarr(2) the time range for which the monitor rates are requested, in Anytim format.
• det_index_mask: Bytarr(18) flags the segments for which the monitor rates are requested

Info parameters:

• dtime: Float
• mon_ut_ref: Double the reference time of the time in the monitor rate structure
• ncycles: Long the number of cyles found in the time interval read

Data structure:

Source class

HSI_Packet

---

HSI_Lightcurve

TBA

HSI_Calib_EventList

Provides data structures and methods to build and access the calibrated event list.

• Construction:

  obj = Obj_New( 'hsi_calib_eventlist' )
  obj = hsi_calib_eventlist()

• Methods defined in this class

  result = obj->Get()
  result = obj->GetData()
  obj->Plot
  obj->Print
  obj->Set
  

• Control parameters defined in this class

  saszero
  time_bin_def
  time_bin_min
  xyoffset
  

• Data structures defined in this class:

  {hsi_calib_event}
  {hsi_calib_eventlist_control}
  {hsi_calib_eventlist_info}
  

• Inheritance:

  HSI_Eventlist(direct)
  HSI_Packet
  HSI_Super
  

HSI_Packet

This class provides data structures and methods to work with HESSI telemetry packets. Packets come in several formats, and one of the main task of this class is to provide a common interface to all formats. The formats (1) construction of a packet object associates a data file with the object. This file can be either a HESSI FITS file, an ITOS-formatted telemetry file or a file containing GSE data.
A selection list determines which packets are to be returned. The selection list is built by requesting specific time range and packet types.

Construction

obj = Obj_New( 'hsi_packet' )
obj = hsi_packet()

Method defined in this class

The function Get returns control data. The type of the returned parameter depends on the keyword set. The SELECTION keyword used alone returns an index list packets given a time range and an application id. The SELECTION keyword used with other keywords will return the corresponding data for only the selected packets
The function GetPacket returns packet data, of type {hsi_packet_source}

Keywords defined in this class:

TBA

---

HSI_PSF

Provides data structure and methods to process and access HESSI point spread functions. This class has a memory: already processed point spread function will not be recalculated.

Construction

obj = Obj_New( 'hsi_psf' )
obj = hsi_psf()

Method defined in this class

psf = obj->GetData( NO_SUM=no_sum, THIS_DET_INDEX=this_det_index )
THIS_HARMONIC_INDEX=this_harmonic_index )


The function GetData allows retrieving point spread functions

Control parameters associated with this class:

• xy_pixel: determines the pixel in the map defined by image_dim and xyoffset for which the psf must be processed

---

HSI_Spectrogram

Abstract class generating spectrograms for a given channel binning / energy binning and time binning.

Construction

Used with a concrete class, see hsi_lighctcurve and hsi_spectrum

Control parameters

• poisson
(Byte)
• seed
(Float)
• coincidence_flag
(Byte)
• other_a2d_index_mask
Bytarr(27)
• sum_flag
(Byte)

Info parameters

• binning

Keywords

Class relationships

HSI_Modpat

TBA

HSI_Spectrum

Generates and provides access to count rate spectra.

Construction

obj = Obj_New( 'hsi_spectrum' )
obj = hsi_spectrum()

Method

result = obj->Get( )
result = obj->GetData()

Keywords

HSI_Modpat

TBA

---

Methods: detail

Get()

Retrieves ancillary parameters, from control, information, administration and/or source objects. If only one parameter is requested, Get returns the value of this parameter unless /NOSINGLE is set. If more than one parameter are requested, Get returns an anonymous structure that have for tags the parameters requested. For pointer-type variables, Get does an automatic dereferencing, i.e. it returns the variables to which the pointers are pointing rather than the pointers (but see also /NO_DEREFERENCE).

GetData()

Retrieves primary data. When this function is called, the object checks whether the control parameters have changed, using the function Need_Update (see below). If parameters have changed, it assumes that data need to be recomputed and Process is called. Otherwise the object retrieves the contents of its memory, and makes the appropriate selection depending on the keyword parameters. Note that most of the time this procedure is only the generic part of a redefined procedure GetData in the concrete class.

Set

Sets values to control parameters. Set does not just store the parameter values into a data structure. It first checks if the parameters are the same as those already stored. If they are, it just returns. If they are not, it will set the need_update flag in the administration structure to 1.

SetData

Input primary data into the framework. This is usually called by the procedure Process

Plot

Plots data associated with an object. This generally first calls GetData, and generates a "view" of the data. Often, tough, the data may be strongly summarized. The generic plotting routine is empty.

Process

This procedure is called whenever an object needs to be updated. It reads in the control parameters associated with the class, reads in the data form a source object (or from any other sources), process the source data and stpres the results into the object's memory.

Print

Prints control, information, and administration parameters.

Need_Update()

Returns "1" if the object must call the procedure Process to update its state; otherwise "0."

Write

Write FITS files, usually binary extensions, with the data associated with the object.

Parameters: detail

A2D_INDEX_MASK (Get, Set)

Allows selecting which a2ds to use. Note that this setting is very low level. Usually you may want to select the detectors instead, with det_index_mask

• Defined in: structure {hsi_eventlist_control}, class HSI_Eventlist.
• Format: Bytarr( 27 ). Each position of the array correspond to a selected a2d
• Range: Each element of the array may take the value 0 or 1.
• Default values: BytArr(27) + 1B
• Example:

  o->Set, A2D_INDEX_MASK = [0,0,0,1,1,1,1,0,0, BytArr(18)]

  This selects the a2ds 3 to 6.

FILENAME (Get, Set)

Specifies the filename containing the level-0 data. The filename may be of type FITS, ITOS, GSE, SMEX or RAW. See the HESSI file formats document for more information on the different formats. Note that usually you may use obs_time_interval to select data, whereby the filename will be automatically selected.

• Defined in: HSI_Packet_File
• Format:String or array of string.
• Range:It is assumed that the files in the list are chronologically ordered.
• Default:Empty string
• Example:

  o->Set, FILENAME = ['gaga1.fits', 'gaga2.fits']

IMAGE_ALGORITHM (Get, Set)

Specifies which algorithm is used to reconstruct the image.

• Defined in:HSI_Image
• Format:String scalar
• Default:'bproj'
• Example:

  o->Set, IMAGE_ALG = 'clean'

IMAGE_DIM (Get, Set)

Specifies the dimension of the image in pixels.

• Defined in: HSI_Modul_Pattern
• Format: 2-Element integer array IntArr(2)
• Range:[16,16] to [1024,1024]. Large images may take exessively long to process.
• Default:[64,64]
• Example:

  o->Set, IMAGE_DIM=[128,128]

N_PACKET (Get)

Returns the number of packets in the file. If used with SELECTION keyword, then returns the number of packets selected.

• Defined in: HSI_Packet_File
• Format: Long Integer Scalar
• Example:

  print, o->Get( /N_PACKET )

PIXEL_SIZE

Specifies the size of the image pixel in arcseconds. See also: IMAGE_DIM

• Defined in: HSI_Modul_Pattern
• Format: 2-Element float array FltArr(2)
• Range: 1 to 100.
• Default: [4,4]
• Example:

  o->Set, PIXEL_SIZE=[1.,1.]

SELECTION (Get)

Returns the indices of the selected packets

• Defined in: HSI_Packet
• Format: Long Integer Array
• Example:

  Help, o->Get( /SELECTION )

SASZERO (Get, Set)

Specifies that the Aspect solution sould be considered as perfect.

• Defined in:HSI_Calib_Eventlist
• Format: Byte scalar with either 1 or 0
• Range: Either 1 or 0
• Default: 0
• Example:

  o->Set, /SASZERO

TIME_BIN_DEF (Get, Set)

Specifies the time bin definition factor for each detector. It is multiplied by TIME_BIN_MIN.

• Defined in: HSI_Binned_Eventlist
• Format: 9-Element float array FltArr(9)
• Range: 1 to ... . You should be very careful when using other values than powers of two
• Default: [...]
• Example:

  o->Set, TIME_BIN_DEF=[1,1,2,4,8,8,16,32,64]

TIME_BIN_MIN (Get, Set)

Specifies the minimum time bin in binary microseconds. It is multiplied by TIME_BIN_DEF.

• Defined in: {hsi_binned_evenlist_control}, class HSI_Binned_Eventlist
• Format: 2-Element integer array IntArr(2)
• Range: [16,16] to [1024,1024]. Large images may take exessively long to process.
• Default [64,64]
• Example:

  o->Set, IMAGE_DIM=[128,128]

VERBOSE (Get, Set)

Flag for controlling whether process messages are printed or not.

• Defined in: {hsi_admin_control}, class Structure_Manager
• Format:Byte scalar
• Range:0B or 1B
• Default:0B
• Example:

  o->Set, /VERBOSE, /THIS_CLASS_ONLY

  will set the verbose flag for the clas o only, i.e. the source classes of o will not be influenced by this setting.

VRATE (Get, Set)

Allows allows passing an arbitrary count rate to the backprojection object. It must have the dimensions defined by time_bin_min and time_bin_def in hsi_binned_eventlist. The best way to know these dimensions is to look at the observed count rates (see example below)

• Defined in: {hsi_bproj_control}, class HSI_BProj
• Format:Array of pointers to array of floats. See the examples on how to know th dimension of the array of floats
• Range:n/a
• Default:array of nil pointers. In this case, the backprojection is computed using the observed count rates.
• Example: To set correctly vrate:

  be = o->getdata( class='hsi_binned_eventlist' )
  vrate = be
  modify_vrate_here_as_you_want
  bp = o->getdata( vrate = vrate )

  will get the observed count rate, assign the values to a new variable whare you can modify them to whatever you want.

XYOFFSET (Get, Set)

Specifies the offset of the map center from the sun center in arcsecs.

• Defined in: {hsi_calib_eventlist_control}, class HSI_Calib_Eventlist
• Format: 2-Element float array FltArr(2)
• Range: [0,0] to [1000,1000].
• Default: [600,200] for the standard default simulation. No defaults for flare data. The values to set here may be taken from the flare list.
• Example:

  o->Set, XYOFFSET=[200,400]

Keywords: detail

Keywords are different from parameters in the sense that they are used to change a standard behaviour of a procedure, but the values they pass are not sorted in the object

XAXIS

Returns the x axis of the data in the class. This may be the pixel location (in arcseconds) if the class is HSI_Image, or time if the class is HSI_Binned_Eventlist

• Use with the method: GetData, classes HSI_Binned_Eventlist HSI_Image HSI_Lightcurve HSI_Spectrogram
• Example:

  image_x_axis = o->GetData( /XAXIS )

YAXIS

Returns the y axis of the data in the class. This may be the pixel location (in arcseconds) if the class is HSI_Image, or the energy edges for the class HSI_Lightcurve

• Use with the method: GetData, classes HSI_Image HSI_Lightcurve HSI_Spectrogram
• Example:

  image_x_axis = o->GetData( /XAXIS )

A. Csillaghy