binny.api.nz_tomography module#

Tools for building tomographic redshift bins.

This module provides a simple interface for constructing tomographic redshift bins using either photometric or spectroscopic redshifts. Bins can be built from survey presets, configuration mappings, or directly from user-supplied redshift distributions.

Once bins are built, the results are kept internally so that related quantities such as population statistics or bin-to-bin comparisons can be computed without repeating the setup.

class binny.api.nz_tomography.NZTomography#

Bases: object

Builds and caches tomographic n(z) bins with a small public API.

An instance caches the most recent parent distribution (z, nz), the tomography settings used to build the bins, the constructed bin curves, and optional metadata. This lets follow-up calls (stats, comparisons, combo filtering) reuse the same build without re-parsing inputs.

Initialize an empty cache.

between_sample_stats(other: NZTomography, *, overlap: Mapping[str, Any] | None = None, pairs: Mapping[str, Any] | None = None, interval_mass: Mapping[str, Any] | None = None, pearson: Mapping[str, Any] | None = None) → dict[str, Any]#

Compute a bundle of between-sample comparison and diagnostic matrices.

This returns quantitative comparisons between bins from two different tomographic samples, such as lens and source bins used in galaxy-galaxy lensing. The returned quantities can be used to assess overlap, similarity, ordering, and interval-based contamination across sample families.

Parameters:

other – Second tomography instance to compare against. Both instances must be built on the same redshift grid.
overlap – Keyword arguments for between-sample overlap metrics, or None to skip.
pairs – Keyword arguments for between-sample pair summaries, or None to skip.
interval_mass – Keyword arguments for interval-mass computation, or None to skip. Must include "target_edges".
pearson – Keyword arguments for between-sample Pearson correlation computation, or None to skip.

Returns:

A dictionary containing a subset of keys "overlap", "correlations", "interval_mass", and "pearson".

Raises:

ValueError – If bins are not cached, if the two instances do not share the same redshift grid, or if interval-mass computation is requested without providing target_edges.

bin_combo_filter(spec: Mapping[str, Any], other: NZTomography | None = None) → list[tuple[int, ...]]#

Select bin-index combinations using a combo-filter specification.

This is a high-level entry point for “give me the bin pairs/tuples that satisfy these criteria.” It constructs a BinComboFilter on the cached bins (optionally using a second tomography instance for cross-sample comparisons), applies the provided selection spec, and returns the resulting index tuples.

Parameters:

spec – Selection specification for topology + ordered filters.
other – Optional second tomography instance for cross-sample selections.

Returns:

A list of index tuples representing the selected bin combinations.

Raises:

ValueError – If bins are not cached, or if cross-sample filtering is requested but the two instances do not share the same redshift grid.
KeyError – If the selection spec references an unknown topology, filter, or metric kernel.
TypeError – If the selection spec has an unexpected structure.

property bin_keys: list[int]#

Bin indices for the most recent build, in mapping insertion order.

Returns:: List of integer bin indices in the same order they appear in bins.
Raises:: ValueError – If bins have not been built yet (call build_bins()).

property bins: Mapping[int, ndarray]#

Mapping of bin index to bin curve from the most recent build.

Returns:: Mapping from integer bin index to the corresponding bin n(z) array.
Raises:: ValueError – If bins have not been built yet (call build_bins()).

Builds tomographic bins from a config, mapping, or explicit arrays.

Given either a survey configuration or direct (z, nz) arrays, this method constructs the corresponding tomographic bins and returns the resulting bin distributions along with the relevant inputs.

Exactly one of the following input modes must be used: - config_file=... (optionally with key=...), - cfg=... (an in-memory config mapping), - (z=..., nz=..., tomo_spec=...) (explicit arrays plus a spec mapping).

Parameters:

config_file – Path to a YAML config file. If provided, the tomography entry is selected from the file (optionally using key).
cfg – In-memory config mapping using the same schema as the YAML files.
z – True-redshift grid. Used only in the explicit arrays mode.
nz – Parent distribution evaluated on z. Used only in the explicit arrays mode.
tomo_spec – Tomography specification mapping for the explicit arrays mode.
key – Optional entry key when selecting an item from a config file.
role – Optional selector for a tomography entry (e.g., “lens” or “source”).
year – Optional selector for a tomography entry (e.g., “1”, “10”).
kind – Optional tomography kind override (“photoz” or “specz”).
overrides – Optional mapping of values merged into the resolved tomography spec. Nested mappings are merged shallowly at the first level.
include_survey_metadata – Whether to include survey-level metadata in the output when building from a config file or mapping.
include_tomo_metadata – Whether to request tomography metadata from the builder.

Returns:

A TomographyBins object containing the true-redshift grid, parent distribution, resolved tomography spec, constructed bins, and optional tomography and survey metadata.

Raises:

ValueError – If inputs are inconsistent, no unique entry can be selected, the tomography spec is invalid, or the requested kind is unsupported.

Builds tomographic bins from a built-in survey preset.

This method loads the configuration for a given survey preset, builds the corresponding tomographic bins, and returns the resulting bin distributions.

Parameters:

survey – Survey preset name (case-insensitive), resolved to a shipped YAML file.
role – Optional selector for a tomography entry (e.g., “lens” or “source”).
year – Optional selector for a tomography entry (e.g., “1”, “10”).
z – Optional override for the config-defined redshift grid.
overrides – Optional mapping merged into the resolved tomography spec.
include_survey_metadata – Whether to include survey-level metadata in the output.
include_tomo_metadata – Whether to include tomography metadata in the output.
config_file – Optional explicit path to a survey-spec YAML file. If provided, it is used instead of resolving a shipped preset.

Returns:

A TomographyBins object, which provides convenience methods such as shape_stats() and population_stats().

Raises:

FileNotFoundError – If the requested preset name does not resolve to a shipped file.
ValueError – If the selected entry is invalid or required metadata is unavailable.

static calibrate_smail_from_mock(z_true: ndarray, mag: ndarray, *, maglims: ndarray, area_deg2: float, 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.
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.

clear() → None#: Clears the cached parent distribution, spec, bins, and metadata.

cross_bin_stats(*, overlap: Mapping[str, Any] | None = None, pairs: Mapping[str, Any] | None = None, leakage: Mapping[str, Any] | None = None, pearson: Mapping[str, Any] | None = None) → dict[str, Any]#

Compute a bundle of cross-bin similarity and diagnostic matrices.

This returns quantitative comparisons between tomographic bins, such as how much two bins overlap in redshift, how strongly their shapes co-vary, and (optionally) how much probability mass leaks across a set of bin edges.

Parameters:

overlap – Keyword arguments for overlap metrics, or None to skip.
pairs – Keyword arguments for pairwise overlap summaries, or None to skip.
leakage – Keyword arguments for leakage matrix computation. Must include "bin_edges" (the bin edges corresponding to the bins), or None to skip.
pearson – Keyword arguments for Pearson correlation computation, or None to skip.

Returns:

A dictionary containing a subset of keys "overlap", "correlations", "leakage", and "pearson".

Raises:

ValueError – If bins are not cached, or if leakage is requested without providing bin_edges.

static list_nz_models() → list[str]#

Lists available registered n(z) model names.

Returns the set of model identifiers currently registered with the n(z) registry. This is useful for discovery and for validating configuration inputs.

Returns:: A sorted list of registered n(z) model names.

static list_surveys() → list[str]#

List available shipped survey preset names.

Survey presets are YAML configuration files shipped with the package, following the naming convention <preset>_survey_specs.yaml. This method returns the available preset base names (without the suffix), suitable for passing to build_survey_bins().

Returns:: A sorted list of available survey preset base names.

property nz: ndarray#

Parent n(z) from the most recent build.

Returns:: The cached parent distribution evaluated on z.
Raises:: ValueError – If no build has been performed yet.

static nz_model(name: str, z: Any, /, **params: Any) → ndarray#

Computes a registered parent n(z) model on a redshift grid.

This is a convenience wrapper around the n(z) registry. It computes the named model on the provided redshift grid and returns the resulting array.

Parameters:

name – Name of a registered n(z) model.
z – Redshift grid (array-like) to compute the model on.
**params – Model-specific parameters passed to the registered implementation.

Returns:

Model values on z.

Raises:

ValueError – If the model name is unknown or the provided parameters are invalid for the requested model.

population_stats(**kwargs: Any) → dict[str, Any]#

Compute population statistics for the cached bins.

Population statistics describe how galaxies are distributed across bins, including quantities related to bin occupancy and normalization relative to the parent redshift distribution.

Parameters:: **kwargs – Additional keyword arguments forwarded to the underlying stats function.
Returns:: A dictionary of population statistics computed from the cached bins and cached tomography metadata.
Raises:: ValueError – If bins have not been built, or if tomography metadata is not available (rebuild with include_tomo_metadata=True).

shape_stats(**kwargs: Any) → dict[str, Any]#

Computes shape statistics for the cached bins.

Shape statistics summarize the structure of each bin’s redshift distribution (e.g. bin moments, centers, etc.) using the parent redshift grid and the most recently built bins.

Parameters:: **kwargs – Additional keyword arguments forwarded to the underlying stats function.
Returns:: A dictionary of shape statistics computed from the cached bins.
Raises:: ValueError – If bins have not been built yet.

property z: ndarray#

True-redshift grid from the most recent build.

Returns:: The cached redshift grid used to build the parent n(z) and bins.
Raises:: ValueError – If no build has been performed yet.

binny.api.nz_tomography.available_metric_kernels() → list[str]#: List registered metric-kernel names for combo-filter specs.

binny.api.nz_tomography.register_metric_kernel(name: str, func: Callable[[...], float]) → None#

The name is referenced in selection specs via:

{"name": "metric", "metric": "<name>", "threshold": ..., "compare": ...}

Parameters:

name – Kernel identifier used in selection specs.
func – Callable that receives one curve per slot and returns a float.

Raises:

ValueError – If name is already registered.