Sort ESO/VLT UVES exposures based on header-card values

By: Michael T. Murphy

Usage: UVES_headsort [OPTIONS] [FITS file or list]

Brief description:
When one wishes to reduce ESO/VLT UVES spectra, typically extracted from the science archive, one must go through all the FITS files and decide which ones are the relevant science exposures and which calibration exposures are best to use. This can take a long time. If one has many objects to reduce, it can also be very tedious and you are prone to making mistakes. This can be true even with nice programs provided by ESO, like Gasgano.

UVES_headsort is a C code designed to automate this organisational task. In principle, it is very simple: for each science exposure that it identifies in a given list, it searches for calibration exposures taken soon before or soon after. It creates directories which are named according to the science object names in the FITS headers and then creates links to all the necessary science and calibration files within that directory. The links are named in an obvious way such that the ESO MIDAS and CPL VLT/UVES pipeline software can be used. It also goes one step further and writes reduction scripts which the pipeline understands. The only input required (for default behaviour) is a list of FITS files.

Non-standard requirements:
CFITSIO library.

Copyright 2003-2016 Michael T Murphy

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  1. Download and installation
  2. System architectures tested
  3. Update information
  4. Basic Operation
    1. The input FITS file list: ABSOLUTE PATH NAMES!
    2. Debug mode
  5. Options
  6. Calibration exposure selection
  7. Output

1. Download and installation:
The best, and now only, way to grab the code is to get it from GitHub. You can grab a zip file from that site or, better, you can just use the"git" to "pull" the code to your computer, i.e.

prompt> git clone https://github.com/MTMurphy77/UVES_headsort.git

After grabbing the code (and unzipping the zip file, if that's what you downloaded), change to the source code directory:

prompt> cd UVES_headsort/

You will need to edit the Makefile to reflect your system's architecture, where your CFITSIO libraries are and where you'd like the final executables to be put. For the latter, change the TARGET keyword in the Makefile header. You should then just be able to type

prompt> make

and hopefully things will just compile nicely. Let me know if you have problems compiling the code.

Then, to install the various programs compiled and some additional shell scripts (used by the reduction scripts written out when one runs UVES_headsort), you should type

prompt> make install

Afterwards you might like to do a

prompt> make clean

to remove the *.o and temporary *~ files.

2. System architectures tested:
UVES_headsort is designed to run on UNIX and Linux systems. So far, it has been tested on a wide variety of linux and UNIX platforms, including linux-based Mac OS versions. UVES_headsort should work on any UNIX/Linux installation since the libraries it uses are fairly standard. Let me know if you have problems getting it to work on a specific platform.

3. Update information:
UVES_headsort is a new program and it's written by a C-code amateur. I will try to update the available version (as well as this page) when I make changes. Please let me know if you find bugs or you wish UVES_headsort to do something differently or something new.

I also maintain a list of interested parties to which I send emails regarding update information. If you would like to receive such emails, send an email to me with the Subject heading "Subscribe: UVES_headsort". If you want to stop receiving such emails, send an email to me with the Subject heading "Unsubscribe: UVES_headsort".

4. Basic operation:
To execute the program for the first time, it's best to use the debugging mode so that you can look for errors associated with your input FITS files:

prompt> UVES_headsort -d file_list.txt

You will no doubt receive either an error message or several warning messages. These will probably be associated with your input file (file_list.txt) or the FITS files pointed to by that file.
  1. The input FITS file list: ABSOLUTE PATH NAMES!: Getting the input FITS file list correct is crucial to the workings of UVES_headsort. This file should be text only and should only contain one file name per line. The crucial thing is that each FITS file should be listed with its full absolute path name. For example, the following file list is NOT valid:


    because each line doesn't begin with a "/". It's also a good idea to have the FITS files (pointed to by file_list.txt) somewhere other than the present working directory (PWD).

  2. Debug mode: Using the "-d" option causes the program to enter debug mode in which no changes are made to your system, i.e. the program executes normally up to the point where directories and files/links need to be created. This allows you to quickly check whether the list of files you have supplied in file_list.txt (i) is a list of valid FITS files and (ii) contains all the required calibration frames for each science frame. Any error or warning messages returned should prompt you to change your file list in some way, whether that be (i) correcting errors in file_list.txt or (ii) including/excluding more files from the list. It may also prompt you to change the defaults using the other options (by, for example, increasing the calibration period).

5. Options:

6. Calibration exposure selection:
There are several criteria which a calibration exposure must satisfy if it is to be used to calibrate a given science exposure. These are listed below for each calibration type. One selection criterion common to all is that each calibration exposure must be within the specified calibration period of the science exposure.

7. Output:
Apart from warning and error messages, the optional header information output and object-specific file-list files, UVES_headsort is designed to make science object directories, appropriately named links to the raw FITS files within those directories and MIDAS and CPL reduction scripts to ease the overall pain of doing the pipeline reduction. These are described below.

Last updated: 09th April 2008 by Michael Murphy.