----------------------------------------------------------------------- The Duchamp Source Finder ----------------------------------------------------------------------- Duchamp 1.6.1 -- an object finder for spectral-line data cubes Copyright (C) 2006-2014 Matthew Whiting, CSIRO Astronomy & Space Science Duchamp 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. Duchamp 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. You should have received a copy of the GNU General Public License along with Duchamp; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA Correspondence concerning Duchamp may be directed to: Internet email: Matthew.Whiting [at] atnf.csiro.au Postal address: Dr. Matthew Whiting Australia Telescope National Facility, CSIRO PO Box 76 Epping NSW 1710 AUSTRALIA ----------------------------------------------------------------------- Introduction ============ Duchamp is a stand-alone program designed to find objects in astronomical data cubes, particularly spectral-line observations. Its features include a wavelet-based reconstruction technique for reducing the noise in the cube (and thereby enhancing detectability of sources), easy-to-use text-based interface, flexibility to control all relevant parameters such as detection thresholds, and a useful range of text- and graphics-based output. Duchamp works on any FITS image using the CFITSIO package, and uses Mark Calabretta's WCSLIB library to provide accurate position and velocity information for all detected sources. Obtaining and Building Duchamp ============================== The Duchamp web page is at http://www.atnf.csiro.au/people/Matthew.Whiting/Duchamp where you can download a gzipped tar archive of the source code. Duchamp uses three main external libraries: pgplot (although see note below), cfitsio (version 2.5 and greater, version 3+ preferred) and wcslib. If you do not have the libraries, they can be downloaded from the following locations: PGPLOT -- http://www.astro.caltech.edu/~tjp/pgplot/ cfitsio -- http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html wcslib -- http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/index.html Note that PGPLOT is optional. Duchamp can be compiled and run without PGPLOT, but you will miss out on the useful graphical outputs! The other two libraries, cftisio and wcslib, are essential. Basic Compilation and Installation ---------------------------------- Duchamp can be built and installed on Unix systems by typing (note that the terminal prompt here is represented by > -- don't type this character!): > ./configure > make > make lib (optional -- this makes libraries for use in code development) > make clean (again optional -- to remove the object files from the src directory) > make install This default setup will search in standard locations for the necessary libraries, and install the executable ("Duchamp") in /usr/local/bin (a copy will also be in the current directory). It also installs the libraries libduchamp.1.6.a and libduchamp.1.6.so in /usr/local/lib and the header (.hh) files in /usr/local/include/duchamp. If you want these to go somewhere else, eg if you don't have write-access to that directory, or you need to tweak the libraries, see the next section. Otherwise, jump to the testing section. Tweaking the installation setup ------------------------------- To install Duchamp in a directory other than /usr/local/bin, use the --prefix option with configure, specifying the directory above the \texttt{bin/} directory. eg: > ./configure --prefix=/home/mduchamp which, if you run "make" and "make install", will result in the binary being put in the directory /home/mduchamp/bin. Similarly the library will be put in /home/mduchamp/lib and the header files in /home/mduchamp/include/duchamp and subdirectories thereof. If the above-mentioned libraries have been installed in non-standard locations, or you have more than one version installed on your system, you can specify specific locations by using the --with-cfitsio=, --with-wcslib= or --with-pgplot= flags. For example: > ./configure --with-wcslib=/home/mduchamp/wcslib-4.2 And then just run make in the usual fashion: > make Duchamp can be compiled without PGPLOT if it is not installed on your system -- the searching and text-based output remains the same, but you will not have any graphical output. To manually specify this option, use the --without-pgplot flag, eg: > ./configure --without-pgplot (Note that CFITSIO and WCSLIB are essential, however, so --without-wcslib or --without-cfitsio will not work.). Even if you do not give the --without-pgplot option, and the PGPLOT library is not found, Duchamp will still compile (albeit without graphical capabilities). Troubleshooting the installation -------------------------------- There may be issues with the configure/make/install process that arise from non-standard locations of key libraries. The User's Guide has a section in Appendix A discussing some of the more common problems and potential solutions. Feeback is welcome if you have trouble getting Duchamp working -- see the feedback section below. Testing ======= There is a script included in the distribution that allows you to make sure Duchamp is running correctly. It will use a dummy FITS image in the verification/ directory -- this image has some Gaussian random noise, with five Gaussian sources present, plus a dummy WCS. The script runs Duchamp on this image with three different sets of inputs, and compares to known results, looking for differences and reporting any. There should be none reported if everything is working correctly. To run, enter the command > ./VerifyDuchamp.sh This performs basic checks on the output files, but ignoring most of the actual values of source parameters (to avoid picking up just differences due to precision errors). For complete checks of the files, run > ./VerifyDuchamp.sh -f Be warned that on some systems this could provide a large number of apparent errors which may only be due to precision differences. Once you know it is working, you can install Duchamp on your system with the command > make install (this may need to be run as sudo depending on your system setup and your prefix directory). You can also use the dummy image for your own testing if you like (for instance, testing different thresholds to get a feel for how the program works). Using Duchamp ============= There are two possible ways to run Duchamp. The first is: > Duchamp -f image.fits where image.fits is the data cube to be searched. This method simply uses the default values of all parameters. The second method allows some determination of the parameter values by the user. Type: > Duchamp -p parameterFile where parameterFile is a file with the input parameters, including the name of the cube you want to search. There are two example input files included with the distribution. The smaller one, InputExample, shows the typical parameters one might want to set. The large one, InputComplete, lists all possible parameters that can be entered, and a brief description of them. To get going quickly, just replace the "your-file-here" in InputExample with your image name, and type > Duchamp -p InputExample By default, a map of detections is displayed in a PGPLOT X-window. This can be disabled by using the flagXOutput parameter, or using the -x command-line option along with the -f or -p options. The -x option will override the setting in the parameter file. You can specify a flux threshold from the command line by using the -t option. This is particularly useful when combined with -f to enable a quick search to some flux level: > Duchamp -f image.fits -t 0.001 A User's Guide in the docs/ directory provides complete documentation. It comes in both postscript and portable document format (pdf -- note that this contains hyperlinks). This guide will provide full descriptions of all parameters, and of all steps in the execution of Duchamp. Feedback ======== Any questions, please contact me. To report problems or bugs, or to suggest improvements, please go to the Duchamp Trac wiki site: http://svn.atnf.csiro.au/trac/duchamp/newticket and submit a "ticket", or view previously submitted reports. Acknowledging the use of Duchamp ================================ Duchamp is provided in the hope that it will be useful for your research. If you find that it is, I would ask that you acknowledge it in your publication by using the following: "This research made use of the Duchamp source finder, produced at the Australia Telescope National Facility, CSIRO, by M. Whiting." The journal paper describing Duchamp, and providing basic comparative tests of its different functions, is Whiting 2012, MNRAS 421, 3242, which can be found online at http://onlinelibrary.wiley.com/doi/10.1111/j.1365-2966.2012.20548.x/full. This paper should be cited when describing Duchamp. An earlier conference proceedings paper briefly describing it was: "Astronomers! Do you know where your galaxies are?", M.Whiting, in "Galaxies in the Local Volume", Eds. B.Koribalski & H.Jerjen, Astrophysics & Space Science Proceedings, Springer, 2008, p.343-344 http://adsabs.harvard.edu/abs/2008glv..book..343W Those interested in the development of a source-finder for ASKAP (known for now as Selavy), which make use of the Duchamp code, should read Whiting & Humphreys 2012, PASA 29, 371, which can be found online at http://www.publish.csiro.au/paper/AS12028.htm ------- Author: Matthew Whiting, Australia Telescope National Facility, April 2014 Matthew.Whiting [at] csiro.au