Aggregation configuration

cfg_aggregations.yaml in the selected configuration directory has one top-level entry per aggregation: a joint GEX, ATAC and WNN analysis of one or more GEM wells. You add an entry at step 3 of Configure your data; the running guide explains when to revise each setting at its checkpoint.

The public configuration contains these entries; inactive ones can stay as examples:

template_aggregation (inactive): a starting point for your own entry.
immune_human_2x (active): the public demo, combining two human PBMC GEM wells with optional modules disabled.
brain_mouse (inactive): a mouse example from 10x Genomics’ E18 embryonic brain, with marker sets for progenitors and immature cortical, hippocampal and inhibitory neurons.
ENCODE_heart_LV_6x (inactive): six ENCODE left-ventricle GEM wells with a differential-analysis example.

configuration_dev/ holds the larger public-data aggregations: mixed_human_31x, the aggregation behind the output gallery with all optional modules enabled, and comparison_1x to comparison_31x, nested sets of its GEM wells for the manuscript’s resource comparisons. The seven 10x Genomics and 24 ENCODE GEM wells of mixed_human_31x are processed locally with Cell Ranger ARC 2.1.0 and GRCh38-2024-A, so its PBMC well healthy_PBMC_human_2024A is separate from the demo’s downloaded healthy_PBMC_human.

Minimal entry

Copy template_aggregation, rename the copy and fill it in. The result needs at least:

cfg_aggregations.yaml

my_aggregation:
  is_active: true
  aggregation_GEM_well_IDs: [my_GEM_well]
  aggregation_donor_id_metadata_tsv: /path/to/donor_metadata.tsv
  aggregation_GEX_marker_genes:
    Cell_type_A: [GENE1, GENE2]
    Cell_type_B: [GENE3, GENE4]

is_active: true replaces the template’s false; an entry written from scratch is active by default. Every other parameter is optional or has a default, listed in the parameter browser. Add a parameter to the entry only to change its default.

Keys

aggregation_GEM_well_IDs: the GEM_well_ID values to combine, from the GEM well table.
aggregation_donor_id_metadata_tsv: the donor metadata table for these GEM wells, or a list of tables, for example one per cohort, which are joined into one.
aggregation_GEX_marker_genes: marker genes per expected cell type, used for cluster annotation and marker plots.
is_active (default true): whether targets are constructed for the aggregation. Set it to false for aggregations you are not ready to run before an unqualified targets::tar_make(); this does not delete existing results.

Marker genes and transcription factors

Replace the placeholder genes with symbols appropriate for the tissue. List at least two cell types, and use gene names from the Cell Ranger ARC reference. A gene without a suffix or with a + suffix is a positive marker; a - suffix marks a gene that should be absent. Each cell type needs at least one positive marker. The optional aggregation_ATAC_marker_TFs names transcription factors per cell type for the motif-accessibility plots at checkpoint 7. Cluster annotation describes how the marker lists are used.

Rules checked

When the pipeline starts, it checks every entry against the parameter manifest: unknown parameters fail, and the resolved values are checked for missingness, type, cardinality and allowed values. It also checks that every listed GEM well exists and is active, and that each listed module has an entry in its configuration file. When the targets run, all GEM wells of an aggregation must share the same Cell Ranger ARC reference, and every marker gene must be present in the GEX count matrix.

QC filters after peak calling

Leave aggregation_QC_exclude_list_combined_object unset for the first run. After reviewing the peak QC distributions at checkpoint 4, list filters and run checkpoint 5, which applies them to the GEX-retained nuclei. Each filter is a complete R expression over the per-nucleus metadata:

cfg_aggregations.yaml

aggregation_QC_exclude_list_combined_object:
  - atac_fragments_in_peaks < 590
  - atac_fragments_in_peaks_frac < 0.12
  - atac_fragments_in_blacklist_frac > 0.012

A nucleus for which any expression is TRUE is excluded, and each expression is reported as a separate exclusion reason in the checkpoint 5 UpSet and retention plots. Filters can use the metrics that QC_metric_manifest.tsv lists as available from checkpoint 4 or earlier. These cutoffs are examples, not recommendations for your tissue.

Inherit settings from another aggregation

An entry can start from the settings of other entries listed in inherits, for example to rerun an aggregation with more GEM wells:

cfg_aggregations.yaml

my_aggregation:
  aggregation_GEM_well_IDs: [GEM_well_1, GEM_well_2]
  aggregation_donor_id_metadata_tsv: /path/to/donor_metadata.tsv
  aggregation_GEX_marker_genes:
    Cell_type_A: [GENE1, GENE2]
    Cell_type_B: [GENE3, GENE4]

my_aggregation_all_wells:
  inherits: my_aggregation
  aggregation_GEM_well_IDs: [GEM_well_1, GEM_well_2, GEM_well_3]

The entry starts from the parameter defaults, applies each parent in the listed order and then its own values. Every parameter is inherited, including is_active, and a value replaces the inherited one as a whole: here the child’s aggregation_GEM_well_IDs replaces the parent’s list rather than extending it. Entries in the module configuration files can inherit in the same way.

Combine several tissues

An aggregation can add GEM wells from other tissues to a single-tissue analysis, for example public wells as background. Such aggregations usually need these settings revised:

Batch correction: when each GEM well holds one tissue, GEM_well_ID is confounded with tissue, and Harmony on it aligns tissue-specific populations, so that, for example, hepatocytes or cardiomyocytes join clusters of the main tissue. Leave aggregation_harmony_correction_metadata_col_names unset. List GEM_well_tissue or GEM_well_dataset in aggregation_categorical_vars and check each cluster’s makeup in categorical_by_cluster_bars_plots/ before accepting the labels.
Clustering resolution: many diverse nuclei coarsen the clusters at a given resolution, so the single-tissue aggregation_GEX_cluster_res gives the main tissue fewer clusters. Raise it, aggregation_ATAC_cluster_res and aggregation_WNN_cluster_res above the single-tissue values; marker sets that lead no cluster in the marker-set summary suggest that the clusters are too coarse.
Dimensions: the PCA and LSI compute at least 50 components, or as many as the largest value in aggregation_GEX_data_PCs and aggregation_ATAC_data_PCs if that is more, and the elbow plots show them all. Small populations from other tissues may need more dimensions, for example 40 instead of 20 to separate related epithelial or stromal cell types. Raising them up to 50 does not recompute the PCA or LSI.
Marker genes: for the background tissues, one marker set per broad population, such as one colon-epithelium set rather than separate colonocyte and goblet-cell sets, gives clearer labels. Markers well detected in nuclei work better than short transcripts, for example BCL11B and THEMIS rather than only CD3D and TRAC for T cells.
Optional modules: every module analyses all nuclei of the aggregation. To keep the background tissues out of the differential analyses or the peak–gene correlation, list the main tissue’s GEM_well_dataset values in differential_analyses_GEM_well_datasets or peak_gene_correlation_GEM_well_datasets. Genetic enrichment ranks cell types against each other, so it usually keeps the background.

Optional modules

Omit modules for the first run. After reviewing the primary module’s results, list the optional modules to run:

cfg_aggregations.yaml

my_aggregation:
  modules: [differential_analyses]

Each listed module also needs an entry named after the aggregation in its own configuration file, in the same directory. The module pages describe these entries:

Module	Configuration file	Page
`differential_analyses`	`cfg_module_differential_analyses.yaml`	Differential analyses
`genetic_enrichment`	`cfg_module_genetic_enrichment.yaml`	Genetic enrichment
`peak_gene_correlation`	`cfg_module_peak_gene_correlation.yaml`	Peak–gene correlation

Public example

The public demo’s entry is shown below; the committed example shows every entry.

YAML

immune_human_2x:
  is_active: true
  aggregation_donor_id_metadata_tsv: configuration/immune_human_dataset_donor_id_metadata.tsv
  aggregation_GEM_well_IDs: [healthy_PBMC_human, controller_PBMC_human]
  aggregation_GEX_marker_genes:
    B: [MS4A1, PAX5, EBF1, CD22]
    Mono: [LYZ, S100A9, FCN1, VCAN]
    NK: [KLRF1, NCR1, NCAM1, SH2D1B]
    DC: [LILRA4, CLEC4C, CD1C, FCER1A, CLEC10A]
    T: [TRAC, CD3D, CD3E, CD3G, BCL11B, THEMIS, CD247, CD2]
    MAIT: [SLC4A10, ZBTB16, KLRB1, NCR3]
  # Effector CD8 and other cytotoxic T cells form their own WNN cluster; the absent KLRF1 keeps NK cells out.
  aggregation_WNN_marker_genes:
    Cytotoxic_T: [CD8A, CD8B, GZMK, GZMH, CCL5, NKG7, KLRF1-]
  modules: null
  aggregation_categorical_vars: [donor_id]
  aggregation_harmony_correction_metadata_col_names: GEM_well_ID
  aggregation_GEX_cluster_annotation_min_advantage: 0.02
  aggregation_ATAC_cluster_annotation_min_advantage: 0.02
  aggregation_WNN_cluster_annotation_min_advantage: 0.02
  # Two donors' 7,800 nuclei hold MAIT and other populations of about 100 nuclei.
  aggregation_cluster_min_barcodes: 50
  aggregation_QC_exclude_list_combined_object: [atac_fragments_in_peaks < 590, atac_fragments_in_peaks_frac < 0.12, atac_fragments_in_blacklist_frac > 0.012]
  aggregation_ATAC_marker_TFs:
    B: [EBF1]
    Mono: [CEBPA, CEBPB]
    NK: [EOMES, TBX21]
    DC: [TCF4]
    T: [TCF7, LEF1]
  aggregation_roadmap_EDACC_names: [Peripheral_Blood_Mononuclear_Primary_Cells, CD4_Memory_Primary_Cells, CD4_Naive_Primary_Cells, CD8_Memory_Primary_Cells, CD8_Naive_Primary_Cells, Monocytes-CD14+_RO01746]