Contents

PySpexio (Python Libary)

The commands in this section are all related to the data structures within SPEX. They deal with spectral data and responses, simulation of data, etc. A SPEX model is organised in sectors and components. Sectors are groups of components that model a particular source of radiation. Below, the basic commands for building the model and change its parameters are listed.

Start a pyspex session

For this example pyspex session in python, we use the interactive mode of python. We simply start python from the Linux command line (making sure that the environment is set using a spexdist script located in the SPEX install directory):

linux:~> source nextspex/nextspex.sh
linux:~> python
Python 3.8.11 (default, Jul 29 2021, 14:57:32)
[Clang 12.0.0 ] :: Anaconda, Inc. on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

If the PYTHONPATH variable is correctly set, we should now be able to import the Amodel class from pyspex.atom:

>>> from pyspex.atom import Amodel

Next you can easily start a session to obtain data from the atomic database.

>>> dm = Amodel()

>>> dir(dm)
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__gt__', '__hash__', '__init__',
'__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__',
 '__subclasshook__', '__weakref__', 'abun', 'abun_show', 'aerror', 'ascdump', 'calc', 'com', 'com_del', 'com_rel', 'com_show', 'egrid', 'egrid_get', 'egrid_read',
 'egrid_save', 'egrid_set', 'egrid_step', 'elim', 'flux_get', 'ibal', 'ibal_show', 'instance', 'mod', 'mod_egrid', 'mod_flux', 'mod_ibal', 'mod_var', 'par_show',
 'read_init', 'sector', 'sector_adump', 'sector_copy', 'sector_del', 'var_calc', 'var_cxcon', 'var_doppler', 'var_gacc', 'var_gacc_reset', 'var_ibalmaxw',
 'var_line',

The dm object now contains all the functions and commands that are available to control the NEXTSPEX session.

Data

Loading spectral data and responses in SPEX is done with the data command. Data can be added by loading a .res and .spo file that contain the response and spectral information for an instrument. The PYSPEX command is:

Spex.data(resfile, spofile)

Load instrument data into SPEX using a .res and a .spo file.

Parameters:

  • resfile (str) – SPEX response file name (including .res extension).

  • spofile (str) – SPEX spectrum file name (including .spo extension).

where resfile is the response file and spofile the spectrum file. Note that this command needs the full filename (and if necessary the path to the file) including the extension. This is the only difference with the SPEX syntax. Example:

>>> s.data('xifu.res','xifu.spo')

Data delete

Deleting a loaded spectrum and response is done in SPEX with the data delete instrument #i command. In PYSPEX, this command is:

Spex.data_del(ins)

Delete an instrument from the dataset.

Parameters:

ins (int) – Instrument number to delete.

where ins is the instrument number to be deleted. For example:

>>> s.data_del(1)

Data save

Simulated spectra can be saved as a .spo file. In SPEX, this is done using the data save #i <spofile> command. In PYSPEX, the command is:

Spex.data_save(ins, spofile, overwrite=False)

Save the (simulated) spectrum to a .spo file.

Parameters:

  • ins (int) – Instrument number to save.

  • spofile (str) – Output filename for SPEX output file (including .spo extension).

  • overwrite (bool) – (Optional) Overwrite an existing .spo file with the same name.

where ins is the instrument number of the data to be saved, spofile is the name of the output .spo file. Again note that you should give the full file name, including the .spo extension. Optionally, you can tell the command that existing files may be overwritten. For example:

>>> s.data_save(1,'sim.spo',overwrite=True)

or simply:

>>> s.data_save(1,'sim.spo')

if the file does not exist yet.

Binning and data selection

Unlike some other fitting packages, SPEX rebins the spectra within the program. The easiest binning method is to just rebin with a certain integer factor. This is the bin command in SPEX. In addition, SPEX contains a binning method based on the bin statistics (vbin) and an optimal binning algorithm (obin) which takes the instrument resolution into account.

Binning with factor

Binning with an integer factor is done with the bin command:

Spex.bin(inst, reg, elow, ehigh, factor, unit)

Bin the spectrum using a fixed factor.

Parameters:

  • inst (int) – Instrument number.

  • reg (int) – Region number.

  • elow (float) – Start point of energy/channel interval.

  • ehigh (float) – End point of energy/channel interval.

  • factor (int) – Binning factor

  • unit (str) – Unit of the energy/channel range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

In this example, we bin the spectrum with a factor of 5 between 0.3 and 10 keV:

>>> s.bin(1,1,0.3,10.,5,'kev')

Variable binning

Variable binning is done with the vbin command:

Spex.vbin(inst, reg, elow, ehigh, factor, snr, unit)

Bin the spectrum using a variable bin size, given a minimum bin factor and a minimum signal to noise ratio.

Parameters:

  • inst (int) – Instrument number.

  • reg (int) – Region number.

  • elow (float) – Start point of energy/channel interval.

  • ehigh (float) – End point of energy/channel interval.

  • factor (int) – Minimal binning factor

  • snr (float) – Minimal signal to noise for a data point after binning.

  • unit (str) – Unit of the energy/channel range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

In this example, we bin the spectrum with a minimum factor of 3 and a minimum signal-to-noise ratio of 25 between 0.3 and 10 keV:

>>> s.vbin(1,1,0.3,10.,3,25.,'kev')

Optimal binning

The optimal binning algorithm bins based on the instrument resolution and statistics:

Spex.obin(inst, reg, elow, ehigh, unit)

Bin the spectrum optimally given the instrument resolution and statistics.

Parameters:

  • inst (int) – Instrument number.

  • reg (int) – Region number.

  • elow (float) – Start point of energy/channel interval.

  • ehigh (float) – End point of energy/channel interval.

  • unit (str) – Unit of the energy/channel range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

In this example, we optimally bin the spectrum between 0.3 and 10 keV:

>>> s.obin(1,1,0.3,10.,'kev')

Data selection

Selecting data is done using the use and ignore commands. By default, the bin selection in the .spo file is loaded, which should use all the good bins.

Use function

Spex.use(inst, reg, elow, ehigh, unit=None)

Use the bins given by the energy/channel range.

Parameters:

  • inst (int) – Instrument number.

  • reg (int) – Region number.

  • elow (float) – Start point of energy/channel interval.

  • ehigh (float) – End point of energy/channel interval.

  • unit (str) – Unit of the energy/channel range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

Example:

>>> s.use(1,1,0.3,10.,'kev')

Ignore function

Spex.ignore(inst, reg, elow, ehigh, unit)

Ignore the bins given by the energy/channel range.

Parameters:

  • inst (int) – Instrument number.

  • reg (int) – Region number.

  • elow (float) – Start point of energy/channel interval.

  • ehigh (float) – End point of energy/channel interval.

  • unit (str) – Unit of the energy/channel range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

Example:

>>> s.ignore(1,1,0.0,0.3,'kev')
>>> s.ignore(1,1,10.,100.,'kev')

Systematic errors

If needed, the error bars on the source and background spectrum can be enlarged by the syserr command:

Spex.syserr(inst, reg, elow, ehigh, src, bkg, unit)

Add an additional error to the source and background spectrum.

Parameters:

  • inst (int) – Instrument number.

  • reg (int) – Region number.

  • elow (float) – Start point of energy/channel interval.

  • ehigh (float) – End point of energy/channel interval.

  • src (float) – Error value to be quadratically added to the current error bar of the source spectrum.

  • bkg (float) – Error value to be quadratically added to the current error bar of the background spectrum.

  • unit (str) – Unit of the energy/channel range, for example: ‘kev’, ‘ev’, ‘ryd’, ‘j’, ‘hz’, ‘ang’, ‘nm’

Warning

To use this function, you need to know what you are doing statistically. In many cases, this function would produce wrong results.

Simulate

Based on an instrument response and a model spectrum, SPEX can simulate an observed spectrum using the simulate commands. In SPEX, the options can be set by giving multiple commands, but in PYSPEX this is done in a single command with optional parameters:

Spex.simulate(extime, ssys=None, bsys=None, noise=None, bnoise=None, seed=None)

Simulate a spectrum using a loaded response file.

Parameters:

  • extime (float) – Exposure time to simulate.

  • inst (str) – (Optional) Instrument range to simulate (default all)

  • reg (str) – (Optional) Region range to simulate (default all)

  • ssys (float) – (Optional) Add a systematic error to the source spectrum (Default 0).

  • bsys (float) – (Optional) Add a systematic error to the background spectrum (Default 0).

  • noise (bool) – (Optional) Add Poisson noise to the simulated source spectrum (Default True).

  • bnoise (bool) – (Optional) Add Poisson noise to the simulated background spectrum (Default False).

  • seed (int) – (Optional) Set the random seed for the simulation (Default: system clock).

The only required parameter is extime, which is the desired exposure time (float) for the simulation.

The optional parameters are:

  • inst The instrument number range to simulate (string). Just like in SPEX, the range can be provided by giving two numbers with a : in between, like 1:3.

  • reg The region number range to simulate (string). This has the same behaviour as inst.

  • ssys Adds a systematic error to the source spectrum (float, default is 0.).

  • bsys Adds a systematic error to the background spectrum (float, default is 0.).

  • noise Adds Poisson noise to the simulated spectrum (default is True).

  • bnoise Adds Poisson noise the the background spectrum (default is False).

  • seed Provide a random seed for the simulation (by default the seed is randomly generated using the system clock).

For example:

>>> s.simulate(1E+5, inst='1:3', bnoise=True, seed=42)