hats.pixel_math.spatial_index#

spatial_index.py: Utilities to convert between healpix coordinates and a scalar spatial index.

Attributes#

Functions#

compute_spatial_index(ra_values, dec_values[, ...]) → numpy.ndarray

Compute the healpix index field.

spatial_index_to_healpix(ids[, target_order, ...]) → numpy.ndarray

Convert healpix index values to the healpix pixel at the specified order

healpix_to_spatial_index(order, pixel[, ...]) → numpy.int64 | numpy.ndarray

Convert a healpix pixel to the healpix index

split_to_row_groups(table, row_group_kwargs[, pixel_order]) → list[pyarrow.Table]

Split the pixel table into row group chunks.

Module Contents#

SPATIAL_INDEX_COLUMN = '_healpix_29'[source]#
SPATIAL_INDEX_ORDER = 29[source]#
compute_spatial_index(ra_values: float | numpy.typing.ArrayLike, dec_values: float | numpy.typing.ArrayLike, spatial_index_order: int = SPATIAL_INDEX_ORDER) → numpy.ndarray[source]#

Compute the healpix index field.

Parameters:
ra_valuesfloat | ArrayLike

celestial coordinates, right ascension in degrees

dec_valuesfloat | ArrayLike

celestial coordinates, declination in degrees

spatial_index_order: int

(Default value = SPATIAL_INDEX_ORDER = 29) order to use for spatial index

Returns:
np.ndarray

HEALPix pixel indices at specified order, for all coordinates provided.

Raises:
ValueError

if the length of the input lists don’t match.

spatial_index_to_healpix(ids: numpy.typing.ArrayLike, target_order: int = SPATIAL_INDEX_ORDER, spatial_index_order: int = SPATIAL_INDEX_ORDER) → numpy.ndarray[source]#

Convert healpix index values to the healpix pixel at the specified order

Parameters:
idsArrayLike

list (or array) of well-formatted _healpix_29 values

target_orderint

Defaults to SPATIAL_INDEX_ORDER. The order of the pixel to get from the healpix index.

spatial_index_order: int

(Default value = SPATIAL_INDEX_ORDER = 29) order to use for spatial index

Returns:
np.ndarray

numpy array of target_order pixels from the healpix index

healpix_to_spatial_index(order: int | list[int], pixel: int | list[int], spatial_index_order: int = SPATIAL_INDEX_ORDER) → numpy.int64 | numpy.ndarray[source]#

Convert a healpix pixel to the healpix index

This maps the healpix pixel to the lowest pixel number within that pixel at the specified healpix order.

Useful for operations such as filtering by _healpix_29.

Parameters:
orderint | list[int]

order of pixel to convert

pixelint | list[int]

pixel number in nested ordering of pixel to convert

spatial_index_order: int

(Default value = SPATIAL_INDEX_ORDER = 29) order to use for spatial index

Returns:
np.int64 | np.ndarray

healpix index or numpy array of healpix indices

split_to_row_groups(table: pyarrow.Table, row_group_kwargs: dict | None, pixel_order: int | None = None) → list[pyarrow.Table][source]#

Split the pixel table into row group chunks. You can split by number of rows (num_rows), or by spatial proximity (subtile_order_delta).

Parameters:
tablepa.Table

Pixel table.

row_group_kwargsdict
if “num_rows” (int >= 1) in row_group_kwargs, limit each chunk to a maximum of

this many rows. e.g. if the input table has 32 rows and num_rows == 10, then the chunks will have [10, 10, 10, 2] rows.

if “subtile_order_delta” (int >= 0) in row_group_kwargs, create row groups

corresponding to angular proximity, approximated by HEALPix pixels. If subtile_order_delta == 0, then each row group contains objects in the same HEALPix pixel of order pixel_order. If subtile_order_delta == 1, then the row groups are split by HEALPix pixels at order pixel_order + 1, etc. Higher numbers correspond to a finer grid (smaller pixels, fewer rows per pixel).

pixel_orderint | None

The HEALPix order to split when using subtile_order_delta.

Returns:
split_tableslist[pa.Table]

The input table split into row group chunks.