binny.nz_tomo.photoz module#

Functions to build photometric-redshift tomographic bins.

This module builds true-redshift distributions selected by observed-redshift (photo-z) tomographic bins. The primary entry point is build_photoz_bins, which returns a dict mapping bin index -> photo-z-selected n_bin(z) evaluated on a common true-z grid.

Model#

For each observed-redshift bin [z_ph_min, z_ph_max], we compute:

n_bin(z) = n(z) * P(bin | z),

where P(bin | z) is the probability that an object at true redshift z is assigned to that photo-z bin. The core photo-z model is Gaussian:

z_ph ~ Normal(mu(z), sigma(z)),
mu(z)    = mean_scale * z - mean_offset,
sigma(z) = scatter_scale * (1 + z).

Optionally, a second Gaussian outlier component may be included with mixture weight outlier_frac (enabled only when outlier_scatter_scale is not None).

All bin-assignment probabilities are computed analytically by integrating the Gaussian(s) between the photo-z bin edges using the error function.

Notes

  • All outputs are evaluated on the input true-z grid z.

  • If normalize_bins=True (default), each returned bin distribution is normalized to integrate to 1 on z.

  • bin_edges live in observed-redshift (photo-z) space.

Metadata / population fractions#

If metadata is requested (include_metadata=True or save_metadata_path is set), the builder records how much of the parent distribution falls into each observed (photo-z) bin before any per-bin normalization is applied.

Specifically, it stores:

  • parent_norm: the total area under the parent curve nz on the provided grid

  • bins_norms[i]: the area under the raw (pre-normalization) bin curve for bin i

  • frac_per_bin[i]: bins_norms[i] / parent_norm when parent_norm > 0

If normalize_bins=True, the returned bin curves are each normalized to integrate to 1 on z and should be treated as shape-only PDFs. Use frac_per_bin (or survey-level inputs) for population statistics such as relative bin weights, number densities, or counts.

binny.nz_tomo.photoz.build_photoz_bins(z: ndarray[tuple[Any, ...], dtype[float64]], nz: ndarray[tuple[Any, ...], dtype[float64]], bin_edges: ndarray[tuple[Any, ...], dtype[float64]] | None = None, *, scatter_scale: Sequence[float] | float = 0.0, mean_offset: Sequence[float] | float = 0.0, binning_scheme: str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None = None, n_bins: int | None = None, bin_range: tuple[float, float] | None = None, mean_scale: Sequence[float] | float = 1.0, outlier_frac: Sequence[float] | float = 0.0, outlier_scatter_scale: Sequence[float] | float | None = None, outlier_mean_offset: Sequence[float] | float = 0.0, outlier_mean_scale: Sequence[float] | float = 1.0, z_ph: ndarray[tuple[Any, ...], dtype[float64]] | None = None, nz_ph: ndarray[tuple[Any, ...], dtype[float64]] | None = None, normalize_input: bool = True, normalize_bins: bool = True, norm_method: Literal['trapezoid', 'simpson'] = 'trapezoid', include_metadata: bool = False, save_metadata_path: str | None = None) → dict[int, ndarray[tuple[Any, ...], dtype[float64]]] | tuple[dict[int, ndarray[tuple[Any, ...], dtype[float64]]], dict[str, Any]]#

Builds photo-z-selected true-redshift distributions per tomographic bin.

Parameters:

  • z – True-redshift grid.

  • nz – Parent distribution evaluated on z.

  • bin_edges – Optional photo-z bin edges. If not provided, edges are derived from binning_scheme.

  • scatter_scale – Per-bin (or constant scalar) photo-z scatter scale.

  • mean_offset – Per-bin (or constant scalar) photo-z mean offset.

  • binning_scheme – Scheme name or mixed segment specification used to derive bin edges when bin_edges is not provided.

  • n_bins – Number of bins for simple scheme names.

  • bin_range – Optional photo-z interval used when deriving equidistant edges.

  • mean_scale – Per-bin (or constant scalar) photo-z mean scale.

  • outlier_frac – Per-bin (or constant scalar) outlier mixture fraction.

  • outlier_scatter_scale – Per-bin (or scalar) outlier scatter scale. When provided, enables an outlier component.

  • outlier_mean_offset – Per-bin (or constant scalar) outlier mean offset.

  • outlier_mean_scale – Per-bin (or constant scalar) outlier mean scale.

  • z_ph – Optional photo-z axis used for edge derivation in population-based schemes.

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

  • normalize_input – Whether to normalize nz before computing bins.

  • normalize_bins – Whether to normalize each returned bin curve.

  • norm_method – Integration method used for normalization.

  • include_metadata – Whether to return metadata alongside the bins.

  • save_metadata_path – Optional path for writing metadata.

Returns:

Mapping from bin index to n_bin(z). If include_metadata=True, returns (bins, metadata).

Raises:

ValueError – If edge inputs are inconsistent, the binning specification is invalid, or photo-z model parameters are invalid.

binny.nz_tomo.photoz.true_redshift_distribution(z: ndarray[tuple[Any, ...], dtype[float64]], nz: ndarray[tuple[Any, ...], dtype[float64]], bin_min: float, bin_max: float, scatter_scale: float, mean_offset: float, *, mean_scale: float = 1.0, outlier_frac: float = 0.0, outlier_scatter_scale: float | None = None, outlier_mean_offset: float = 0.0, outlier_mean_scale: float = 1.0) → ndarray[tuple[Any, ...], dtype[float64]]#

Computes the true-redshift distribution for a single photo-z bin.

The photo-z-selected true-redshift distribution is n_bin(z) = n(z) * P(bin | z), where n(z) is the parent distribution and P(bin | z)` is the probability that an object at true redshift ``z falls into the photo-z bin. The probability is modeled with a Gaussian core photo-z relation, with an optional Gaussian outlier component controlled by outlier_frac and the corresponding outlier parameters..

Parameters:

  • z – True-redshift grid.

  • nz – Parent distribution evaluated on z.

  • bin_min – Lower photo-z edge for the bin.

  • bin_max – Upper photo-z edge for the bin.

  • scatter_scale – Core photo-z scatter scale.

  • mean_offset – Core photo-z mean offset.

  • mean_scale – Core photo-z mean scale.

  • outlier_frac – Outlier mixture fraction.

  • outlier_scatter_scale – Outlier scatter scale.

  • outlier_mean_offset – Outlier mean offset.

  • outlier_mean_scale – Outlier mean scale.

Returns:

Photo-z-selected true-redshift distribution evaluated on z.

Raises:

ValueError – If outlier_frac is outside [0, 1], if required outlier parameters are missing, or if any active scale parameter is invalid.