To start using mangle, download the latest version of the software,
and unpack it with the following commands (for Mac OSX, replace 'linux' with 'intelmac' or 'ppcmac'):
tar xvf mangle2.1-linux.tar
This should produce a directory called mangle2.1 containing the following directories:
- bin containing the binary executables for each mangle command,
- src containing the source code,
- scripts containing shell scripts for doing interesting tasks with mangle, and
- masks containing data files for masks of several galaxy surveys.
To give you a flavor for how mangle works, the rest of this page walks you through a step-by-step example.
Let's start by constructing a portion of the angular mask for the Sloan Digital Sky Survey, a.k.a. SDSS:
The first step is to define your mask. Mangle can read masks described in a variety of formats (see Polygon Formats). Fortunately, in the case of SDSS, much of the work has already been done for us. The NYU Value-Added Galaxy Catalog provides a description of the SDSS angular mask with two files in mangle polygon format:
- window.XXX.ply gives the completeness of the survey in regions defined by the stripes of the photometric survey and the 3° circular plates of the spectroscopic survey. The weight of each polygon represents the fraction of galaxies with measured redshifts in that region: a weight of 0 means no galaxies in that region have measured redshifts, and a weight of 1 means that 100% of the target galaxies selected in that region by the photometric survey have measured redshifts.
- mask.XXX.ply provides polygons representing the holes in the survey area, i.e., regions that are blocked out to avoid bright stars, satellite trails, and so forth. It is not a 'mask' in the usual mangle sense, but should rather be thought of as something that 'masks' the view out of the 'window' described in the file above. The polygons in the mask file have weights equal to the weights of the window polygons they are obscuring.
For our example, we will use portions of the window and mask files for DR6, containing just the polygons in one of SDSS's equatorial slices, which are in the masks/sdss directory:
Our goal with mangle is to resolve these window and hole polygons into the full angular selection function consisting of non-overlapping polygons. The basic procedure for how to do this is outlined in the table below. (The tutorial continues after the table.)
Walkthrough for Making the SDSS Example Mask
Our first order of business is to set the weights of the polygons representing the holes to zero.
First, make a file called jw just containing a 0 with the command
echo 0 > jw
Then we apply weight 0 to all of the polygons in mask.dr6safe0.slice.ply with the command
../../bin/weight -zjw mask.dr6safe0.slice.ply holes.dr6safe0.slice.ply
The -z switch tells mangle where to read the weight(s) from - in this case, the file jw.
The next step is to run the pixelize command on our input files. This speeds up the computation for the following steps, and combines the window and holes polygons into one file called jfhp:
../../bin/pixelize window.dr6safe0.slice.ply holes.dr6safe0.slice.ply jfhp
Note that the window file comes before the holes file on the command line - this is important! For polygons that overlap, the weights of polygons listed later in the file take precedence. By putting the holes after the window, this ensures that the holes are assigned a weight of zero in the final mask.
The next step is to snap this file, which makes nearly-coincident polygon boundaries exactly coincident to avoid numerical problems later. This command takes the file we just made with the pixelize step and writes the snapped polygons to jfh:
../../bin/snap jfhp jfh
We then balkanize the file jfh to resolve it into non-overlapping polygons, and write the output to jb:
../../bin/balkanize jfh jb
(Note that we don't have to apply weight here, as suggested in the table, because the window file comes with the appropriate weights defined and we already weighted the holes to 0 in the first step.)
Finally, we unify the mask to clean things up by combining neighboring polygons with the same weight. This step takes our balkanized file jb as input and outputs our final angular mask of the SDSS slice to sdss_dr6safe0_slice.pol.
../../bin/unify jb sdss_dr6safe0_slice.pol
As an example application, let's make a list of a thousand random SDSS "galaxies" with the appropriate angular distribution in our slice:
../../bin/ransack -r1000 sdss_dr6safe0_slice.pol galaxies.dat
This produces galaxies.dat, a list of right ascensions and declinations (RA and Dec) describing the positions of the mock galaxies on the sky.
Plotting the SDSS Slice Mask
If you have Matlab installed on your system, you can plot the SDSS slice mask in an EPS file with the script graphmask.sh as follows: first convert it into list format which can be read by Matlab:
../../bin/poly2poly -ol30 sdss_dr6safe0_slice.pol sdss_dr6safe0_slice.list
Then run the plotting script, which calls Matlab from the command line:
sh ../../scripts/graphmask.sh sdss_dr6safe0_slice.list sdss_dr6safe0_slice.eps -45 35 8 21 "Completeness mask for a slice of SDSS dr6 safe0"
The "-45 35 8 21" in the arguments specifies the range in RA and Dec (in degrees) over which to plot the mask.
If you have Supermongo installed on your system, you can plot the SDSS slice mask with the script graphmasksm.sh as follows:
../../bin/poly2poly -og10 -p3 sdss_dr6safe0_slice.pol sdss_dr6safe0_slice.grph
converts the polygon file to graphics format, and
sh ../../scripts/graphmasksm.sh sdss_dr6safe0_slice.grph sdss_dr6safe0_slice1.eps 0 35 0 0 "Completeness mask for a slice of SDSS dr6 safe0"
sh ../../scripts/graphmasksm.sh sdss_dr6safe0_slice.grph sdss_dr6safe0_slice2.eps 315 360 0 0 "Completeness mask for a slice of SDSS dr6 safe0"
plot the mask using Supermongo. Note that the range arguments "0 35 0 0" and "315 360 0 0" range arguments tell the script to plot the mask in two halves to avoid trickiness at the RA=360° to RA=0° crossover.
You can view your newly-created plot with gv or ggv, e.g.:
If you used the Matlab script and everything worked properly, it will look like this: sdss_dr6safe0_slice.eps.
Mangle Environment Variables
If you want to avoid typing the path to the mangle commands, e.g., just type balkanize rather than ../../bin/balkanize, run the following command, which defines environment variables pointing to the mangle directories and adds them to your path:
source setup_mangle_environment $PWD/
where you should replace [MANGLEDIR] with the path to where you installed mangle, e.g., /home/yourname/mangle2.1/.
To do this automatically when you log in, add the following line to the script that runs each time you start your shell. (this is a file in your home directory called either .bashrc, .tcshrc, .cshrc, .login, or .profile, depending on your system.)
source [MANGLEDIR]setup_mangle_environment [MANGLEDIR]
How not to Reinvent the Wheel
We have compiled a collection of scripts that perform many of the most common tasks that mangle can handle, so before spending time trying to figure out how to best combine the various mangle tools to do what you want, please check our script collection to see if it contains what you're looking for.