.. _simple_usage:
********************************************************
Getting a quick spectrum with default parameter settings
********************************************************
There are three ways to run the program. The preferred method for me (the developer) is
while using an `ipython `_ shell and the how-to was briefly
shown earlier as :ref:`running_from_commandline`. The second method is as a
command-line call, while the third method would be to run within a Python shell.
The command line call has not been updated since version 1.0, but is calling the
revised spectral extraction code.
.. _preparations:
Preparations
============
Before starting the spectral extraction, the data for your observation(s) needs to be
available on your system. Besides the image files, the spacecraft attitude file and
its directory should be available. Although some options were built-in to the program
for other arrangements, the only known way that works has the same directory and file
structure as that distributed by the Swift archive::
/
/auxil/swpat.fits # these files may be compressed
/auxil/swuat.fits
/auxil/swsat.fits
/uvot/image/swugu_rw.img (optional)
/uvot/image/swugu_dt.img (required)
/uvot/image/swugu_sk.img
(example for UV GRISM, *ugv_sk.img for V GRISM)
/uvot/image/swuw1_sk.img (if present)
/uvot/image/swuw2_sk.img (if present)
The ```` is typically of the form ``"00032323001"``, and is one of the
required inputs needed. During the ground processing at NASA-GSFC, the
initial attitude file ``swsat.fits`` may be updated
to ``swuat.fits``, or ``swpat.fits``
based on further analysis.
..
note:
Start the program from the ``/uvot/image/`` directory to get all files
written to one place. The program supports a directory option, but writes also to the
local directory.
Alternatively, you can leave the original Swift files where they are
and do all processing in a dedicated directory folder which will only
contain the products of the processing.
The second most important item needed is the source position in **RA, Dec (J2000)**
decimal degrees (not in sexagesimal).
Finally, the ``FITS`` extension of the spectrum image (``/uvot/image/`` file) is
needed; when not given it defaults to 1.
The analysis uses the ``detector image *_dt.img`` files which have been *distortion*
corrected. This means that the same correction was applied to the grism image as was
found for the lenticular filter images, but additional distortions remain in the grism
spectra.
IMPORTANT: Internet access is needed so that the USNO-B1 on-line catalog can
be queried for a list of stellar data in the field.
A quick inspection of the ``sky images *_sk.img`` is useful to make sure the spectrum
exposure was correct. There are several other pitfalls, like overlapping orders which
can be diagnosed by using DS9 in combination with a DSS image. That is discussed
elsewhere in :ref:`analysis_basics`.
.. _with_ipython:
Extracting with IPython
=======================
The `ipython` shell is more versatile and user-friendly in interactive sessions, with
command line finish and recall, for example. A session can be started from the
``/uvot/image/`` directory, or use `cd ``/uvot/image/`` ` from within
the ipython shell to go to the directory.
Use the `--pylab` argument to load matplotlib for the session, and define
the required parameters::
ipython --pylab
from uvotpy import uvotgetspec
ra, dec = 123.45678, +65.789012
obsid = "00032109002"
ext = 2
We will use the `getSpec` program from the `uvotpy.uvotgetspec` module of the `uvotpy` package.
We can now do a simple call to the program.
Assuming the obsid and position are all correct::
uvotgetspec.getSpec(ra,dec,obsid,ext, fit_second=False, clobber=False)
I have set here one more parameter "fit_second" to "False", since this can cause problems
when the second order completely overlaps the first order, i.e., is not offset in the
cross-dispersion direction. An offset will have an anchor position for the first order
listed in the output not close to (1100,1100).
Three graphs will appear.
* The first one to quickly view the extraction is positioned
approximately right, and crosses are plotted at about 200A offsets at the
*estimated* location of the spectrum.
* In the second graph the extracted raw data in the form as total counts,
i.e., (no background subtraction, and not as rates), aligned with the image
section obtained after rotating to the dispersion). Also, a *very* rough guess
of the second order counts is made based on those in the first order. It tends
to over-estimate, sometimes as much as a factor of two.
* In the third graph, the flux calibrated spectrum.
It should be noted that the flagging of bad areas is at the moment *pretty bad*, and
needs to be looked at again. I noticed that when running uvotgrism from the command
line the figures don't always show.
The spectra will be written to a file which includes a data extension for use
with XSPEC. However, the RMF file for XSPEC is not produced automatically, since it
involves a very slow piece of code.
For that set the ``getSpec`` parameter ``write_RMF = True``.
The RMF is useful, since the spectral
resolution gets worse to the red, and is especially affecting wavelengths above
400nm in the UV Grism spectra.