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.

Discovering and loading presets

Built-in survey presets can be discovered and loaded directly through NZTomography. The YAML files remain the single source of truth, while users can access them by survey name.

from binny import NZTomography


print(NZTomography.list_surveys())

cfg = NZTomography.load_survey_config("lsst")
NZTomography.show_survey_config("lsst")

The returned cfg can be passed directly to build_bins.

from binny import NZTomography


cfg = NZTomography.load_survey_config("lsst")

tomo = NZTomography()

source = tomo.build_bins(
    cfg=cfg,
    role="source",
    year="1",
)

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:
  description: LSST lens and source redshift distributions for Year 1 and Year 10.

  footprint:
    # Can provide either survey_area [deg^2] or frac_sky (or both).
    nominal:
      survey_area: 18000.0
      description: Nominal LSST wide survey area.

    years:
      # Year labels are strings on purpose (stable keys).
      '1':
        survey_area: 14000.0
        description: LSST Year 1 effective survey area.
      '10':
        survey_area: 18000.0
        description: LSST Year 10 effective survey area.

  notes:
    - Year labels are strings to keep YAML keys stable.
    - Number densities are stored as sample-level metadata.
    - Shape noise is only attached to source samples.
    - Shot noise is only attached to lens samples.

# 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

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

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

    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

    normalize_bins: true

  # LENS (Y10)
  - role: lens
    year: '10'

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

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 48.0  # surface density [gal/arcmin^2]; optional
      shot_noise:
        model: poisson

    nz:
      model: smail
      params:
        z0: 0.28
        alpha: 2.0
        beta: 0.9

    # 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: 10
      range: [0.2, 1.2]

    # Photo-z uncertainty / error model parameters (name intentionally not "photoz")
    uncertainties:
      scatter_scale: 0.03
      mean_offset: 0.0

    normalize_bins: true

  # SOURCE (Y1)
  - role: source
    year: '1'

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

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 10.0  # surface density [gal/arcmin^2]; optional
      shape_noise:
        sigma_e: 0.26  # ellipticity dispersion

    nz:
      model: smail
      params:
        z0: 0.13
        alpha: 2.0
        beta: 0.78

    # 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: equal_number
      n_bins: 5
      # edges: [...]  # alternative to scheme-based

    # Photo-z uncertainty / error model parameters (name intentionally not "photoz")
    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

    normalize_bins: true

  # SOURCE (Y10)
  - role: source
    year: '10'

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

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 27.0  # surface density [gal/arcmin^2]; optional
      shape_noise:
        sigma_e: 0.26  # ellipticity dispersion

    nz:
      model: smail
      params:
        z0: 0.11
        alpha: 2.0
        beta: 0.68

    # 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: equal_number
      n_bins: 5

    # Photo-z uncertainty / error model parameters (name intentionally not "photoz")
    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

    normalize_bins: true


  # LSST DP2 degraded r < 24.5 sample
  - role: source
    sample: dp2_r24p5
    name: LSST DP2 degraded r < 24.5
    kind: photoz

    sample_properties:
      magnitude_limit:
        band: r_lsst
        value: 24.5
        selection: mag_r_lsst <= 24.5

      mask:
        name: dp2_24p5_combined_mask_nmin=500_nside=512.fits
        nside: 512
        n_min: 500

      counts:
        n_total: 185018080
        n_maglim: 137134326
        n_final: 104471348

      footprint:
        survey_area: 1351.8398
        frac_sky: 0.032770

      number_density:
        n_gal_arcmin2: 21.466907
        n_gal_deg2: 77280.8652

      shape_noise:
        sigma_e: 0.26

    nz:
      model: tabulated
      source:
        path: lsst_dp2_nz_degraded_r24p5_masked.txt
        z_col: 0
        nz_col: 1
        skiprows: 4
      params:
        normalize: true

    bins:
      scheme: equal_number
      n_bins: 3
      range: [ 0.6, 3.0 ]

    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

    normalize_bins: true

Visualizing the preset

The figure below loads the LSST preset directly through Binny, 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:
  description: Euclid weak-lensing and spectroscopic clustering forecast validation setup.
  reference: arXiv:1910.09273

  footprint:
    nominal:
      survey_area: 15000.0
      description: Nominal Euclid survey area used for the forecast validation setup.

  notes:
    - Euclid weak-lensing source density is n_gal_arcmin2 = 30.0.
    - Euclid weak-lensing total intrinsic ellipticity dispersion is sigma_e = 0.30.
    - Euclid spectroscopic clustering uses H-alpha emitters in 0.90 <= z <= 1.80.
    - Spectroscopic redshift uncertainty follows sigma_z = 0.001 * (1 + z).
    - Spectroscopic H-alpha number densities and galaxy biases are stored per redshift bin.

z_grid:
  start: 0.0
  stop: 2.5
  n: 501

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

    sample_properties:
      number_density:
        n_gal_arcmin2: 30.0
      shape_noise:
        sigma_e: 0.30

    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

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

    sample_properties:
      number_density:
        n_gal_comoving_h3_mpc3: [6.86e-4, 5.58e-4, 4.21e-4, 2.61e-4]
        dndz_deg2: [1815.0, 1701.5, 1410.0, 940.97]
      volume:
        gpc3_hminus3: [7.94, 9.15, 10.05, 16.22]
      shot_noise:
        model: poisson
      galaxy_bias:
        values: [1.46, 1.61, 1.75, 1.90]

    nz:
      # Simple approximation to the H-alpha 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

    normalize_bins: true

Visualizing the preset

The figure below loads the Euclid preset directly through Binny 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'

    kind: photoz

    sample_properties:
      number_density:
        n_gal_arcmin2: 0.6
      shot_noise:
        model: poisson

    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'

    kind: photoz

    sample_properties:
      number_density:
        n_gal_arcmin2: 8.0
      # shape_noise:
      #   sigma_e: TODO

    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

    normalize_bins: true

Visualizing the preset

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

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

Roman survey preset

Binny also includes a Roman-inspired survey preset based on the Wenzl22 HLS and wide survey configurations.

The preset contains photometric lens and source samples for the optimistic HLS, conservative HLS, and wide Roman scenarios.

Show Roman YAML preset

Roman survey configuration

name: roman  # Wenzl22 / arXiv:2112.07681 Roman HLS + wide specs

# Optional survey metadata
survey_meta:
  reference: Wenzl22
  notes:
    - Roman HLS and wide survey specifications follow Wenzl22 / arXiv:2112.07681.
    - Source shape noise uses sigma_e: 0.37 following the Wenzl22 two-component Roman covariance convention.
    - Some newer Roman forecast setups use sigma_e: 0.26 per component, e.g. arXiv:2411.04088.

  footprint:
    scenarios:
      hls_optimistic:
        survey_area: 2000.0
        description: Roman HLS optimistic scenario.
      hls_conservative:
        survey_area: 2000.0
        description: Roman HLS conservative scenario.
      wide:
        survey_area: 18000.0
        description: Roman wide survey scenario.

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

tomography:
  # HLS OPTIMISTIC SOURCE
  - role: source
    scenario: hls_optimistic
    kind: photoz

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 51.0  # surface density [gal/arcmin^2]; optional
      shape_noise:
        sigma_e: 0.37  # ellipticity dispersion / Roman Wenzl22 covariance convention

    nz:
      model: smail
      params: {z0: 0.13, alpha: 2.0, beta: 0.66}

    bins:
      scheme: equal_number
      n_bins: 10

    uncertainties:
      scatter_scale: 0.01
      mean_offset: 0.0

  # HLS OPTIMISTIC LENS
  - role: lens
    scenario: hls_optimistic
    kind: photoz

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 66.0  # surface density [gal/arcmin^2]; optional
      shot_noise:
        model: poisson

    nz:
      model: smail
      params: {z0: 0.08, alpha: 2.0, beta: 0.58}

    bins:
      scheme: equal_number
      n_bins: 10

    uncertainties:
      scatter_scale: 0.01
      mean_offset: 0.0

  # HLS CONSERVATIVE SOURCE
  - role: source
    scenario: hls_conservative
    kind: photoz

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 51.0  # surface density [gal/arcmin^2]; optional
      shape_noise:
        sigma_e: 0.37  # ellipticity dispersion / Roman Wenzl22 covariance convention

    nz:
      model: smail
      params: {z0: 0.13, alpha: 2.0, beta: 0.66}

    bins:
      scheme: equal_number
      n_bins: 10

    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

  # HLS CONSERVATIVE LENS
  - role: lens
    scenario: hls_conservative
    kind: photoz

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 66.0  # surface density [gal/arcmin^2]; optional
      shot_noise:
        model: poisson

    nz:
      model: smail
      params: {z0: 0.08, alpha: 2.0, beta: 0.58}

    bins:
      scheme: equal_number
      n_bins: 10

    uncertainties:
      scatter_scale: 0.05
      mean_offset: 0.0

  # WIDE SOURCE
  - role: source
    scenario: wide
    kind: photoz

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 43.0  # surface density [gal/arcmin^2]; optional
      shape_noise:
        sigma_e: 0.37  # ellipticity dispersion / Roman Wenzl22 covariance convention

    nz:
      model: smail
      params: {z0: 0.16, alpha: 2.0, beta: 0.70}

    bins:
      scheme: equal_number
      n_bins: 10

    uncertainties:
      scatter_scale: 0.02
      mean_offset: 0.0

  # WIDE LENS
  - role: lens
    scenario: wide
    kind: photoz

    # Optional population metadata (not needed to build bins)
    sample_properties:
      number_density:
        n_gal_arcmin2: 59.0  # surface density [gal/arcmin^2]; optional
      shot_noise:
        model: poisson

    nz:
      model: smail
      params: {z0: 0.10, alpha: 2.0, beta: 0.62}

    bins:
      scheme: equal_number
      n_bins: 10

    uncertainties:
      scatter_scale: 0.02
      mean_offset: 0.0

Visualizing the preset

The figure below loads the Roman preset directly through Binny and visualizes the resulting photometric lens and source tomographic bins. The top row compares the optimistic High Latitude Survey (HLS) configuration against the conservative HLS configuration, while the bottom row shows the wide survey configuration.

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

DESI survey preset

Binny also includes a DESI-inspired survey preset containing tabulated spectroscopic LRG and ELG lens redshift distributions.

The default preset uses the redshift windows from arXiv:2511.19194: \(0.4 \leq z \leq 1.0\) for LRGs and \(0.6 \leq z \leq 1.5\) for ELGs.

Show DESI YAML preset

DESI survey configuration

name: desi

survey_meta:
  description: DESI LRG and ELG tabulated lens redshift distributions.

  footprint:
    nominal:
      survey_area: 5000.0
      description: Plain DESI LRG overlap with LSST used for Delta Sigma analyses.

    overlap_scenarios:
      desi_lrg_lsst:
        survey_area: 5000.0
        lens_sample: lrg
        description: Plain DESI LRG overlap with LSST.

      desi_plus_20pc_lsst:
        survey_area: 3600.0
        lens_sample: lrg
        description: DESI LRG overlap with LSST plus 20 percent scenario.

      desi_plus_50pc_lsst:
        survey_area: 4500.0
        lens_sample: lrg
        description: DESI LRG overlap with LSST plus 50 percent scenario.

      desi_4most_lrg_lsst:
        survey_area: 10500.0
        lens_sample: lrg
        description: DESI/4MOST-style LRG overlap with LSST.

      desi150pc_4most_lrg_lsst:
        survey_area: 12000.0
        lens_sample: lrg
        description: DESI/4MOST-style LRG 150 percent scenario overlap with LSST.

      desi200pc_4most_lrg_lsst:
        survey_area: 13500.0
        lens_sample: lrg
        description: DESI/4MOST-style LRG 200 percent scenario overlap with LSST.

      desi_4most_18000deg2_lrg_lsst:
        survey_area: 18000.0
        lens_sample: lrg
        description: DESI/4MOST-style LRG full 18000 deg2 overlap scenario.

      desi_4most_elg_lsst:
        survey_area: 4000.0
        lens_sample: elg
        description: DESI/4MOST-style ELG overlap with LSST.

      desi150pc_4most_elg_lsst:
        survey_area: 5500.0
        lens_sample: elg
        description: DESI/4MOST-style ELG 150 percent scenario overlap with LSST.

      desi200pc_4most_elg_lsst:
        survey_area: 7000.0
        lens_sample: elg
        description: DESI/4MOST-style ELG 200 percent scenario overlap with LSST.

      desi_4most_18000deg2_elg_lsst:
        survey_area: 18000.0
        lens_sample: elg
        description: DESI/4MOST-style ELG full 18000 deg2 overlap scenario.

  notes:
    - Delta Sigma analyses use the DESI LRG redshift window 0.4 <= z <= 1.0.
    - Delta Sigma analyses use the DESI/4MOST-style ELG redshift window 0.6 <= z <= 1.5.
    - The nominal footprint is the plain DESI-LSST overlap area used for Delta Sigma analyses.
    - Additional footprint values are analysis scenarios inherited from the old Delta Sigma setup.

z_grid:
  start: 0.0
  stop: 2.0
  n: 500

tomography:
  # LRGs
  - role: lens
    sample: lrg
    name: DESI LRG
    kind: specz

    sample_properties:
      number_density:
        n_gal_comoving_h3_mpc3: 5.0e-4
      shot_noise:
        model: poisson

    nz:
      model: tabulated
      source:
        path: desi_lrg_nz.txt
        z_col: 0
        nz_col: 1
        skiprows: 1
      params:
        normalize: true

    bins:
      edges: [0.4, 1.0]

    normalize_bins: true

  # ELGs
  - role: lens
    sample: elg
    name: DESI ELG
    kind: specz

    sample_properties:
      number_density:
        n_gal_comoving_h3_mpc3: 5.0e-4
      shot_noise:
        model: poisson

    nz:
      model: tabulated
      source:
        path: desi_elg_nz.txt
        z_col: 0
        nz_col: 1
        skiprows: 1
      params:
        normalize: true

    bins:
      edges: [0.6, 1.5]

    normalize_bins: true


  # BGS SGC
  - role: lens
    sample: bgs_sgc
    name: DESI BGS SGC
    kind: specz

    sample_properties:
      survey_area_deg2: 2173.1756
      effective_area_deg2: 2147.7451156526713

      number_density:
        model: tabulated_comoving
        n_gal_comoving_h3_mpc3_col: 3
        volume_col: 5
        total_count_col: 4

      shot_noise:
        model: poisson

    nz:
      model: tabulated
      source:
        path: desi_bgs_sgc_nz.txt
        z_col: 0
        nz_col: 4
        skiprows: 1
      params:
        normalize: true

    bins:
      edges: [0.01, 0.5]

    normalize_bins: true

  # LRG SGC
  - role: lens
    sample: lrg_sgc
    name: DESI LRG SGC
    kind: specz

    sample_properties:
      survey_area_deg2: 1983.8884
      effective_area_deg2: 1770.198402421271

      number_density:
        model: tabulated_comoving
        n_gal_comoving_h3_mpc3_col: 3
        volume_col: 5
        total_count_col: 4

      shot_noise:
        model: poisson

    nz:
      model: tabulated
      source:
        path: desi_lrg_sgc_nz.txt
        z_col: 0
        nz_col: 4
        skiprows: 1
      params:
        normalize: true

    bins:
      edges: [0.4, 0.75, 1.1]

    normalize_bins: true

Visualizing the preset

The figure below loads the DESI preset directly through Binny and visualizes the tabulated LRG and ELG redshift distributions. The rows show the same redshift windows split into one, three, and five equal-width tomographic bins.

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