binny.nz.calibration module#

Calibration tools for magnitude-limited galaxy redshift distributions.

This module provides utilities for calibrating the parameters of the Smail redshift distribution and related survey scaling relations from mock or simulated galaxy catalogs.

The main goal is to derive empirical mappings between survey depth (limiting magnitude) and the statistical properties of a galaxy sample, including:

  • the parameters of the Smail redshift distribution

  • the evolution of the redshift scale parameter with magnitude limit

  • the number density of galaxies as a function of survey depth

These calibration routines allow realistic survey specifications to be derived directly from simulated catalogs rather than adopting fixed parametric assumptions. The resulting fits can then be used to generate analytic redshift distributions and galaxy densities for forecasting and survey design studies.

binny.nz.calibration.calibrate_depth_smail_from_mock(z_true: ndarray, mag: ndarray, *, maglims: ndarray, area_deg2: float, weights: ndarray | None = None, infer_alpha_beta_from: Literal['deep_cut', 'all_selected_at_maglim'] = 'deep_cut', alpha_beta_maglim: float | None = None, z_max: float | None = None) → dict[str, Any]#

Run an end-to-end calibration of survey depth scaling relations.

This routine performs a complete calibration of the relations linking survey limiting magnitude to both the redshift distribution and the galaxy number density of a sample.

The procedure estimates the shape parameters of the Smail redshift distribution from a representative galaxy sample, calibrates how the redshift scale parameter varies with magnitude limit, and measures the corresponding galaxy number density.

The resulting calibration can be used to construct realistic analytic redshift distributions and galaxy densities for survey forecasts.

Parameters:

  • z_true – True redshifts of galaxies in the mock catalog.

  • mag – Apparent magnitudes of the same galaxies.

  • maglims – Limiting magnitudes defining magnitude-limited samples.

  • area_deg2 – Survey area of the mock catalog in square degrees.

  • weights – Optional non-negative weights for fitting the Smail redshift distribution.

  • infer_alpha_beta_from – Strategy used to determine the shape parameters of the Smail distribution.

  • alpha_beta_maglim – Magnitude limit defining the deep sample used to infer the Smail shape parameters.

  • z_max – Maximum redshift included when fitting redshift distributions.

Returns:

Dictionary containing the calibrated Smail parameters, the fitted z0–magnitude relation, and the galaxy density calibration.

binny.nz.calibration.eval_ngal_of_maglim(maglim: ndarray, fit: dict[str, Any]) → ndarray#

Evaluate the calibrated galaxy density–magnitude relation.

This function computes the predicted galaxy number density for a set of magnitude limits using a previously calibrated density relation.

Parameters:

  • maglim – Limiting magnitudes at which the density should be evaluated.

  • fit – Calibration result describing the fitted galaxy density relation.

Returns:

Predicted galaxy number densities in galaxies per arcmin².

binny.nz.calibration.eval_z0_of_maglim(maglim: ndarray, fit: dict[str, Any]) → ndarray#

Evaluate the calibrated z0–magnitude relation.

This function computes the characteristic Smail redshift scale for one or more magnitude limits using a previously calibrated z0–magnitude relation.

Parameters:

  • maglim – Limiting magnitudes at which the relation should be evaluated.

  • fit – Calibration result describing the fitted z0–magnitude relation.

Returns:

Predicted z0 values corresponding to the input magnitude limits.

binny.nz.calibration.fit_ngal_of_maglim_from_mock(mag: ndarray, *, maglims: ndarray, area_deg2: float, ngal_law: Literal['linear', 'loglinear'] = 'loglinear') → dict[str, Any]#

Calibrate the galaxy number density as a function of survey depth.

This function measures the number density of galaxies in a mock catalog for a series of magnitude limits and fits a smooth empirical relation between survey depth and galaxy density.

The resulting relation can be used to predict the effective galaxy density expected for different magnitude limits in survey forecasts.

Parameters:

  • mag – Apparent magnitudes of galaxies in the mock catalog.

  • maglims – Limiting magnitudes used to define magnitude-limited samples.

  • area_deg2 – Survey area of the mock catalog in square degrees.

  • ngal_law – Functional form used to model the density–magnitude relation.

Returns:

Dictionary containing measured galaxy densities at each magnitude limit and the parameters of the fitted density relation.

binny.nz.calibration.fit_smail_params_from_mock(z_samples: ndarray, *, weights: ndarray | None = None, alpha_bounds: tuple[float, float] = (0.2, 8.0), beta_bounds: tuple[float, float] = (0.2, 6.0), z0_bounds: tuple[float, float] = (0.01, 5.0), x0: tuple[float, float, float] | None = None, z_max: float | None = None, min_n: int = 200) → dict[str, Any]#

Infer Smail distribution parameters from a mock redshift sample.

This function estimates the Smail parameters alpha, beta, and z0 from galaxy redshifts. Optional weights can be used to represent weighted selections, such as PSF-dependent shear-selection weights.

Parameters:

  • z_samples – Galaxy redshifts drawn from a mock or simulated catalog.

  • weights – Optional non-negative weights for the redshift samples.

  • alpha_bounds – Allowed range for the alpha parameter.

  • beta_bounds – Allowed range for the beta parameter.

  • z0_bounds – Allowed range for the z0 parameter.

  • x0 – Initial parameter guess (alpha, beta, z0).

  • z_max – Maximum redshift used when fitting the distribution.

  • min_n – Minimum number of valid redshift samples required to perform the fit.

Returns:

Dictionary containing the fitted parameters, fit status, and summary information about the calibration sample.

Raises:

  • RuntimeError – If SciPy optimization is unavailable.

  • ValueError – If weights does not have the same shape as z_samples.

binny.nz.calibration.fit_z0_of_maglim_from_mock(z_true: ndarray, mag: ndarray, *, maglims: ndarray, alpha: float, beta: float, weights: ndarray | None = None, z0_law: Literal['linear', 'poly2'] = 'linear', z0_bounds: tuple[float, float] = (0.01, 5.0), z_max: float | None = None, min_n_per_cut: int = 200) → dict[str, Any]#

Calibrate the relation between survey depth and the Smail scale parameter.

This function measures how the characteristic redshift scale (z0) of a galaxy population evolves with survey limiting magnitude. For each magnitude limit, galaxies are selected from a mock catalog and the corresponding redshift distribution is fitted with a Smail model with fixed shape parameters.

The resulting z0 measurements are then used to fit a smooth empirical relation between the magnitude limit and the redshift scale.

Parameters:

  • z_true – True redshifts of galaxies in the mock catalog.

  • mag – Apparent magnitudes of galaxies in the same catalog.

  • maglims – Limiting magnitudes at which the calibration should be evaluated.

  • alpha – Fixed alpha parameter of the Smail distribution.

  • beta – Fixed beta parameter of the Smail distribution.

  • weights – Optional non-negative weights for the redshift samples.

  • z0_law – Functional form used to model the z0–magnitude relation.

  • z0_bounds – Allowed range for the fitted z0 values.

  • z_max – Maximum redshift considered when fitting the distribution.

  • min_n_per_cut – Minimum number of galaxies required for a magnitude selection to be included in the calibration.

Returns:

Dictionary containing the measured z0 values at each magnitude limit and the parameters of the fitted z0–magnitude relation.