Load, QC, and merge 10X scRNA-seq samples

Iterates over a list of samples, reads the 10X count data, optionally adds per-cell annotation CSVs, attaches per-sample metadata, runs DoubletFinder and miQC quality control, saves per-sample QC plots, and finally merges all objects into a single Seurat object.

Usage

LoadSamplesRNA(
  sample_ids,
  run_ids = NULL,
  run_ids_x = NULL,
  input_type = c("h5", "10x_dir"),
  data_paths = NULL,
  metadata = NULL,
  sample_id_col = "sample_id",
  base_dir = NULL,
  h5_template = paste0("{base_dir}/{run_id}/per_sample_outs/", "{run_id_x}/count/",
    "sample_filtered_feature_bc_matrix.h5"),
  matrix_dir_template = "{base_dir}/{run_id}/filtered_feature_bc_matrix",
  cellanno_template = paste0("{base_dir}/{run_id}/per_sample_outs/", "{run_id_x}/count/",
    "cell_types/cell_types.csv"),
  output_dir,
  robj_dir = NULL,
  merged_filename = "merged_object.rds",
  save_individual = FALSE,
  resume = FALSE,
  individual_dir = NULL,
  min.features = 100L,
  mt_pattern = "^MT-",
  run_doublet = TRUE,
  doublet_rate = NULL,
  run_miqc = TRUE,
  miqc_posterior = 0.95,
  force_assay_v3 = TRUE,
  merge_samples = TRUE,
  add_cell_ids = NULL,
  modality = c("scRNA-seq", "snRNA-seq")
)

Arguments

sample_ids: Character vector of human-readable sample IDs (e.g. c("HC1","HC2","AD1")). Used as Seurat project names and as the key column when matching metadata.
run_ids: Character vector of Cellranger run IDs corresponding to sample_ids (e.g. paste0("MYSC", 220:223)). Used to build h5 / matrix paths and as cell-id prefixes on merge. NULL (allowed only when data_paths is supplied) falls back to sample_ids.
run_ids_x: Character vector or NULL. The "underscored" form of run_ids used in per_sample_outs/ subdirectory names (e.g. paste0("MYSC_", 220:223)). NULL auto-generates by inserting _ before the trailing digit block: "MYSC220" → "MYSC_220".
input_type: Character. How to read each sample's counts: "h5" (default) uses Seurat::Read10X_h5(); "10x_dir" uses Seurat::Read10X() on a matrix folder. Ignored if data_paths already points at the right kind of source (the type is still used to pick the reader, so set it to match your data_paths).
data_paths: Character vector or NULL. Exact path to each sample's data source (an h5 file when input_type = "h5", or a matrix folder when input_type = "10x_dir"), one entry per sample_ids. When supplied, base_dir and the path templates are bypassed entirely. Default NULL.
metadata: Data frame or NULL. One row per sample; must contain a column matching sample_id_col. All other columns are attached to @meta.data. NULL skips this step (metadata must be added manually afterwards).
sample_id_col: Character. Name of the column in metadata that matches sample_ids. Default "sample_id".
base_dir: Character or NULL. Root directory containing the Cellranger run folders (one subfolder per run_id). Required unless data_paths is supplied.
h5_template: Character. Path template for the h5 file (input_type = "h5"). Available placeholders: {base_dir}, {run_id}, {run_id_x}. Default matches Cellranger-multi per-sample output layout.
matrix_dir_template: Character. Path template for the 10X matrix folder (input_type = "10x_dir"). Same placeholders as h5_template. Default "{base_dir}/{run_id}/filtered_feature_bc_matrix".
cellanno_template: Character or NULL. Path template for the per-cell annotation CSV (e.g. from Cellranger cell-type calling). NULL disables cell annotation loading. Files that do not exist are silently skipped per sample - it is safe to provide a template even when only some samples have the file.
output_dir: Character. Directory for per-sample QC PDF plots.
robj_dir: Character or NULL. Directory for saving the final merged Seurat object. NULL skips saving.
merged_filename: Character. Filename for the saved merged object. Default "merged_object.rds".
save_individual: Logical. Save each fully-processed sample as its own <sample_id>.rds in individual_dir as it finishes. Combined with resume = TRUE, this lets a long load survive interruptions. Default FALSE.
resume: Logical. Before processing a sample, check individual_dir for an existing <sample_id>.rds; if found, load it and skip all re-processing (read, QC, doublets, miQC) for that sample. Default FALSE.
individual_dir: Character or NULL. Directory for the per-sample .rds files used by save_individual / resume. NULL defaults to <robj_dir or output_dir>/Individual_Samples.
min.features: Integer. Minimum features per cell for CreateSeuratObject(). Default 100.
mt_pattern: Character. Regex pattern for mitochondrial genes. Default "^MT-" (human). Use "^mt-" for mouse.
run_doublet: Logical. Run SCP::db_scDblFinder() doublet detection? Default TRUE.
doublet_rate: Numeric or NULL. Expected doublet rate per 1 000 cells loaded. NULL auto-computes as ncol(seurat_object) / 1000 * 0.01.
run_miqc: Logical. Run SeuratWrappers::RunMiQC()? Default TRUE.
miqc_posterior: Numeric. miQC posterior probability cutoff. Cells above this are flagged as low quality. Default 0.95.
force_assay_v3: Logical. Convert the RNA assay to Seurat v3 format (as(seurat_object[["RNA"]], "Assay")) after creation? Needed for compatibility with older packages. Default TRUE.
merge_samples: Logical. Merge all sample objects into one Seurat object at the end? Default TRUE.
add_cell_ids: Character vector or NULL. Prefix added to each cell barcode on merge. NULL uses run_ids.
modality: Character. Sequencing modality label stored in the merged object's metadata and @misc$scSidekick_params. One of "scRNA-seq" (default) or "snRNA-seq".

Value

If merge_samples = TRUE, the merged Seurat object (invisibly). If merge_samples = FALSE, a named list of individual Seurat objects.

Input methods

Three ways to point the function at your data:

h5 files via templates (default, input_type = "h5"): paths built from base_dir + h5_template using Read10X_h5(). Matches Cellranger-multi output.
10X matrix folders via templates (input_type = "10x_dir"): paths built from base_dir + matrix_dir_template and read with Read10X(). Each folder must contain barcodes.tsv(.gz), features.tsv(.gz), and matrix.mtx(.gz) (the Cellranger filtered_feature_bc_matrix/ directory).
Explicit paths (data_paths = ...): a character vector of exact h5 files or matrix folders, one per sample, used verbatim. Use this when your samples are not organized in a consistent layout. base_dir and the templates are then ignored for path building.

Metadata (recommended - `metadata` data.frame)

Pass a data.frame with one row per sample. The column named by sample_id_col must match sample_ids exactly. Every other column is added to @meta.data automatically.

sample_meta <- data.frame(
  sample_id = c("HC1","HC2","AD1","FTD1"),
  run_id    = c("MYSC220","MYSC221","MYSC222","MYSC223"),
  patient   = c("Firstable","Cododge","Transferism","Promiseable"),
  group     = c("HC","HC","AD","FTD"),
  sex       = c("M","F","M","F"),
  batch     = c(1L, 1L, 1L, 1L)
)

Path templates

Paths are built from base_dir, run_id, and run_id_x using {placeholder} substitution. The defaults match Cellranger-multi output:

{base_dir}/{run_id}/per_sample_outs/{run_id_x}/count/
  sample_filtered_feature_bc_matrix.h5