binny.nz_tomo.binning_core module#

Shared utilities for tomographic redshift binning.

This module contains the shared building blocks for creating tomographic bins from a parent redshift distribution. Photo-z and spec-z builders use these helpers to keep behavior consistent across binning methods.

binny.nz_tomo.binning_core.build_bins_on_edges(*, z: ndarray[tuple[Any, ...], dtype[float64]], nz_parent_for_meta: ndarray[tuple[Any, ...], dtype[float64]], bin_edges: ndarray[tuple[Any, ...], dtype[float64]], raw_bin_for_edge: Callable[[int, float, float], ndarray[tuple[Any, ...], dtype[float64]]], normalize_bins: bool, norm_method: Literal['trapezoid', 'simpson'], mixer: Callable[[dict[int, ndarray[tuple[Any, ...], dtype[float64]]]], dict[int, ndarray[tuple[Any, ...], dtype[float64]]]] | None = None, need_meta: bool) → tuple[dict[int, ndarray[tuple[Any, ...], dtype[float64]]], dict[int, float] | None, float | None]#

Builds tomographic bins on fixed edges.

Parameters:

  • z – Redshift grid for all returned curves.

  • nz_parent_for_meta – Parent distribution used for metadata.

  • bin_edges – Validated 1D array of bin edges.

  • raw_bin_for_edge – Callable that returns the raw bin curve for a bin index and edge pair.

  • normalize_bins – Whether to normalize each bin curve.

  • norm_method – Normalization method used when normalize_bins=True.

  • mixer – Optional transformation applied to the set of raw bins.

  • need_meta – Whether to compute per-bin norms and the parent norm.

Returns:

A tuple (bins, bins_norms, parent_norm), where bins is a mapping of bin index to bin curve, bins_norms is the per-bin integral (or None), and parent_norm is the parent integral (or None).

Raises:

ValueError – If a raw bin curve does not match the shape of z.

binny.nz_tomo.binning_core.finalize_tomo_metadata(*, kind: str, z: ndarray[tuple[Any, ...], dtype[float64]], parent_nz: ndarray[tuple[Any, ...], dtype[float64]], bin_edges: ndarray[tuple[Any, ...], dtype[float64]], bins: Mapping[int, ndarray[tuple[Any, ...], dtype[float64]]], inputs: Mapping[str, Any], parent_norm: float | None, bins_norms: Mapping[int, float] | None, include_metadata: bool, save_metadata_path: str | None) → dict[str, Any] | None#

Builds tomography metadata and optionally writes it to disk.

Parameters:

  • kind – Tomography kind label (e.g. “photoz”, “specz”).

  • z – Redshift grid.

  • parent_nz – Parent redshift distribution.

  • bin_edges – Bin-edge array used to construct the bins.

  • bins – Mapping of bin index to bin curve.

  • inputs – Input settings to record in the metadata.

  • parent_norm – Integral of the parent distribution, if available.

  • bins_norms – Per-bin integrals, if available.

  • include_metadata – Whether to return the metadata dictionary.

  • save_metadata_path – Optional path for writing a text metadata file.

Returns:

Metadata dictionary if requested, otherwise None.

binny.nz_tomo.binning_core.resolve_bin_edges(*, z_axis: ndarray[tuple[Any, ...], dtype[float64]], nz_axis: ndarray[tuple[Any, ...], dtype[float64]], bin_edges: Any | None, binning_scheme: str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None, n_bins: int | None, bin_range: tuple[float, float] | None = None, equal_number_axis: Any | None = None, equal_number_weights: Any | None = None, z_ph: Any | None = None, nz_ph: Any | None = None, norm_method: Literal['trapezoid', 'simpson'] = 'trapezoid', normalize_equal_number_weights: bool = True) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns tomographic bin edges.

Parameters:

  • z_axis – Default axis used when edges are derived from the input range.

  • nz_axis – Default weights used when edges are derived from weights.

  • bin_edges – Explicit bin edges. Mutually exclusive with binning_scheme and n_bins.

  • binning_scheme – Binning description. May be a scheme name (e.g. “equidistant”, “equal_number”) or a mixed-segment specification.

  • n_bins – Number of bins for simple scheme names.

  • bin_range – Optional (min, max) range for equidistant binning.

  • equal_number_axis – Optional axis used for equal-number binning.

  • equal_number_weights – Optional weights used for equal-number binning.

  • z_ph – Optional axis used by mixed-segment specifications.

  • nz_ph – Optional weights used by mixed-segment specifications.

  • norm_method – Normalization method used when normalizing weights.

  • normalize_equal_number_weights – Whether to normalize the weights used for equal-number binning.

Returns:

A 1D array of bin edges.

Raises:

ValueError – If inputs are inconsistent or the binning specification is not supported.

binny.nz_tomo.binning_core.validate_bin_edges(bin_edges: Any, *, require_within: tuple[float, float] | None = None) → ndarray[tuple[Any, ...], dtype[float64]]#

Validates a bin-edge array.

Parameters:

  • bin_edges – Candidate bin edges.

  • require_within – Optional (min, max) interval that the edges must lie within.

Returns:

A validated 1D array of bin edges as float64.

Raises:

ValueError – If the edges are not 1D, not finite, not strictly increasing, or fall outside require_within.