HEALPix

class astropy_healpix.HEALPix(nside=None, order='ring', frame=None)[source]

Bases: object

A HEALPix pixellization.

Parameters:

nside : int

Number of pixels along the side of each of the 12 top-level HEALPix tiles

order : { ‘nested’ | ‘ring’ }

Order of HEALPix pixels

frame : BaseCoordinateFrame, optional

The celestial coordinate frame of the pixellization. This can be ommitted, in which case the pixellization will not be attached to any particular celestial frame, and the methods ending in _skycoord will not work (but the _lonlat methods will still work and continue to return generic longitudes/latitudes).

Attributes Summary

npix The number of pixels in the pixellization of the sphere.
pixel_area The area of a single HEALPix pixel.
pixel_resolution The resolution of a single HEALPix pixel.

Methods Summary

bilinear_interpolation_weights(lon, lat) Get the four neighbours for each (lon, lat) position and the weight associated with each one for bilinear interpolation.
boundaries_lonlat(healpix_index, step) Return the longitude and latitude of the edges of HEALPix pixels
boundaries_skycoord(healpix_index, step) Return the celestial coordinates of the edges of HEALPix pixels
cone_search_lonlat(lon, lat, radius) Find all the HEALPix pixels within a given radius of a longitude/latitude.
cone_search_skycoord(skycoord, radius) Find all the HEALPix pixels within a given radius of a celestial position.
healpix_to_lonlat(healpix_index[, dx, dy]) Convert HEALPix indices (optionally with offsets) to longitudes/latitudes
healpix_to_skycoord(healpix_index[, dx, dy]) Convert HEALPix indices (optionally with offsets) to celestial coordinates.
interpolate_bilinear_lonlat(lon, lat, values) Interpolate values at specific longitudes/latitudes using bilinear interpolation
interpolate_bilinear_skycoord(skycoord, values) Interpolate values at specific celestial coordinates using bilinear interpolation.
lonlat_to_healpix(lon, lat[, return_offsets]) Convert longitudes/latitudes to HEALPix indices (optionally with offsets)
neighbours(healpix_index) Find all the HEALPix pixels that are the neighbours of a HEALPix pixel
nested_to_ring(nested_index) Convert a healpix ‘nested’ index to a healpix ‘ring’ index
ring_to_nested(ring_index) Convert a healpix ‘ring’ index to a healpix ‘nested’ index
skycoord_to_healpix(skycoord[, return_offsets]) Convert celestial coordinates to HEALPix indices (optionally with offsets).

Attributes Documentation

npix

The number of pixels in the pixellization of the sphere.

pixel_area

The area of a single HEALPix pixel.

pixel_resolution

The resolution of a single HEALPix pixel.

Methods Documentation

bilinear_interpolation_weights(lon, lat)[source]

Get the four neighbours for each (lon, lat) position and the weight associated with each one for bilinear interpolation.

Parameters:

lon, lat : Quantity

The longitude and latitude values as Quantity instances with angle units.

Returns:

indices : ndarray

2-D array with shape (4, N) giving the four indices to use for the interpolation

weights : ndarray

2-D array with shape (4, N) giving the four weights to use for the interpolation

boundaries_lonlat(healpix_index, step)[source]

Return the longitude and latitude of the edges of HEALPix pixels

This returns the longitude and latitude of points along the edge of each HEALPIX pixel. The number of points returned for each pixel is 4 * step, so setting step to 1 returns just the corners.

Parameters:

healpix_index : ndarray

1-D array of HEALPix pixels

step : int

The number of steps to take along each edge.

Returns:

lon, lat : Quantity

The longitude and latitude, as 2-D arrays where the first dimension is the same as the healpix_index input, and the second dimension has size 4 * step.

boundaries_skycoord(healpix_index, step)[source]

Return the celestial coordinates of the edges of HEALPix pixels

This returns the celestial coordinates of points along the edge of each HEALPIX pixel. The number of points returned for each pixel is 4 * step, so setting step to 1 returns just the corners.

This method requires that a celestial frame was specified when initializing HEALPix. If you don’t know or need the celestial frame, you can instead use boundaries_lonlat().

Parameters:

healpix_index : ndarray

1-D array of HEALPix pixels

step : int

The number of steps to take along each edge.

Returns:

skycoord : SkyCoord

The celestial coordinates of the HEALPix pixel boundaries

cone_search_lonlat(lon, lat, radius)[source]

Find all the HEALPix pixels within a given radius of a longitude/latitude.

Note that this returns all pixels that overlap, including partially, with the search cone. This function can only be used for a single lon/lat pair at a time, since different calls to the function may result in a different number of matches.

Parameters:

lon, lat : Quantity

The longitude and latitude to search around

radius : Quantity

The search radius

Returns:

healpix_index : ndarray

1-D array with all the matching HEALPix pixel indices.

cone_search_skycoord(skycoord, radius)[source]

Find all the HEALPix pixels within a given radius of a celestial position.

Note that this returns all pixels that overlap, including partially, with the search cone. This function can only be used for a single celestial position at a time, since different calls to the function may result in a different number of matches.

This method requires that a celestial frame was specified when initializing HEALPix. If you don’t know or need the celestial frame, you can instead use cone_search_lonlat().

Parameters:

skycoord : SkyCoord

The celestial coordinates to use for the cone search

radius : Quantity

The search radius

Returns:

healpix_index : ndarray

1-D array with all the matching HEALPix pixel indices.

healpix_to_lonlat(healpix_index, dx=None, dy=None)[source]

Convert HEALPix indices (optionally with offsets) to longitudes/latitudes

Parameters:

healpix_index : ndarray

1-D array of HEALPix indices

dx, dy : ndarray, optional

1-D arrays of offsets inside the HEALPix pixel, which must be in the range [0:1] (0.5 is the center of the HEALPix pixels). If not specified, the position at the center of the pixel is used.

Returns:

lon : Longitude

The longitude values

lat : Latitude

The latitude values

healpix_to_skycoord(healpix_index, dx=None, dy=None)[source]

Convert HEALPix indices (optionally with offsets) to celestial coordinates.

Note that this method requires that a celestial frame was specified when initializing HEALPix. If you don’t know or need the celestial frame, you can instead use healpix_to_lonlat().

Parameters:

healpix_index : ndarray

1-D array of HEALPix indices

dx, dy : ndarray, optional

1-D arrays of offsets inside the HEALPix pixel, which must be in the range [0:1] (0.5 is the center of the HEALPix pixels). If not specified, the position at the center of the pixel is used.

Returns:

coord : SkyCoord

The resulting celestial coordinates

interpolate_bilinear_lonlat(lon, lat, values)[source]

Interpolate values at specific longitudes/latitudes using bilinear interpolation

If a position does not have four neighbours, this currently returns NaN.

Parameters:

lon, lat : Quantity

The longitude and latitude values as Quantity instances with angle units.

values : ndarray

1-D array with the values in each HEALPix pixel. This must have a length of the form 12 * nside ** 2 (and nside is determined automatically from this).

Returns:

result : ndarray

1-D array of interpolated values

interpolate_bilinear_skycoord(skycoord, values)[source]

Interpolate values at specific celestial coordinates using bilinear interpolation.

If a position does not have four neighbours, this currently returns NaN.

Note that this method requires that a celestial frame was specified when initializing HEALPix. If you don’t know or need the celestial frame, you can instead use interpolate_bilinear_lonlat().

Parameters:

skycoord : SkyCoord

The celestial coordinates at which to interpolate

values : ndarray

1-D array with the values in each HEALPix pixel. This must have a length of the form 12 * nside ** 2 (and nside is determined automatically from this).

Returns:

result : ndarray

1-D array of interpolated values

lonlat_to_healpix(lon, lat, return_offsets=False)[source]

Convert longitudes/latitudes to HEALPix indices (optionally with offsets)

Parameters:

lon, lat : Quantity

The longitude and latitude values as Quantity instances with angle units.

return_offsets : bool

If True, the returned values are the HEALPix pixel as well as dx and dy, the fractional positions inside the pixel. If False (the default), only the HEALPix pixel is returned.

Returns:

healpix_index : ndarray

1-D array of HEALPix indices

dx, dy : ndarray

1-D arrays of offsets inside the HEALPix pixel in the range [0:1] (0.5 is the center of the HEALPix pixels). This is returned if return_offsets is True.

neighbours(healpix_index)[source]

Find all the HEALPix pixels that are the neighbours of a HEALPix pixel

Parameters:

healpix_index : ndarray

Array of HEALPix pixels

Returns:

neigh : ndarray

Array giving the neighbours starting SW and rotating clockwise. This has one extra dimension compared to healpix_index - the first dimension - which is set to 8. For example if healpix_index has shape (2, 3), neigh has shape (8, 2, 3).

nested_to_ring(nested_index)[source]

Convert a healpix ‘nested’ index to a healpix ‘ring’ index

Parameters:

nested_index : ndarray

Healpix index using the ‘nested’ ordering

Returns:

ring_index : ndarray

Healpix index using the ‘ring’ ordering

ring_to_nested(ring_index)[source]

Convert a healpix ‘ring’ index to a healpix ‘nested’ index

Parameters:

ring_index : ndarray

Healpix index using the ‘ring’ ordering

Returns:

nested_index : ndarray

Healpix index using the ‘nested’ ordering

skycoord_to_healpix(skycoord, return_offsets=False)[source]

Convert celestial coordinates to HEALPix indices (optionally with offsets).

Note that this method requires that a celestial frame was specified when initializing HEALPix. If you don’t know or need the celestial frame, you can instead use lonlat_to_healpix().

Parameters:

skycoord : SkyCoord

The celestial coordinates to convert

return_offsets : bool

If True, the returned values are the HEALPix pixel as well as dx and dy, the fractional positions inside the pixel. If False (the default), only the HEALPix pixel is returned.

Returns:

healpix_index : ndarray

1-D array of HEALPix indices

dx, dy : ndarray

1-D arrays of offsets inside the HEALPix pixel in the range [0:1] (0.5 is the center of the HEALPix pixels). This is returned if return_offsets is True.