API

This is the API for the cdshealpix Python package.

This package is a wrapper around the Rust cdshealpix crate. The functions currently implemented by cdshealpix are the following:

cdshealpix

The HEALPix cells can be represented following two schema. The nested and the ring one.

Here are two methods in the cdshealpix base module allowing to convert HEALPix cells represented in the nested scheme into cells represented in the ring scheme and vice versa.

to_ring(ipix, depth[, num_threads])

Convert HEALPix cells from the NESTED to the RING scheme.

from_ring(ipix, depth[, num_threads])

Convert HEALPix cells from the RING to the NESTED scheme.

cdshealpix.nested

_images/nested.png

The HEALPix cells at \(depth=1\) represented in the nested scheme

lonlat_to_healpix(lon, lat, depth[, ...])

Get the HEALPix indexes that contains specific sky coordinates.

skycoord_to_healpix(skycoord, depth[, ...])

Get the HEALPix indexes that contains specific sky coordinates.

healpix_to_lonlat(ipix, depth[, dx, dy, ...])

Get the longitudes and latitudes of the center of some HEALPix cells.

healpix_to_skycoord(ipix, depth[, dx, dy, ...])

Get the coordinates of the center of a healpix cell.

healpix_to_xy(ipix, depth[, num_threads])

Project the center of a HEALPix cell to the xy-HEALPix plane.

lonlat_to_xy(lon, lat[, num_threads])

Project sky coordinates to the HEALPix space.

xy_to_lonlat(x, y[, num_threads])

Project coordinates from the HEALPix space to the sky coordinate space.

vertices(ipix, depth[, step, num_threads])

Get the longitudes and latitudes of the vertices of some HEALPix cells at a given depth.

vertices_skycoord(ipix, depth[, step, ...])

Get the sky coordinates of the vertices of some HEALPix cells at a given depth.

neighbours(ipix, depth[, num_threads])

Get the neighbouring cells of some HEALPix cells at a given depth.

external_neighbours(ipix, depth, delta_depth)

Get the neighbours of specific healpix cells.

cone_search(lon, lat, radius, depth[, ...])

Get the HEALPix cells contained in a cone at a given depth.

polygon_search(lon, lat, depth[, flat])

Get the HEALPix cells contained in a polygon at a given depth.

elliptical_cone_search(lon, lat, a, b, pa, depth)

Get the HEALPix cells contained in an elliptical cone at a given depth.

bilinear_interpolation(lon, lat, depth[, ...])

Compute the HEALPix bilinear interpolation from sky coordinates.

cdshealpix.ring

The ring scheme HEALPix methods take a nside parameter instead of a depth one. nside refers to the number of cells being contained in the side of a base cell (i.e. the 12 cells at the depth 0). While in the nested scheme, nside is a power of two (because \(N_{side} = 2 ^ {depth}\)), in the ring scheme, nside does not necessary have to be a power of two!

_images/ring.png

The HEALPix cells at \(N_{side}=2\) represented in the ring scheme

lonlat_to_healpix(lon, lat, nside[, ...])

Get the HEALPix indexes that contains specific sky coordinates.

skycoord_to_healpix(skycoord, nside[, ...])

Get the HEALPix indexes that contains specific sky coordinates.

healpix_to_lonlat(ipix, nside[, dx, dy, ...])

Get the longitudes and latitudes of the center of some HEALPix cells at a given depth.

healpix_to_skycoord(ipix, nside[, dx, dy, ...])

Get the sky coordinates of the center of some HEALPix cells at a given nside.

healpix_to_xy(ipix, nside[, num_threads])

Project the center of a HEALPix cell to the xy-HEALPix plane.

vertices(ipix, nside[, step, num_threads])

Get the longitudes and latitudes of the vertices of some HEALPix cells at a given nside.

vertices_skycoord(ipix, nside[, step])

Get the sky coordinates of the vertices of some HEALPix cells at a given nside.

cdshealpix.skymap

This module provides a minimal interface to interact with Skymaps, as defined in the data format for gamma ray astronomy specification.

class cdshealpix.skymap.SkymapExplicit(keys, values, order)

An explicit Skymap, containing values to associate to healpix cells.

values is a 2D numpy array.

__init__(keys, values, order)

Instantiate an explicit skymap.

Parameters:
keysnp.array

Is a one-dimensional array-like. Contains the HEALPix number.

valuesnp.array

Is a one dimensional array-like.

Examples

>>> from cdshealpix.skymap import SkymapExplicit
>>> import numpy as np
>>> map = SkymapExplicit(np.array([0, 1, 2]), np.array([2, 3, 4]), 0)
>>> map.order
0
classmethod from_fits(path: str | Path)

Read an explicit skymap in the nested schema from a FITS file.

This reader supports files which are:

  • in the nested scheme

  • and the explicit format

Parameters:
pathstr, pathlib.Path

The file’s path.

Returns:
SkymapExplicit

An explicit skymap. Its values are in a 2D numpy array which data type in inferred from the FITS header.

to_fits(path)

Write an explicit Skymap in a fits file.

Parameters:
pathstr, pathlib.Path

The file’s path.

to_implicit(null_value=None)

Convert this SkymapExplicit into a SkymapImplicit.

Parameters:
null_value: `int` or `float`

Is the value to be used as a null to fill the implicit skymap where the explicit one has gaps. Its type should be compatible with the type of values. It defaults to 0.

Examples

>>> from cdshealpix.skymap import SkymapExplicit
>>> import numpy as np
>>> map = SkymapExplicit(np.array([0, 1, 2]), np.array([2.1, 3.2, 4.4]), 0)
>>> map.to_implicit(null_value=np.nan).values
array([2.1, 3.2, 4.4, nan, nan, nan, nan, nan, nan, nan, nan, nan])
class cdshealpix.skymap.SkymapImplicit(values, null_value=None)

An implicit Skymap, containing values to associate to healpix cells.

__init__(values, null_value=None)

Instantiate an implicit skymap.

Parameters:
valuesnp.array

Is a one dimensional array-like. It should have

null_valuenumber, optional

Is the value to use in case of missing data. It defaults to 0.

Examples

>>> from cdshealpix.skymap import SkymapImplicit
>>> import numpy as np
>>> map = SkymapImplicit(np.array([1.1] * 11 + [np.nan]))
>>> map.order
0
classmethod from_fits(path: str | Path)

Read a skymap in the nested schema from a FITS file.

This reader supports files which are:

  • all sky maps

  • in the nested scheme

  • and the implicit format

Parameters:
pathstr, pathlib.Path

The file’s path.

Returns:
SkymapImplicit

A skymap. Its values are in a numpy array which data type in inferred from the FITS header.

to_fits(path)

Write an implicit Skymap in a fits file.

Parameters:
pathstr, pathlib.Path

The file’s path.

to_explicit()

Convert this implicit skymap into an explicit one.

Returns:
SkymapExplicit

Examples

>>> from cdshealpix.skymap import SkymapImplicit
>>> implicit_map = SkymapImplicit([-1]*8 + [1, 2, 3, 4], null_value=-1)
>>> explicit_map = implicit_map.to_explicit()
>>> print(explicit_map.keys, explicit_map.values)
[ 8  9 10 11] [1 2 3 4]
quick_plot(*, size=256, convert_to_gal=True, path=None)

Preview a skymap in the Mollweide projection.

Parameters:
sizeint, optional

The size of the plot in the y-axis in pixels. It fixes the resolution of the image. By default 256

convert_to_galbool, optional

Should the image be converted into a galactic frame? by default True

pathstr or pathlib.Path, optional

If different from none, the image will not only be displayed, but also saved at the given location. By default None