binny.nz.models module#

Module defining various redshift distributions for astronomical sources.

All functions here return shapes by default (unnormalized). If normalize=True, the returned curve is normalized to integrate to 1 over the provided redshift grid z using binny.utils.normalization.normalize_over_z().

Notes

  • Normalization requires a 1D, strictly increasing z grid with at least two points.

  • Passing a scalar z with normalize=True will raise.

binny.nz.models.gamma_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], k: float, theta: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a gamma-shaped redshift distribution.

This function defines an unnormalized gamma-shaped distribution:

n(z) = z^(k-1) * exp(-z/theta)    for z >= 0
n(z) = 0                         for z < 0
Parameters:

  • z – Redshift or array of redshifts.

  • k – Shape parameter (must be positive).

  • theta – Scale parameter (must be positive).

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Gamma-shaped distribution evaluated at z (normalized if requested).

Raises:

ValueError – If k or theta is not positive.

binny.nz.models.gaussian_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], mu: float, sigma: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a Gaussian redshift distribution.

This function defines an unnormalized Gaussian shape:

n(z) = exp[-0.5 * ((z - mu) / sigma)^2]
Parameters:

  • z – Redshift or array of redshifts.

  • mu – Mean redshift.

  • sigma – Standard deviation (must be positive).

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Gaussian evaluated at z (normalized if requested).

Raises:

ValueError – If sigma is not positive.

binny.nz.models.gaussian_mixture_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], mus: ndarray[tuple[Any, ...], dtype[float64]], sigmas: ndarray[tuple[Any, ...], dtype[float64]], weights: ndarray[tuple[Any, ...], dtype[float64]] | None = None, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a Gaussian mixture redshift distribution.

This function defines an unnormalized Gaussian mixture shape:

n(z) = sum_{i=1}^K w_i * exp[-0.5 * ((z - mu_i) / sigma_i)^2]
Parameters:

  • z – Redshift or array of redshifts.

  • mus – Array of component means, shape (K,).

  • sigmas – Array of component std devs, shape (K,). Must be positive.

  • weights – Optional nonnegative weights, shape (K,). If None, equal weights are used. Weights do not need to sum to 1.

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Gaussian mixture evaluated at z (normalized if requested).

Raises:

ValueError – If shapes mismatch, any sigma is non-positive, or any weight is negative.

binny.nz.models.lognormal_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], mu_ln: float, sigma_ln: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a lognormal redshift distribution.

This function defines an unnormalized lognormal shape:

n(z) approx (1/z) * exp[- (ln z - mu_ln)^2 / (2 sigma_ln^2)]  for z > 0
n(z) = 0  for z <= 0
Parameters:

  • z – Redshift or array of redshifts.

  • mu_ln – Mean of ln(z).

  • sigma_ln – Std dev of ln(z) (must be positive).

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Lognormal shape evaluated at z (normalized if requested).

Raises:

ValueError – If sigma_ln is not positive.

binny.nz.models.schechter_like_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], z0: float, alpha: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a Schechter-like redshift distribution.

This function defines an unnormalized Schechter-like shape:

n(z) = (z / z0)^alpha * exp(-(z / z0))

This is equivalent to a Smail-like form with beta = 1.

Parameters:

  • z – Redshift or array of redshifts.

  • z0 – Characteristic redshift scale (must be positive).

  • alpha – Power-law index.

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Schechter-like distribution evaluated at z.

Raises:

ValueError – If z0 is not positive.

binny.nz.models.shifted_smail_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], z0: float, alpha: float, beta: float, z_shift: float = 0.0, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a shifted Smail-type redshift distribution.

This function defines a shifted Smail-like shape:

n(z) = ((z - z_shift)/z0)^alpha * exp(-((z - z_shift)/z0)^beta)  for z >= z_shift
n(z) = 0                                                        for z < z_shift
Parameters:

  • z – Redshift or array of redshifts.

  • z0 – Characteristic redshift scale (must be positive).

  • alpha – Power-law index for low redshifts.

  • beta – Exponential cutoff index for high redshifts.

  • z_shift – Shift applied to redshift (domain cutoff at z_shift).

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Shifted Smail-like distribution evaluated at z.

Raises:

ValueError – If z0 is not positive.

binny.nz.models.skew_normal_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], xi: float, omega: float, alpha: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a skew-normal-like redshift distribution.

This function defines an unnormalized skew-normal-like shape:

n(z) = exp[-0.5 * ((z - xi) / omega)^2] * Phi(alpha * (z - xi) / omega)

where Phi is the standard normal CDF approximated via tanh. Parameters are xi (location), omega > 0 (scale), and alpha (shape/skewness).

Parameters:

  • z – Redshift or array of redshifts.

  • xi – Location parameter.

  • omega – Scale parameter (must be positive).

  • alpha – Shape (skewness) parameter.

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Skew-normal-like shape evaluated at z (normalized if requested).

Raises:

ValueError – If omega is not positive.

binny.nz.models.smail_like_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], z0: float, alpha: float, beta: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a Smail-type redshift distribution.

This function defines an unnormalized Smail-like shape often used to model galaxy redshift distributions in weak lensing studies:

n(z) = (z / z0)^alpha * exp[-(z / z0)^beta]
Parameters:

  • z – Redshift or array of redshifts.

  • z0 – Characteristic redshift scale (must be positive).

  • alpha – Power-law index for low redshifts.

  • beta – Exponential cutoff index for high redshifts.

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Smail-like distribution evaluated at z (normalized if requested).

Raises:

ValueError – If z0 is not positive.

binny.nz.models.student_t_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], mu: float, sigma: float, nu: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a Student-t redshift distribution.

This function defines an unnormalized Student-t shape:

n(z) = [1 + ((z - mu) / sigma)^2 / nu]^(-(nu + 1) / 2)

with parameters mu (location), sigma > 0 (scale), and nu > 0 (degrees of freedom).

Parameters:

  • z – Redshift or array of redshifts.

  • mu – Location parameter.

  • sigma – Scale parameter (must be positive).

  • nu – Degrees of freedom (must be positive).

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Student-t shape evaluated at z (normalized if requested).

Raises:

ValueError – If sigma or nu is not positive.

binny.nz.models.tophat_distribution(z: float | ndarray[tuple[Any, ...], dtype[float64]], zmin: float, zmax: float, *, normalize: bool = False) → ndarray[tuple[Any, ...], dtype[float64]]#

Returns a tophat (uniform) redshift distribution.

This function defines a top-hat (uniform) distribution:

n(z) = 1    for zmin <= z <= zmax
n(z) = 0    otherwise
Parameters:

  • z – Redshift or array of redshifts.

  • zmin – Lower edge.

  • zmax – Upper edge (must be greater than zmin).

  • normalize – If True, normalizes the curve to have integral 1 over z.

Returns:

Tophat evaluated at z (normalized if requested).

Raises:

ValueError – If zmax <= zmin.