SPEX data format support¶
pyspextools.io
is a Python submodule to read, write and manipulate
SPEX spectrum and response file (.spo and .res). The
format of these FITS files is described in Chapter 5
of the SPEX manual: http://var.sron.nl/SPEX-doc/
Dataset class description¶
SPEX res and spo files can contain a set of spectra and responses from, for example, different instruments used in the same observation or spectra from different spatial regions. Each combination of a spectrum and response is called a region in SPEX (see the region class below). The dataset class is basically a list of regions and allows the user to add and remove regions from a dataset.
- class pyspextools.io.Dataset[source]¶
The dataset class is the most general class containing a dataset with multiple regions. Using this class, users can read, write and manipulate spectral datasets.
- Variables
regions (list) – List of regions.
config (numpy.ndarray) – Response configuration (combinations of sector and region values).
- read_region(isector, iregion, spofile, resfile, label='')[source]¶
Read one region with number iregion from the two SPEX files and add it to the dataset.
- Parameters
isector (int) – Sector number associated with the region to select.
iregion (int) – Region number to select.
spofile (str) – File name of the .spo file.
resfile (str) – File name of the .res file.
label (str) – Text string to identify the region (optional).
- read_all_regions(spofile, resfile)[source]¶
Read all the regions from a spo and res file and add them to the dataset.
- Parameters
spofile (str) – File name of the input .spo file.
resfile (str) – File name of the input .res file.
- append_region(region, isector, iregion)[source]¶
Append a region object to the dataset.
- Parameters
region (pyspextools.io.Region) – Input region object.
isector (int) – Sector number to be selected from the region object.
iregion (int) – Region number to be selected from the region object.
- write_region(spofile, resfile, iregion, exp_rate=True, overwrite=False, history=None)[source]¶
Write one region to a spo and res file.
- Parameters
spofile (str) – File name of the input .spo file.
resfile (str) – File name of the input .res file.
iregion (int) – Region number to be selected from the region object.
exp_rate (bool) – Write an EXP_RATE column or not.
overwrite (bool) – Should we overwrite existing files?
history (List/Array of strings) – History information.
- write_all_regions(spofile, resfile, exp_rate=True, overwrite=False, history=None)[source]¶
Write all regions in the data object to spo and res.
- Parameters
spofile (str) – File name of the input .spo file.
resfile (str) – File name of the input .res file.
exp_rate (bool) – Write an EXP_RATE column or not.
overwrite (bool) – Should we overwrite existing files?
history (List/Array of strings) – History information.
- read_config(res)[source]¶
Read the response configuration.
- Parameters
res (pyspextools.io.Res) – SPEX response object.
- assign_sector(iregion, newsector)[source]¶
Assign a new sector number to a specific region.
- Parameters
iregion (int) – Region number to assign new sector number for.
newsector (int) – New sector number.
- assign_region(iregion, newregion)[source]¶
Assign a new region number to a specific region.
- Parameters
iregion (int) – Region number to assign new number for.
newregion (int) – New region number.
The region class¶
A combination of a spectrum and its response matrix is called a region in SPEX. This name originates from the idea that a dataset (see above) can contain spectra extracted from multiple regions in a spatial image. The region class combines a spo and res object into one region and provides tests to see if the spo and res files actually belong to each other.
- class pyspextools.io.Region[source]¶
A SPEX region is a spectrum/response combination for a specific observation, instrument or region on the sky. It combines the spectrum and response file in one object.
- Variables
spo (pyspextools.io.Spo) – Spo object
res (pyspextools.io.Res) – Res object
- change_label(label)[source]¶
Attach a label to this region to easily identify it. For example: MOS1, annulus 2, etc.
- Parameters
label (str) – Text string to identify region.
- set_sector(sector)[source]¶
Set the sector number for this region.
- Parameters
sector (int) – Sector number to set for this region.
- set_region(region)[source]¶
Set the region number for this region.
- Parameters
region (int) – Region number to set for this region.
- increase_region(amount)[source]¶
Increase the region numbers by an integer amount.
- Parameters
amount (int) – Integer amount to add to region numbers.
The spo class¶
The SPEX .spo file contains the source and background spectra, including information about systematic uncertainties and grouping. This class manages the reading and writing of (regions) in spo files.
- class pyspextools.io.Spo[source]¶
The spo class contains the spectral information for one spo file. This file can contain multiple spectra (regions). A call to spo() sets the variables that will contain the spectral information.
- Variables
sponame (str) – File name of .spo file
empty (bool) – Is this object file empty?
nregion (int) – Number of regions in file
nchan (numpy.ndarray) – Number of channels
echan1 (numpy.ndarray) – Lower energy bin value (keV).
echan2 (numpy.ndarray) – Upper energy bin value (keV).
tints (numpy.ndarray) – Exposure time (s).
ochan (numpy.ndarray) – Source rate (c/s).
dochan (numpy.ndarray) – Error Source rate (c/s).
mbchan (numpy.ndarray) – Background rate (c/s).
dbchan (numpy.ndarray) – Error Background rate (c/s).
brat (numpy.ndarray) – Backscale ratio.
ssys (numpy.ndarray) – Systematic error fraction in ochan.
bsys (numpy.ndarray) – Systematic error fraction in bchan.
used (numpy.ndarray) – True if data channel is used in the calculations.
first (numpy.ndarray) – True if first channel of a binned group, or if it is an unbinned data channel; otherwise false.
last (numpy.ndarray) – True if last channel of a binned group, or if it is an unbinned data channel; otherwise false.
brat_exist (bool) – Does the Exp_rate column exist?
swap (bool) – Does the channel order need to be swapped?
anames (dict) – Dictionary with column names.
mask_region (numpy.ndarray) – Mask for region selection.
mask_spectrum (numpy.ndarray) – Mask for spectrum selection.
- zero_spo(nchan)[source]¶
Creates empty arrays of size nchan.
- Parameters
nchan (int) – Number of channels to create.
- add_spo_region(origspo, iregion=1)[source]¶
Function to add spectrum regions to a spo file.
- Parameters
origspo (pyspextools.io.Spo) – Spo object to import region from.
iregion (int) – Region number to select from spo object.
- del_spo_region(iregion)[source]¶
Remove spectrum from region with number ‘iregion’
- Parameters
iregion (int) – Region number to delete from spo object.
- read_file(spofile)[source]¶
Function to read a spectrum from a .spo file.
- Parameters
spofile (str) – File name of .spo file.
- return_region(iregion)[source]¶
- Function to return a spo object with containing the
spectrum of the region with number ‘iregion’.
- Parameters
iregion (int) – Region number to return.
- write_file(sponame, exp_rate=True, overwrite=False, history=None)[source]¶
Function to write the spectrum to a .spo file with the name ‘sponame’. The exp_rate flag determines whether the Exp_Rate column is added containing the ratio between the backscales of the source and background spectra. This column can only be read by SPEX >=3.05.00.
- Parameters
sponame (str) – File name of the .spo file to write.
exp_rate (bool) – Create an Ext_rate column (yes/no)?
overwrite (bool) – Overwrite existing files (yes/no)?
history (str) – History strings to be added to the file.
- swap_order()[source]¶
Swap the channel order of the spectrum between wavelength or energy order. This is for example helpful for grating spectra, which are originally stored in wavelength order but must be flipped to energy order in SPEX format.
- check_filename(filename)[source]¶
Check if the output filename has the correct .spo extension. The method returns a correct file name.
- Parameters
filename (str) – File name to check.
The res class¶
The SPEX .res file contains the response matrix and effective area information for a spectrum. This class manages the reading and writing of (regions) in res files.
- class pyspextools.io.Res[source]¶
The res class contains the response information for one res file. This file can contain multiple responses (regions).
- Variables
resname (str) – Name of the res file.
empty (bool) – Is the object still empty? (True/False)
nchan (numpy.ndarray) – Number of energy channels.
neg (numpy.ndarray) – Number of energy bins.
sector (numpy.ndarray) – Array containing sector numbers.
region (numpy.ndarray) – Array containing region numbers.
shcomp (numpy.ndarray) – Array containing shared components.
nsector (int) – Number of sectors.
nregion (int) – Number of regions.
ncom (int) – Number of response components
share_comp (bool) – Are there any shared components?
area_scal (bool) – Is there areascal information?
resp_der (bool) – Are there response derivatives?
eg1 (numpy.ndarray) – Start energies for response group.
eg2 (numpy.ndarray) – End energies for response group.
ic1 (numpy.ndarray) – Start channel for response group.
ic2 (numpy.ndarray) – End channel for response group.
nc (numpy.ndarray) – Number of data channels in the group.
relarea (numpy.ndarray) – Area scaling factors.
resp (numpy.ndarray) – Response values for group (m**2).
dresp (numpy.ndarray) – Response derivatives for group (optional).
mask_resp (numpy.ndarray) – Mask array used to select certain response values.
mask_group (numpy.ndarray) – Mask array used to select certain groups.
mask_icomp (numpy.ndarray) – Mask array used to select certain components.
swap (bool) – Should the channel order be swapped?
- add_res_region(origres, isector=1, iregion=1)[source]¶
Function to add region(s) to a response.
- Parameters
origres (pyspextools.io.Res) – Response object to be added to this one.
isector (int) – Sector number of the response object to add.
iregion (int) – Region number of the response object to add.
- del_res_region(isector, iregion)[source]¶
Remove region with number ‘iregion’.
- Parameters
isector (int) – Sector number of the region to be removed.
iregion (int) – Region number of the region to be removed.
- read_file(resfile)[source]¶
Function to read a response from a .res file.
- Parameters
resfile (str) – Response filename to be read.
- return_region(isector, iregion)[source]¶
Return a res object with the data from 1 selected region.
- Parameters
isector (int) – Sector number of the region to be returned.
iregion (int) – Region number of the region to be returned.
- write_file(resfile, overwrite=False, history=None)[source]¶
Write the response information to a .res file with name ‘resfile’.
- Parameters
resfile (str) – Name of the response file to write to.
overwrite (bool) – Should we overwrite existing files?
history (List/Array of strings) – History information
- swap_order()[source]¶
Swap the channel order of the response between wavelength or energy order. This is for example helpful for grating spectra, which are originally stored in wavelength order but must be flipped to energy order in SPEX format.
- append_component(addres, iregion=1, isector=1)[source]¶
Append a component to the response matrix from another matrix. This is used to add orders to the response file for Chandra grating data.
- Parameters
addres (pyspextools.io.Res) – Response object to extract response information from.
iregion (int) – Region number to add to the response.
isector (int) – Sector number to add to the response.
- get_mask(isector, iregion)[source]¶
Create masks to select a particular region in a .res file.
- Parameters
isector (int) – Sector number to create mask for.
iregion (int) – Region number to create mask for.
- channel_shift(shift)[source]¶
Shift the response array indices with an integer number provided by input parameter ‘shift’.
- Parameters
shift (int) – Number of channels to shift the spectrum with.