binny.nz_tomo.specz module#

Build spectroscopic-redshift tomographic bins on a common true-z grid.

This module constructs tomographic-bin redshift distributions for true-z (spectroscopic) binning. The main entry point is build_specz_bins(), which returns a mapping from observed-bin index to an observed-bin distribution n_obs_i(z), all evaluated on the same true-redshift grid z.

Selection model#

True bins are defined by edges [z_j, z_{j+1}] and a per-bin completeness factor c_j. The true-bin selection window is

S_j(z) = c_j * 1_{[z_j, z_{j+1})}(z),

and the corresponding true-bin distribution is: n_true_j(z) = n(z) * S_j(z).

Bin-to-bin response (optional)#

Observed bins may differ from true bins due to survey-style response effects. These are represented by a column-stochastic response matrix M with

M[i, j] = P(i_obs | j_true), sum_i M[i, j] = 1 for every true bin j,

which mixes true bins into observed bins via

n_obs_i(z) = sum_j M[i, j] * n_true_j(z).

Two response components are supported:

Catastrophic reassignment (bin-level) A per-bin fraction f_j is redistributed away from the diagonal according to a leakage prescription (uniform, neighbor, or Gaussian in bin-index space). If an explicit response_matrix is provided, it is used directly.
Measurement scatter (optional) A Gaussian measurement model for z_hat | z_true is integrated over observed bin edges to form a response, then averaged within each true bin to obtain a column-stochastic matrix M_scatter.

If both are enabled, the total response is applied as

M_total = M_scatter @ M_cat.

Normalization#

If normalize_input=True (default), the parent distribution n(z) is normalized to integrate to 1 over the grid z before binning.
If normalize_bins=True (default), each returned n_obs_i(z) is normalized to integrate to 1 over z when the bin has nonzero support.

binny.nz_tomo.specz.apply_response_matrix(bins: Mapping[int, ndarray[tuple[Any, ...], dtype[float64]]], matrix: ndarray[tuple[Any, ...], dtype[float64]]) → dict[int, ndarray[tuple[Any, ...], dtype[float64]]]#

Applies a bin-response matrix to a set of tomographic bin distributions.

Treats the input bins as a stacked array with shape (n_bins, ...) and returns the mixed bins obs = M @ true. The response matrix is expected to be column-stochastic and compatible with the number of bins and array shapes.

Parameters:

bins – Mapping from bin index to bin distribution arrays. Must contain exactly keys 0..n_bins-1 and all arrays must share the same shape.
matrix – Response matrix of shape (n_bins, n_bins).

Returns:

Dict mapping observed bin index to the mixed bin distribution.

Raises:

ValueError – If keys/shapes are inconsistent or the matrix is invalid.

binny.nz_tomo.specz.build_specz_bins(z: ndarray[tuple[Any, ...], dtype[float64]], nz: ndarray[tuple[Any, ...], dtype[float64]], bin_edges: ndarray[tuple[Any, ...], dtype[float64]] | None = None, *, binning_scheme: str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None = None, n_bins: int | None = None, bin_range: tuple[float, float] | None = None, completeness: Sequence[float] | float = 1.0, catastrophic_frac: Sequence[float] | float = 0.0, leakage_model: Literal['uniform', 'neighbor', 'gaussian'] = 'neighbor', leakage_sigma: Sequence[float] | float = 1.0, response_matrix: ndarray[tuple[Any, ...], dtype[float64]] | None = None, specz_scatter: Sequence[float] | float | None = None, specz_scatter_model: Literal['sigma0_plus_sigma1_1pz'] = 'sigma0_plus_sigma1_1pz', sigma0: float = 0.0, sigma1: float = 0.0, 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]]#

Build spectroscopic-redshift tomographic bins on a common true-z grid.

Constructs per-bin true-redshift distributions from a parent n(z) using true-redshift bin edges. Optionally applies survey-style bin-response effects that mix true bins into observed bins via a column-stochastic response matrix.

If response effects are enabled, the returned bins correspond to observed bins, each expressed as a distribution on the true-z grid.

Parameters:

z – True-redshift grid where all outputs are evaluated.
nz – Parent true-redshift distribution evaluated on z.
bin_edges – Optional true-redshift bin edges. If provided, binning_scheme and n_bins are ignored.
binning_scheme – Scheme used to derive edges when bin_edges is not provided. May be a simple scheme name or a mixed-segment specification.
n_bins – Number of bins for simple scheme names.
bin_range – Optional interval used when deriving equidistant edges.
completeness – Per-bin completeness factor(s) applied to the true-bin selection (scalar or per-bin sequence).
catastrophic_frac – Per-bin fraction(s) reassigned to other observed bins through the catastrophic response model (scalar or per-bin sequence).
leakage_model – Redistribution rule for catastrophic reassignment.
leakage_sigma – Width parameter for Gaussian leakage in bin-index space.
response_matrix – Optional explicit bin-response matrix overriding the catastrophic leakage model.
specz_scatter – Optional measurement-scatter scale(s) used to build a scatter response matrix (scalar or per-bin sequence).
specz_scatter_model – Scatter parameterization used when specz_scatter is not provided.
sigma0 – Additive scatter component for specz_scatter_model.
sigma1 – Redshift-dependent scatter component for specz_scatter_model.
normalize_input – Whether to normalize the parent nz before binning.
normalize_bins – Whether to normalize each returned bin to integrate to 1 on z when the bin has nonzero support.
norm_method – Integration method used for normalization.
include_metadata – Whether to return a metadata mapping alongside the bins.
save_metadata_path – Optional path where metadata is written in text form.

Returns:

A dict mapping observed bin index to a true-z distribution n_obs_i(z). If include_metadata=True, returns (bins, metadata).

Raises:

ValueError – If edge inputs are inconsistent, response settings are invalid, or any parameter constraints are violated.

binny.nz_tomo.specz.build_specz_response_matrix(n_bins: int, *, catastrophic_frac: Sequence[float] | float = 0.0, leakage_model: Literal['uniform', 'neighbor', 'gaussian'] = 'neighbor', leakage_sigma: Sequence[float] | float = 1.0, response_matrix: ndarray[tuple[Any, ...], dtype[float64]] | None = None) → ndarray[tuple[Any, ...], dtype[float64]]#

Constructs a bin-to-bin response matrix for catastrophic reassignment.

Builds a column-stochastic matrix M with entries M[i, j] = P(i_obs|j_true) that describes reassignment of a fraction of objects in each true bin to other observed bins. If an explicit response_matrix is provided, it is validated and returned directly.

Parameters:

n_bins – Number of tomographic bins.
catastrophic_frac – Per-bin catastrophic fraction(s) in [0, 1].
leakage_model – Redistribution rule for the catastrophic fraction.
leakage_sigma – Width parameter for Gaussian leakage in bin-index space.
response_matrix – Optional explicit response matrix overriding the model.

Returns:

A float array of shape (n_bins, n_bins) that is column-stochastic.

Raises:

ValueError – If inputs are invalid or the resulting matrix fails validation.

binny.nz_tomo.specz.specz_gaussian_response_matrix(*, z_arr: ndarray[tuple[Any, ...], dtype[float64]], bin_edges: ndarray[tuple[Any, ...], dtype[float64]], specz_scatter: Sequence[float] | float | None, model: Literal['sigma0_plus_sigma1_1pz'] = 'sigma0_plus_sigma1_1pz', sigma0: float = 0.0, sigma1: float = 0.0) → ndarray[tuple[Any, ...], dtype[float64]]#

Builds a Gaussian measurement-scatter response matrix for spec-z binning.

Constructs a column-stochastic matrix that maps true bins to observed bins under a Gaussian measurement model for z_hat at fixed true redshift. Probabilities are computed by integrating the Gaussian over observed-bin edges and then averaging within each true bin.

The scatter scale may be provided explicitly per bin, or derived from a simple parameterization controlled by sigma0 and sigma1.

Parameters:

z_arr – True-redshift grid used to evaluate within-bin averaging.
bin_edges – True-redshift bin edges defining both true and observed bins.
specz_scatter – Optional scatter scale(s) (scalar or per-bin sequence).
model – Scatter parameterization used when specz_scatter is None.
sigma0 – Additive scatter component for model.
sigma1 – Redshift-dependent scatter component for model.

Returns:

A float array of shape (n_bins, n_bins) that is column-stochastic.

Raises:

ValueError – If scatter settings are inconsistent or invalid.

binny.nz_tomo.specz.specz_selection_in_bin(z: ndarray[tuple[Any, ...], dtype[float64]], bin_min: float, bin_max: float, completeness: float = 1.0, *, inclusive_right: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Evaluates a true-z bin selection window on a redshift grid.

Returns a top-hat selection function over [bin_min, bin_max) (or [bin_min, bin_max] when inclusive_right=True), scaled by a completeness factor. This selection is multiplied by the parent n(z) to form a true-bin distribution.

Parameters:

z – True-redshift grid.
bin_min – Lower edge of the true-z bin.
bin_max – Upper edge of the true-z bin.
completeness – Multiplicative completeness factor in [0, 1].
inclusive_right – Whether to include bin_max in the selection.

Returns:

Array of selection values on z.

Raises:

ValueError – If completeness is outside [0, 1].