binny.surveys.config_utils module

Survey config parsing utilities.

This module reads survey YAML files using a flat tomography-list schema. Each tomography entry defines one sample, its parent redshift distribution, its bin definition, and optional observational sample metadata.

Expected schema:

name: <optional str>

survey_meta:
  description: <optional str>
  footprint:
    nominal:
      survey_area: <optional float>
      frac_sky: <optional float>

z_grid:
  start: <float>
  stop: <float>
  n: <int>

tomography:
  - role: <optional str>
    year: <optional str>
    sample: <optional str>
    scenario: <optional str>
    name: <optional str>
    kind: photoz|specz

    nz:
      model: <str>
      params: <optional mapping>
      # For tabulated n(z), either inline arrays:
      z_input: <optional list[float]>
      nz_input: <optional list[float]>
      # Or a packaged source file:
      source:
        path: <str>
        skiprows: <optional int>
        z_col: <optional int>
        nz_col: <optional int>

    sample_properties:
      number_density:
        n_gal_arcmin2: <optional float>
        n_gal_comoving_h3_mpc3: <optional float | list[float]>
        dndz_deg2: <optional list[float]>
      shape_noise:
        sigma_e: <optional float>
      shot_noise:
        model: <optional str>
      volume:
        gpc3_hminus3: <optional float | list[float]>
      footprint:
        survey_area: <optional float>
        frac_sky: <optional float>

    bins:
      edges: <list[float]>
      # OR
      scheme: <str>
      n_bins: <int>
      range: <optional [float, float]>

    uncertainties:
      <builder kwargs>

binny.surveys.config_utils.config_path(filename: str) → Path

Resolve a shipped survey config filename.

Parameters:

filename – Name of a bundled YAML config file.

Returns:

Filesystem path to the bundled config.

Raises:

FileNotFoundError – If no bundled config has the requested filename.

binny.surveys.config_utils.list_configs() → list[str]

List shipped survey configuration filenames.

Returns:

Sorted YAML filenames shipped in the survey config package.

binny.surveys.config_utils.load_config(path: str | Path) → Mapping[Any, Any]

Load a survey configuration from a YAML file.

Parameters:

path – Path to a YAML file, or the filename of a shipped Binny survey configuration.

Returns:

Parsed survey configuration mapping.

Raises:

• ValueError – If the YAML root is not a mapping or the config has no tomography list.

• FileNotFoundError – If path is neither an existing file nor a shipped config filename.