Instructions on how to install and use Clumpfind 6/10/04 jpw ================================================ Description ----------- Clumpfind is a simple algorithm that finds connected x-y-z regions in a datacube. It is designed to be applied to spectral line datasets of molecular clouds though has found applications in other fields. A discussion of the algorithm, its testing on simulated data, and the results of applying it to 13CO(1-0) observations of the Rosette molecular cloud is in Williams, de Geus & Blitz 1994, ApJ, 428, 693. Clumpfind was originally written in fortran and subsequently translated to IDL. As datasets have increased in size, I have returned to the program and rewritten using the "search3d" function in IDL to be more efficient. This version also includes a nicer imaging routine to visualize the results. Note that you will need access to the readfits routine in the IDL astronomy library (http://idlastro.gsfc.nasa.gov/). Also, I have included a copy of tvimage.pro from Fanning Software Consulting (www.dfanning.com). This is used in the plotting procedure. Running the procedures ---------------------- The programs are written as IDL procedures and require the data to be in FITS format. Clumpfind (procedure clfind) works by effectively contouring the data, and you should adjust the levels with the contouring parameters low and inc. Based on tests with simulated data, Williams, de Geus & Blitz, concluded that the optimal size for the increment is twice the rms noise in the data for best results (this gives highest contrast between clumps, with least chance of being misled by noise). The parameter low tells clfind where to start contouring the data: this is generally also set equal to twice the rms but there may be cases where you do not want to follow emission down to the lowest level (for example, if there is a high, approximately, uniform background). If the noise in the dataset is not uniform as in, for example, an interferometer map, you may want to apply the routine to a signal-to-noise datacube. To compile clfind, enter ".run clfind" at the IDL> prompt. There should be no error messages, and you should only see the names of various procedures that have been compiled. If you now enter "clfind" at the IDL> prompt, it will tell you that it needs a filename and the two parameters nstart and inc. Enter these on these on the command name, e.g. clfind,file='../example/rosette',low=0.5,inc=0.5,/log clfind will print out what parameters it is reading in, and start running. There are two output files, a log file and clump assignment file, both named using the input file as root. In this example the /log flag is set which causes a copy of the screen output to be sent to the file clfind.log in the same directory that IDL was started. Computing times depend sensitively on the size of the data cube and the amount of emission within it. It greatly helps to trim the data cube by removing excess baseline and map borders where there is no signal. For really large data cubes, IDL may run out of internal memory, and in this case, there really is no alternative but to break up the data cube into smaller pieces, analyze them, and then piece them back together again afterwards. Eventually when all is done you will see a message that it has finished sucessfully, and you will find a new fits file in the same directory as the data file, and with the same name but with a ".clf" suffix. This is the clump assignment data cube: the original data cube is unchanged. The clump decomposition is done, and now you can examine the results and calculate statistics. The clump assignment file is also a 3d data cube with the exact same dimensions as the original data cube, but instead of temperatures, each pixel is assigned a number of the clump that it has been assigned to. The two other programs are run in a similar fashion, and work on both data cubes in tandem, using the clump assigment cube to determine which pixels belong to each clump. The clump plotting program can be compiled and run with the following commands: .run clplot clplot,file='../example/rosette' There is no log file for this. Just enter in a clump number and two windows will open up. The left window shows the integrated map of the entire cloud, an outline of the clump and a cross marking the position of peak intensity. The right window shows three autoscaled contour plots showing the x-y, v-y, and x-v clump projections and the clump average spectrum (heavy line) compared to the cloud average spectrum (light line) along the projected line of sight to the clump. Use this program to image each clump and make sure there are no "runaway" clumps from extended low surface brightness features or contour levels that are too low, etc. You should also manually write down a list of poorly defined clumps or clumps that lie near a boundary in the map so that they are not included in future statistical analysis. A procedure to calculate basic quantities for each clump is also included. To compile and run it, type .run clstats clstats,file='../example/rosette',/log This program loops over the total number of clumps and calculates integrated intensities, peak positions, sizes, etc. for each clump. Clumps are flagged if they contain pixels that lie on the edge of the data cube: X, Y, or V (or any combination) for each axis. For maximum flexibility here, the program outputs (into clstats.log if the "/log" option is present) the numbers as pixels, and intensities, without converting to physical units. FITS headers come in a variety of units, e.g. degrees, radians, km/s, m/s, etc, so I leave it to the user to either edit in the conversion lines themselves, or write a second program that reads in the clstats.log output and converts pixels to parsecs, integrated intensities, to masses, etc. If you have any problems with setting up or running these programs please contact me at jpw@ifa.hawaii.edu or (808) 956-8355. If your analysis results in a publication, please cite the Williams et al. paper (1994, ApJ, 428, 693). Happy clump-finding! -------------------------------------------------------------------------------