Using the Observing Summary and Quicklook Data

The HESSI observing summary and quicklook data is comprised of the level-1 data products listed in Table 1. below. Each type of data is stored in a separate binary extension of a FITS file. Originally we appended the observing summary binary extensions to the level-0 data FITS files. Because of problems associated with reprocessing the observing summary data, after September 2002, we instead append the observing summary extensions to a daily catalog file, and remove them from the level-0 files. Click here for a complete description of the contents of each observing summary data type.

Type	Object Name	Description
Main object	hsi_obs_summary	Access to all Obs. Summ. Data
Individual Data Products	hsi_obs_summ_rate	Observing Summary Rates
	hsi_mod_variance	Modulation Variance
	hsi_ephemeris	Ephemerides
	hsi_qlook_pointing	Quicklook pointing
	hsi_qlook_roll_angle	Roll angle
	hsi_qlook_roll_period	Roll period
	hsi_obs_summ_flag	Obs. Summ. flags
	hsi_flare_list	Flare list
	hsi_qlook_image	Quicklook images
	hsi_qlook_spectra	Quicklook spectra
	hsi_qlook_summary_page	Summary page
	hsi_qlook_monitor_rate	Quicklook monitor rates
	hsi_qlook_packet_rate	Quicklook packet rates
	hsi_qlook_soh	Quicklook state of health data

The hsi_obs_summary object provides access to all of the data types in the observing summary. The purpose of the hsi_obs_summary object is to provide a uniform interface to each individual object, access methods that are identical to the access methods in the rest of the HESSI objects (imaging, spectra, etc.), and to provide a container object for organization.

Note: any of the individual observing summary objects can be created directly, and used to retrieve or plot data, however some of the access methods are not standard. Using these objects directly is described here.

There are only three control parameters for the hsi_obs_summary object, shown in Table 2.

Parameter	Description
obs_time_interval	Time interval of data to retrieve in any anytim format (e.g. any ASCII time, or seconds relative to 1979/1/1)
filename	Name of level-0 FITS file to read
datadir	Directory containing FITS file specified in filename parameter

Table 3 lists the methods that are available in the hsi_obs_summary object, and the classes they currently apply to.

Method Name	Classes	Purpose
set	all classes	procedure to set parameters
get	all classes	function to get parameters
getdata	all classes	function to retrieve data according to control parameters
getaxis	all classes	function to retrieve time axis
plot	hsi_obs_summ_rate hsi_mod_variance hsi_ephemeris hsi_qlook_pointing hsi_qlook_roll_angle hsi_qlook_roll_period hsi_obs_summ_flag	procedure to plot data
plotman	same classes as for plot	procedure to plot data in Plot Manager window
list	same classes as for plot, except hsi_obs_summ_flag	function to return formatted ASCII table of data
changes	hsi_obs_summ_flag	function to return times of changes in the state of each observing summary flag (saa, night, etc.)

Using the HSI_OBS_SUMMARY Object

or alternatively you can set a filename to read and the directory the file is in using the filename and datadir parameters. You must set obs_time_interval or filename (and optionally datadir), but not both. If you set the obs_time_interval, the software automatically finds the file containing that time interval.

Retrieving Data

The hsi_obs_summary object provides access to up to 20 individual obs summary object classes (those listed in Table 1 above). To retrieve data from the different individual objects, we use the class_name keyword. If the class_name keyword is not specified, then the default data type is the Observing Summary Rates (the internal hsi_obs_summ_rate object).

whereas, for example, to retrieve data from the modulation variance data (from internal object hsi_mod_variance), we type:

In fact, we can use any shorthand for the class_name that is unique, such as 'ephem' for 'hsi_ephemeris', or 'pointing' for 'hsi_qlook_pointing'.

The data returned by the getdata method is always a structure. The contents of the structure returned for each class are described here.

Retrieving Corrected Count Rates

We use the corrected count rates keyword to retrieve the observing summary corrected count rates:

We don't need to specify class_name since observing summary count rates are the default data type.

Retrieving Times

Use getaxis(/ut) or getdata(/time_array) or getdata(/xaxis) to retrieve the time array. Include the class_name keyword for data types other than the default.

INFO Parameters

There are no info parameters for the hsi_obs_summary object itself. When you retrieve info parameters, they are specific to the class_name you specify (or to the default hsi_obs_summ_rate object if no class_name is specified). So in the following examples, the first line lists the structure of info parameters for the hsi_obs_summ_rate object, and the second example does the same for the hsi_obs_summ_flag object.

The info parameters specific to each object are described here. Info parameter can be retrieved only after data has been retrieved for the object through getdata, plot, getaxis, etc.

Plotting with the PLOT or PLOTMAN methods

The observing summary classes that have a plot or plotman method are shown in Table 2. The plot method sends the plot to a static IDL plot window. The plotman method sends the plot to an interactive Plot Manager interface that lets you zoom, print, save to file, etc. If you haven't explicitly already retrieved the data for your selected time interval, the plot and plotman methods do it automatically before plotting. The primary keywords that can be used on the plot or plotman command are listed in Table 4. In addition to these keywords, most standard plot keywords can be used.

Keyword	Description
flare	Show flare interval as bar across plot
night (or eclipse)	Show night time interval as bar across plot
saa	Show saa time interval as bar across plot
attenuator	Show time intervals of different attenuator states as bar across plot
decimation	Show time intervals of different decimation states as bar across plot
fast_rate	Show fast_rate time intervals as bar across plot (not implemented yet)
bottom	Show flag interval bars across bottom of plot instead of top
flag_colors	An array of color indices to use for the flag bars on plot (in the following order: saa, night, flare, decimation, attenuator, fast_rate)
ylog	y axis log
dim1_use	Array of indices into y array to plot
dim1_colors	An array of color indices to use for the different traces in the plot (e.g. for obs_summ_rate, the 9 energy bands will be shown separately with these colors, unless dim1_sum is set)
dim1_sum	Sum different traces to produce just one curve in plot (only allowed in cases where it makes sense)
flag_name	Used in the hsi_obs_summ_flag object to specify which flag to get or plot
legend_loc	Location of legend - 0/1/2/3/4/5/6 = none / topleft / topright / bottomleft / bottomright / outside left / outside right

The plotman method automatically defines an appropriate color table and plots in color. The plot method plots in black and white with different line styles unless you set up a color table, and specify the dim1_colors keyword.

If you use the plotman interface, some of the items listed in Table 4 can be controlled interactively using buttons in the plotman interface.

Plotting Manually

obj =hsi_obs_summary(obs_time= ['23-jul-2002 00:16','23-jul-2002 01:15'])
data = obj -> getdata(/corrected)
time = obj -> getdata(/time)
utplot, time - time[0], data.countrate[1,*], time[0]
or
utplot,atime(time), data.countrate[1,*]

The first utplot example uses time in seconds relative to a base time (base time provided as the third argument). The second utplot example uses fully qualified time in ASCII.

Extracting Individual Observing Summary Objects

To extract any of the individual observing summary objects out of the hsi_obs_summary object, use the get method with the object_reference keyword. For example,

Using the Flare List

To extract the flare list from the hsi_obs_summary object, use the class_name keyword as above:

This returns a structure containing start/end/peak times, peak count rates, etc. for each flare within the time range specified in the obs_time_interval control parameter. For a description of all of the parameters in the flare list, click here.

Several utilities have been written to access the flare list more easily, perform selections, and to format the flare parameters into strings. They are described here.

Using the LIST method

Some of the individual objects have a list method (see Table 3). The list method formats the data returned by the object into an ASCII table, and displays the results on the screen, saves the results in a file, or prints the results, as well as returning the string array as the function result. Use the show_text, file_text, or print_text keywords respectively to specify these options. The default is show_text. An example that sends the hsi_ephemeris data to a file is:

Extracting Flag Information

As with the other types of summary data, the flag information can be extracted by the following:

flags contains an array giving the state of all flags for every time in the times array, and info.flag_ids is a string array giving the names of the flags.

To determine when changes in state of any flag occurred, use the changes method:

flag_changes is a structure with a tag for every flag name. Each flag name tag is itself a structure containing an array of start / end times and the state of the flag during those times. Thus, flag_changes.eclipse_flag.start_times are the start times for when the eclipse flag was in the state given by flag_changes.eclipse_flag.state.