uvex_transients.surveys.base.SurveySchedule.get_healpix_coverage_index#

SurveySchedule.get_healpix_coverage_index(nside: int | None = None, order: str | None = None, cache: bool = True, overwrite: bool = False) → tuple[ndarray, ndarray][source]#

Lazily build the HEALPix coverage index as a CSR (compressed-sparse-row) structure.

Rasterizes every "observe" row’s rolled footprint in a single, vectorized footprint_healpix() call – not one call per row – then groups the resulting (row, pixel) hits by pixel via one vectorized sort plus numpy.bincount()/numpy.cumsum(), into two flat arrays rather than a Python dict: pixel id doubles directly as an array index into pixel_offsets, so a lookup is a memory offset, not a hash-table probe, and a whole batch of pixel ids can be resolved in one fancy-index call instead of a per-query Python loop.

footprint_healpix follows HEALPix’s own convention of pixel-center membership, not full-pixel overlap: a row is registered under pixel p only if p’s center falls inside that row’s rolled footprint. A query point can therefore sit inside a footprint while its own pixel goes unregistered (a one-directional miss, never a false claim – see get_observation_indices_of(), which confirms every candidate this index returns with an exact geometric test, so nothing reached through this index is ever wrongly included, only occasionally left out near a footprint’s edge). Raise nside to shrink how often that happens; there is no dilation margin built into the index itself.

Parameters:

  • nside (int, optional) – HEALPix resolution parameter, or None to use config["healpix.default_nside"].

  • order (str, optional) – HEALPix pixel ordering scheme, "nested" or "ring", or None to use config["healpix.default_order"].

  • cache (bool) – If True (the default), reuse a previously built index for this (nside, order) when available, and store the freshly built one for later reuse. If False, always rebuild and never store the result – useful for a one-off query at a resolution not worth caching.

  • overwrite (bool) – If True, rebuild even if a cached index for this (nside, order) already exists. Ignored if cache is False, since every call already rebuilds in that case.

Returns:

  • pixel_offsets (numpy.ndarray) – int64 array of shape (12 * nside**2 + 1,). Row indices whose footprint covers pixel p are sorted_rows[pixel_offsets[p]:pixel_offsets[p + 1]] – an empty slice if pixel p is not covered by any observation.

  • sorted_rows (numpy.ndarray) – int64 array of row indices into observe_rows, grouped contiguously by pixel and ordered to match pixel_offsets.