healpix_resample.ConservativeResampler#
- class healpix_resample.ConservativeResampler(*args, area=None, out_cell_ids=None, **kwargs)[source]#
Area-weighted, flux-conserving HEALPix resampler.
Bins each source sample into its containing HEALPix cell (exact grouping, like
GroupByResampler) and accumulates area-weighted sums, so the total integrated quantity is exactly preserved between the sample-space and HEALPix-cell representations. See the module docstring for the extensive-vs-intensive distinction that determines whetherareaneeds to be supplied.- Parameters:
area (
array-likeorNone) – Per-sample pixel area/weight, shape(N,). Any consistent unit works since only ratios matter. Defaults to1.0for every sample (equal-area pixels / already-extensive quantities).All other parameters are forwarded to ``KNeighborsResampler``
(``lon_deg``, ``lat_deg``, ``level``, ``nest``, ``device``, ``dtype``,
``ellipsoid``, ``verbose``, …). ``out_cell_ids`` is not supported.
- __init__(*args, area=None, out_cell_ids=None, **kwargs)[source]#
Pre-compute sparse operators.
- Parameters:
lon_deg, lat_deg – unstructured sample coordinates in degrees, shape (N,); float32 or float64, the geometry is computed in float64
Npt – number of nearest HEALPix cells used per sample. A sample that does not find Npt kept cells within
ring_search_maxrings (samples much sparser than the cells) keeps the ones it found.ring_search_init, ring_search_max – first and last HEALPix ring of the per-sample neighbour search; a
ring_search_maxbelowring_search_initis raised to itlevel – HEALPix level, nside = 2**level
sigma_m – Gaussian length scale (meters). If None, uses the HEALPix pixel scale sigma = sqrt(4*pi/(12*4**level))*R.
threshold – keep only HEALPix cells whose global weight sum >= threshold
nest – HEALPix indexing scheme
dtype/device – torch dtype/device for all matrices and computations
out_cell_ids – optional subset of
levelcells to restrict the output to (e.g. one chunk or one parent cell). If none of these cells has enough support among the samples, the operator is built withK = 0instead of raising:resample()then returnscell_idsof size 0 andcell_dataof shape(B, 0), exceptNearestResampler, whose fallback fills the requested cells with their nearest sample (see itsmax_distance_m).batch_size – process the samples in slices of this size when building the operators (see
healpix_weighted_nearest): the temporary memory of the neighbour search is then about 2 kB per sample of a slice instead of 2 kB per sample.None(default) processes all samples at once. The result is the same.coarse_level_delta – number the cells of the neighbour search from their parents this many levels coarser (nested only; see
healpix_weighted_nearest): the same cells, neighbours and ties as the fine-level search, in less time and memory.None(default): the fine-level search.neighbours – the links (NeighbourLinks) of an earlier resampler on the same samples, level and search parameters (its
neighboursattribute): the neighbour search is skipped and the distances computed again, so the resampler is the same, bit for bit. WithNpt=1it is ignored.
- Raises:
RuntimeError – without
out_cell_ids, when no cell passesthreshold(lowerthresholdor widen the neighbourhood rings), or when cells pass it but no sample reaches any of them withinring_search_maxrings.
Methods
__init__(*args[, area, out_cell_ids])Pre-compute sparse operators.
comp_matrix()Build
self.M(N,K), sparse CSC: links weighted by _link_weights() (and the tied links by _tie_weights()), normalised per cell (column).get_cell_area()Return the total input area binned into each HEALPix cell (K,).
get_cell_ids()invert(hval)HEALPix cells → source samples, mass-conserving redistribution.
resample(val, **_kwargs)Source samples → HEALPix cells, area-weighted sum.
Attributes
MTSparse CSR
(K, N)operator, cells -> samples (invert()); built on first access.M_consSparse CSR
(N, K)conservative operator (resample(conservative=True), same links asM, each sample's weights summing to 1); built on first access.