Writing `DATA_DESCRIPTION.md`¶

DATA_DESCRIPTION.md lives in a catalogue's data directory (sibling to the FITS/HDF5/CSV file, not in workspace/). It describes the data — what's in the catalogue, its columns, and its known properties — not the analysis task (that's TASK.md). It feeds two things:

Parameter resolution's data_description authority tier — a value can be read straight out of it instead of falling through to a hardcoded default.
The dataset registry's identity key — two directories are matched as the same dataset by the content hash of this file.

Template¶

Copy DATA_DESCRIPTION.md.template into the data directory and fill it in:

# Dataset: [Survey Name]

## Survey description
[Brief description of the survey, footprint, redshift range]

## Observable
[What is being measured: galaxy clustering auto-Cls, cross-correlations, etc.]

## Tomographic bins
[Number of bins, redshift ranges, expected n(z) shape]

## Known systematics
[e.g. stellar contamination, seeing variations, dust, depth variations]

## Expected signal
[Rough expected Cl amplitude and shape, or reference paper]

## Pipeline parameters
nside: [e.g. 512]
lmax: [e.g. 1535]
lmin: [e.g. 2]
n_bandpowers: [e.g. 20]
apodisation_scale: [e.g. 3.0]

## Reference papers
[Key papers this analysis follows]

Any ## Pipeline parameters value you fill in is available to bootstrap_session at the data_description authority tier — lower priority than an explicit user value or a matched profile, higher than the built-in default.

Example — single-bin, full-sky clustering¶

A single-bin, full-sky galaxy-clustering catalogue's DATA_DESCRIPTION.md looks closer to this — the template's sections are a guide, not a rigid schema, and a real file can add whatever probe-specific detail matters:

# My Survey (galaxy clustering, full sky, no tomography)
- catalogue file: my_survey_galaxy_clustering_catalogue.fits
- redshift distribution: nz_no_tomography.dat
- theory cls: my_survey_theory_cls.txt

## Probe & ingestion
- probe: galaxy_density (spin-0, positions only — no shapes)
- full_sky: true  (no mask; apodisation disabled by construction)
- tomography: none — the whole catalogue is a SINGLE bin (no ZBIN column;
  do NOT pass z_edges or bin_col).
- columns → roles:
    - RA  → RA (deg)
    - DEC → DEC (deg)
    - Z   → photometric redshift (reference; single bin, not sliced)
    - SYST_WEIGHT → weight (systematics-correction weight; used in map-making,
      NOT a mask and NOT a systematics template)
- Maximum usable multipole for this catalogue: Lmax = 256.

## Redshift distribution
Single calibrated photometric n(z) for the whole survey (no tomography):
nz_no_tomography.dat. Columns: z, dndz (galaxies/arcmin^2).

## Theory Cls
Single fiducial-cosmology theory spectrum: my_survey_theory_cls.txt.
Multipoles cover the usable range. Columns: ell, Cl.

## Systematics template maps
None. (SYST_WEIGHT is a correction weight, not a survey-property map — no
template ingestion / cross-correlation step.)

Note the explicit "do NOT pass z_edges" and "NOT a mask" callouts — being explicit about what a column isn't is as useful as saying what it is, since ingest_to_session's auto-detection otherwise has to guess from column naming conventions alone.

What to be explicit about¶

Probe and spin — never left for the pipeline to infer from prose (see Parameter resolution). State galaxy_density or galaxy_shear explicitly.
Tomography — if there's no bin column, say so, and say not to pass z_edges/bin_col.
What a weight column is (and isn't) — a systematics-correction weight used in map-making is not automatically a mask or a systematics template; say which it is.
Multiple candidate files — if there's more than one plausible n(z) or theory file in the directory, name the one that applies per bin; ingest_to_session will not guess between candidates (see Multi-format ingestion).

Writing DATA_DESCRIPTION.md¶

Template¶

Example — single-bin, full-sky clustering¶

What to be explicit about¶

Writing `DATA_DESCRIPTION.md`¶