binny.nz_tomo.bin_stats module#

Basic statistics of binned redshift distributions.

This module provides two families of diagnostics for tomographic bin curves:

  • Shape statistics: summaries that depend only on the shape of each bin curve (moments, quantiles, peaks, centers, in-range fractions). These are safe to compute even when each bin curve is individually normalized.

  • Population statistics: quantities that depend on relative bin populations (fractions, optional surface densities and counts). In Binny, these should be taken from tomographic-builder metadata (photo-z / spec-z), not inferred from normalized bin curves.

The public entry points are shape_stats() and population_stats().

binny.nz_tomo.bin_stats.bin_centers(z: Any, bins: Mapping[int, Any], *, method: str = 'mean', decimal_places: int | None = 2) → dict[int, float]#

Compute one center value per tomographic bin.

Supported methods:

  • "mean": weighted mean redshift.

  • "median": weighted median redshift.

  • "mode": grid-point mode.

  • "pXX": weighted percentile, where XX is between 0 and 100

    (e.g. "p50").

Parameters:

  • z – One-dimensional redshift grid shared by all bins.

  • bins – Mapping from bin index to bin curves evaluated on z.

  • method – Center definition.

  • decimal_places – If not None, round each returned center to this many decimal places. If None, return full-precision floats.

Returns:

Mapping from bin index to the chosen center value.

Raises:

  • ValueError – If method is invalid.

  • ValueError – If any bin has non-positive total weight when needed.

binny.nz_tomo.bin_stats.bin_moments(z: Any, nz_bin: Any) → dict[str, float]#

Compute standard shape summaries for a single bin curve.

The input is a redshift grid z and a corresponding bin curve nz_bin evaluated on that grid. The curve is treated as a nonnegative weight function; it does not need to be normalized.

Returned keys:

  • "mean": weighted mean redshift.

  • "median": weighted median redshift.

  • "mode": redshift value on the input grid where nz_bin is maximal.

  • "std": weighted standard deviation.

  • "skewness": standardized third central moment (dimensionless).

  • "kurtosis": standardized fourth central moment minus 3 (dimensionless).

  • "iqr": interquartile range (q75 - q25).

  • "width_68": central 68% interval width (q84 - q16).

Notes

  • Percentile-based summaries depend on the sampling of the grid.

  • The mode is grid-dependent by definition.

Parameters:

  • z – One-dimensional redshift grid.

  • nz_bin – Bin curve values evaluated on z.

Returns:

Dictionary of summary statistics.

Raises:

ValueError – If the total weight (integral of nz_bin) is not positive.

binny.nz_tomo.bin_stats.bin_quantiles(z: Any, nz_bin: Any, qs: Sequence[float]) → dict[float, float]#

Compute weighted quantiles of a single bin curve.

The curve nz_bin is treated as a nonnegative weight curve evaluated on z. For each requested quantile q in [0, 1], this returns the redshift value where the cumulative integral reaches q of the total weight.

Parameters:

  • z – One-dimensional redshift grid.

  • nz_bin – Bin curve values evaluated on z.

  • qs – Quantiles to compute, as fractions between 0 and 1.

Returns:

Mapping from each requested quantile to the corresponding redshift value.

Raises:

  • ValueError – If any q is outside [0, 1].

  • ValueError – If the total weight is not positive.

binny.nz_tomo.bin_stats.comoving_density_per_bin(total_count_per_bin: Mapping[int, float], volume_per_bin: Mapping[int, float]) → dict[int, float]#

Compute per-bin comoving number densities from counts and volumes.

binny.nz_tomo.bin_stats.galaxy_count_per_bin(density_per_bin: Mapping[int, float], survey_area: float) → dict[int, float]#

Convert per-bin surface densities to effective counts using a survey area.

Conventions:

  • density_per_bin values are in galaxies per square arcminute.

  • survey_area is in square arcminutes.

  • returned counts are dimensionless effective counts.

Parameters:

  • density_per_bin – Mapping from bin index to surface density (gal/arcmin^2).

  • survey_area – Survey area (arcmin^2).

Returns:

Mapping from bin index to effective counts.

Raises:

  • ValueError – If survey_area is not positive.

  • ValueError – If any density is negative.

binny.nz_tomo.bin_stats.galaxy_density_per_bin(metadata: Mapping[str, Any], density_total: float) → dict[int, float]#

Computes per-bin surface densities from tomo metadata and total effective density..

Parameters:

  • metadata – Tomography metadata containing "frac_per_bin".

  • density_total – Total effective surface density (gal/arcmin^2).

Returns:

gal/arcmin^2}.

Return type:

Mapping {bin_idx

Raises:

  • ValueError – If density_total is negative.

  • ValueError – If metadata does not contain valid fractions.

binny.nz_tomo.bin_stats.galaxy_fraction_per_bin(meta: Mapping[str, Any]) → dict[int, float]#

Extract and normalize per-bin population fractions from tomo metadata.

binny.nz_tomo.bin_stats.in_range_fraction(z: Any, nz_bin: Any, z_min: float, z_max: float) → float#

Compute the fraction of a bin curve contained in a redshift range.

This integrates nz_bin over the full grid and over [z_min, z_max] and returns inside / total.

Parameters:

  • z – One-dimensional redshift grid.

  • nz_bin – Bin curve values evaluated on z.

  • z_min – Lower bound of the range.

  • z_max – Upper bound of the range.

Returns:

Fraction of the total bin weight contained in [z_min, z_max].

Raises:

  • ValueError – If z_max <= z_min.

  • ValueError – If the total weight is not positive.

binny.nz_tomo.bin_stats.in_range_fraction_per_bin(z: Any, bins: Mapping[int, Any], bin_edges: Mapping[int, tuple[float, float]] | Sequence[float]) → dict[int, float]#

Compute the in-range fraction for each bin given nominal edges.

bin_edges can be either:

  • mapping {bin_idx: (z_min, z_max)}, or

  • a sequence of edges [e0, e1, ..., eN] where bin i uses [e_i, e_{i+1}].

Parameters:

  • z – One-dimensional redshift grid shared by all bins.

  • bins – Mapping from bin index to bin curves evaluated on z.

  • bin_edges – Nominal edges mapping or edge sequence.

Returns:

Mapping from bin index to fraction of its weight inside its nominal range.

Raises:

ValueError – If required edges are missing or malformed.

binny.nz_tomo.bin_stats.parent_stats(z: Any, nz: Any, *, decimal_places: int | None = 2, quantiles: Sequence[float] = (0.16, 0.5, 0.84), min_rel_height: float = 0.1) → dict[str, Any]#

Compute shape statistics for the parent redshift distribution.

This function summarizes the shape of the parent n(z), independently of its tomographic binning. The distribution is treated as a nonnegative weight function and does not need to be normalized.

The returned statistics include moments, weighted quantiles, and peak diagnostics. All quantities are computed directly from the supplied parent distribution rather than reconstructed from tomographic bins.

Parameters:

  • z – One-dimensional redshift grid.

  • nz – Parent redshift distribution evaluated on z.

  • decimal_places – Number of decimal places used to round returned statistics. If None, return full-precision values.

  • quantiles – Quantiles to compute, expressed as fractions in [0, 1].

  • min_rel_height – Minimum relative peak height used to identify significant local maxima.

Returns:

  • "moments": Mean, median, mode, standard deviation, skewness, excess kurtosis, interquartile range, and central 68% interval width.

  • "quantiles": Mapping from requested quantiles to redshift values.

  • "peaks": Global mode, mode height, number of significant peaks, and second-highest peak ratio.

Return type:

Dictionary containing the following statistics

Raises:

ValueError – If the redshift grid or distribution is invalid, the total weight is not positive, or a requested quantile is outside [0, 1].

binny.nz_tomo.bin_stats.peak_flags(z: Any, nz_bin: Any, *, min_rel_height: float = 0.1) → dict[str, float | None]#

Compute simple peak diagnostics for a single bin curve.

A point is treated as a peak if it is greater than its immediate neighbors. Peaks below min_rel_height * global_max are ignored.

Returned keys:

  • "mode": redshift of the global maximum on the grid.

  • "mode_height": curve value at the mode.

  • "num_peaks": number of detected peaks passing the height cut.

  • "second_peak_ratio": second-highest peak height divided by the highest (None if no second peak).

binny.nz_tomo.bin_stats.peak_flags_per_bin(z: Any, bins: Mapping[int, Any], *, min_rel_height: float = 0.1) → dict[int, dict[str, float | None]]#

Compute peak diagnostics for each bin curve.

binny.nz_tomo.bin_stats.population_stats(bins: Mapping[int, Any], metadata: Mapping[str, Any], *, density_total: float | None = None, survey_area: float | None = None, normalize_frac: bool = True, rtol: float = 0.01, atol: float = 0.001, total_count_per_bin: Mapping[int, float] | None = None, volume_per_bin: Mapping[int, float] | None = None, decimal_places: int | None = 2) → dict[str, Any]#

Compute population / normalization statistics for tomographic bins.

This function computes quantities that depend on relative bin populations, using metadata produced by Binny’s tomo builders.

The primary input is metadata["frac_per_bin"] (mapping bin index to fraction). Fractions are checked against the bin indices present in bins.

Optional allocations:

  • If density_total is provided, return per-bin allocated surface densities in galaxies per square arcminute.

  • If survey_area is also provided, return effective counts using the surface density and survey area in square arcminutes.

  • If total_count_per_bin and volume_per_bin are provided, return per-bin comoving densities computed as count divided by volume.

Parameters:

  • bins – Mapping from bin index to bin curves.

  • metadata – Tomography metadata containing "frac_per_bin".

  • density_total – Optional total effective surface density in galaxies per square arcminute.

  • survey_area – Optional survey area in square arcminutes. Requires density_total.

  • normalize_frac – If True, renormalize metadata fractions to sum to 1. If False, require they sum to 1 within rtol and atol.

  • rtol – Relative tolerance for sum-to-one checks when normalize_frac=False.

  • atol – Absolute tolerance for sum-to-one checks when normalize_frac=False.

  • total_count_per_bin – Optional mapping from bin index to total galaxy count in that bin.

  • volume_per_bin – Optional mapping from bin index to comoving volume in that bin.

  • decimal_places – Rounding precision for returned values.

Returns:

Mapping with key "fractions" and, when requested, surface-density fields, count fields, or comoving-density fields. Comoving densities are returned under "density_per_bin" with "density_unit" set to "h^3 Mpc^-3".

Raises:

  • ValueError – If bins is empty.

  • ValueError – If metadata does not contain "frac_per_bin".

  • ValueError – If metadata fractions are missing any bin index.

  • ValueError – If survey_area is provided without density_total.

  • ValueError – If only one of total_count_per_bin and volume_per_bin is provided.

  • ValueError – If any requested comoving volume is non-positive.

  • ValueError – If fractions cannot be normalized or validated.

binny.nz_tomo.bin_stats.shape_stats(z: Any, bins: Mapping[int, Any], *, center_method: str = 'mean', decimal_places: int | None = 2, quantiles: Sequence[float] = (0.16, 0.5, 0.84), min_rel_height: float = 0.1, bin_edges: Mapping[int, tuple[float, float]] | Sequence[float] | None = None) → dict[str, Any]#

Compute shape-only summary statistics for tomographic bin curves.

This function computes redshift-shape diagnostics that depend only on the per-bin curve shapes, not on relative bin populations. It is safe to call on individually normalized bin PDFs.

Per bin, it returns:

Optionally, if bin_edges are supplied, it also returns the fraction of each bin curve contained within its nominal redshift range via in_range_fraction_per_bin().

Parameters:

  • z – One-dimensional redshift grid shared by all bins.

  • bins – Mapping from bin index to bin curves evaluated on z.

  • center_method – Center definition (“mean”, “median”, “mode”, or “pXX”).

  • decimal_places – If not None, round centers to this many decimal places.

  • quantiles – Quantiles to compute per bin (fractions in [0, 1]).

  • min_rel_height – Peak height threshold relative to the global maximum.

  • bin_edges – Optional nominal edges for in-range fractions.

Returns:

  • "centers": {bin_idx: center}

  • "peaks": {bin_idx: peak_flags_dict}

  • "per_bin": {bin_idx: {“moments”: …, “center”: …,

    ”quantiles”: …, “peaks”: …}}

  • "in_range_fraction": {bin_idx: fraction} if bin_edges

    is not None

Return type:

Nested mapping with keys

Raises:

  • ValueError – If bins is empty.

  • ValueError – If any bin has non-positive total weight.

  • ValueError – If center_method is invalid.

  • ValueError – If quantiles are outside [0, 1].

  • ValueError – If bin_edges are malformed when provided.