Collections — curated, named sets of catalog studies and samples

config/collections.yaml defines the Collections section of the site: named sets of curated-catalog studies and/or samples with pre-entered explorer filters (benchmark and reference cohorts, landmark population cohorts, disease reference sets, age bands, lifestyle and design sets). The site generator (site_generator/gen/build_site.py, Collections track) renders one card per entry and links each to the Samples explorer with the filters applied. First shipped in R2026.12 / package 1.12.0.

Schema (one entry per collection)

collections:
  - id: crc-meta-analysis-cohorts          # slug: [a-z0-9]+(-[a-z0-9]+)*, unique
    title: Colorectal cancer meta-analysis cohorts (Wirbel / Thomas 2019)
    kind: disease                          # benchmark | population | disease | design | age | lifestyle | other
    blurb: <= 60 words, factual — what the set is and why someone would want it
    studies: [PRJEB6070, PRJEB7774, ...]   # optional; every accession MUST be in gut_studies.parquet
    filters:                               # optional; keys among age_category, country, health_condition, lifestyle,
      health_condition: [colorectal_cancer]  #   antibiotic_exposure, sex, collection_year, study_accession,
      body_site_class: [primary]             #   body_site_class, min_samples_per_subject
      min_samples_per_subject: {min: 5}      # list = any-of; {min, max} = inclusive range
    references:
      - {label: Wirbel et al. 2019, Nature Medicine, url: https://doi.org/10.1038/s41591-019-0406-6}
    notes: free text shown under the card (caveats, what was left out and why)

Semantics: studies restricts to the listed accessions; filters restrict samples; when both are present the filters apply within the listed studies. A collection needs at least one of the two. Filter values must come from the catalog vocabularies: age_category from config/packs/gut.yaml (neonate, infant, child, adolescent, adult, elderly, unknown), health_condition from config/vocab/health_conditions.yaml, lifestyle from config/vocab/lifestyle.yaml, country as ISO-3166 alpha-2, sex in female | male | unknown, antibiotic_exposure in yes | no | unknown, body_site_class in primary | linked | unknown | excluded. lifestyle and collection_year are populated from package 1.12.0 onward; a lifestyle-based collection must therefore also list its studies explicitly so it renders on releases where the column is still empty.

How to propose a collection

1. Fork OlmLab/microbiome_repo-pipeline and edit config/collections.yaml (append an entry; keep ids stable once shipped — rename by adding a new entry and retiring the old one in notes).
2. Verify every accession exists in the current package: duckdb -c "select study_accession, study_title, n_samples from 'gut_studies.parquet' where study_accession in ('PRJ...')" — accessions that are not catalog studies are dropped at build time and reported, never silently kept. If the study is a human gut shotgun study missing from the catalog, open a registry issue instead (it must enter through triage; see RUNBOOK §2).
3. Run python scripts/build_collections.py --check (validates schema, vocabularies, accession existence, blurb length, and that every filter-only collection returns >= 100 samples) and attach the printed preview (n_studies, n_samples) to the PR description.
4. Cite how you identified the accessions (paper data-availability statement, ENA record, BioProject search) in references; blurbs state facts that can be checked against the paper or the ENA record — no claims about sample quality or results.
5. Open a PR titled collections: add <id>. The owner reviews for scope (human gut shotgun only), non-duplication and naming; merged collections ship with the next release and appear in collections_preview.csv of the package.

Provenance rules

Collections are curation, so the catalog's evidence rules apply: a study belongs to a collection only if its paper, ENA record or study description states the property the collection is about (e.g. the word "Hadza", an FMT trial registration, a mock-community control). Filter-based membership is computed from per-sample determinations that each carry their own evidence quote; the collection inherits that provenance. Nothing is inferred from country or centre name alone.