The OSPEX ANY SPECFILE method was implemented in November 2014 to allow you to analyze any type of input data file by supplying your own software readers. This should be especially useful for new data types that haven't been explicitly implemented in OSPEX (yet), but that you would like to analyze. The idea is that you supply two routines - readers for a spectrum and response file - and tell OSPEX the base name of those readers. When you set the spectrum input file in OSPEX to a file that it doesn't recognize, it will call your reader routines.
Setup
You create one or two routines: one to read the input spectrum file, and, if necessary, another to read the detector response file (input and output required is described below).
The names of those routines must be xxx_data and xxx_drm where xxx is chosen by you.
At the command line, set the ospex control parameter spex_file_reader to a string corresponding to xxx, the base name of those two routines.
o->set, spex_file_reader='xxx'
Using the GUI or the command line, set the input spectrum file, and if necessary, the input response file. If using the command line:
o->set,spex_specfile='yourspectrumfile.yyy'
o->set, spex_drmfile='yourdrmfile.yyy'
Proceed as usual in OSPEX to analyze the data.
xxx_data Routine Requirements
The procedure definition of your xxx_data routine should look like this:
PRO xxx_data, FILES=files, data_str=data_str, ERR_CODE=err_code, ERR_MSG=err_msg, _REF_EXTRA=_ref_extra
The xxx_data routine must have the following keyword arguments:
FILES - (INPUT) Scalar or vector string of file names to read
DATA_STR - (OUTPUT) Structure containing info read from file (described below)
ERR_CODE - (OUTPUT) 0 means success reading file(s). 1 means failure
ERR_MSG - (OUTPUT) string containing error message if any. '' means no error.
_REF_EXTRA - (INPUT) - Only needed if you want to pass arguments through to another routine.
The DATA_STR structure returned by the xxx_data routine must contain these fields:data_str = { $
START_TIME: start_time, $ start time of file in anytim format
END_TIME: end_time, $ end time of file in anytim format
RCOUNTS: rcounts, $ [nenergy,ntime] count data
ERCOUNTS: ercounts, $ [nenergy,ntime] error in count data
UT_EDGES: ut_edges, $ [2,ntime] edges of time bins in anytim format
UNITS: units, $ units of rcounts, usually 'counts'
AREA: area, $ geometric detector area in cm^2
LTIME: ltime, $ [nenergy,ntime] livetimes in sec
CT_EDGES: ct_edges, $ [2,nenergy] edges of energy bins in keV
DATA_NAME: data_name, $ string name of data, e.g. 'RHESSI'
TITLE: title, $ string title of data, e.g. 'RHESSI SPECTRUM'
RESPFILE: respfile, $ string name of corresponding SRM file, or blank string
OR [nedges_out, nedges_in] numeric array of DRM values
OR structure containing fields drm ([nedges_out, nedges_in]), edges_in, and edges_out
DETUSED: detused, $ string of detector names
ATTEN_STATES: atten_states, $ [ntime] array of filter states, or scalar -1 if doesn't apply
DECONVOLVED: deconvolved, $ If 1, original data is already photons
PSEUDO_LIVETIME: pseudo_livetime, $ if 1, livetime isn't a real livetime
XYOFFSET: xyoffset } [2] x,y location of source on Sun
xxx_drm Routine Requirements
The xxx_drm routine is needed only if the RESPFILE value returned by the xxx_data routine did not contain the DRM values (i.e. RESPFILE was not numeric or a structure). In that case, RESPFILE was either the name of the DRM file or a blank string. If you used the GUI to set the spectrum file, and RESPFILE was the name of the DRM file, it will automatically be set for you. If you're using the command line, whether RESPFILE was the name of the file or a blank string, you must explicitly set it via the spex_drmfile parameter.
The procedure definition of your xxx_drm routine should look like this:
PRO xxx_drm, DRM_STR, FILE=file, ERR_CODE=err_code, ERR_MSG=err_msg
The xxx_drm routine must have the following keyword arguments:
FILE - (INPUT) string of file name to read
ERR_CODE - (OUTPUT) 0 means success reading file. 1 means failure.
ERR_MSG - (OUTPUT) string containing error message if any. Blank string means no error.
and the following positional argument:
DRM_STR - (OUTPUT) Structure containing info read from DRM file (must contain these fields):drm_str = { $
EDGES_OUT: edges_out, $ [2,nedges_out] count energy edges in keV
PH_EDGES: ph_edges, $ [2,nedges_in] photon energy edges in keV
AREA: area, $ geometric detector area in cm^2
DRM: drm, $ [nedges_out,nedges_in,nmatrix] DRM matrix for each time interval. If only one time interval, then just [nedges_out,nedges_in]. In units of counts/photon/keV (where keV is the width of each output energy bin).
SEPDETS: sepdets, $ 1 if separate detectors
DATA_NAME: data_name, $ string name of data, e.g. 'RHESSI'
FILTER: atten_state, $ [nfilter] value of filter states, or set to -1 if doesn't apply. If nfilter>1, then TIMES array should contain times of the different filter states.
DETUSED: detused, $ string of detectors used, e.g. '1F 3F 4F 5F 6F 8F 9F'
TIMES: time intervals } [2,ntimes] if nmatrix is > 1 in anytim format. If nmatrix is 1, set to 0.Note that you can supply multiple matrices in the DRM field. If you do, you should specify corresponding time intervals for which each matrix applies in the TIMES field. If the different matrices apply to different filter states (e.g. attenuator states in the RHESSI data), the FILTER field should contain the values of the filter for each of the time intervals. I.e., the third dimension of the DRM array should be equal to the number of TIMES intervals, and the number of FILTER values (if any).
Example
There is an example of using this new 'ANY' input method in the SSW OSPEX directory. The routines stx_read_data.pro and stx_read_drm.pro were written to read simulated STX data. To use them, you would do the following:
o->set, spex_file_reader='stx_read'
o->set, spex_specfile='stx_spectrum_20190101_0000.fits' ; name of your spectrum file
o->set, spex_drmfile='stx_srm_20190101_0000.fits' ; name of your response fileor if you're using the OSPEX GUI:
o->set, spex_file_reader='stx_read'
then use the GUI to navigate to your spectrum input file.
Kim Tolbert
Last Modified:
14 December 2023