Project an assay into an existing PCA reference space

Projects normalized expression from a query assay into a PCA model fitted on a reference assay. The original PCA feature set, reference gene means and standard deviations, and PCA loadings are reused so that reference and query coordinates share the same geometric ruler.

Usage

ProjectPCAReference(
  seurat_object,
  query_assay,
  reference_assay = "RNA",
  reference_reduction = "pca",
  dims = NULL,
  layer = "data",
  scale.max = 10,
  reduction.name = NULL,
  reduction.key = NULL,
  unchanged.cells = NULL,
  tolerance = 1e-06,
  block.size = 5000L,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

seurat_object: A Seurat object containing the reference assay, query assay, and reference PCA reduction.
query_assay: Name of the assay to project.
reference_assay: Name of the assay used to fit the reference PCA.
reference_reduction: Name of the stored PCA reduction to reuse.
dims: Leading sequence of reference PCs to project, such as 1:30. If NULL, all stored loading columns are used. Seurat reductions require consecutive dimension identifiers, so skipped or reordered PCs are rejected.
layer: Expression layer used to reconstruct scaling and project the query. Usually "data" for log-normalized expression.
scale.max: Upper clipping value used when the reference assay was scaled. This must match the original ScaleData() call. Use Inf for no clipping. Seurat clips values greater than scale.max.
reduction.name: Name for the projected reduction. Defaults to paste0(query_assay, "_pca_fixed").
reduction.key: Optional key for the projected dimensions. If NULL, a valid key is derived from reduction.name.
unchanged.cells: Optional character vector of cells known to be unchanged between the reference and query assays. Their expression and projected coordinates are checked within tolerance.
tolerance: Maximum allowed absolute reconstruction or unchanged-cell error.
block.size: Number of query cells projected per block.
overwrite: Logical; overwrite an existing reduction.name when TRUE.
verbose: Logical; print progress and validation messages.

Value

The input Seurat object with the fixed-reference query coordinates stored as a new dimensional reduction. Projection parameters and validation results are stored in the reduction's misc$fixed_reference field.

Details

ProjectPCAReference() is intended for comparisons such as observed versus in-silico perturbed expression stored as separate assays in the same Seurat object. It does not refit PCA and does not modify either assay or the original reduction.

By default, reference scaling parameters are reconstructed from the reference_assay data layer. The reconstructed scaled values and PCA scores must reproduce the stored scale.data and reference PCA embeddings within tolerance. This validation deliberately rejects PCA models produced with incompatible preprocessing, such as regression in ScaleData(), rather than silently creating a non-comparable projection.

The query layer must already use the same normalization definition as the reference layer. In particular, the function does not call NormalizeData().

Examples

if (FALSE) { # \dontrun{
object <- ProjectPCAReference(
  object,
  reference_assay = "RNA",
  query_assay = "M6_up",
  reference_reduction = "pca",
  dims = 1:30,
  unchanged.cells = WhichCells(object, expression = treatment == "Bortezomib")
)

pre <- ComputeDistance(
  object, "treatment_subcluster", "pca", method = "edist", dims = 1:30
)
post <- ComputeDistance(
  object, "treatment_subcluster", "M6_up_pca_fixed",
  method = "edist", dims = 1:30
)
HeatmapDistance(pre, post)
} # }