liminfoHEALPix Reference
Free reference guide: HEALPix Reference
About HEALPix Reference
The HEALPix Reference provides a comprehensive, searchable guide to the Hierarchical Equal Area isoLatitude Pixelization framework and its Python implementation through the healpy library. It covers the core concepts of spherical pixelization including Nside resolution parameters (from Nside=1 with 12 pixels to Nside=2048 with approximately 50 million pixels used by Planck CMB), RING versus NESTED numbering schemes, and pixel area calculations using the formula Omega_pix = 4*pi / Npix.
This reference details the full healpy API for coordinate conversion (ang2pix, pix2ang, ang2vec, vec2ang), map I/O (read_map, write_map for FITS files), visualization functions (mollview for Mollweide all-sky projections, gnomview for small-area zoom, cartview for Cartesian views), and resolution manipulation (ud_grade for upgrading and downgrading map resolution). Each entry includes ready-to-use Python code snippets with numpy integration.
The guide also covers advanced topics essential for astrophysics research: spherical harmonic analysis with anafast for power spectrum computation, synfast for CMB simulations, map2alm/alm2map for harmonic decomposition, Gaussian beam smoothing, spatial queries using query_disc and query_polygon, Multi-Order Coverage (MOC) for survey footprint description, and LIGO/Virgo gravitational wave probability skymap processing with credible region calculations.
Key Features
- Complete healpy API reference with Python code examples for ang2pix, pix2ang, mollview, gnomview, and 20+ functions
- Nside resolution parameter guide with pixel count and angular resolution tables from Nside=1 to Nside=2048
- Spherical harmonic analysis functions including anafast power spectrum, synfast simulation, and alm2map/map2alm transforms
- Spatial query recipes for query_disc, query_polygon, get_all_neighbours, and MOC (Multi-Order Coverage) operations
- Visualization examples covering Mollweide, Gnomonic, and Cartesian projections with coordinate transformation (Galactic to Equatorial)
- LIGO/Virgo gravitational wave skymap processing with 90% credible region area calculation
- RING versus NESTED pixel numbering scheme comparison with conversion functions ring2nest/nest2ring
- Map resolution manipulation with ud_grade for downgrading and upgrading HEALPix maps
Frequently Asked Questions
What is HEALPix and why is it used in astrophysics?
HEALPix (Hierarchical Equal Area isoLatitude Pixelization) is a framework for dividing a sphere into equal-area pixels arranged along iso-latitude rings. It is the standard pixelization used by CMB experiments like Planck, gravitational wave observatories (LIGO/Virgo), and large-scale survey missions because it enables efficient spherical harmonic transforms and hierarchical spatial indexing.
What is the relationship between Nside and the number of pixels?
The total number of pixels is 12 * Nside^2, where Nside must be a power of 2. For example, Nside=64 gives 49,152 pixels (~0.92 deg^2 each), Nside=512 gives 3,145,728 pixels (~0.0134 deg^2 each), and Nside=2048 gives approximately 50 million pixels (~2.95 arcmin^2 each), which is the resolution used by the Planck satellite for CMB maps.
When should I use RING versus NESTED pixel ordering?
Use RING ordering when performing spherical harmonic analysis (anafast, map2alm, synfast) because pixels are arranged along iso-latitude rings which makes Fourier transforms efficient. Use NESTED ordering for spatial queries, cross-matching, and hierarchical operations because pixels follow a space-filling curve that keeps spatially close pixels numerically close. Convert between schemes with hp.ring2nest() and hp.nest2ring().
How do I compute the angular power spectrum of a HEALPix map?
Use hp.anafast(skymap, lmax=500) to compute the C_l angular power spectrum. The result is an array of C_l values indexed by multipole l. To plot the conventional CMB power spectrum, use ell*(ell+1)*cl/(2*pi) on the y-axis against multipole l on the x-axis. You can also generate simulated maps from a power spectrum using hp.synfast(cl, nside=256).
How do I find all pixels within a circular region on the sky?
Use hp.query_disc(nside, vec, radius) where vec is a 3D unit vector pointing to the center (created with hp.ang2vec) and radius is in radians. For example, to find pixels within 5 degrees of (RA=180, Dec=45): vec = hp.ang2vec(np.radians(90-45), np.radians(180)), then ipix = hp.query_disc(nside, vec, np.radians(5)).
What is MOC and how does it relate to HEALPix?
MOC (Multi-Order Coverage) is a representation built on HEALPix that describes arbitrary sky regions using pixels at multiple Nside resolutions. It is used by the IVOA (International Virtual Observatory Alliance) to efficiently describe survey footprints, observation coverage, and catalog spatial extents. The mocpy Python library provides MOC creation from cones, HEALPix cells, and polygons.
How do I process a LIGO/Virgo gravitational wave skymap?
Read the probability map with hp.read_map("bayestar.fits.gz"), visualize with hp.mollview(prob), and compute the 90% credible region by sorting pixel probabilities in descending order, computing the cumulative sum, and counting pixels above the threshold. Multiply the pixel count by hp.nside2pixarea(nside, degrees=True) to get the area in square degrees.
How do I smooth a HEALPix map with a Gaussian beam?
Use hp.smoothing(skymap, fwhm=np.radians(1.0)) where fwhm is the full-width-at-half-maximum of the Gaussian beam in radians. For example, np.radians(1.0) applies a 1-degree beam. This is commonly used to degrade angular resolution for comparison between maps at different resolutions or to suppress noise at small angular scales.