Imaging Spectroscopy with OSPEX

Overview
Defining Regions
Saving and Restoring Region Definitions
Computing Spectra and Errors
New OSPEX Methods for Region Selection
New OSPEX Parameters for Region Selection

Back to Main OSPEX page

Overview

To perform imaging spectroscopy in OSPEX, start with an image cube FITS file.  Currently (October 2005), RHESSI is the only supported data type for image cube input, but the software was written so that other data types can be added easily. 

In order to form a spectrum from the image cube, you must define source region(s) in each image.  For each image in the time/energy grid, the image flux values in the pixels enclosed by the selected region(s) are summed to form a single point in the spectrum for a time bin. Once the spectra are computed, you can proceed through OSPEX in a manner similar to if you had started with a spectrum FITS file.  These are the only differences:

• You don't need an SRM file since the data are already in photons.

• You don't need to subtract background from the spectra derived from images.

• You can not view the data as anything other than a rate or flux.

• Since the data are already in photons, you can't view them in count space.

The photon flux in an image only takes into account the counts within the given energy range, i.e. there are no corrections for effects such as k-escape and compton scattering (the off-diagonal elements of the detector response matrix).  Pileup effects are also not taken into account.  

However, in February, 2006, a new option was added to convert the photon flux back to a count flux, and calculate a full detector response matrix (SRM) to use in making a better estimate of the photon flux.  In this mode (see the parameter spex_image_full_srm),  you can analyze images in lower energies, and you can view the data in count or photon space.

Defining Regions

To select regions in your images, use the Region Selection widget.  You can start it by clicking the Select Regions->  Region Selection Widget button from the 'Select Input widget in the OSPEX GUI, or by calling the roi method:

o -> roi

A panel display of all images in your image cube will appear.  The following (not very good) example shows an image cube containing 7 time intervals and 5 energy bands in which I've selected a single region in every image except one time interval.

By left- and right-clicking in this widget, you are presented with options for selecting or deleting regions, and displaying spectra and time profiles.  When you select options to show spectra or time profiles, the region number(s) in each image used to compute the data are controlled by the value selected in the Region # box on the 'Select Input' widget, (spex_roi_use and spex_roi_integrate parameters from the command line).  Every time you change any region definitions, or the region number(s) to use, new spectra will be computed.

Up to 4 regions can be selected in each image.  (This is a hard-coded limit, but the value is arbitrary and can be increased if there's a need.)  The first region you define in an image is Region 0, the next Region 1, etc.  You should define a region for every part of the image that contains a source, even if you don't plan to use all of the regions.  This is because the error calculation assumes that everything outside all the regions is noise.

The region selections are stored in the object, so you can exit and re-enter the Region Selection widget any time without disturbing the regions.  They are deleted from the object when you select a different input image cube file (see below for saving and restoring regions from files).

Left-click in a single image:

This list of options will appear when you left-click in a single image in the panel display:

If you click one of the 'Define region' options, a plotman window showing that image will open with the plotman mark_box interface for drawing single or multiple regions in that image.  When accepted, the defined regions will be set for that single image, all the images,  or the images at all energies in that time interval depending on which option you chose.

The 'Clear regions' options delete all the regions in the images specified.

Left-click and drag for multiple images:

This list of options will appear when you left-click and drag in the panel display to select more than one image:

If you click one of the 'Define region' options, you have selected which images to apply the next region selection to, but you must then left-click in a single image to specify which image to use for defining the regions.  Once you've made that single-click selection, a plotman window showing that image will open with the plotman mark_box interface for drawing single or multiple regions in that image.  When accepted, the defined regions will be set for the set of images selected, or for the images at all energies in the time intervals selected depending on which option you chose.

Right-click anywhere in panel display for general options:

This list of options will appear when you right-click anywhere in the panel display.

The 'Show Region x' options are useful for seeing how the regions are numbered - these correspond to the region specified by the Region # button in the 'Select Input' widget (spex_roi_use parameter).

The auto plots display the spectrum and time profile for whichever column and row the cursor is hovering over.  As you move the cursor to different columns or rows, the plots will be redrawn automatically.  This can be a little slow, so you probably want to disable it normally.

Configuring the Region Selection Widget

If you want to change the appearance of the panel display or ROI save file settings, close the panel display and use the Region Selection Options widget by clicking Select Regions -> Configure Region Selection Parameters from the Select Input widget, or by calling the roi_config method:

o -> roi_config

or by setting any of the ROI parameters directly at the command line.

Saving and Restoring Region Definitions

Your region definitions can be stored in IDL save files so that you don't have to define them more than once.

Set spex_roi_infile (from the command line or from the Region Selection Options widget) to an existing IDL save file (previously written by OSPEX) to initialize regions.  The regions in the save file must be compatible with the current image cube file (same number of times and energies).  If spex_roi_infile is valid, the regions in the file will be restored into the object at the following times:

• When you set the parameter spex_roi_infile.

• When spectra are computed, if the current ROIs aren't valid.

• When entering the Region Selection Widget, if the current ROIs aren't valid.

• When you call the restore_roi method.

Set spex_roi_outfile (from the command line or from the Region Selection Options widget) to the name of an output IDL save file to save your regions.  If spex_roi_infile is set, the current region definitions are stored in that file at the following times:

• Whenever you change any region definition in any image.

• When you call the save_roi method.

To check what an ROI save file contains, use the list_roi method:

o -> list_roi, 'filename.sav'

Computing Spectra and Errors

For each time interval, the image at each energy band contributes a single point to the spectrum.  The result will be a spectrum for each time interval. 

The spectrum point from a single image is computed  by summing the photon flux (photons/cm^2/sec/arcsec^2) for all the image elements contained inside the region numbers specified by spex_roi_use, or all regions if spex_roi_integrate is set, and multiplying by the area of each pixel.   For rate output, this is multiplied by the detector area.  For flux output, this is divided by the energy width.

The error on that point is computed by finding the maximum value of the image elements outside all defined regions, and dividing by the maximum value of the image elements in the regions used, and dividing by 3, i.e.  (max of noise) / (max of signal) / 3.  This error determination is heuristic and improvements are being studied.

If the spex_image_full_srm option is set (RHESSI only), then the diagonal SRM is calculated and applied to the spectrum to convert to counts/cm^2/sec/arcsec^2 (basically reversing the conversion from counts to photons applied in the RHESSI image object).  A full SRM incorporating all off-diagonal elements is calculated for each attenuator state that occurred during the time of the image cube, and stored in the spex_drm object for  use in converting the spectrum to photon rate or flux.  You will notice that if this option is set (spex_image_full_srm=1), you have the option to plot in count or photon space, whereas you can only plot in photon space if the option is not set.  You can retrieve the calculated SRM in the same way you would normally retrieve data from any of the objects: drm = o->getdata(class='spex_drm').  Use the /all_filters keyword to get the drm matrix for all attenuator states.  print o->get(/spex_drm_filter) prints the attenuator state values.

New OSPEX Methods for Region Selection

New OSPEX Parameters for Region Selection

Kim Tolbert
Last Modified: 21 February 2006