hats.pixel_math =============== .. py:module:: hats.pixel_math .. autoapi-nested-parse:: Utilities for performing fun math on healpix pixels .. !! processed by numpydoc !! Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/hats/pixel_math/healpix_pixel/index /autoapi/hats/pixel_math/healpix_pixel_convertor/index /autoapi/hats/pixel_math/healpix_pixel_function/index /autoapi/hats/pixel_math/healpix_shim/index /autoapi/hats/pixel_math/partition_stats/index /autoapi/hats/pixel_math/pixel_margins/index /autoapi/hats/pixel_math/region_to_moc/index /autoapi/hats/pixel_math/sparse_histogram/index /autoapi/hats/pixel_math/spatial_index/index /autoapi/hats/pixel_math/validators/index Classes ------- .. autoapisummary:: hats.pixel_math.HealpixPixel Functions --------- .. autoapisummary:: hats.pixel_math.get_healpix_pixel hats.pixel_math.empty_histogram hats.pixel_math.generate_alignment hats.pixel_math.generate_histogram hats.pixel_math.generate_incremental_alignment hats.pixel_math.get_margin hats.pixel_math.compute_spatial_index hats.pixel_math.spatial_index_to_healpix Package Contents ---------------- .. py: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 .. !! processed by numpydoc !! .. py:attribute:: order :type: int HEALPix order .. !! processed by numpydoc !! .. py:attribute:: pixel :type: int HEALPix pixel number in NESTED ordering scheme .. !! processed by numpydoc !! .. py:method:: __post_init__() -> None Initialize a HEALPix pixel .. !! processed by numpydoc !! .. py:method:: __str__() -> str .. py:method:: __repr__() .. py:method:: __getitem__(key: int) -> int .. py:method:: convert_to_lower_order(delta_order: int) -> HealpixPixel Returns the HEALPix pixel that contains the pixel at a lower order :Parameters: **delta_order** : int 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 .. !! processed by numpydoc !! .. py:method:: 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** : int 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 .. !! processed by numpydoc !! .. py:property:: dir :type: 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:: /Norder=/Dir= Where the directory number is calculated using integer division as:: (pixel_number/10000)*10000 .. !! processed by numpydoc !! .. py:function:: 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** : HealpixPixel | tuple[int, int] an object to be converted to a HealpixPixel object :Returns: HealpixPixel the pixel .. !! processed by numpydoc !! .. py:function:: 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: 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. .. !! processed by numpydoc !! .. py:function:: generate_alignment(row_count_histogram, highest_order=10, lowest_order=0, threshold=1000000, drop_empty_siblings=False, mem_size_histogram=None, supplemental_count_histogram=None, use_lower_order=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: **row_count_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) (Default value = 10) **lowest_order** : int the lowest healpix order (e.g. 1-5). specifying a lowest order constrains the partitioning to prevent spatially large pixels. (Default value = 0) **threshold** : int the maximum number of objects allowed in a single pixel (Default value = 1_000_000) **drop_empty_siblings** : bool if 3 of 4 pixels are empty, keep only the non-empty pixel (Default value = False) **mem_size_histogram** : np.array or None DEPRECATED: to be replaced by `supplemental_count_histogram`. **supplemental_count_histogram: np.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. .. !! processed by numpydoc !! .. py:function:: 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 (Default value = "ra") **dec_column** : str 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. .. !! processed by numpydoc !! .. py:function:: 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, supplemental_count_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_histogram** : np.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_pixels** : Sequence[tuple[int,int]] the list of pixels in the existing catalog that we want to keep **highest_order** : int the highest healpix order (e.g. 5-10) (Default value = 10) **lowest_order** : int the lowest healpix order (e.g. 1-5). specifying a lowest order constrains the partitioning to prevent spatially large pixels. (Default value = 0) **threshold** : int the maximum number of objects allowed in a single pixel (Default value = 1_000_000) **mem_size_histogram** : np.ndarray or None DEPRECATED. To be replaced by `supplemental_count_histogram`. **supplemental_count_histogram** : np.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 .. !! processed by numpydoc !! .. py:function:: 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. **pixel** : 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: list[int] one-dimensional numpy array of integers, filled with the healpix pixels at order `order+delta_order` that border pixel. .. !! processed by numpydoc !! .. py:function:: 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_values** : float | list[float] celestial coordinates, right ascension in degrees **dec_values** : float | 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. .. !! processed by numpydoc !! .. py:function:: 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: **ids** : list[int] list of well-formatted _healpix_29 values **target_order** : int 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 .. !! processed by numpydoc !!