binny.utils.metadata module#

Metadata helpers for tomographic redshift-bin products.

This module builds and writes metadata for generated tomography outputs. The metadata records the redshift grid, parent distribution, returned bin curves, bin-population summaries, and the user-facing inputs used to produce the bins.

The metadata is intentionally descriptive only: this module does not decide how number densities, bin fractions, counts, shape noise, or shot noise should be computed. Callers compute those quantities under their own conventions and pass them in explicitly.

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, normalize_bins: bool | None = None, notes: Mapping[str, Any] | None = None) → dict[str, Any]#

Build metadata for tomographic redshift-bin outputs.

The returned dictionary is designed to be saved alongside generated bin curves. It records the common redshift grid, the parent redshift distribution, the nominal bin definition, the returned per-bin curves, and optional summaries such as per-bin fractions, number densities, and counts.

The bin curves may be normalized per bin or may carry population information, depending on the calling convention. This function only records what it is given.

Parameters:

  • kind – Tomography mode. Use "photoz" for photo-z selected bins and "specz" for spectroscopic/redshift-sharp bins.

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

  • parent_nz – Parent redshift distribution evaluated on z.

  • bin_edges – Nominal tomographic bin edges.

  • bins_returned – Mapping from bin index to the returned per-bin curve n_i(z) evaluated on z.

  • inputs – User-facing configuration used to generate the bins.

  • parent_norm – Optional scalar normalization associated with the parent distribution.

  • bins_norms – Optional mapping from bin index to per-bin normalization values.

  • frac_per_bin – Optional mapping from bin index to the fraction of the parent sample in that bin.

  • density_per_bin – Optional mapping from bin index to a number density associated with that bin. The unit convention should be documented in inputs.

  • count_per_bin – Optional mapping from bin index to galaxy counts.

  • normalize_bins – Optional flag recording whether returned bin curves were normalized to unit integral.

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

Returns:

A nested dictionary suitable for deterministic text or JSON output.

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

Round floating-point values in nested metadata.

Parameters:

  • obj – Metadata object to process. May be a scalar, mapping, list, tuple, NumPy scalar, or nested combination of these.

  • decimal_places – Number of decimal places to keep. If None, obj is returned unchanged.

Returns:

A copy of obj with floating-point values rounded where applicable.

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

Write metadata to a deterministic UTF-8 text file.

Parameters:

  • meta – Metadata mapping to write.

  • path – Output text-file path.

  • decimal_places – Optional number of decimal places used when writing floating-point values. If None, values are written without rounding.

Returns:

Path to the written file.