Using Duchamp at ATNF

Duchamp should be available on most machines at ANTF, in /usr/local/bin. To run, just type Duchamp at a prompt:

 prompt> Duchamp  
 Usage: Duchamp [OPTION] [FILE] 
 Duchamp is an object finder for spectral-line FITS cubes.
  -p FILE      Read in parameters from FILE, including FITS image location.   
  -f FILE      Use default parameters with imageFile=FILE   
  -t THRESH    Sets the detection threshold to THRESH, overriding that given by the parameter file.   
  -x           Do not use X-windows PGPLOT output
               (equivalent to setting flagXOutput=false -- overrides the parameter file)   

  -v           Return version number and exit   
  -h           Display this help information and exit  

 prompt> Duchamp -v 
 Duchamp version 1.6.1  

The latest documentation can be found online at /nfs/atapplic/duchamp/docs in PDF format.


The Duchamp Source Finder

| Background | Duchamp | The Name | Download | Feedback |


A lot of radio astronomy data consist of three dimensions: two representing the position on the sky, and the third representing frequency (or wavelength, or velocity). If one is observing a particular spectral line, objects such as galaxies (if it is HI) or masers (OH, say) will appear as discrete objects in three dimensions, being constrained in spatial position and frequency coverage.

If one is conducting a survey over a reasonably large area of the sky, one will not want to search manually through the data, but instead do so in an automated and repeatable way, with well-defined selection criteria.

| Top |


Duchamp is a solution to this problem of three-dimensional source finding. It has the following features:

  • Efficient three-dimensional searching and merging of detected objects.
  • Optional noise-reduction prior to searching via the technique of wavelet reconstruction. This innovative procedure greatly enhances the detectability of fainter sources.
  • Alternative use of spatial or spectral smoothing to reduce noise and enhance features.
  • Ease-of-use through a simple parameter file input.
  • Flexibility to control all relevant parameters such as signal-to-noise threshold or the minimum size of detections.
  • A useful range of text- and graphics-based output (click on links to see examples):
    • A list of the detections and their properties, as well as the input parameters that were used. [text file]
    • Integrated spectra of each detection. [postscript file]
    • A map showing the spatial location and integrated flux of the detections. [postscript file]
    • Optional production of Karma annotation files and VOTables (XML format) for use in other programs.

Example of the spectral output
Example of the spectral output of Duchamp.

Duchamp does not make assumptions about the shape of the detections -- it does not fit Gaussians or any other function to the detected objects, it simply reports their locations. Note that it has been designed for the case of small numbers of object pixels in a lot of noise (what one would expect for HI or maser surveys). As it keeps track of all detected pixels, it may not perform as efficiently for cubes with a large amount of extended emission, such as millimetre observations of molecular lines. You are welcome to try it however, and feedback is always well received.

| Top |

Why "Duchamp"?

Odd name — where does it come from? I wanted the program to have an interesting name, preferably not an acronym (so many are just too forced and dodgy...). As it is designed for data cubes, I had initially though of Picasso, after the leading cubist, but that had already been taken by Robert Minchin. So I went with Marcel Duchamp, a cubist, dadaist and surrealist artist, who pioneered the art of "readymades", or "found objects".

| Top |

Obtaining Duchamp


Version 1.6.1 of Duchamp is now available [1 May 2014]. It can be downloaded in source format, in a gzipped tar archive. The code will need to be compiled on your local machine: a configure script and a Makefile are provided to make this as easy as possible.

This release contains a patch for a particular memory leak issue that was present in 1.5 and 1.6. In the process, some changes have been made to a few function interfaces, although this will be transparent to all save for code developers using the library. The progress bar now also prints a percentage as well as the series of hashes. For further details of these changes, consult the CHANGES file.

Three external libraries are required (in addition to the standard C/C++ libraries): PGPLOT, CFITSIO and WCSLIB. It is possible to compile Duchamp without having PGPLOT on your system: you just won't get any of the nice useful graphical output. See the README file for complete information on installation of Duchamp.

Downloads available:

Changes from the previous version can be seen here (this file is included in the tar archive), while the archive files and documentation from the previous release versions are here, if you are really interested.

| Top |

Feedback and bug reporting

I'm always keen to hear from people who have used Duchamp, especially if they have comments on the way it works or suggestions as to how it can be improved. I may not have been thinking of your particular application when I wrote it, so if it doesn't do something you think it should, let me know!

There is a mailing list duchamp-user<at> that users of Duchamp can subscribe to. This will be used to announce updates to the code and any other general issues. All messages will be archived here.

Note that you need to be subscribed to send and receive messages from this list:

  • To subscribe, please send a message to duchamp-user-request<at> with the single word "subscribe" in the body of the message. Send this from your normal email account.
  • If you wish to be removed from this list send an email to duchamp-user-request<at> with the single word "unsubscribe" in the body of the message.

If you wish to report a bug or a problem, or make a suggestion for new and/or improved features, then go to the Duchamp Trac wiki site. There you can submit a new ticket (computer-speak for a bug report or feature request). You can also view any previous reports -- perhaps your problem has already been reported.

| Top |