Survey presets

Binny allows survey configurations to be stored as YAML survey presets. A preset groups together the parent redshift distribution, tomographic binning scheme, uncertainty model, and optional survey metadata such as footprint or galaxy density.

Using a YAML preset makes it easier to keep survey configurations consistent across forecasts, examples, and analyses.

LSST survey preset

The example below shows the LSST survey preset included with Binny. It defines tomographic configurations for lens and source samples for both year 1 and year 10.

Show LSST YAML preset

LSST survey configuration

name: lsst  # https://arxiv.org/abs/1809.01669

# Optional survey metadata (binning code can ignore unless requested)
survey_meta:
  footprint:
    # Can provide either survey_area [deg^2] or frac_sky (or both).
    nominal: {survey_area: 18000.0}
    years:
      # Year labels are strings on purpose (stable keys).
      '1':  {survey_area: 12000.0}
      '10': {survey_area: 14000.0}

# Redshift grid used for evaluating n(z) and all n_i(z) outputs
z_grid: {start: 0.0, stop: 3.5, n: 500}


tomography:
  # LENS (Y1)
  - role: lens  # optional label (e.g. lens/source); used for bookkeeping/keys
    year: '1'   # optional label; string is recommended for stable YAML keys

    # Optional population metadata (not needed to build bins)
    n_gal_arcmin2: 18.0  # surface density [gal/arcmin^2]; optional

    # Tomography kind (dispatcher). If omitted, default could be "photoz".
    kind: photoz

    nz:
      model: smail
      params: { z0: 0.26, alpha: 2.0, beta: 0.94}

    # Bin specification:
    # - Option A (scheme-based): provide scheme + n_bins (+ optional range)
    # - Option B (explicit edges): provide edges only (no scheme / n_bins)
    bins:
      scheme: equidistant
      n_bins: 5
      range: [0.2, 1.2]
      # edges: [0.2, 0.4, 0.6, 0.8, 1.0, 1.2]  # alternative to scheme-based

    # Photo-z uncertainty / error model parameters (name intentionally not "photoz")
    uncertainties:
      scatter_scale: 0.03  # sigma(z) ~ scatter_scale * (1+z) * mean_scale
      mean_offset: 0.0     # mu(z) ~ mean_scale * z - mean_offset
      # mean_scale: 1.0     # optional (scalar broadcasts), if supported

  # LENS (Y10)
  - role: lens
    year: '10'
    n_gal_arcmin2: 48.0  # surface density [gal/arcmin^2]; optional
    kind: photoz
    nz:
      model: smail
      params: { z0: 0.28, alpha: 2.0, beta: 0.9 }
    bins:
      scheme: equidistant
      n_bins: 10
      range: [0.2, 1.2]
    uncertainties:
      scatter_scale: 0.03
      mean_offset: 0.0

  # SOURCE (Y1)
  - role: source
    year: '1'
    n_gal_arcmin2: 10.0  # surface density [gal/arcmin^2]; optional
    kind: photoz
    nz:
      model: smail
      params: { z0: 0.13, alpha: 2.0, beta: 0.78 }
    bins:
      scheme: equal_number
      n_bins: 5
      # edges: [...]  # alternative to scheme-based
    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

  # SOURCE (Y10)
  - role: source
    year: '10'
    n_gal_arcmin2: 27.0  # surface density [gal/arcmin^2]; optional
    kind: photoz
    nz:
      model: smail
      params: { z0: 0.11, alpha: 2.0, beta: 0.68 }
    bins:
      scheme: equal_number
      n_bins: 5
    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

Visualizing the preset

The figure below loads the LSST preset directly, constructs the corresponding tomographic bins, and plots the resulting redshift distributions for lens and source samples in years 1 and 10.

(Source code, png, hires.png, pdf)

Euclid survey preset

Binny can also be used with a Euclid-inspired survey preset containing a photometric source sample and a spectroscopic lens sample.

In this simplified preset, the source sample follows the commonly used Euclid weak-lensing redshift distribution with 10 explicit tomographic bin edges, while the lens sample is represented as a spectroscopic sample over the Euclid clustering redshift range.

Show Euclid YAML preset

Euclid survey configuration

name: euclid  # based on Euclid forecast validation setup, arXiv:1910.09273

survey_meta:
  footprint:
    nominal: {survey_area: 15000.0}

z_grid:
  start: 0.0
  stop: 2.5
  n: 501

tomography:
  # Euclid weak-lensing source sample
  - role: source
    year: "nominal"
    kind: photoz
    n_gal_arcmin2: 30.0

    nz:
      model: smail
      params:
        z0: 0.636
        alpha: 2.0
        beta: 1.5

    bins:
      edges: [0.0010, 0.42, 0.56, 0.68, 0.79, 0.90, 1.02, 1.15, 1.32, 1.58, 2.50]

    uncertainties:
      # Core photo-z component
      scatter_scale: 0.05
      mean_offset: 0.0
      mean_scale: 1.0

      # Catastrophic outlier component
      outlier_frac: 0.10
      outlier_scatter_scale: 0.05
      outlier_mean_offset: 0.10
      outlier_mean_scale: 1.0

    normalize_bins: true

  # Euclid spectroscopic clustering sample
  - role: lens
    year: "nominal"
    kind: specz

    nz:
      # simple approximation to the Hα sample; the actual paper uses the tabulated sample properties
      model: smail
      params:
        z0: 1.0
        alpha: 2.0
        beta: 1.5

    bins:
      edges: [0.90, 1.10, 1.30, 1.50, 1.80]

    uncertainties:
      completeness: [1.0, 1.0, 1.0, 1.0]
      catastrophic_frac: [0.0, 0.0, 0.0, 0.0]
      leakage_model: neighbor
      leakage_sigma: [1.0, 1.0, 1.0, 1.0]

      specz_scatter: null
      specz_scatter_model: z_dependent
      sigma0: 0.001
      sigma1: 0.001

    galaxy_bias:
      values: [1.46, 1.61, 1.75, 1.90]

    normalize_bins: true

Visualizing the preset

The figure below loads the Euclid preset and visualizes the resulting spectroscopic lens bins and photometric source bins.

(Source code, png, hires.png, pdf)

DES survey preset

Binny also includes a simplified configuration inspired by the tomographic setup used in the Dark Energy Survey (DES).

Compared to LSST, DES covers a smaller area of the sky and has lower galaxy number densities, resulting in fewer tomographic bins and a shallower redshift reach.

Show DES YAML preset

DES survey configuration

name: des

survey_meta:
  footprint:
    nominal:
      survey_area: 5000.0

z_grid: {start: 0.0, stop: 2.0, n: 500}

tomography:

  # DES redMaGiC lens sample
  - role: lens
    year: 'y1'

    n_gal_arcmin2: 0.6

    kind: photoz

    nz:
      model: smail
      params: {z0: 0.25, alpha: 2.0, beta: 1.5}

    bins:
      edges: [0.15, 0.30, 0.45, 0.60, 0.75, 0.90]

    uncertainties:
      scatter_scale: 0.015
      mean_offset: 0.0


  # DES source sample
  - role: source
    year: 'y1'

    n_gal_arcmin2: 8.0

    kind: photoz

    nz:
      model: smail
      params: {z0: 0.35, alpha: 2.0, beta: 1.5}

    bins:
      edges: [0.20, 0.43, 0.63, 0.90, 1.30]

    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

Visualizing the preset

The figure below loads the DES preset and visualizes the resulting lens and source tomographic bins.

(Source code, png, hires.png, pdf)