Getting started

Installing UVOTPY

UVOTPY instructions are only given for linux and Mac OSX.

You may already have Python installed on your system. The current version of UVOTPY was originally written for Python 2.7, but has been adapted to support also Python 3.5+. Since we rely on the Astropy package, Python versions 2.5 and 2.6 are no longer supported. You can check the Python version by opening an X-window or terminal window, and issuing the command:

python --version

Other Python software is required. In particular, UVOTPY relies on Numpy (version >= 1.5), Scipy (version >= 0.15), matplotlib (version >= 1.0), Astropy (version > 1.3), stsci.convolve and stsci.imagestats, while ipython (version >= 0.11) is recommended for interactive sessions.

Note::

For some time now Astropy has provided a replacement for Pyfits and pywcs and now replaces those dependencies.

If you do not have the required software on your computer, and want to install everything in close to one go, there are several options.

For ease of use I recommend the Astroconda <http://astroconda.readthedocs.io/en/latest/>_ environment, whose only drawback is that it only runs under the “bash” shell, and not under the “csh” shell.

If you are on the Mac, installing the required packages using macports is another option, but more work. Some years ago the required software could be found in Fink, but updates of the packages have often been been missing in Fink.

Headas

Not only Python packages are required. The software requires a working, configured Heasoft Swift distribution (version > 6.18), and a recently updated version of the Swift calibration database (CALDB).

Note:

The swift CALDB is updated regularly, and includes frequent clock corrections (one every
few months), and other spacecraft parameters. The UVOT CALDB updates are closer to being
on a yearly basis and mainly affect the photometry.  The grism calibration files have
been distributed with this software since 2010 and are not yet included in the swift
UVOTA CALDB.

Fetching the program and data

If you have all those installed and configured, the UVOTPY package (continually updated since 2014-10-21) can be downloaded from the UVOTPY github repository , or the most current version can also be retrieved via GIT.

For testing this installation, some test data can be downloaded from uvot_testdata.tar.gz.

Installing the program

Personally, I use the uvotpy software by placing it in a directory in my HOME folder, and copy by hand the uvotgrism script to my bin directory (after fixing the first line by hand). I define the global variable UVOTPY to point to the directory (mine is called pymodules) above the uvotpy directory, which contains all the python modules and the calfiles, and add this directory also to my global PYTHONPATH variable.

If that is not your kind of thing it may be easier to have the UVOTPY package installed in your python distribution using the following directions.

To install into the python distribution, make sure that you first activate your python environment. Often there are other distributions of Python on your system, and it is important to start with the environment you will use.

For example, when using “Anaconda3”, you might have installed the “iraf27” environment, so you start with:

> bash  (if you were using "csh")
> source activate iraf27

For details and help, check the information referred to in installing-uvotpy above. Many other setups are possible, and we cannot go into more details here, just make sure that your environment points to the right python installation (with the required libraries installed).

I assume for the example that the software version is -1.0.:

> tar xzf uvotpy-latest.tar.gz
> cd uvotpy-1.0
> python setup.py install (you may need "sudo python setup.py install ")

To install in your “HOME” directory, use

> cd $HOME
> tar xzf uvotpy-latest.tar.gz
> cd uvotpy-1.0
> python setup.py install --home=$HOME

The scripts will then be placed in your $HOME/bin and the UVOTPY modules are in $HOME/lib/python/uvotpy.

Installing the test data

Unpack the uvot_testdata.tgz file in one of your local directories. I’ll assume under your HOME directory for this example:

> tar xzf $HOME/uvot_testdata.tgz

When discussing the example below, I’ll assume it is in the $HOME/uvotpy_test/ directory.

Next thing to do is to set up the environment. I discuss that for unix-like systems only.

Setting up the environment

The package installs a number of calibration and other template files which it needs to find. That is done through defining in the environment the variable UVOTPY. Say your python packages live in /usr/stsci/pyssg/Python-2.7.3/lib/python2.7/site-packages, as you can find out by the command:

which python

and you should now have uvotpy installed there. Then, from the command line, use

setenv UVOTPY <your-python-site-packages-dir>/uvotpy   for [csh shell]
export UVOTPY="<your-python-site-packages-dir>/uvotpy" for [bash shell]

to define the required environment variable. (find your shell with “echo $SHELL”)

If you want to keep things simple, you can just do the following to install in your home directory (assuming the uvotpy version is 1.0):

> cd
> tar xzvf uvotpy-latest.tar.gz
> setenv UVOTPY $HOME/uvotpy-1.0
> setenv PYTHONPATH $HOME/lib/python/
> setenv PATH {$PATH}:{$HOME}/bin

You see in the example above that you will also need to make sure that the UVOTPY software is included in the PATH and the PYTHONPATH environment variables. When you installed UVOTPY in the default location (i.e., not using –prefix <dir>) means your paths will already be fine.

Older versions:

You can keep older versions of the UVOTPY software, just make sure that the environment variables point to the desired version.

More command parameters are available. These can be found in the API description.

Running UVOTPY interactively

The most hands-on processing of the UVOT data is to use interactive python:

> ipython --pylab
> from uvotpy import uvotgetspec

Now a few lines should be printed with the version of uvotpy:

> ra,dec = 254.7129625, 34.3148667  # in decimal degrees
> obsid = "00055900056"  # note the required quotes
> ext = 1
> datadir = "./uvot_test/VGRISM/00055900056/uvot/image"
> uvotgetspec.getSpec(ra,dec,obsid,ext,indir=datadir,fit_second=True,chatter=1,)

Note::

If the program stops with an error message, first check if your path, your ra,dec, and obsid parameters are correct. Those are my most common errors. Also the path for the data “indir=” is often wrong if you change obsids and use the Swift directory structures. Barring those errors, when first running the program, check that your python distribution, libraries, paths, and environment variables are all defined, including “CALDB”.

You should get three plots appearing as explained later, and output files with the extracted spectrum.

Running from the command line

After installation of uvotpy and setting up the environment, the program uvotgrism can be called to extract spectra.

an example would be:

uvotgrism --ra=254.7129625 --dec=34.3148667 --obsid=00055900056 \
--dir=uvot_test/VGRISM/00055900056/uvot/image

There is also a spectrum for the UV grism, but for that example the slit fails to automatically find the right spectrum location. The program is then forced to prompt for a different offset as follows:

uvotgrism --ra=254.7129625 --dec=34.3148667 --obsid=00055900056 \
--anchor_offset=No --dir=UVGRISM/00055900056/uvot/image

when prompted enter for example “1” to position the spectrum correctly. The “1” is a one pixel vertical offset which works in this case.

The data for these examples is included the uvot_testdata.tgz which needs to be downloaded separately as discussed in Fetching the program and data. To save space a set without lenticular images has been used. The test writes the extracted spectrum (fits) files to the current directory. The fits output file names are of the form:

"sw"<10-character obsid number>ug<u or v>_1ord_<ext>_<method>.pha

where ‘ext’ is the extension number of the image in the grism detector image file. <method> flags the way the wavelength anchor position was derived from the sky position, where it is f when a lenticular filter was used or g when the uvotgraspcorr ftool was used. If you provide your own name for the output files, the “sw”<obsid> will be replaced by your string.

Getting a simple ASCII text file

Some people are used to a simple text file with columns for wavelength (in A), flux (in erg/cm2/s/A), and flux error. To extract these from your output fits file, do the following.

Assuming that your output file name is sw00032323001ugu_1ord_4_g.pha, issue the following command:

> ftlist sw00032323001ugu_1ord_4_g.pha+2 t colums=lambda,flux,fluxerr \
rownum=no colheader=no > spectrum.txt

The file usually contains in the start and end rows with NULL values when the flux was negative. Bad data is included, and I recommend checking the data does not include zeroth orders, or have other problems. The fits output file includes other parameters, like the coincidence correction factor which should be less than 2 for a good flux.