Getting Started

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'):

gunzip mangle2.1-linux.tar.gz
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:

cd mangle2.1/masks/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.

The 'XXX' above is a placeholder for tags denoting the data release and the sample - for example, the window file for the 'safe0' sample of Data Release 6 is called window.dr6safe0.ply. The window and mask files for several SDSS data releases can be downloaded from the NYU-VAGC or from the data section of this website.

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:

• window.dr6safe0.slice.ply
• mask.dr6safe0.slice.ply

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.)

Basic Commands

Basic mangle commands, listed in the order that they would normally be applied command does purpose pixelize splits polygons in the mask so that each polygon is in only one pixel Several mangle commands require comparing each polygon to all of the other polygons in the mask. If the mask is pixelized first, mangle only needs to compare a polygon to the other polygons in the same pixel, which speeds up the processing considerably. snap identifies almost coincident cap boundaries and snaps them together The positions of the intersections of two almost but not exactly coincident cap boundaries may be subject to significant numerical uncertainty. To avoid numerical problems, such boundaries must be made exactly coincident. balkanize subdivides the angular mask into many disjoint polygons Polygons must not overlap, to avoid regions being double-counted. weight assigns a weight to each polygon Define the weight to be applied to each polygon, for example in computing the weighted sum of spherical harmonics of polygons. This command may be avoided in many cases: see Losing Weight in the Manual. unify unifies polygons where possible Reduce the number of polygons, for grace and efficiency.

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.:

ggv sdss_dr6safe0_slice.eps

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:

cd [MANGLEDIR]
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.