binny.nz_tomo.nz_tomo_utils module#

Helpers for tomographic binning workflows in binny.nz_tomo.

binny.nz_tomo.nz_tomo_utils.extract_bin_edges_from_meta(meta: Mapping[str, Any]) → ndarray[tuple[Any, ...], dtype[float64]] | None#

Extracts bin edges from tomography builder metadata.

This helper pulls out the bin_edges entry from tomography builder metadata when present. It is used to support downstream diagnostics (e.g., leakage matrices) without forcing users to thread bin edges through manually.

Parameters:

meta – Builder metadata mapping.

Returns:

An array of bin edges if present, otherwise None.

binny.nz_tomo.nz_tomo_utils.mixed_edges_from_segments(segments: Sequence[Mapping[str, Any]], *, z_axis: Any, nz_axis: Any, z_ph: Any | None, nz_ph: Any | None) → ndarray#

Returns bin edges for a mixed segment specification.

This function creates a single 1D array of bin edges by stitching together multiple binning segments. Each segment defines a redshift interval and a binning scheme (e.g. equidistant, log, equal-number).

For equal-number segments, the function needs an axis and weight curve that represent the population being split. You may provide a photo-z proxy (z_ph, nz_ph). If not provided, the function uses (z_axis, nz_axis) as a proxy.

Parameters:

  • segments – Sequence of segment specification mappings. Each segment must include scheme, n_bins, z_min, and z_max.

  • z_axis – Redshift axis for the parent distribution (proxy for photo-z if z_ph is not provided).

  • nz_axis – Weights or distribution values evaluated on z_axis.

  • z_ph – Optional photo-z axis used for equal-number binning decisions.

  • nz_ph – Optional photo-z weights evaluated on z_ph.

Returns:

One-dimensional numpy array of bin edges of length (N_total + 1), where N_total is the sum of n_bins over segments.

Raises:

  • ValueError – If exactly one of z_ph or nz_ph is provided.

  • ValueError – If any segment is missing required keys.

  • ValueError – If the provided axis/weights are invalid (propagated from validation utilities or downstream edge builders).

binny.nz_tomo.nz_tomo_utils.photoz_segments_to_axes(segments: Sequence[Mapping[str, Any]]) → list[dict[str, Any]]#

Converts photo-z segment specifications to the mixed-binning format.

This helper translates a list of segment mappings (each describing a binning scheme and redshift range) into the format expected by binny.axes.mixed_edges.mixed_edges().

Each input segment must provide:

  • "scheme": binning method name (aliases resolved downstream).

  • "n_bins": number of bins in this segment.

  • "z_min": lower redshift bound.

  • "z_max": upper redshift bound.

Parameters:

segments – Sequence of segment specification mappings.

Returns:

List of axes-style segment dictionaries with keys "method", "n_bins", and "params" (containing "x_min" and "x_max").

Raises:

ValueError – If any required key is missing from a segment.

binny.nz_tomo.nz_tomo_utils.resolve_bin_edges_for_leakage(*, bin_edges: Any | None, cached_bin_edges: Any | None) → ndarray[tuple[Any, ...], dtype[float64]]#

Resolve bin edges for leakage-style diagnostics.

This helper supports two user workflows: providing explicit bin edges at call time, or relying on cached bin edges from the most recent tomography build. It exists to keep error messages consistent and avoid duplicating checks.

Parameters:

  • bin_edges – Explicit bin edges provided by the caller.

  • cached_bin_edges – Cached bin edges stored on a wrapper instance.

Returns:

Bin edges as a float64 NumPy array.

Raises:

ValueError – If neither explicit nor cached bin edges are available.

binny.nz_tomo.nz_tomo_utils.resolve_n_bins_for_builder(*, bin_edges: Any | None, n_bins: int | None) → int | None#

Resolves n_bins when optional explicit edges are supported.

This helper enforces a single rule: when explicit bin_edges are provided, builders should not also receive n_bins. It keeps the logic consistent across config-driven and programmatic entry points.

Parameters:

  • bin_edges – Optional explicit bin edge specification.

  • n_bins – Optional number of bins.

Returns:

None if bin_edges is provided, otherwise n_bins.