.. _getting_started: *************** Getting started *************** .. _installing-uvotpy: 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 _ 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-data: 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 :download:`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-environment: 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 /uvotpy for [csh shell] export UVOTPY="/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 ) 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_interactively: 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_commandline: 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 :ref:`fetching-the-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_1ord__.pha where 'ext' is the extension number of the image in the grism detector image file. 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" 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.