hpgeom modules

hpgeom

hpgeom.hpgeom.angle_to_pixel(nside, a, b, nest=True, lonlat=True, degrees=True, n_threads=1)

Convert angles to pixels.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• a (float or np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b (float or np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

pixels – HEALPix pixel numbers.

Return type:

int or np.ndarray (N,)

Raises:

ValueError – If angles are out of range, or arrays cannot be broadcast together.

hpgeom.hpgeom.angle_to_vector(a, b, lonlat=True, degrees=True)

Convert angles to cartesion (x, y, z) unit vectors.

Parameters:

• a (float or np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b (float or np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• lonlat (bool, optional) – Use longitude/latitude instead of co-latitude/longitude (radians).

• degrees (bool, optional) – If lonlat is True then this sets if the units are degrees or radians.

Returns:

vec – If a, b are vectors, returns a 2D array with dimensions (N, 3) with one vector per row. If not vectors, a 1D array with dimensions (3,).

Return type:

np.ndarray (N, 3) or (3,)

hpgeom.hpgeom.boundaries(nside, pix, step=1, nest=True, lonlat=True, degrees=True, n_threads=1)

Returns an array containing lon/lat or colatitude/longitude to the boundary of the given pixel(s).

The returned arrays have the shape (4*step) or (npixel, 4*step). In order to get coordinates for just the corners, specify step=1.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pixels (int or np.ndarray (N,)) – HEALPix pixel numbers.

• step (int, optional) – Number of steps for each side of the pixel.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

a, b – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

Return type:

np.ndarray (4*step,) or (N, 4*step,)

Raises:

ValueError – If pixel values are out of range, or nside, pix arrays are not compatible, or step is not positive.

hpgeom.hpgeom.get_interpolation_weights(nside, a, b, nest=True, lonlat=True, degrees=True, n_threads=1)

Return the 4 closest pixels and weights to perform bilinear interpolation along latitude and longitude.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• a (float or np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b (float or np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

• pixels (np.ndarray (N, 4)) – Array of pixels (np.int64), each set of 4 can be used to do bilinear interpolation of a map.

• weights (np.ndarray (N, 4)) – Array of weiaghts (np.float64), each set of 4 corresponds with the pixels.

hpgeom.hpgeom.lonlat_to_thetaphi(lon, lat, degrees=True)

Convert longitude/latitude to theta/phi.

Parameters:

• lon (float or np.ndarray (N,)) – Longitude/latitude.

• lat (float or np.ndarray (N,)) – Longitude/latitude.

• degrees (bool, optional) – If True, longitude and latitude will be in degrees.

Returns:

theta, phi – Co-latitude (theta) and longitude (phi) in radians.

Return type:

float or np.ndarray (N,)

hpgeom.hpgeom.max_pixel_radius(nside, degrees=True, n_threads=1)

Compute maximum angular distance between any pixel center and its corners.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

• degrees (bool, optional) – If True, returns pixel radius in degrees, otherwise radians.

Returns:

radii – Angular distance(s) (in degrees or radians).

Return type:

np.ndarray (N, ) or float

hpgeom.hpgeom.neighbors(nside, pix, nest=True, n_threads=1)

Return 8 nearest neighbors for given pixels.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pixels (int or np.ndarray (N,)) – HEALPix pixel numbers.

• nest (bool, optional) – Use nest ordering scheme?

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

neighbor_pixels – Pixel numbers of the SW, W, NW, N, NE, E, SE, and S neighbors. If a neighbor does not exist (as can be the case for W, N, E, and S) the corresponding pixel number will be -1.

Return type:

np.ndarray (8,) or (N, 8)

Raises:

ValueError – If pixel is out of range, or nside, pix arrays are not compatible.

hpgeom.hpgeom.nest_to_ring(nside, pix, n_threads=1)

Convert pixel number from nest to ring ordering.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pix (int or np.ndarray (N,)) – The pixel numbers in nest scheme.

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

pix – The pixel numbers in ring scheme.

Return type:

int or np.ndarray (N,)

Raises:

ValueError – Pixel or nside values are out of range.

hpgeom.hpgeom.npixel_to_nside(npixel)

Return the nside given a number of pixels.

Parameters:

npixel (int or np.ndarray (N,)) – Number of pixels.

Returns:

nside – HEALPix nside associated with that number of pixels.

Return type:

int or np.ndarray (N,)

hpgeom.hpgeom.nside_to_npixel(nside)

Return the number of pixels given an nside.

Parameters:

nside (int or np.ndarray (N,)) – HEALPix nside.

Returns:

npixel – Number of pixels associated with that nside.

Return type:

int or np.ndarray (N,)

hpgeom.hpgeom.nside_to_order(nside)

Return the resolution order for a given nside.

Parameters:

nside (int or np.ndarray (N,)) – HEALPix nside parameter.

Returns:

order – Order corresponding to given nside, such that nside = 2**order.

Return type:

int or np.ndarray (N,)

Raises:

ValueError if nside is not valid (must be power of 2 and less than 2**30). –

hpgeom.hpgeom.nside_to_pixel_area(nside, degrees=True)

Return the pixel area given an nside in square degrees or square radians.

Parameters:

• nside (int) – HEALPix nside parameter.

• degrees (bool, optional) – Return area in square degrees? Otherwise square radians.

Returns:

pixel_area – Pixel area in square degrees or square radians.

Return type:

float

hpgeom.hpgeom.nside_to_resolution(nside, units='degrees')

Return the approximate resolution (pixel size in radians, arcseconds, arcminutes, or degrees) given an nside.

Resolution is just the square root of the pixel area, which is an approximation given the varying pixel shapes.

Parameters:

• nside (int) – HEALPix nside parameter.

• units (str, optional) – Units to return. Valid options are radians, degrees, arcminutes, arcseconds.

Returns:

resolution – Approximate pixel size in specified units.

Return type:

float

hpgeom.hpgeom.order_to_nside(order)

Return the nside for a given order.

Parameters:

order (int or np.ndarray (N,)) – Resolution order. Will raise ValueError if order is not valid (must be 0 to 29 inclusive).

Returns:

nside – HEALPix nside corresponding to given order, such that nside = 2**order.

Return type:

int or np.ndarray (N,)

hpgeom.hpgeom.pixel_ranges_to_pixels(pixel_ranges, inclusive=False)

Convert (M, 2) array of pixel ranges to an array of pixels.

Parameters:

pixel_ranges (np.ndarray (M, 2)) – Array of pixel ranges, [lo, high) (if inclusive=False) or [lo, high] (if inclusive=True).

Returns:

pixels – Array of pixels.

Return type:

np.ndarray (N,)

hpgeom.hpgeom.pixel_to_angle(nside, pix, nest=True, lonlat=True, degrees=True, n_threads=1)

Convert pixels to angles.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pixels (int or np.ndarray (N,)) – HEALPix pixel numbers.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

a, b – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

Return type:

float or np.ndarray (N,)

Raises:

ValueError – If pixel values are out of range, or arrays cannot be broadcast together.

hpgeom.hpgeom.pixel_to_vector(nside, pix, nest=True, n_threads=1)

Convert pixels to vectors.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pixels (int or np.ndarray (N,)) – HEALPix pixel numbers.

• nest (bool, optional) – Use nest ordering scheme?

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

• x (float or np.ndarray (N,)) – x coordinates for vectors.

• y (float or np.ndarray (N,)) – y coordinates for vectors.

• z (float or np.ndarray (N,)) – z coordinates for vectors.

Raises:

ValueError – If pixel values are out of range, or nside and pix arrays are not compatible.

hpgeom.hpgeom.query_box(nside, a0, a1, b0, b1, inclusive=False, fact=4, nest=True, lonlat=True, degrees=True)

Returns pixels whose centers lie within a box if inclusive is False, or which overlap with this box if inclusive is True. The box is defined by all the points within [a0, a1] and [b0, b1] ([lon, lat] if lonlat=True otherwise [theta, phi] (in degrees if lonlat=True and degrees=True, otherwise radians). The box will have boundaries in constant longitude/latitude, rather than great circle boundaries as with query_polygon. If a0 > a1 then the box will wrap around 360 degrees. If a0 == 0.0 and a1 == 360.0 then the box will contain points at all longitudes. If b0 == 90.0 or -90.0 then the box will be an arc of a circle with the center at the north/south pole.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• a0 (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• a1 (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b0 (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b1 (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the box. If True, return all pixels that overlap with the box. This is an approximation and may return a few extra pixels.

• fact (int, optional) – Only used when inclusive=True. The overlap test is performed at a resolution fact*nside. For nest ordering, fact must be a power of 2, and nside*fact must always be <= 2**29. For ring ordering fact may be any positive integer.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• return_pixel_ranges (bool, optional) – Return an array of pixel ranges instead of a list of pixels. The ranges will be sorted, and each range is of the form [lo, high). This option is only compatible with nest ordering.

Returns:

• pixels (np.ndarray (N,)) – Array of pixels (np.int64) which cover the box. (if return_pixel_ranges is False) or

• pixel_ranges (np.ndarray (M, 2)) – Array of pixel ranges, [lo, high), which cover the box.

Raises:

• ValueError – If positions are out of range, or fact is not allowed.

• RuntimeError – If query_box has an internal error.

Notes

This method runs natively only with nest ordering. If called with ring ordering then a ResourceWarning is emitted and the pixel numbers will be converted to ring and sorted before output. For inclusive=True, the algorithm may return some pixels which do not overlap with the box. Higher fact values result in fewer false positives at the expense of increased run time.

hpgeom.hpgeom.query_circle(nside, a, b, radius, inclusive=False, fact=4, nest=True, lonlat=True, degrees=True)

Returns pixels whose centers lie within the circle defined by a, b ([lon, lat] if lonlat=True otherwise [theta, phi]) and radius (in degrees if lonlat=True and degrees=True, otherwise radians) if inclusive is False, or which overlap with this circle (if inclusive is True).

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• a (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• radius (float) – The radius of the circle. Degrees if degrees=True otherwise radians.

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the circle. If True, return all pixels that overlap with the circle. This is an approximation and may return a few extra pixels.

• fact (int, optional) – Only used when inclusive=True. The overlap test is performed at a resolution fact*nside. For nest ordering, fact must be a power of 2, and nside*fact must always be <= 2**29. For ring ordering fact may be any positive integer.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• return_pixel_ranges (bool, optional) – Return an array of pixel ranges instead of a list of pixels. The ranges will be sorted, and each range is of the form [lo, high). This option is only compatible with nest ordering.

Returns:

• pixels (np.ndarray (N,)) – Array of pixels (np.int64) which cover the circle. (if return_pixel_ranges is False) or

• pixel_ranges (np.ndarray (M, 2)) – Array of pixel ranges, [lo, high), which cover the circle.

Raises:

• ValueError – If position or radius are out of range, or fact is not allowed.

• RuntimeError – If query_circle has an internal error.

Notes

This method is more efficient with ring ordering. For inclusive=True, the algorithm may return some pixels which do not overlap with the circle. Higher fact values result in fewer false positives at the expense of increased run time.

hpgeom.hpgeom.query_circle_vec(nside, vec, radius, inclusive=False, fact=4, nest=True)

Returns pixels whose centers lie within the circle defined by vec and radius (in radians) if inclusive is False, or which overlap with this circle (if inclusive is True).

Parameters:

• nside (int) – HEALPix nside. Must be power of 2 for nest ordering.

• vec (iterable with 3 elements, float) – The coordinates of the unit vector defining the circle center.

• radius (float) – The radius (in radians) of the circle.

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the circle. If True, return all pixels that overlap with the disk. This is an approximation and may return a few extra pixels.

• fact (int, optional) – Only used when inclusive=True. The overlap test is performed at a resolution fact*nside. For nest ordering, fact must be a power of 2, and nside*fact must always be <= 2**29. For ring ordering fact may be any positive integer.

• nest (bool, optional) – If True, use nest ordering.

Returns:

pixels – Array of pixels (np.int64) which cover the circle.

Return type:

np.ndarray (N,)

hpgeom.hpgeom.query_ellipse(nside, a, b, semi_major, semi_minor, alpha, inclusive=False, fact=4, nest=True, lonlat=True, degrees=True)

Returns pixels whose centers lie within an ellipse if inclusive is False, or which overlap with this ellipse if inclusive is True. The ellipse is defined by a center a, b ([lon, lat] if lonlat=True otherwise [theta, phi] and semi-major and semi-minor axes (in degrees if lonlat=True and degrees=True, otherwise radians). The inclination angle alpha is defined East of North, and is in degrees if lonlat=True and degrees=True, otherwise radians. The shape of the ellipse is defined by the set of points where the sum of the distances from a point to each of the foci add up to less than twice the semi-major axis.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• a (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b (float) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• semi_major (float) – The semi-major and semi-minor axes of the ellipse. Degrees if degrees=True and lonlat=True, otherwise radians. The semi-major axis must be >= the semi-minor axis.

• semi_minor (float) – The semi-major and semi-minor axes of the ellipse. Degrees if degrees=True and lonlat=True, otherwise radians. The semi-major axis must be >= the semi-minor axis.

• alpha (float) – Inclination angle, counterclockwise with respect to North. Degrees if degrees=True and lonlat=True, otherwise radians.

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the ellipse. If True, return all pixels that overlap with the ellipse. This is an approximation and may return a few extra pixels.

• fact (int, optional) – Only used when inclusive=True. The overlap test is performed at a resolution fact*nside. For nest ordering, fact must be a power of 2, and nside*fact must always be <= 2**29. For ring ordering fact may be any positive integer.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• return_pixel_ranges (bool, optional) – Return an array of pixel ranges instead of a list of pixels. The ranges will be sorted, and each range is of the form [lo, high). This option is only compatible with nest ordering.

Returns:

• pixels (np.ndarray (N,)) – Array of pixels (np.int64) which cover the ellipse. (if return_pixel_ranges is False) or

• pixel_ranges (np.ndarray (M, 2)) – Array of pixel ranges, [lo, high), which cover the ellipse.

Raises:

• ValueError – If position or semi-major/minor axes are out of range, or fact is not allowed.

• RuntimeError – If query_ellipse has an internal error.

Notes

This method runs natively only with nest ordering. If called with ring ordering then a ResourceWarning is emitted and the pixel numbers will be converted to ring and sorted before output. For inclusive=True, the algorithm may return some pixels which do not overlap with the ellipse. Higher fact values result in fewer false positives at the expense of increased run time.

hpgeom.hpgeom.query_polygon(nside, a, b, inclusive=False, fact=4, nest=True, lonlat=True, degrees=True)

Returns pixels whose centers lie within the convex polygon defined by the points in a, b ([lon, lat] if lonlat=True, otherwise [theta, phi]) if inclusive is False, or which overlap with this polygon (if inclusive is True).

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• a (np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• b (np.ndarray (N,)) – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the polygon. If True, return all pixels that overlap with the polygon. This is an approximation and may return a few extra pixels.

• fact (int, optional) – Only used when inclusive=True. The overlap test is performed at a resolution fact*nside. For nest ordering, fact must be a power of 2, and nside*fact must always be <= 2**29. For ring ordering fact may be any positive integer.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

• return_pixel_ranges (bool, optional) – Return an array of pixel ranges instead of a list of pixels. The ranges will be sorted, and each range is of the form [lo, high). This option is only compatible with nest ordering.

Returns:

• pixels (np.ndarray (N,)) – Array of pixels (np.int64) which cover the polygon. (if return_pixel_ranges is False) or

• pixel_ranges (np.ndarray (M, 2)) – Array of pixel ranges, [lo, high), which cover the polygon.

Raises:

• ValueError – If vertices are out of range.

• RuntimeError – If polygon does not have at least 3 vertices, or polygon is not convex, or polygon has degenerate corners, or there is an internal error.

Notes

This method is more efficient with nest ordering. For inclusive=True, the algorithm may return some pixels which do not overlap with the polygon. Higher fact values result in fewer false positives at the expense of increased run time.

hpgeom.hpgeom.query_polygon_vec(nside, vertices, inclusive=False, fact=4, nest=True)

Returns pixels whose centers lie within the convex polygon defined by vertices (if inclusive is False), or which overlap with the polygon (if inclusive is True).

Parameters:

• nside (int) – HEALPix nside. Must be power of 2 for nest ordering.

• vertices (np.ndarray (N, 3)) – Vertex array containing the vertices of the polygon.

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the polygon; if True, return all pixels that overlap with the polygon, and maybe a few more.

• fact (int, optional) – Only used when inclusive=True. The overlapping test will be done at the resolution fact*nside. For NESTED ordering, fact must be a power of 2, less than 2**30, else it can be any positive integer.

• nest (bool, optional) – Use nest ordering scheme?

hpgeom.hpgeom.reorder(map_in, ring_to_nest=True)

Reorder the pixels in a map from ring to nest or nest to ring ordering.

Parameters:

• map_in (np.ndarray) – Input map to reorder.

• ring_to_nest (bool, optional) – If True, convert ring ordering to nest ordering. If False, convert nest ordering to ring ordering.

Returns:

map_out – Reordered map.

Return type:

np.ndarray

hpgeom.hpgeom.ring_to_nest(nside, pix, n_threads=1)

Convert pixel number from ring to nest ordering.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pix (int or np.ndarray (N,)) – The pixel numbers in ring scheme.

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

pix – The pixel numbers in nest scheme.

Return type:

int or np.ndarray (N,)

Raises:

ValueError – Pixel or nside values are out of range.

hpgeom.hpgeom.thetaphi_to_lonlat(theta, phi, degrees=True)

Convert theta/phi to longitude/latitude.

Parameters:

• theta (float or np.ndarray (N,)) – Co-latitude (theta) and longitude (phi) in radians.

• phi (float or np.ndarray (N,)) – Co-latitude (theta) and longitude (phi) in radians.

• degrees (bool, optional) – If True, longitude and latitude will be in degrees.

Returns:

lon, lat – Longitude/latitude.

Return type:

float or np.ndarray (N,)

hpgeom.hpgeom.upgrade_pixel_ranges(nside, pixel_ranges, nside_upgrade)

Upgrade nest pixel ranges from one resolution to another.

Parameters:

• nside (int) – HEALPix nside for input pixel ranges.

• pixel_ranges (np.ndarray (N, 2)) – Input HEALPix pixel ranges (nest ordering only).

• nside_upgrade (int) – Output HEALPix nside, must be >= nside.

Returns:

pixel_ranges_upgrade – Upgraded pixel ranges.

Return type:

np.ndarray (N, 2)

Raises:

ValueError – If nside_upgrade is less than nside, or if either nside is not a power of two.

hpgeom.hpgeom.upgrade_pixels(nside, pixels, nside_upgrade, nest=True)

Upgrade pixels from one resolution to another.

Parameters:

• nside (int) – HEALPix nside for input pixels.

• pixels (int or np.ndarray (N,)) – HEALPix pixel numbers.

• nside_upgrade (int) – Output HEALPix nside, must be >= nside. This is a complete set of higher resolution pixels overlapping the input pixels.

• nest (bool, optional) – Use nest ordering scheme? Performance is much better for upgrading nest pixels. Note that when nest=False the returned pixels will not be sorted.

Returns:

pixels_upgrade – Upgraded list of pixels.

Return type:

np.ndarray (M,)

Raises:

ValueError – If nside_upgrade is less than nside, or if either nside is not a power of two.

hpgeom.hpgeom.vector_to_angle(vec, lonlat=True, degrees=True)

Convert cartesian (x, y, z) vectors to angles.

Parameters:

• vec (np.ndarray (3,) or (N, 3)) – The vectors to convert to angles.

• lonlat (bool, optional) – Use longitude/latitude for a, b instead of co-latitude/longitude.

• degrees (bool, optional) – If lonlat=True then this sets if the units are degrees or radians.

Returns:

a, b – Longitude/latitude (if lonlat=True) or Co-latitude(theta)/longitude(phi) (if lonlat=False). Longitude/latitude will be in degrees if degrees=True and in radians if degrees=False. Theta/phi are always in radians.

Return type:

float or np.ndarray (N,)

hpgeom.hpgeom.vector_to_pixel(nside, x, y, z, nest=True, n_threads=1)

Convert vectors to pixels.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• x (float or np.ndarray (N,)) – x coordinates for vectors.

• y (float or np.ndarray (N,)) – y coordinates for vectors.

• z (float or np.ndarray (N,)) – z coordinates for vectors.

• nest (bool, optional) – Use nest ordering scheme?

• n_threads (int, optional) – Number of threads to use. Any number < 1 will use 1 thread.

Returns:

pixels – HEALPix pixel numbers.

Return type:

int or np.ndarray (N,)

healpy compatibility

hpgeom.healpy_compat.ang2pix(nside, theta, phi, nest=False, lonlat=False)

Convert angles to pixels, with healpy interface.

Parameters:

• nside (int) – The HEALPix nside parameter.

• theta (np.ndarray (N,) or scalar) – Angular coordinate theta (radians) or longitude (degrees).

• phi (np.ndarray (N,) or scalar) – Angular coordinate phi (radians) or latitude (degrees).

• nest (bool, optional) – If True, NEST pixel ordering scheme, otherwise RING.

• lonlat (bool, optional) – If True, input angles are lon/lat instead of theta/phi.

Returns:

pix – HEALPix pixel numbers.

Return type:

np.ndarray (N,) or int

hpgeom.healpy_compat.ang2vec(theta, phi, lonlat=False)

Convert angles to cartesian unit vectors.

Parameters:

• theta (float or np.ndarray (N,)) – Co-latitude (theta, radians) or longitude (degrees).

• phi (float or np.ndarray (N,)) – Longitude (phi, radians) or latitude (degrees).

• lonlat (bool, optional) – Use longitude/latitude (degrees) instead of longitude/co-latitude (radians).

Returns:

vec – If theta, phi are vectors, returns a 2D array with dimensions (N, 3) with one vector per row. If not vectors, a 1D array with dimensions (3,).

Return type:

np.ndarray (N, 3) or (3,)

hpgeom.healpy_compat.boundaries(nside, pix, step=1, nest=False)

Returns an array containing vectors to the boundary of the given pixel.

The returned array has shape (3, 4*step) (for a single pixel) or (N, 3, 4*step) for multiple pixels. The elements are the x,y,z positions on the unit sphere of the pixel boundary. To retrieve corners, specify step=1.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pix (int or np.ndarray (N,)) – Pixel number(s).

• step (int, optional) – Number of steps for each side of the pixel.

• nest (bool, optional) – Use nest ordering scheme?

Returns:

boundary – x,y,z for positions on the boundary of the pixel.

Return type:

np.ndarray (N, 3, 4*step)

hpgeom.healpy_compat.get_all_neighbours(nside, theta, phi=None, nest=False, lonlat=False)

Return the 8 nearest neighbor pixels.

Parameters:

• nside (int) – HEALPix nside. Must be power of 2 for nest ordering.

• theta (np.ndarray (N,) or float or int) – If phi is None, this is interpreted as integer pixel numbers. If phi is not None, then this is interpreted as angular coordinate theta (if lonlat=False) or longitude (if lonlat=True).

• phi (np.ndarray (N,) or float, optional) – Angular coordinate phi (if lonlat=False) or latitude (if lonlat=True).

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude (degrees) instead of co-latitude/longitude (radians)

Returns:

pixels – Neighboring pixel numbers of the SW, W, NW, N, NE, E, SE, and S neighbors. If a neighbor does not exist (as can be the case for W, N, E, and S), the corresponding pixel number will be -1.

Return type:

np.ndarray (8,) or (8, N)

hpgeom.healpy_compat.get_interp_weights(nside, theta, phi=None, nest=False, lonlat=False)

Return the 4 closest pixels and weights for bilinear interpolation.

Parameters:

• nside (int) – HEALPix nside.

• theta (float or np.ndarray) – If phi is not given, theta is interpreted as pixel number, otherwise theta/phi are angular coordinates.

• phi (float or np.ndarray) – If phi is not given, theta is interpreted as pixel number, otherwise theta/phi are angular coordinates.

• nest (bool, optional) – Use nest ordering scheme?

• lonlat (bool, optional) – Use longitude/latitude (degrees) instead of co-latitude/longitude (radians).

Returns:

• pixels (np.ndarray (4, N)) – Array of pixel neighbors (4 for each input position).

• weights (np.ndarray (4, N)) – Array of pixel weights corresponding with pixels.

hpgeom.healpy_compat.max_pixrad(nside, degrees=False)

Compute maximum angular distance between any pixel and its corners.

Parameters:

• nside (int or np.ndarray) – HEALPix nside.

• degrees (bool, optional) – If True, returns pixel radius in degrees, otherwise radians.

Returns:

radii – Angular distance(s) in degrees or radians.

Return type:

np.ndarray (N, ) or float

hpgeom.healpy_compat.nest2ring(nside, pix)

Convert pixel number from nest to ring ordering.

Parameters:

• nside (int, scalar) – The healpix nside parameter. Must be power of 2.

• pix (int or np.ndarray (N,)) – The pixel numbers in nest scheme.

Returns:

pix – The pixel numbers in ring scheme.

Return type:

int or np.ndarray (N,)

hpgeom.healpy_compat.npix2nside(nside)

Return the nside given a number of pixels.

Parameters:

npixel (int or np.ndarray (N,)) – Number of pixels.

Returns:

nside – HEALPix nside associated with that number of pixels.

Return type:

int or np.ndarray (N,)

hpgeom.healpy_compat.nside2npix(nside)

Return the number of pixels given an nside.

Parameters:

nside (int or np.ndarray (N,)) – HEALPix nside

Returns:

npixel – Number of pixels associated with that nside.

Return type:

int or np.ndarray (N,)

hpgeom.healpy_compat.nside2order(nside)

Return the resolution order for a given nside.

Parameters:

nside (int) – HEALPix nside parameter. Will raise ValueError if nside is not valid (must be a power of 2 and less than 2**30).

Returns:

order – Order corresponding to given nside, such that nside = 2**order.

Return type:

int

hpgeom.healpy_compat.nside2pixarea(nside, degrees=False)

Return the pixel area given an nside in square degrees or square radians.

Parameters:

• nside (int) – HEALPix nside parameter.

• degrees (bool, optional) – Return area in square degrees?

Returns:

pixel_area – Pixel area in square degrees or square radians.

Return type:

float

hpgeom.healpy_compat.nside2resol(nside, arcmin=False)

Return the approximate resolution (pixel size in radians or arcminutes), given an nside.

Resolution is just the square root of the pixel area, which is an approximation given the varying pixel shapes.

Parameters:

• nside (int) – HEALPix nside parameter.

• arcmin (bool, optional) – If True, return resolution in arcminutes, otherwise radians.

Returns:

resolution – Approximate pixel size in specified units.

Return type:

float

hpgeom.healpy_compat.order2nside(order)

Return the nside for a given order.

Parameters:

order (int) – Resolution order. Will raise ValueError if order is not valid (must be 0 to 29 inclusive).

Returns:

nside – HEALPix nside corresponding to given order, such that nside = 2**order.

Return type:

int

hpgeom.healpy_compat.pix2ang(nside, pix, nest=False, lonlat=False)

Convert pixels to angles, with healpy interface.

Parameters:

• nside (int) – The HEALPix nside parameter.

• pix (np.ndarrat (N,) or scalar) – Pixel numbers.

• nest (bool, optional) – If True, NEST pixel ordering scheme, otherwise RING.

• lonlat (bool, optional) – If True, input angles are lon/lat instead of theta/phi.

Returns:

• theta (np.ndarray (N,) or scalar) – Angular coordinate theta (radians) or longitude (degrees).

• phi (np.ndarray (N,) or scalar) – Angular coordinate phi (radians) or latitude (degrees).

hpgeom.healpy_compat.pix2vec(nside, pix, nest=False)

Convert pixels to cartesian vectors (x, y, z).

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• pix (int or np.ndarray (N,)) – Pixel number(s).

• nest (bool, optional) – Use nest ordering scheme?

Returns:

• x (np.ndarray (N,)) – x coordinates of vectors.

• y (np.ndarray (N,)) – y coordinates of vectors.

• z (np.ndarray (N,)) – z coordinates of vectors.

hpgeom.healpy_compat.query_disc(nside, vec, radius, inclusive=False, fact=4, nest=False, buff=None)

Returns pixels whose centers lie within the disk defined by vec and radius (in radians) (if inclusive is False), or which overlap with this disk (if inclusive is True).

Parameters:

• nside (int) – The HEALPix nside parameter.

• vec (float, sequence of 3 elements) – The coordinates of unit vector defining the disk center.

• radius (float) – The radius (in radians) of the disk

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the disk; if True, return all pixels that overlap with the disk, and maybe a few more.

• fact (int, optional) – Only used when inclusive=True. The overlapping test will be done at the resolution fact*nside. For NESTED ordering, fact must be a power of 2, less than 2**30, else it can be any positive integer.

• nest (bool, optional) – If True, assume NESTED pixel ordering, otherwise, RING pixel ordering

• buff (int array, optional) – If provided, this numpy array is used to contain the return values and must be at least long enough to do so. Note that this is provided for compatibility only and is not optimized.

Returns:

pixels – Array of pixels (np.int64) which cover the disk.

Return type:

np.ndarray (N,)

hpgeom.healpy_compat.query_polygon(nside, vertices, inclusive=False, fact=4, nest=False, buff=None)

Returns pixels whose centers lie within the polygon defined by vertices (if inclusive is False), or which overlap with the polygon (if inclusive is True).

Parameters:

• nside (int) – The HEALPix nside parameter.

• vertices (np.ndarray (N, 3)) – Vertex array containing the vertices of the polygon.

• inclusive (bool, optional) – If False, return the exact set of pixels whose pixel centers lie within the polygon; if True, return all pixels that overlap with the polygon, and maybe a few more.

• fact (int, optional) – Only used when inclusive=True. The overlapping test will be done at the resolution fact*nside. For NESTED ordering, fact must be a power of 2, less than 2**30, else it can be any positive integer.

• nest (bool, optional) – If True, assume NESTED pixel ordering, otherwise, RING pixel ordering

• buff (int array, optional) – If provided, this numpy array is used to contain the return values and must be at least long enough to do so. Note that this is provided for compatibility only and is not optimized.

Returns:

pixels – Array of pixels (np.int64) which cover the disk.

Return type:

np.ndarray (N,)

hpgeom.healpy_compat.ring2nest(nside, pix)

Convert pixel number from ring to nest ordering.

Parameters:

• nside (int, scalar) – The healpix nside parameter. Must be power of 2.

• pix (int or np.ndarray (N,)) – The pixel numbers in ring scheme.

Returns:

pix – The pixel numbers in nest scheme.

Return type:

int or np.ndarray (N,)

hpgeom.healpy_compat.vec2ang(vectors, lonlat=False)

Convert cartesian (x, y, z) vectors to angles.

Parameters:

• vec (np.ndarray (3,) or (N, 3)) – The vectors to convert to angles.

• lonlat (bool, optional) – Use longitude/latitude instead of co-latitude/longitude (radians).

• degrees (bool, optional) – If lonlat is True then this sets if the units are degrees or radians.

Returns:

• theta (float or np.ndarray (N,)) – Longitude or co-latitude theta (radians if lonlat=False, degrees if lonlat=True and degrees=True).

• phi (float or np.ndarray (N,)) – Latitude or longitude phi (radians if lonlat=False, degrees if lonlat=True and degrees=True).

hpgeom.healpy_compat.vec2pix(nside, x, y, z, nest=False)

Convert cartesian vectors (x, y, z) to pixels.

Parameters:

• nside (int or np.ndarray (N,)) – HEALPix nside. Must be power of 2 for nest ordering.

• x (np.ndarray (N,)) – x coordinates of vectors.

• y (np.ndarray (N,)) – y coordinates of vectors.

• z (np.ndarray (N,)) – z coordinates of vectors.

• nest (bool, optional) – Use nest ordering scheme?

Returns:

pix – Pixel number(s).

Return type:

int or np.ndarray (N,)