Astropy HEALPix

1.1.3 · active · verified Thu Apr 16

astropy-healpix provides HEALPix (Hierarchical Equal Area isolations of the Sphere) functionality, including coordinate transformations, pixelization, and query methods, tightly integrated with the Astropy ecosystem. It is currently at version 1.1.3 and maintains an active development status, with releases often coordinated with major Astropy versions or for bug fixes as needed.

Common errors

```
ImportError: cannot import name 'HEALPix' from 'astropy.healpix'
```
cause Users often confuse the dedicated `astropy-healpix` library with an internal or deprecated `astropy.healpix` module, leading to incorrect import paths.

fix The correct import path for the `astropy-healpix` library is `from astropy_healpix import HEALPix` (note the underscore).
```
ValueError: nside must be a power of 2
```
cause The `nside` parameter for `HEALPix` or `HpxGeom` was set to an integer that is not a power of 2.

fix Change `nside` to a power of 2 (e.g., 2, 4, 8, 16, 32, 64, etc.). For instance, `HEALPix(nside=32, ...)` is valid, while `HEALPix(nside=50, ...)` is not.
```
TypeError: HpxGeom() got an unexpected keyword argument 'frame'
```
cause The `frame` argument was incorrectly passed to the `HpxGeom` class. `HpxGeom` represents the geometric properties of a HEALPix grid and does not require a coordinate frame; `frame` is only applicable to the `HEALPix` class which handles sky coordinates.

fix Remove the `frame` argument when initializing `HpxGeom`. If you need to work with sky coordinates, use the `HEALPix` class instead.

Warnings

breaking The default value of the `order` parameter for `HEALPix` and `HpxGeom` constructors changed from `'ring'` to `'nested'` in `astropy-healpix v1.0.0`. If your code relies on the implicit `'ring'` order from older versions and you update, it will now silently produce incorrect pixel indices or coordinate conversions unless `order='ring'` is explicitly set.
Fix: Explicitly specify `order='ring'` in your `HEALPix` or `HpxGeom` constructor if you intend to use ring ordering (e.g., `HEALPix(nside=32, order='ring', frame=ICRS())`).
gotcha `astropy-healpix` has specific minimum `astropy` requirements (e.g., `>=5.0.0` for `astropy-healpix` 1.x.x). Using an older `astropy` version can lead to `ImportError`s, `TypeError`s, or unexpected behavior due to API mismatches between the two libraries.
Fix: Always ensure your `astropy` installation meets the minimum version requirement specified by `astropy-healpix` (typically found in the `pyproject.toml` or `setup.cfg` on GitHub, or PyPI's `Requires-Dist` section).
gotcha The `nside` parameter, which determines the resolution of the HEALPix grid, must always be a power of 2 (e.g., 1, 2, 4, 8, 16, 32, ...). Providing a non-power-of-2 integer will result in a `ValueError`.
Fix: Ensure the value passed to `nside` is always a power of 2. For example, `HEALPix(nside=64, ...)` is valid, but `HEALPix(nside=10, ...)` is not.

Install

pip install astropy-healpix Install stable version

Imports

HEALPix
wrong:
```
from astropy.healpix import HEALPix
```
correct:
```
from astropy_healpix import HEALPix
```
HEALPix is part of the dedicated `astropy-healpix` library, not directly `astropy.healpix` (which might refer to an internal Astropy module or a coordinate frame).
HpxGeom
```
from astropy_healpix import HpxGeom
```

Quickstart

This quickstart demonstrates how to initialize a `HEALPix` object, convert HEALPix pixel indices to sky coordinates, and convert sky coordinates back to pixel indices. It uses common Astropy coordinate and unit objects for integration.

from astropy_healpix import HEALPix
from astropy.coordinates import ICRS, SkyCoord
from astropy import units as u
import numpy as np

# Create a HEALPix object with nside=32, 'nested' order, and ICRS frame
hp = HEALPix(nside=32, order='nested', frame=ICRS())

# Convert HEALPix pixel indices to SkyCoord objects
pixel_indices = np.array([0, 100, 20000])
sky_coords = hp.healpix_to_skycoord(pixel_indices)

print(f"Sky Coordinates for pixels {pixel_indices}:\n{sky_coords}")

# Convert SkyCoord objects to HEALPix pixel indices
ra = np.array([0, 10, 20]) * u.deg
dec = np.array([0, 5, 10]) * u.deg
coords_to_convert = SkyCoord(ra, dec, frame='icrs')
pix_at_coords = hp.skycoord_to_healpix(coords_to_convert)

print(f"HEALPix pixels for coordinates {coords_to_convert}: {pix_at_coords}")

view raw JSON →