hats.pixel_math

Utilities for performing fun math on healpix pixels

Submodules

• hats.pixel_math.box_filter
• hats.pixel_math.filter
• hats.pixel_math.healpix_pixel
• hats.pixel_math.healpix_pixel_convertor
• hats.pixel_math.healpix_pixel_function
• hats.pixel_math.healpix_shim
• hats.pixel_math.partition_stats
• hats.pixel_math.pixel_margins
• hats.pixel_math.sparse_histogram
• hats.pixel_math.spatial_index
• hats.pixel_math.validators

Classes

HealpixPixel

A HEALPix pixel, represented by an order and pixel number in NESTED ordering scheme

Functions

get_healpix_pixel(...)	Function to convert argument of either HealpixPixel or a tuple of (order, pixel) to a
empty_histogram(highest_order)	Use numpy to create an histogram array with the right shape, filled with zeros.
generate_alignment(histogram[, highest_order, ...])	Generate alignment from high order pixels to those of equal or lower order
generate_histogram(data, highest_order[, ra_column, ...])	Generate a histogram of counts for objects found in data
get_margin(order, pixel, delta_order)	Get all the pixels at order order+delta_order bordering pixel pixel.
compute_spatial_index(→ numpy.ndarray)	Compute the healpix index field.
spatial_index_to_healpix(→ numpy.ndarray)	Convert _healpix_29 values to the healpix pixel at the specified order

Package Contents

class HealpixPixel

A HEALPix pixel, represented by an order and pixel number in NESTED ordering scheme

see https://lambda.gsfc.nasa.gov/toolbox/pixelcoords.html for more information

order: int

pixel: int

__post_init__() → None

Initialize a HEALPix pixel :param order: HEALPix order :param pixel: HEALPix pixel number in NESTED ordering scheme

__str__() → str

__repr__()

__getitem__(key: int) → int

convert_to_lower_order(delta_order: int) → HealpixPixel

Returns the HEALPix pixel that contains the pixel at a lower order

Parameters:

delta_order – the difference in order to be subtracted from the current order to generate the pixel at a lower order. Must be non-negative

Returns:

A new HealpixPixel at the current order - delta_order which contains the current pixel

Raises:

ValueError – If delta_order is greater than the current order, a pixel cannot be generated at a negative order. Or if delta_order is negative

convert_to_higher_order(delta_order: int) → list[HealpixPixel]

Returns a list of HEALPix pixels making up the current pixel at a higher order

Parameters:

delta_order – the difference in order to be added to the current order to generate the pixels at a higher order. Must be non-negative

Returns:

A new HealpixPixel at the current order - delta_order which contains the current pixel

Raises:

ValueError – If delta_order + current order is greater than the maximum HEALPix order, pixels cannot be generated. Or if delta_order is negative

property dir: int

Directory number for the pixel.

This is necessary for file systems that limit to 10,000 subdirectories. The directory name will take the HiPS standard form of:

<catalog_base_dir>/Norder=<pixel_order>/Dir=<directory number>

Where the directory number is calculated using integer division as:

(pixel_number/10000)*10000

get_healpix_pixel(pixel: hats.pixel_math.healpix_pixel.HealpixPixel | tuple[int, int]) → hats.pixel_math.healpix_pixel.HealpixPixel

Function to convert argument of either HealpixPixel or a tuple of (order, pixel) to a HealpixPixel

Parameters:

pixel – an object to be converted to a HealpixPixel object

empty_histogram(highest_order)

Use numpy to create an histogram array with the right shape, filled with zeros.

Parameters:

highest_order (int) – the highest healpix order (e.g. 0-10)

Returns:

one-dimensional numpy array of long integers, where the length is equal to the number of pixels in a healpix map of target order, and all values are set to 0.

generate_alignment(histogram, highest_order=10, lowest_order=0, threshold=1000000, drop_empty_siblings=False)

Generate alignment from high order pixels to those of equal or lower order

We may initially find healpix pixels at order 10, but after aggregating up to the pixel threshold, some final pixels are order 4 or 7. This method provides a map from pixels at order 10 to their destination pixel. This may be used as an input into later partitioning map reduce steps.

Parameters:

• histogram (np.array) – one-dimensional numpy array of long integers where the value at each index corresponds to the number of objects found at the healpix pixel.

• highest_order (int) – the highest healpix order (e.g. 5-10)

• lowest_order (int) – the lowest healpix order (e.g. 1-5). specifying a lowest order constrains the partitioning to prevent spatially large pixels.

• threshold (int) – the maximum number of objects allowed in a single pixel

• drop_empty_siblings (bool) – if 3 of 4 pixels are empty, keep only the non-empty pixel

Returns:

one-dimensional numpy array of integer 3-tuples, where the value at each index corresponds to the destination pixel at order less than or equal to the highest_order.

The tuple contains three integers:

• order of the destination pixel

• pixel number at the above order

• the number of objects in the pixel

Raises:

ValueError – if the histogram is the wrong size, or some initial histogram bins exceed threshold.

generate_histogram(data: pandas.DataFrame, highest_order, ra_column='ra', dec_column='dec')

Generate a histogram of counts for objects found in data

Parameters:

• data (pd.DataFrame) – tabular object data

• highest_order (int) – the highest healpix order (e.g. 0-10)

• ra_column (str) – where in the input to find the celestial coordinate, right ascension

• dec_column (str) – where in the input to find the celestial coordinate, declination

Returns:

one-dimensional numpy array of long integers where the value at each index corresponds to the number of objects found at the healpix pixel.

Raises:

ValueError – if the ra_column or dec_column cannot be found in the input file.

get_margin(order, pixel, delta_order)

Get all the pixels at order order+delta_order bordering pixel pixel.

Parameters:

• order (int) – the healpix order of pixel.

• pix (int) – the healpix pixel to find margin pixels of.

• delta_order (int) – the change in order that we wish to find the margins for.

Returns:

one-dimensional numpy array of integers, filled with the healpix pixels at order order+delta_order that border pixel.

compute_spatial_index(ra_values: float | list[float], dec_values: float | list[float]) → numpy.ndarray

Compute the healpix index field.

Parameters:

• ra_values (float|list[float]) – celestial coordinates, right ascension in degrees

• dec_values (float|list[float]) – celestial coordinates, declination in degrees

Returns:

one-dimensional numpy array of int64s with healpix NESTED pixel numbers at order 29

Raises:

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

spatial_index_to_healpix(ids: list[int], target_order: int = SPATIAL_INDEX_ORDER) → numpy.ndarray

Convert _healpix_29 values to the healpix pixel at the specified order

Parameters:

• ids (List[int64]) – list of well-formatted _healpix_29 values

• target_order (int64) – Defaults to SPATIAL_INDEX_ORDER. The order of the pixel to get from the healpix index.

Returns:

numpy array of target_order pixels from the healpix index