hats.pixel_math

Utilities for performing fun math on healpix pixels

Submodules

• 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.region_to_moc
• 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(row_count_histogram[, ...])	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
generate_incremental_alignment(row_count_histogram, ...)	Generate alignment for an incremental catalog.
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 index 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

HEALPix order

pixel: int

HEALPix pixel number in NESTED ordering scheme

__post_init__() → None

Initialize a HEALPix pixel

__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_orderint

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

Returns:

HealpixPixel

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_orderint

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

Returns:

list[HealpixPixel]

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:

pixelHealpixPixel | tuple[int, int]

an object to be converted to a HealpixPixel object

Returns:

HealpixPixel

the pixel

empty_histogram(highest_order)

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

Parameters:

highest_orderint

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

Returns:

np.ndarray

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(row_count_histogram, highest_order=10, lowest_order=0, threshold=1000000, drop_empty_siblings=False, mem_size_histogram=None)

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:

row_count_histogramnp.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_orderint

the highest healpix order (e.g. 5-10) (Default value = 10)

lowest_orderint

the lowest healpix order (e.g. 1-5). specifying a lowest order constrains the partitioning to prevent spatially large pixels. (Default value = 0)

thresholdint

the maximum number of objects allowed in a single pixel (Default value = 1_000_000)

drop_empty_siblingsbool

if 3 of 4 pixels are empty, keep only the non-empty pixel (Default value = False)

mem_size_histogramnp.array or None

one-dimensional numpy array of long integers where the value at each index corresponds to the memory size (in bytes) of objects found at the healpix pixel. If provided, this will be used to determine the thresholding instead of the param histogram. (Default value = None)

Returns:

tuple

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:

datapd.DataFrame

tabular object data

highest_orderint

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

ra_columnstr

where in the input to find the celestial coordinate right ascension (Default value = “ra”)

dec_columnstr

where in the input to find the celestial coordinate declination (Default value = “dec”)

Returns:

np.ndarray

one-dimensional numpy array of long integers where the value at each index corresponds

Raises:

ValueError

if the ra_column or dec_column cannot be found in the input data.

generate_incremental_alignment(row_count_histogram: numpy.ndarray, existing_pixels: Sequence[tuple[int, int]], highest_order: int = 10, lowest_order: int = 0, threshold: int = 1000000, mem_size_histogram: numpy.ndarray | None = None)

Generate alignment for an incremental catalog.

We will keep the existing pixels and add new pixels for the points in the histogram that fall out of the existing coverage. Those pixels will be the largest (non-overlapping) possible that obey to the defined pixel threshold.

Unlike generate_alignment there is no global guarantee that the number of points per pixel remains under the previous pixel_threshold.

Parameters:

row_count_histogramnp.ndarray

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

existing_pixelsSequence[tuple[int,int]]

the list of pixels in the existing catalog that we want to keep

highest_orderint

the highest healpix order (e.g. 5-10) (Default value = 10)

lowest_orderint

the lowest healpix order (e.g. 1-5). specifying a lowest order constrains the partitioning to prevent spatially large pixels. (Default value = 0)

thresholdint

the maximum number of objects allowed in a single pixel (Default value = 1_000_000)

mem_size_histogramnp.ndarray or None

one-dimensional numpy array of long integers where the value at each index corresponds to the memory size (in bytes) of objects found at the healpix pixel. If provided, this will be used to determine the thresholding instead of the param histogram. (Default value = None)

Returns:

tuple

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 mapping order. The tuple contains three integers:

• order of the destination pixel

• pixel number at the above order

• the number of objects in the pixel

get_margin(order, pixel, delta_order)

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

Parameters:

orderint

the healpix order of pixel.

pixelint

the healpix pixel to find margin pixels of.

delta_orderint

the change in order that we wish to find the margins for.

Returns:

list[int]

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], spatial_index_order: int = SPATIAL_INDEX_ORDER) → numpy.ndarray

Compute the healpix index field.

Parameters:

ra_valuesfloat | list[float]

celestial coordinates, right ascension in degrees

dec_valuesfloat | list[float]

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: list[int], target_order: int = SPATIAL_INDEX_ORDER, spatial_index_order: int = SPATIAL_INDEX_ORDER) → numpy.ndarray

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

Parameters:

idslist[int]

list 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