.. _cmd-spectra:
Command Line Scripts for Spectra
================================
These are scripts that create ASCII tables of spectra for use by other
modules in SOXS. For details on what's going on under the hood, see :ref:`thermal-spectra`.
.. _cmd-make-cie-spectrum:
``make_cie_spectrum``
---------------------
This script creates an ASCII table of an optionally absorbed thermal spectrum
using a CIE model. Options are APEC (the default), SPEX, MeKaL, and Cloudy. For more
details on these options, see :ref:`thermal-spectra`.
.. code-block:: text
usage: make_cie_spectrum [-h] [--velocity VELOCITY] [--model_vers MODEL_VERS]
[--binscale BINSCALE] [--absorb_model ABSORB_MODEL]
[--nH_abs NH_ABS] [--overwrite] [--nolines]
[--abund_table ABUND_TABLE] [--model MODEL]
[--broadening | --no_broadening]
kT abund redshift norm specfile emin emax nbins
Create a thermal CIE spectrum and write it to a file. The abundances of individual
elements can be set by supplying optional arguments in the form of --O=0.5, --Mg=0.6,
etc.
positional arguments:
kT The temperature in keV.
abund The metal abundance in solar units.
redshift The redshift of the source.
norm The normalization of the model, in the standard Xspec units
of 1.0e-14*EM/(4*pi*(1+z)**2*D_A**2).
specfile The filename to write the spectrum to.
emin The minimum energy in keV.
emax The maximum energy in keV.
nbins The number of bins in the spectrum.
options:
-h, --help show this help message and exit
--velocity VELOCITY The velocity broadening parameter, in units of km/s. Default:
0.0 Only available for 'apec' and 'spex' models.
--model_vers MODEL_VERS
The version of the CIE tables to use. Default is to use the
version currently included with this version of SOXS.
--binscale BINSCALE The scale of the energy binning: "linear" or "log". Default:
"linear"
--absorb_model ABSORB_MODEL
Model for applying foreground Galactic absorption.
--nH_abs NH_ABS The hydrogen column in units of 10**22 atoms/cm**2.
--overwrite Overwrite an existing file with the same name.
--nolines Make a spectrum without lines. Only available for 'apec' and
'spex' models.
--abund_table ABUND_TABLE
The abundance table to be used for solar abundances. Either a
string corresponding to a built-in table or an ASCII file
containing a column of 30 floats corresponding to the
abundances of each element relative to the abundance of H.
Default is set in the SOXS configuration file, the default
for which is 'angr'.
--model MODEL The CIE model to use when generating the spectrum, either
'apec', 'spex', 'mekal', or 'cloudy'. Default: 'apec'
--broadening Turn thermal and velocity broadening on. On by default. Only
available for 'apec' and 'spex' models.
--no_broadening Turn thermal and velocity broadening off. On by default. Only
available for 'apec' and 'spex' models.
Examples
++++++++
Make a basic spectrum for a thermal plasma.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --overwrite
The same spectrum, but with velocity broadening.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --velocity=200.0 --overwrite
The same spectrum, but with velocity and thermal broadening turned off.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --no_broadening --overwrite
The same spectrum, but with foreground galactic absorption using the "wabs" model
with :math:`N_H = 0.04~\times~10^{22}~\rm{atoms~cm^{-2}}`.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --absorb_model="wabs" --nH_abs 0.04 --overwrite
The same spectrum, but with a different APEC version.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --model_vers=2.0.2 --overwrite
The same spectrum, but without emission lines.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --nolines --overwrite
The same spectrum, but setting the abundances of elements oxygen and calcium separately.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --O=0.5 --Ca=0.7 --overwrite
The same spectrum, but using Asplund abundances instead of Anders & Grevesse.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --abund_table=aspl --overwrite
The same spectrum, but with log-spaced binning.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --binscale=log --overwrite
The same spectrum, but using abundances drawn from an ASCII table file instead of Anders & Grevesse.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --abund_table=my_abund.dat --overwrite
The same spectrum, but using the SPEX model instead of APEC.
.. code-block:: bash
[~]$ make_cie_spectrum 6.0 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --model=spex --overwrite
.. _cmd-make-igm-spectrum:
``make_pion_spectrum``
----------------------
This script creates an ASCII table of an optionally absorbed thermal spectrum
using the SOXS Cloudy-based photoionization model. For more details on what's
going on under the hood, see :ref:`pion-spectra`.
.. code-block:: text
usage: make_pion_spectrum [-h] [--binscale BINSCALE] [--resonant_scattering]
[--cxb_factor CXB_FACTOR]
[--absorb_model ABSORB_MODEL] [--nH_abs NH_ABS]
[--overwrite]
kT nH abund redshift norm specfile emin emax nbins
Create a thermal spectrum using the SOXS Cloudy-based photoionization model and write
it to a file. The abundances of individual elements can be set by supplying optional
arguments in the form of --O=0.5, --Mg=0.6, etc.
positional arguments:
kT The temperature in keV.
nH The hydrogen number density in cm**-3.
abund The metal abundance in solar units.
redshift The redshift of the source.
norm The normalization of the model, in the standard Xspec units
of 1.0e-14*EM/(4*pi*(1+z)**2*D_A**2).
specfile The filename to write the spectrum to.
emin The minimum energy in keV.
emax The maximum energy in keV.
nbins The number of bins in the spectrum.
options:
-h, --help show this help message and exit
--binscale BINSCALE The scale of the energy binning: "linear" or "log". Default:
"linear"
--resonant_scattering
Whether or not to include the effects of resonant scattering
from CXB photons. Default: False
--cxb_factor CXB_FACTOR
The fraction of the CXB photons that are resonant scattered
to enhance the lines. Default: 0.5
--absorb_model ABSORB_MODEL
Model for applying foreground Galactic absorption.
--nH_abs NH_ABS The hydrogen column in units of 10**22 atoms/cm**2.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a basic photoionization spectrum for a thermal plasma.
.. code-block:: bash
[~]$ make_pion_spectrum 6.0 1.0e-3 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --overwrite
The same spectrum, but with foreground galactic absorption using the "tbabs" model
with :math:`N_H = 0.04~\times~10^{22}~\rm{atoms~cm^{-2}}`.
.. code-block:: bash
[~]$ make_pion_spectrum 6.0 1.0e-3 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --absorb_model="tbbs" --nH_abs 0.04 --overwrite
The same spectrum, but with log-spaced binning.
.. code-block:: bash
[~]$ make_pion_spectrum 6.0 1.0e-3 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --binscale=log --overwrite
The same spectrum, but with resonant scattering.
.. code-block:: bash
[~]$ make_pion_spectrum 6.0 1.0e-3 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --resonant_scattering --overwrite
The same spectrum, but with resonant scattering and only 0.3 of the CXB scattered.
.. code-block:: bash
[~]$ make_pion_spectrum 6.0 1.0e-3 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --cxb_factor=0.3 --resonant_scattering --overwrite
The same spectrum, but with abundances of O, Ne, and Fe specified.
.. code-block:: bash
[~]$ make_pion_spectrum 6.0 1.0e-3 0.3 0.05 1.0e-4 my_thermal_spectrum.dat 0.1 10.0 10000 --O=0.7 --Ne=0.6 --Fe=0.8 --overwrite
``make_powerlaw_spectrum``
--------------------------
This script creates an ASCII table of an optionally absorbed power-law spectrum. This spectrum has the
form:
.. math::
F_E = K\left[\frac{E(1+z)}{{\rm 1~keV}}\right]^{-\alpha}
.. code-block:: text
usage: make_powerlaw_spectrum [-h] [--binscale BINSCALE]
[--absorb_model ABSORB_MODEL] [--nH_abs NH_ABS]
[--abund_table ABUND_TABLE] [--overwrite]
photon_index redshift norm specfile emin emax nbins
Create a power-law spectrum and write it to a file.
positional arguments:
photon_index The spectral index of the power law.
redshift The redshift of the source.
norm The normalization of the source in units of
photons/s/cm**2/keV at 1 keV in the source frame.
specfile The filename to write the spectrum to.
emin The minimum energy in keV.
emax The maximum energy in keV.
nbins The number of bins in the spectrum.
options:
-h, --help show this help message and exit
--binscale BINSCALE The scale of the energy binning: "linear" or "log". Default:
"linear"
--absorb_model ABSORB_MODEL
Model for applying foreground Galactic absorption.
--nH_abs NH_ABS The hydrogen column in units of 10**22 atoms/cm**2.
--abund_table ABUND_TABLE
The abundance table to be used if the absorption model is
TBabs. Takes a string corresponding to a built-in table.
Default is set in the SOXS configuration file, the default
for which is 'angr'.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a basic power-law spectrum.
.. code-block:: bash
[~]$ make_powerlaw_spectrum 1.1 0.05 1.0e-4 my_powerlaw_spectrum.dat 0.1 10.0 10000 --overwrite
The same spectrum, but with foreground galactic absorption using the "tbabs" model
with :math:`N_H = 0.04~10^{22}~\rm{atoms~cm^{-2}}`.
.. code-block:: bash
[~]$ make_powerlaw_spectrum 1.1 0.05 1.0e-4 my_powerlaw_spectrum.dat 0.1 10.0 10000 --absorb_model="tbabs" --nH_abs 0.04 --overwrite
The same spectrum, but with log-spaced binning.
.. code-block:: bash
[~]$ make_powerlaw_spectrum 1.1 0.05 1.0e-4 my_powerlaw_spectrum.dat 0.1 10.0 10000 --binscale=log --overwrite
The same spectrum, but switching the abundance table used for the "tbabs" model.
.. code-block:: bash
[~]$ make_powerlaw_spectrum 1.1 0.05 1.0e-4 my_powerlaw_spectrum.dat 0.1 10.0 10000 --absorb_model="tbabs" --nH_abs 0.04 --abund_table="feld" --overwrite