Donor metadata table

The donor metadata table is a TSV with one row per donor, keyed by donor_id. You prepare it at step 2 of Configure your data, and each aggregation points to its file, or files, with aggregation_donor_id_metadata_tsv.

Minimal table

donor_metadata.tsv

donor_id    condition
donor_1 control

Columns

• donor_id (required): one row for each donor ID that the nuclei receive; see Matching donors to nuclei.
• Every other column is a donor-level variable, such as condition, age or sex. The variables become cell metadata: select them for plots with aggregation_categorical_vars or aggregation_continuous_vars, and use them in the model formulas of the differential analyses.

Put library-, run- or batch-specific variables in the GEM well table instead, with a GEM_well_ prefix.

Matching donors to nuclei

Every nucleus receives a donor_id from its GEM well: GEM_well_donor_id for a single-donor well, or the VCF sample name that Vireo assigns in a pooled well. Give each of those IDs one row, with identical spelling; the nuclei-per-donor plot at checkpoint 1 shows the IDs the nuclei received. Nuclei whose donor is missing from the table get NA donor variables, and rows for donors without nuclei are ignored.

Several tables

When an aggregation combines cohorts that each have their own donor table, list the files instead of merging them by hand:

cfg_aggregations.yaml

my_aggregation:
  aggregation_donor_id_metadata_tsv: [/path/to/cohort_donor_metadata.tsv, /path/to/reference_donor_metadata.tsv]

The pipeline joins the files into one donor table. A column that only some files have is left empty for the donors of the others. A donor may appear in more than one file only if those files agree on every column they share.

Several samples per donor

A donor sampled more than once, for example in two tissues or conditions, can enter one aggregation with each sample as its own replicate. cfg_GEM_well_samples.tsv in the configuration directory maps each donor of a GEM well to a sample, with columns GEM_well_ID, donor_id and sample_id; sample IDs may not contain underscores. The nuclei then carry the sample ID as their donor_id, so pseudobulks and differential analyses treat samples as replicates.

Each sample inherits its donor’s row of the donor table. Add rows for samples only for variables that differ between a donor’s samples, such as a condition; a value given for a sample overrides its donor’s.

Rules checked

When the targets that read the table run, they check that:

• donor_id values are unique within each file;
• a donor listed in several files has no conflicting values, and columns shared by several files have compatible types; and
• apart from donor_id and GEM_well_ID, no column name appears both here and in the GEM well table.

Extended table for differential analyses

The differential analyses module can read its donor-level model variables from a separate table given in differential_analyses_extended_donor_id_metadata_tsv. The module then reads only this table, so it must hold every variable that any model uses, keyed by a unique donor_id. If it is not set, the module uses the aggregation’s donor table.

Public example

The public demo’s table lists its two donors:

configuration/immune_human_dataset_donor_id_metadata.tsv

donor_id    condition
pbmc1   healthy
pbmc2   healthy