.. _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 <http://ipython.org/>`_  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::

   <obsid>/
   <obsid>/auxil/sw<obsid>pat.fits  # these files may be compressed
   <obsid>/auxil/sw<obsid>uat.fits
   <obsid>/auxil/sw<obsid>sat.fits
   <obsid>/uvot/image/sw<obsid>ugu_rw.img (optional)
   <obsid>/uvot/image/sw<obsid>ugu_dt.img (required)
   <obsid>/uvot/image/sw<obsid>ugu_sk.img 
       (example for UV GRISM, *ugv_sk.img for V GRISM)
   <obsid>/uvot/image/sw<obsid>uw1_sk.img (if present)
   <obsid>/uvot/image/sw<obsid>uw2_sk.img (if present)
   
The ``<obsid>``  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  ``sw<obsid>sat.fits`` may be updated 
to ``sw<obsid>uat.fits``, or ``sw<obsid>pat.fits`` 
based on further analysis. 

.. 

  note:

  Start the program from the  ``<obsid>/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 (``<obsid>/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 
``<obsid>/uvot/image/`` directory, or use `cd ``<obsid>/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.