.. _cmd-spatial:
Command Line Scripts for Spatial Models
=======================================
These are scripts that create photon lists for SIMPUT catalogs that can serve
as inputs to the instrument simulator. For details on what's going on under the
hood, see :ref:`spatial`, :ref:`spectra`, and :ref:`simput`.
Each of these scripts accepts a ``specfile`` argument, which is a two-column ASCII
table of energy (keV) and specific flux (:math:`\rm{photons~s^{-1}~cm^{-2}~keV^{-1}}`)
which can be written using the spectra command-line scripts (see :ref:`cmd-spectra`),
the Python method :meth:`~soxs.spectra.Spectrum.write_file` (see :ref:`spectra`),
or can be created by hand.
.. _cmd-make-point-source:
``make_point_source``
---------------------
This script creates a SIMPUT source of a point source from a spectrum supplied in a
file.
.. code-block:: text
usage: make_point_source [-h] [--src_filename SRC_FILENAME] [--append] [--overwrite] filename name ra0 dec0 specfile
Create a SIMPUT source of a point from a spectrum supplied in a file.
positional arguments:
filename The filename of the SIMPUT catalog to write or to append to.
name The name of the source in the SIMPUT catalog.
ra0 The right ascension of the source in degrees.
dec0 The declination of the source in degrees.
specfile The file containing the spectrum to be used.
optional arguments:
-h, --help show this help message and exit
--src_filename SRC_FILENAME
An optional filename to store the source instead of the SIMPUT catalog file.
--append If set, append a new source an existing SIMPUT catalog.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a brand-new SIMPUT catalog for a point source.
.. code-block:: bash
[~]$ make_point_source pt_src.simput src1 20.0 -32.0 pt_src_spectrum.dat --overwrite
Add a new point source to an existing SIMPUT catalog.
.. code-block:: bash
[~]$ make_point_source pt_src.simput src2 19.0 -31.0 pt_src_spectrum.dat --append --overwrite
Make a brand-new SIMPUT catalog for a point source, but write the source to a different file.
.. code-block:: bash
[~]$ make_point_source pt_src.simput src2 19.0 -31.0 pt_src_spectrum.dat --src_filename=pt.fits --overwrite
.. _cmd-make-beta-model-source:
``make_beta_model_source``
--------------------------
This script creates a SIMPUT source of a :math:`\beta`-model from a spectrum supplied in a
file. The functional form of the :math:`\beta`-model for a surface brightness profile is:
.. math::
S(r) = S_0\left[1+\left(\frac{r}{r_c}\right)^2\right]^{(-3\beta+1/2)}
.. code-block:: text
usage: make_beta_model_source [-h] [--theta THETA] [--ellipticity ELLIPTICITY] [--src_filename SRC_FILENAME] [--append] [--overwrite]
filename name ra0 dec0 r_c beta specfile image_width nx
Create a SIMPUT source of a beta-model from a spectrum supplied in a file.
positional arguments:
filename The filename of the SIMPUT catalog to write or to append to.
name The name of the source in the SIMPUT catalog.
ra0 The right ascension of the source center in degrees.
dec0 The declination of the source center in degrees.
r_c The core radius in arcseconds.
beta The beta parameter.
specfile The file containing the spectrum to be used.
image_width The width of the image in arcminutes.
nx The resolution of the image.
optional arguments:
-h, --help show this help message and exit
--theta THETA The angle through which to rotate the beta model in degrees. Only makes sense if ellipticity is added. Default:
0.0
--ellipticity ELLIPTICITY
The ellipticity of the radial profile, expressed as the ratio between the length scales of the x and y
coordinates. The value of this parameter will shrink or expand the profile in the direction of the "y"
coordinate, so you may need to rotate to get the shape you want. Default: 1.0
--src_filename SRC_FILENAME
An optional filename to store the source instead of the SIMPUT catalog file.
--append If set, append a new source an existing SIMPUT catalog.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a brand-new SIMPUT catalog for a :math:`\beta`-model source.
.. code-block:: bash
[~]$ make_beta_model_source my_srcs.simput beta_src1 20.0 -32.0 10.0 1.0 my_spectrum.dat 30.0 2000 --overwrite
Add a new :math:`\beta`-model to an existing SIMPUT catalog.
.. code-block:: bash
[~]$ make_beta_model_source my_srcs.simput beta_src2 19.0 -31.0 10.0 1.0 my_spectrum.dat 30.0 2000 --append --overwrite
Make a brand-new SIMPUT catalog for a :math:`\beta`-model source, but write the source to a different file.
.. code-block:: bash
[~]$ make_beta_model_source my_srcs.simput src2 19.0 -31.0 10.0 1.0 my_spectrum.dat 30.0 2000 --src_filename=beta.fits --overwrite
Add a new :math:`\beta`-model to an existing SIMPUT catalog, but write the source to
a different file.
.. code-block:: bash
[~]$ make_beta_model_source my_srcs.simput beta_src2 19.0 -31.0 10.0 1.0 my_spectrum.dat 30.0 2000 --append --overwrite --src_filename=pt.fits
Add ellipticity and tilt the model:
.. code-block:: bash
[~]$ make_beta_model_source my_srcs.simput beta_src1 20.0 -32.0 10.0 1.0 my_spectrum.dat 30.0 2000 --ellipticity=0.5 --theta=45.0 --overwrite
.. _cmd-make-double-beta-model-source:
``make_double_beta_model_source``
---------------------------------
This script creates a SIMPUT source of a double-:math:`\beta`-model from a spectrum
supplied in a file. The functional form of the double-:math:`\beta`-model for a
surface brightness profile is:
.. math::
S(r) = S_{0,1}\left\{\left[1+\left(\frac{r}{r_{c,1}}\right)^2\right]^{(-3\beta_1+1/2)} +
\frac{S_{0,2}}{S_{0,1}}\left[1+\left(\frac{r}{r_{c,2}}\right)^2\right]^{(-3\beta_2+1/2)}\right\}
.. code-block:: text
usage: make_double_beta_model_source [-h] [--theta THETA] [--ellipticity ELLIPTICITY] [--src_filename SRC_FILENAME] [--append] [--overwrite]
filename name ra0 dec0 r_c1 beta1 r_c2 beta2 sb_ratio specfile image_width nx
Create a SIMPUT source of a double-beta-model from a spectrum supplied in a file.
positional arguments:
filename The filename of the SIMPUT catalog to write or to append to.
name The name of the source in the SIMPUT catalog.
ra0 The right ascension of the source center in degrees.
dec0 The declination of the source center in degrees.
r_c1 The inner core radius in arcseconds.
beta1 The inner beta parameter.
r_c2 The outer core radius in arcseconds.
beta2 The outer beta parameter.
sb_ratio The ratio of the outer to the inner SB peak value.
specfile The file containing the spectrum to be used.
image_width The width of the image in arcminutes.
nx The resolution of the image.
optional arguments:
-h, --help show this help message and exit
--theta THETA The angle through which to rotate the beta model in degrees. Only makes sense if ellipticity is added. Default:
0.0
--ellipticity ELLIPTICITY
The ellipticity of the radial profile, expressed as the ratio between the length scales of the x and y
coordinates. The value of this parameter will shrink or expand the profile in the direction of the "y"
coordinate, so you may need to rotate to get the shape you want. Default: 1.0
--src_filename SRC_FILENAME
An optional filename to store the source instead of the SIMPUT catalog file.
--append If set, append a new source an existing SIMPUT catalog.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a brand-new SIMPUT catalog for a double-:math:`\beta`-model source.
.. code-block:: bash
[~]$ make_double_beta_model_source my_srcs.simput beta_src1 20.0 -32.0 10.0 1.0 30.0 0.6666 0.5 my_spectrum.dat 30.0 2000 --overwrite
Add a new double-:math:`\beta`-model to an existing SIMPUT catalog.
.. code-block:: bash
[~]$ make_double_beta_model_source my_srcs.simput beta_src2 19.0 -31.0 10.0 1.0 30.0 0.6666 0.5 my_spectrum.dat 30.0 2000 --append --overwrite
Make a brand-new SIMPUT catalog for a double-:math:`\beta`-model, but write the source to a different file.
.. code-block:: bash
[~]$ make_double_beta_model_source my_srcs.simput src2 19.0 -31.0 10.0 1.0 30.0 0.6666 0.5 my_spectrum.dat 30.0 2000 --src_filename=pt.fits --overwrite
Add a new double-:math:`\beta`-model to an existing SIMPUT catalog, but write the source to
a different file.
.. code-block:: bash
[~]$ make_double_beta_model_source my_srcs.simput beta_src2 19.0 -31.0 10.0 1.0 30.0 0.6666 0.5 my_spectrum.dat 30.0 2000 --append --overwrite --src_filename=pt.fits
Add ellipticity and tilt the model:
.. code-block:: bash
[~]$ make_double_beta_model_source my_srcs.simput beta_src1 20.0 -32.0 10.0 1.0 30.0 0.6666 0.5 my_spectrum.dat 30.0 2000 --ellipticity=0.5 --theta=45.0 --overwrite
.. _cmd-make-annulus-source:
``make_annulus_source``
-----------------------
This script creates a SIMPUT source of an annulus or disk with constant surface brightness
from a spectrum supplied in a file.
.. code-block:: text
usage: make_annulus_source [-h] [--theta THETA] [--ellipticity ELLIPTICITY] [--src_filename SRC_FILENAME] [--append] [--overwrite]
filename name ra0 dec0 r_in r_out specfile image_width nx
Create a SIMPUT source of an annulus with uniform surface brightness from a spectrum supplied in a file.
positional arguments:
filename The filename of the SIMPUT catalog to write or to append to.
name The name of the source in the SIMPUT catalog.
ra0 The right ascension of the source center in degrees.
dec0 The declination of the source center in degrees.
r_in The inner annulus of the source center in arcseconds.
r_out The outer annulus of the source center in arcseconds.
specfile The file containing the spectrum to be used.
image_width The width of the image in arcminutes.
nx The resolution of the image.
optional arguments:
-h, --help show this help message and exit
--theta THETA The angle through which to rotate the beta model in degrees. Only makes sense if ellipticity is added. Default:
0.0
--ellipticity ELLIPTICITY
The ellipticity of the radial profile, expressed as the ratio between the length scales of the x and y
coordinates. The value of this parameter will shrink or expand the profile in the direction of the "y"
coordinate, so you may need to rotate to get the shape you want. Default: 1.0
--src_filename SRC_FILENAME
An optional filename to store the source instead of the SIMPUT catalog file.
--append If set, append a new source an existing SIMPUT catalog.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a brand-new SIMPUT catalog for an annulus source.
.. code-block:: bash
[~]$ make_annulus_source my_srcs.simput ann_src1 20.0 -32.0 0.0 30.0 my_spectrum.dat 30.0 2000 --overwrite
Add a new annulus model to an existing SIMPUT catalog.
.. code-block:: bash
[~]$ make_annulus_source my_srcs.simput ann_src2 19.0 -31.0 0.0 30.0 my_spectrum.dat 30.0 2000 --append --overwrite
Add ellipticity and tilt the model:
.. code-block:: bash
[~]$ make_annulus_source my_srcs.simput ann_src1 20.0 -32.0 0.0 30.0 my_spectrum.dat 30.0 2000 --ellipticity=2.0 --theta=30.0 --overwrite
.. _cmd-make-rectangle-source:
``make_rectangle_source``
-------------------------
This script creates a SIMPUT source of a rectangle shape with constant surface brightness
from a spectrum supplied in a file.
.. code-block:: text
usage: make_rectangle_source [-h] [--theta THETA] [--src_filename SRC_FILENAME] [--append] [--overwrite]
filename name ra0 dec0 width height specfile image_width nx
Create a SIMPUT source of a uniformly filled rectangle from a spectrum supplied in a file.
positional arguments:
filename The filename of the SIMPUT catalog to write or to append to.
name The name of the source in the SIMPUT catalog.
ra0 The right ascension of the source center in degrees.
dec0 The declination of the source center in degrees.
width The width of the rectangle in arcseconds.
height The width of the rectangle in arcseconds.
specfile The file containing the spectrum to be used.
image_width The width of the image in arcminutes.
nx The resolution of the image.
optional arguments:
-h, --help show this help message and exit
--theta THETA The angle through which to rotate the rectangle in degrees. Default: 0.0
--src_filename SRC_FILENAME
An optional filename to store the source instead of the SIMPUT catalog file.
--append If set, append a new source an existing SIMPUT catalog.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a brand-new SIMPUT catalog for a rectangle source.
.. code-block:: bash
[~]$ make_rectangle_source my_srcs.simput rect_src1 20.0 -32.0 20.0 10.0 my_spectrum.dat 30.0 2000 --overwrite
Make the same rectangle, but rotate it by 30.0 degrees.
.. code-block:: bash
[~]$ make_rectangle_source my_srcs.simput rect_src1 20.0 -32.0 20.0 10.0 my_spectrum.dat 30.0 2000 --theta=30.0 --overwrite
Create a line source with the same width and rotation angle.
.. code-block:: bash
[~]$ make_rectangle_source my_srcs.simput rect_src1 20.0 -32.0 20.0 0.0 my_spectrum.dat 30.0 2000 --theta=30.0 --overwrite
Add a new rectangle model to an existing SIMPUT catalog.
.. code-block:: bash
[~]$ make_rectangle_source my_srcs.simput rect_src2 19.0 -31.0 20.0 10.0 my_spectrum.dat 30.0 2000 --append --overwrite
.. _cmd-make-fov-source:
``make_fov_source``
-------------------
This script creates a SIMPUT source of a field of view with constant surface brightness
from a spectrum supplied in a file.
.. code-block:: text
usage: make_fov_source [-h] [--src_filename SRC_FILENAME] [--append] [--overwrite] filename name ra0 dec0 fov specfile image_width nx
Create a SIMPUT source of a uniformly filled field of view from a spectrum supplied in a file.
positional arguments:
filename The filename of the SIMPUT catalog to write or to append to.
name The name of the source in the SIMPUT catalog.
ra0 The right ascension of the source center in degrees.
dec0 The declination of the source center in degrees.
fov The field of view on a side in arcminutes.
specfile The file containing the spectrum to be used.
image_width The width of the image in arcminutes.
nx The resolution of the image.
optional arguments:
-h, --help show this help message and exit
--src_filename SRC_FILENAME
An optional filename to store the source instead of the SIMPUT catalog file.
--append If set, append a new source an existing SIMPUT catalog.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Make a brand-new SIMPUT catalog for a field-of-view source.
.. code-block:: bash
[~]$ make_fov_source my_srcs.simput fov_src1 20.0 -32.0 20.0 my_spectrum.dat 30.0 2000 --overwrite
Add a new field-of-view model to an existing SIMPUT catalog.
.. code-block:: bash
[~]$ make_fov_source my_srcs.simput fov_src2 19.0 -31.0 20.0 my_spectrum.dat 30.0 2000 --append --overwrite
``make_phlist_from_ascii``
--------------------------
This script takes a table of photon RA, Dec, and energies from an ASCII-formatted table and writes them
to a new SIMPUT catalog with a photon list.
.. code-block:: text
usage: make_phlist_from_ascii [-h] [--src_filename SRC_FILENAME] [--append] [--overwrite] name filename infile
Create a SIMPUT source from an ASCII table of positions and energies. The file must contain the total source flux in erg/s/cm**2 on the first line, commented with #, and must have three columns of RA (degrees), Dec (degrees), and energy (keV) for each event.
Example:
# 1.194e-15
30.1 45.5 2.71
29.67 44.95 0.31
31.25 45.03 10.01
29.75 44.44 7.34
30.05 44.01 12.01
31.99 45.21 0.05
...
positional arguments:
filename The filename of the SIMPUT catalog to write or to append to.
name The name of the source in the SIMPUT catalog.
infile The file containing the flux and positions and energies.
optional arguments:
-h, --help show this help message and exit
--src_filename SRC_FILENAME
An optional filename to store the source instead of the SIMPUT catalog file.
--append If set, append a new source an existing SIMPUT catalog.
--overwrite Overwrite an existing file with the same name.
Examples
++++++++
Read photons from a file and write to a new SIMPUT catalog file.
.. code-block:: bash
[~]$ make_phlist_from_ascii my_cat.simput photons events.txt --overwrite
Read photons from a file and write to a new SIMPUT catalog file, but write the photons to a new file.
.. code-block:: bash
[~]$ make_phlist_from_ascii my_cat.simput photons events.txt --src_filename=photons.fits
Read photons from a file and append to an existing SIMPUT catalog file.
.. code-block:: bash
[~]$ make_phlist_from_ascii my_cat.simput photons events.txt --append