6  Configuration and inputs

multiomeR uses two linked configuration layers. A GEM well points to one cellranger-arc count output and defines its pre-aggregation processing and QC. An aggregation selects GEM wells for joint GEX, ATAC, and WNN analysis.

Layer	Configuration	Key relationship
GEM well	cfg_GEM_wells.tsv	Aggregations refer to one or more GEM_well_ID values.
Aggregation	cfg_aggregations.yaml	Selects GEM wells and points to donor-level metadata.

The committed cfg_GEM_wells.tsv and cfg_aggregations.yaml files are the active configuration files. They enable only the two GEM wells and the immune_human_2x aggregation used by the public quickstart. Edit these files directly when configuring another project.

6.1 Start with one explicitly scoped analysis

GEM_well_is_active controls per-GEM-well graph construction, while aggregation is_active controls aggregation graph construction. Every active aggregation must reference active GEM wells. Before an unqualified targets::tar_make(), deactivate every GEM well and aggregation you are not ready to run. The committed quickstart configuration already follows this rule.

The example below describes one non-multiplexed GEM well from one donor. Replace the paths, identifiers, and marker genes for your study. It illustrates how the files connect; one donor is not enough for a replicated comparison.

6.1.1 1. Define one GEM well

Add a row to cfg_GEM_wells.tsv with these values. This vertical view is a reading aid; the saved TSV has one GEM well per row.

Column	Example value
GEM_well_ID	your_GEM_well
GEM_well_dataset	your_dataset
GEM_well_donor_id	donor_1
GEM_well_n_donors	1
GEM_well_cellranger_arc_count_dir	/path/to/your_GEM_well
GEM_well_cellranger_arc_reference_json	/path/to/reference.json
GEM_well_add_cellbender	FALSE
GEM_well_cellbender_h5_file	NA
GEM_well_donors_VCF_file	NA
GEM_well_is_active	TRUE
GEM_well_multiplex_batch	batch_1

Set GEM_well_QC_exclude_list to the exclusions chosen for your data. Follow the numbered QC reviews; do not treat the demo’s numerical cutoffs as recommendations for your tissue.

GEM_well_cellranger_arc_reference_json must point to the reference.json from the exact Cell Ranger ARC reference used to create that GEM well’s output. multiomeR checks that the JSON genome matches the feature HDF5 and rejects aggregations whose GEM wells use different references.

GEM_well_QC_exclude_list contains zero or more complete R filter expressions separated by ;;. Expressions are evaluated individually against per-barcode metadata, preserving their order and their separate exclusion reasons. An empty field applies no pre-aggregation QC filters.

AMULET doublet detection runs as part of the standard QC calculation; see the implementation and validation for details.

GEM_well_cellranger_arc_count_dir points to the directory containing outs/, not to outs/ itself. The baseline pipeline requires:

Text

<GEM_well_cellranger_arc_count_dir>/outs/
|-- summary.csv
|-- filtered_feature_bc_matrix.h5
|-- atac_fragments.tsv.gz
|-- atac_fragments.tsv.gz.tbi
`-- per_barcode_metrics.csv

If GEM_well_donors_VCF_file is configured, atac_possorted_bam.bam is also required for cellsnp-lite. Without a VCF, the pipeline skips genotype demultiplexing and assigns GEM_well_donor_id to every called nucleus. That donor ID must match the donor metadata table.

6.1.2 2. Create keyed donor metadata

The donor metadata table must contain one unique row per donor_id:

donor_metadata.tsv

donor_id    condition
donor_1 control

Put donor-specific phenotypes and covariates in the donor table. Put library-, run-, or batch-specific variables directly in cfg_GEM_wells.tsv, using a GEM_well_ prefix. Apart from their key columns, donor and GEM-well metadata must not reuse column names.

6.1.3 3. Define one aggregation

cfg_aggregations.yaml

your_aggregation:
  aggregation_GEM_well_IDs: [your_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

Replace GENE1–GENE4 with gene symbols appropriate for the tissue and reference. Omit modules for the first run. After reviewing the main results, you can enable optional analyses by adding their module names here and a matching aggregation entry in each module’s configuration.

6.1.4 4. Validate before running

From the repository-root R session, construct the graph and inspect the targets created for the aggregation:

R

manifest <- targets::tar_manifest(callr_function = NULL)

manifest |>
  dplyr::filter(stringr::str_ends(name, ".your_aggregation")) |>
  dplyr::select(name, description)

Manifest construction validates the YAML parameter schema, aggregation references to GEM wells, module names and rows, and controller setup. Metadata file contents are validated when their targets run. Fix manifest-time errors before calling tar_make(), then continue to Running the workflow.

6.2 Configuration reference

The searchable overviews below are generated from cfg_pipeline_parameters.tsv, the same manifest used for runtime defaults and validation. Use them to change a default after the minimum configuration works.

6.2.1 GEM well columns

Use the GEM-well example to check the full set of columns.

The table below is a documentation snapshot of the two public demo wells, showing the core columns and one optional annotation. Bold columns must be present in the TSV; some allow an NA value. Scroll horizontally and focus or hover over a column’s i button for its meaning. The other inactive rows and metadata columns in the public configuration remain available as examples.

cfg_GEM_wells.tsv

GEM_well_IDGEM well ID. Stable ID used by aggregations and target names. Must be unique. Use the same value in aggregation_GEM_well_IDs.	GEM_well_datasetDataset. Groups related GEM wells for pre-aggregation summaries. This is a processing and reporting group, not the donor identifier.	GEM_well_donor_idDonor ID. Links a non-multiplexed GEM well to donor metadata. Use NA when donor identities will instead be resolved from a configured VCF.	GEM_well_n_donorsExpected donors. States how many donors are expected in the GEM well. Use 1 for an unmultiplexed well containing one donor.	GEM_well_cellranger_arc_count_dirCell Ranger ARC count directory. Locates the Cell Ranger ARC count output for this GEM well. Point to the directory containing outs, not to outs itself.	GEM_well_add_cellbenderUse CellBender. Chooses whether corrected GEX counts replace the Cell Ranger counts. When TRUE, the configured or standard-layout CellBender H5 file must exist.	GEM_well_cellbender_h5_fileCellBender H5 file. Optionally gives the corrected GEX count file. Leave as NA when CellBender is disabled or its standard-layout path is used.	GEM_well_donors_VCF_fileDonor VCF file. Optionally enables genotype-based donor demultiplexing. Without a VCF, every called nucleus receives GEM_well_donor_id.	GEM_well_cellranger_arc_reference_jsonReference JSON. Identifies the exact Cell Ranger ARC reference used for count. The genome must match the feature H5, and all GEM wells in an aggregation must use compatible references.	GEM_well_QC_exclude_listPre-aggregation QC filters. Defines per-barcode filters applied before aggregation. Write complete R expressions separated by ;;. An empty value applies no filters.	GEM_well_is_activeActive. Controls whether processing targets are constructed for this GEM well. Every GEM well selected by an active aggregation must also be active.	GEM_well_cell_sortingCell or nuclei sorting. Describes sorting or enrichment before library preparation. Example optional metadata column for values such as sorted, depleted, or unsorted material. Add other GEM_well_ columns when your analysis needs them.
healthy_PBMC_human	immune_human_dataset	pbmc1	1	example_data/healthy_PBMC_human	FALSE	NA	NA	reference_metadata/refdata-cellranger-arc-GRCh38-2020-A-2.0.0/reference.json	TSS.enrichment < 4 ;; nucleosome_signal > 4 ;; nCount_RNA < 250 ;; RNA_mito_percent > 10	TRUE	granulocytes_removed
lymphoma_lymph_human	immune_human_dataset	lymph1	1	example_data/lymphoma_lymph_human	FALSE	NA	NA	reference_metadata/refdata-cellranger-arc-GRCh38-2020-A-2.0.0/reference.json	TSS.enrichment < 4 ;; nucleosome_signal > 4 ;; nCount_RNA < 250 ;; RNA_mito_percent > 10	TRUE	sorted_nuclei

6.2.2 Aggregation parameters

See the aggregation example for a complete configuration. Search by name or purpose, or choose a topic. Defaults are visible beside each parameter; open a row for its type and example.

Find a parameter Topic All topics

Required: supply a value directly or through inheritance. Defaulted: a value is provided. Optional: may remain NULL. Open a parameter for its type, allowed values and example.

Show the public immune_human_2x example

YAML

immune_human_2x:
  is_active: true
  aggregation_donor_id_metadata_tsv: example_data/immune_human_dataset_donor_id_metadata.tsv
  aggregation_GEM_well_IDs: [healthy_PBMC_human, lymphoma_lymph_human]
  aggregation_GEX_marker_genes:
    B: [MS4A1, CD79A]
    Mono: [LYZ, S100A9]
    NK: [KLRD1, GNLY]
    pDC: [LILRA4, CLEC4C]
    Plasma: [MZB1, JCHAIN]
    T: [TRAC, CD3D]
  modules: [differential_analyses, genetic_enrichment]
  aggregation_categorical_vars: [condition, GEM_well_tissue, GEM_well_cell_sorting, GEM_well_instrument, GEM_well_target_recovery]
  aggregation_QC_exclude_list_combined_object:
    - nCount_ATAC < 1000
    - atac_peak_counts_frac < 0.1
    - atac_peak_counts_blacklist_frac > 0.01
  aggregation_ATAC_marker_TFs:
    B: [EBF1]
    Mono: [CEBPA, CEBPB]
    NK: [EOMES, TBX21]
    pDC: [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