Describe a run’s metadata with REMBI#

Attach experiment metadata to a batch run and get a REMBI-structured manifest (deliverables/rembi.yaml) alongside your measurements — so a dataset ships with machine-readable provenance grouped by REMBI module (Study, Biosample, SpecimenPreparation, ImageAcquisition, ImageData, AnalyzedData).

The two metadata inputs#

A run takes metadata from two optional inputs, and folds both into the manifest:

Input

Flag

Scope

Format

Varies per

Sample metadata

--metadata

per image / per colony

CSV

row (image or grid cell)

Study profile

--study

one set per run

YAML

nothing — constant

Neither is required. With no metadata at all you still get a manifest — its image_data and analyzed_data sections are always populated from the run itself. The two flags just enrich the biological sections.

uv run python -m phenotypic ./images -o ./out \
    --metadata metadata.csv \
    --study study.yaml

Note

--mode process (apply-only layer export) writes no deliverables/ bundle, so it emits no manifest. The manifest is produced by full measure runs only.

1. Sample metadata — the --metadata CSV#

This CSV carries the metadata that changes across your images or colonies: strain, media, timepoint, plate, replicate. Example:

metadata.csv — per-image sample metadata#
MetadataImage_ImageName,MetadataGenetic_Strain,MetadataGenetic_MatingType,MetadataCondition_Media,MetadataCulture_Temperature,MetadataCulture_Time,MetadataCulture_TimeUnit,MetadataPlate_PlateID,MetadataSample_BioReplicate
plate_001_t24.tif,BY4741,a,YPD,30,24,h,P1,1
plate_001_t48.tif,BY4741,a,YPD,30,48,h,P1,1
plate_002_t24.tif,BY4742,alpha,YPD,30,24,h,P2,1
plate_002_t48.tif,BY4742,alpha,YPD,30,48,h,P2,1

How it joins. The CSV is inner-joined onto the measurements on every column whose name it shares with them. So a column only participates in the join if its header exactly matches a measurement column:

  • Join per image: give the CSV a MetadataImage_ImageName column (the image filename, matching the framework’s image-name column). Each row then broadcasts to every colony of that image — the pattern shown above.

  • Join per colony: additionally include Grid_RowNum and Grid_ColNum. The row then applies to one grid cell.

Warning

The join key must match the measurement column name exactly. After the REMBI namespace migration the image-name column is MetadataImage_ImageName (not the old Metadata_ImageName). A CSV that still uses the old header shares no column with the measurements and the join is skipped with a warning. Rows with no match are dropped (also warned); duplicate keys multiply rows.

Column names decide the REMBI module. Use the recommended Metadata<Topic>_<Label> vocabulary and each column routes itself to the right manifest section:

CSV prefix

REMBI module → manifest section

MetadataGenetic_*, MetadataSample_*

Biosample → biosample

MetadataCondition_*, MetadataPlate_*

SpecimenPreparation → specimen_preparation

MetadataCulture_Temperature/_Day/_Humidity/…

SpecimenPreparation → specimen_preparation

MetadataCulture_Time/_TimeUnit/_Timepoint/_FrameIndex

Biosample → biosample (time-course modeled as a Biosample variable, per REMBI)

MetadataAcquisition_*

ImageAcquisition → image_acquisition

MetadataStudy_*, MetadataExperiment_*

Study → study

Note the MetadataCulture_ prefix straddles two modules: temperature and atmosphere describe how the specimen was prepared, but elapsed time is a biosample variable in REMBI, so MetadataCulture_Time lands in biosample.

This is a recommended vocabulary, not a validator — any column is accepted. A label outside the vocabulary keeps a generic Metadata_<Label> header and routes to the manifest’s uncategorized section. The full prefix vocabulary is documented in the metadata namespace explanation; per-enum column lists are in the metadata schema reference.

2. Study profile — the --study YAML#

This YAML carries the static study-level fields — the ones that are constant for the whole run (title, authors, license, funding). It is the REMBI Study module as a small file you keep beside the dataset:

study.yaml — static REMBI Study profile#
# ---------------------------------------------------------------------------
# REMBI Study-level metadata profile  (pass with:  --study study.yaml)
#
# One set of values per run. These "static" fields describe the STUDY as a
# whole -- they do not vary from image to image -- and are folded into the
# `study:` section of `deliverables/rembi.yaml`.
#
# Keys are the *bare* STUDY_METADATA / EXPERIMENT_METADATA labels (no
# `MetadataStudy_` / `MetadataExperiment_` prefix). Any key given here
# OVERRIDES a same-named constant `Metadata*` column coming from --metadata.
# Every field is optional; delete the lines you do not need. This is a
# recommended vocabulary, not a validator -- unknown keys are still emitted.
# See the STUDY_METADATA / EXPERIMENT_METADATA schema pages for the full list.
# ---------------------------------------------------------------------------

# --- REMBI Study fields (STUDY_METADATA) ---
Title: "Yeast deletion-collection colony-size time course"
Description: >
  SGA-arrayed S. cerevisiae deletion library imaged on YPD at 30 C,
  endpoint colony size captured at 24 h and 48 h.
Keywords: "colony size; yeast; deletion collection; time course"
Author: "Nguyen, A.; Example Lab"        # delimited string for multiple authors
License: "CC-BY-4.0"
Funding: "NIH R01-XXXXXXX"
Publications: "https://doi.org/10.1000/example"
Links: "https://example.org/datasets/yeast-sga-timecourse"
Acknowledgements: "Imaging performed at the Example Screening Core."
# PrivateUntilDate: "2027-01-01"          # embargo date, if the study is private

# --- Experiment-level bookkeeping (EXPERIMENT_METADATA, also REMBI Study) ---
Project: "SGA-Phenomics"
Dataset: "sga-timecourse-2026"
Protocol: "https://example.org/protocols/sga-pinning-v3"

Keys are the bare labels — Title, Author, License, … — without the MetadataStudy_ / MetadataExperiment_ prefix. A key given here overrides a same-named constant Metadata* column that came in via --metadata, so the study file is the single source of truth for run-level fields even if the CSV also carries them. Every field is optional. The available keys mirror the STUDY_METADATA and EXPERIMENT_METADATA schema pages.

The output: deliverables/rembi.yaml#

The manifest folds the per-colony metadata mirror up to each REMBI module. From the two inputs above it looks like this:

study:
  Title: Yeast deletion-collection colony-size time course
  Author: Nguyen, A.; Example Lab
  License: CC-BY-4.0
  Project: SGA-Phenomics
  # ... remaining study.yaml fields ...
biosample:
  Strain: [BY4741, BY4742]        # distinct values collapse to a list
  MatingType: [a, alpha]
  BioReplicate: 1
  Time: [24, 48]                  # time-course variable (from MetadataCulture_Time)
  TimeUnit: h
specimen_preparation:
  Media: YPD
  Temperature: 30
  PlateID: [P1, P2]
image_acquisition: {}             # empty here — no MetadataAcquisition_* columns
image_data:                       # ALWAYS present, from the run itself
  n_images: 4
  bit_depth: [8]
  files:
    - {name: plate_001_t24.tif, uuid: ..., bit_depth: 8, image_type: RGB}
    # ... one entry per image ...
analyzed_data:                    # ALWAYS present, the measured feature catalog
  features:
    Size: [Area, Perimeter]
    Shape: [Circularity, ...]
    Intensity: [MeanIntensity, ...]

Within a section, a field with a single value across the run collapses to a scalar; multiple distinct values collapse to a sorted list. image_data and analyzed_data are derived from the run and are present even with no metadata inputs.

Refreshing a pre-migration run#

Old output folders still open, but their metadata columns predate the per-module namespace and read as uncategorized. To remap an existing run’s measurement parquets to the current REMBI namespace, re-run with --mode recompile. Background on the rename is in the metadata namespace explanation.