|
Introduction
SDSSPix is a hierarchical, equal area pixelization scheme designed for the
Sloan Digital Sky Survey geometry. Similar in operation to
Healpix for the
CMB, SDSSPix provides a convenient, efficient system to pixelize the sky for
statistical analysis at a variety of resolutions. This page provides links
to a number of C, Fortran and IDL routines for implementing the pixelization
scheme and taking advantage of its properties to greatly increase the speed
and accuracy of astrostatistical calculations.
Survey Geometry
The details of the scan pattern for the SDSS survey can be found at the
official SDSS Website. For our purposes,
we only care about the geometry of the scanned area. The fundamental unit of
the survey is the stripe. Each stripe is the result of two scans of
the telescope with all six cameras. Interwoven together, these twelve
scanlines mark out one stripe approximately 2.5 degrees wide and 120 degrees
long. To handle this sort of survey geometry, the SDSS team developed survey
coordinates: LAMBDA and ETA. In survey coordinates, each
stripe is a longitudinal slice of the sphere down some constant meridian in
ETA (Figure 1). Projecting this on a Cartesian plane,
ETA would be the x-axis and LAMBDA the y-axis. Each stripe has a particular
extent in LAMBDA corresponding to SDSS footprint on the sky, so we can easily
reference all of the pixels associated with a given stripe.
In order to generate a pixelization scheme with equal-area pixels we need to
satisfy a few criteria. Dividing up the sphere along the ETA direction is
easy; we just need to make our step-sizes in ETA equal. For LAMBDA, we need
to take into account the fact that a given step in LAMBDA at low lattitudes
yields a much larger area than the same step at high lattitudes. Thus, instead
of a constant step in LAMBDA, we project LAMBDA onto the z axis and take
constant steps in z (similar to slicing an orange with a series of horizontal
planes). The final piece of the equal area puzzle is assigning the fundamental
resolution level. For our geometry this is
nx = 36
ny = 13
meaning that our most basic resolution (resolution = 1) has 36 pixels in the
ETA direction and 13 in the LAMBDA direction for a total of 468 pixels. This
resolution does does not really address the fundamental geometry of the
survey, however. For that, we want resolution = 4, corresponding to a single
pixel across each stripe (7488 pixels in all). This resolution is typically
referred to as the superpixel resolution.
The second feature of SDSSPix is the hierarchical indexing. At a given
resolution, each pixel is assigned a unique index. This index can be rapidly
converted into a set of angular coordinates and vice versa. To go to higher
resolution, each dimension of the pixel is divided in two, resulting in four
sub-pixels for each original pixels. This makes converting from high
resolution to low resolution very fast. Likewise, given a set of LAMBDA-ETA
bounds (or stripe number), it is trivial to generate a list of pixels in that
region at a given resolution.
Basic Routines
The following table provides a quick index to the set of available utilities
for using the SDSSPix system, along with an indicator of the availability in
each coding language. For IDL, alternate routines are generally available
via flags in the original routine, e.g. pix2ang_radec is available by
calling pix2ang,/radec.
|
Basic Routines |
| Routine |
Description |
C |
IDL |
Fortran |
| pix2ang |
This module takes a pixel index and resolution and
converts them into LAMBDA-ETA coordinates. |
YES |
YES |
YES |
| ang2pix |
The complement to pix2ang, this converts a set of
LAMBDA-ETA coordinates into a pixel index, given a resolution |
YES |
YES |
YES |
| pix2ang_radec |
Same as pix2ang, but generating RA-DEC coordinates.
|
YES |
YES |
NO |
| pix2ang_radec |
Same as ang2pix, but taking RA-DEC coordinates.
|
YES |
YES |
NO |
| eq2csurvey |
Conversion routine for taking RA-DEC coordinates and
changing them to LAMBDA-ETA coordinates.
|
YES |
YES |
NO |
| csurvey2eq |
Conversion routine for taking LAMBDA-ETA coordinates and
changing them to RA-DEC coordinates.
|
YES |
YES |
NO |
| downsample |
Converts a high resolution map to a lower resolution map.
|
YES |
YES |
YES |
| upsample |
Generates a higher resolution map from a lower resolution
map.
|
YES |
YES |
YES |
| superpix |
Given a high resolution pixel index, this returns the
corresponding pixel index at a specified lower resolution.
|
YES |
YES |
YES |
| subpix |
The complement of superpix, this returns the pixel
indices for the four pixels which would be contained in the pixel indexed.
|
YES |
YES |
NO |
| pix_bound |
Given pixel index and resolution, returns the LAMBDA-ETA
bounds of the pixel.
|
YES |
YES |
NO |
| pix_area |
Given pixel index and resolution, returns the area of the
pixel in square degrees
|
YES |
YES |
NO |
| pix2xyz |
Given pixel index and resolution, returns the Cartesian
coordinates of the pixel on the unit sphere. Very useful for calculating
the angular distance between pixels.
|
YES |
NO |
NO |
| area_index |
Given a set of LAMBDA-ETA bounds, returns the x & y
indices of the bounding pixels. These indicies can be converted into an
array of pixel indicies by the following:
nx = nx0*resolution;
ny = ny0*resolution;
n_pixel = (x_max - x_min + 1)*(y_max - y_min + 1);
index_array = gsl_vector_long_alloc(n_pixel);
k = 0;
for (j=y_min;j<=y_max;j++) {
for (i=x_min;i<=x_max;i++) {
index_array->data[k] = nx*j + i;
k++;
}
}
|
YES |
YES |
NO |
| area_index_stripe |
Similar to area_index, but takes the number of a
stripe to infer the bounding region.
|
YES |
YES |
NO |
| display_pixel |
Given a pixel index and resolution (or arrays of indices
and resolutions), plots a Cartesian projections of the pixel boundaries in
LAMBDA-ETA coordinates.
|
NO |
YES |
NO |
| assign_parameters |
A routine for C only. This assigns the default values to
a number of global variables declared in "sdsspix.c", which contains the
code for all of the C utilities described above and below. assign_parameters
must be called at the beginning of any C code or the routines will not
function properly.
|
YES |
NO |
NO |
Advanced Routines
In addition to the routines above, there are two structures (currently
only available only in C) which are extremely useful for filtering objects
against a mask or computing correlation functions: the
res_struct and the superpixnum_struct. Using these structures as
written requires the use of the
GNU Scientific Libraries.
The first of these is an array of structures, separating a given set of pixels
into arrays of the same resolution. Each element in res_struct contains the
following:
|
res_struct |
| Variable |
Type |
Description |
| n_pixel |
unsigned long |
This stores the number of pixels at this
resolution |
| resolution |
int |
The common resolution for all of the pixels in this element
of the structure. |
| pixnum |
int |
A GSL unsigned long vector containing the pixel indices of
the pixels at this resolution. |
| start |
unsigned long |
The first index for these pixels in the input array
of pixel indices. Generally unused. |
| finish |
unsigned long |
The final index for these pixels in the input array
of pixel indices. Generally unused. |
In addition, the elements of res_struct are sorted from lowest to highest
resolution. This makes the structure ideal for data filtering: the first
elements of the structure mask most of the area while typically numbering
far fewer than the higher resolution pixels, making the filtering very
efficient. Making the resolution structure is simple. Given an array of
pixel indices (pixnum_array) and resolutions (resolution_array),
the call would be something like this:
n_res =
find_n_res(resolution_array,n_pixel);
if (!(res_struct=
malloc(n_res*sizeof(resolution_struct)))) {
printf("Couldn't allocate memory...\n");
exit(1);
}
make_resolution_struct(pixnum_array, resolution_array, n_pixel,
res_struct,n_res);
Of course, no matter how efficient this may be, it doesn't help us when we
need to filter a large data set covering a large area; most of the masks are
irrelevent since they're on the other side of the survey. To address this
we make the superpixnum_struct. This structure contains an array of
res_structs, each of which contains all of the pixels which share a given
superpixel. Here's the structure:
|
superpixnum_struct |
| Variable |
Type |
Description |
| n_pixel |
unsigned long |
This stores the number of pixels contained in this
superpixel |
| n_res |
int |
This stores the number of resolutions for the pixels
contained in this superpixel |
| superpixnum |
unsigned long |
The index for this superpixel |
| resolution |
int |
The resolution used to for the superpixels. By convention,
this resolution is set to 4 (each pixel is one stripe wide). Going to a
higher resolution for the superpixel will speed things up somewhat, but will
also require more memory. |
| res_struct |
structure |
The res_struct contains all of the pixels within this
superpixel (see above). |
Calling the routines to make the superpix_struct is similar to those used
for res_struct:
n_superpix = find_n_superpix(superpix_resolution, pixnum_array,
resolution_array, n_pixel);
if (!(superpix_struct=malloc(n_superpix*sizeof(superpixnum_struct)))) {
printf("Couldn't allocate superpixnum_struct memory...\n");
exit(1);
}
make_superpix_struct(superpix_resolution,pixnum_array,
resolution_array,n_pixel,superpix_struct,n_superpix);
Now we can filter a set of galaxies or random points by simply determining the
superpixel containing that point and walking down the res_struct associated
with that superpixel (or moving on if there are no masks in that superpixel).
This avoids looking at the (irrelevant) masks in the vast majority of the
survey area.
Look at data_filter_pixel.c and quick_random_pixel.c for examples using these
structures to great effect.
Download Code
Basic Tarballs
Advanced C code tarball
(needs GSL to compile)
Contains:
- sdsspix.c: file containing the utilities for the basic and
advanced C routines (don't need to download C tarball from above).
- data_filter_pixel.c: a routine for
filtering galaxy files through a pixel mask. Usage: data_filter_pixel
input_file mask_file output_file
- quick_random_pixel.c: a routine for
generating random galaxies within a mask with the same density as a given
data file. Usage: quick_random_pixel input_file mask_file
output_random_file, where input_file is typically a galaxy
file filtered through the same mask.
- quick_random_pixel_density.c: similar to quick_random_pixel,
but you specify an object density (in objects/sq. degree) rather than an
input file. The module for calculating the unmasked area provides the
template for masking in a pixel-based estimator. Usage:
quick_random_pixel_density dnesity mask_file
output_random_file.
- random_dr3.dat: a sample data file of random points to filter.
- stripe_dr3.mask_simple: a sample mask file to feed into the
codes.
To compile these codes, use something like:
gcc data_filter_pixel.c -lm -O6 -lgsl -lgslcblas -o data_filter_pixel
Both of the above routines are provided as examples of various techniques for
filtering data and pixels quickly using superpixnum_struct and res_struct.
Actually using these codes to filter data or generate random points will
likely require some editing to match the data format of your input files.
The codes also use the stripe-resolution convention to designate the boundaries
for the survey. The first several lines in the mask file give the stripe
numbers which combine to make the survey area. These are recognized by the
code by setting the resolution to -1. The codes look for contiguous sets of
stripes to define bounding boxes (with the exception of stripe 76, 82, and 86;
these are the three southern cap stripes and are taken to be in a single
bounding box). Once we know the stripes in each bounding box, determining
the pixels in that bounding box is trivial.
Images
|
Figure 1: A visualization of the north galactic cap of the survey
from the SDSS SkyServer. Each line
represents a stripe which will eventually be filled in; the green line
corresponds to the northern equatorial stripe. LAMBDA changes along
the length of a given stripe, while each stripe has a constant ETA.
|
|
Figure 2: Similar to Figure 1, but rotated to show the
position of the galactic plane with respect to the survey area.
|
More images on the way...
Contact Information
SDSSPix was developed by Max Tegmark,
Yongzhong Xu and
Ryan Scranton.
Questions regarding the Fortran version of the code should be sent to
Max or Yonzhong; questions about the C and IDL versions should be sent to
Ryan.
|
