binny.utils.metadata module#

Metadata utilities.

binny.utils.metadata.build_tomo_bins_metadata(*, kind: Literal['photoz', 'specz'], z: Any, parent_nz: Any, bin_edges: Any, bins_returned: Mapping[int, Any], inputs: Mapping[str, Any], parent_norm: float | None = None, bins_norms: Mapping[int, float] | None = None, frac_per_bin: Mapping[int, float] | None = None, density_per_bin: Mapping[int, float] | None = None, count_per_bin: Mapping[int, float] | None = None, notes: Mapping[str, Any] | None = None) → dict[str, Any]#

Builds metadata for tomographic redshift-bin products.

This function packages tomographic bin outputs into a self-describing, serializable dictionary that can be saved alongside generated bin curves. It records the redshift grid, the parent distribution, the bin definition, the returned per-bin curves, and any optional population summaries supplied by the caller.

The function is intentionally non-opinionated: it does not compute normalization constants, per-bin fractions, number densities, or counts. Callers that need population summaries should compute them under their own conventions and pass them in explicitly.

Parameters:

  • kind – Tomography mode label. Supported values are "photoz" and "specz".

  • z – Redshift grid shared by the parent distribution and all bin curves.

  • parent_nz – Parent redshift distribution evaluated on z. This may be normalized or unnormalized.

  • bin_edges – Bin edges that define the tomographic selection (edge convention is controlled by the caller).

  • bins_returned – Mapping from bin index to the per-bin curve n_i(z) evaluated on z. These curves may be normalized per bin or may carry population information, depending on the caller.

  • inputs – User-facing configuration that fully specifies how the bins were generated (e.g., binning scheme, scatter model parameters, completeness, leakage settings).

  • parent_norm – Optional scalar associated with the parent distribution under the caller’s convention (for example, the integral of the unnormalized parent curve on z).

  • bins_norms – Optional mapping from bin index to a population-carrying scalar under the caller’s convention (for example, integrals of raw bin curves).

  • frac_per_bin – Optional mapping from bin index to population fraction.

  • density_per_bin – Optional mapping from bin index to number density.

  • count_per_bin – Optional mapping from bin index to counts.

  • notes – Optional free-form annotations to store verbatim.

Returns:

A nested dictionary containing metadata suitable for deterministic text or JSON dumps.

binny.utils.metadata.round_floats(obj: Any, decimal_places: int | None) → Any#

Recursively rounds floats in nested metadata.

binny.utils.metadata.save_metadata_txt(meta: Mapping[str, Any], path: str | Path, *, decimal_places: int | None = 2) → Path#

Writes metadata to a UTF-8 text file.