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 the SPEX manual.

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

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='')

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)

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)

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)

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)

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)

Read the response configuration.

Parameters:

res (pyspextools.io.Res) – SPEX response object.

update_config()

Update the response configuration.

assign_sector(iregion, newsector)

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)

Assign a new region number to a specific region.

Parameters:

• iregion (int) – Region number to assign new number for.

• newregion (int) – New region number.

assign_sector_region(iregion, newsector, newregion)

Assign a new sector and region number to a specific region.

Parameters:

• iregion (int) – Region number to assign new sector number for.

• newsector (int) – New sector number.

• newregion (int) – New region number.

show()

Show a summary for the entire dataset

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

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)

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)

Set the sector number for this region.

Parameters:

sector (int) – Sector number to set for this region.

set_region(region)

Set the region number for this region.

Parameters:

region (int) – Region number to set for this region.

increase_region(amount)

Increase the region numbers by an integer amount.

Parameters:

amount (int) – Integer amount to add to region numbers.

check(nregion=False)

Check whether spectrum and response are compatible and whether the arrays really consist of one region (if nregion flag is set).

Parameters:

nregion (bool) – Flag to check whether the arrays just contain one region.

show(isector=1, iregion=1)

Show a summary of the region metadata.

Parameters:

• isector (int) – Sector number to show.

• iregion (int) – Region number to show.

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

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)

Creates empty arrays of size nchan.

Parameters:

nchan (int) – Number of channels to create.

add_spo_region(origspo, iregion=1)

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)

Remove spectrum from region with number ‘iregion’

Parameters:

iregion (int) – Region number to delete from spo object.

read_file(spofile)

Function to read a spectrum from a .spo file.

Parameters:

spofile (str) – File name of .spo file.

return_region(iregion)

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)

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()

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()

Perform several checks whether the information in the spectrum is consistent.

check_filename(filename)

Check if the output filename has the correct .spo extension. The method returns a correct file name.

Parameters:

filename (str) – File name to check.

get_mask(iregion)

Create a mask to select spectral information for one region only.

Parameters:

iregion (int) – Region number to create mask for.

show(iregion=1)

Show some basic properties of the spectrum.

Parameters:

iregion (int) – Region number to show.

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

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)

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)

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)

Function to read a response from a .res file.

Parameters:

resfile (str) – Response filename to be read.

return_region(isector, iregion)

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)

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()

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)

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)

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)

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.

check()

Perform a number of checks to see if the response information is consistent.

check_filename(filename)

Check if the output filename has the correct .res extension. The method returns a correct file name.

Parameters:

filename (str) – File name to check.

show(iregion=1, isector=1)

Show some basic properties of the response file.

Parameters:

• iregion (int) – Region number to show.

• isector (int) – Sector number to show.