Seurat (version 6.0.0)

RunPLS: Run Partial Least Squares (PLS) on Seurat Objects

Description

Performs Partial Least Squares regression analysis on single-cell data. This function provides methods for plsr, spls, and cppls from the pls and spls packages.

Usage

RunPLS(object, ...)
# S3 method for default
RunPLS(
  object,
  assay = NULL,
  ncomp = 20,
  Y = NULL,
  Y.add = NULL,
  pls.function = c("plsr", "spls", "cppls"),
  verbose = TRUE,
  ndims.print = 1:5,
  nfeatures.print = 30,
  reduction.name = "pls",
  reduction.key = "PLS_",
  seed.use = 42,
  eta = 0.5,
  threads = NULL,
  ...
)
# S3 method for IterableMatrix
RunPLS(
  object,
  assay = NULL,
  ncomp = 20,
  Y = NULL,
  Y.add = NULL,
  pls.function = c("plsr", "spls", "cppls"),
  verbose = TRUE,
  ndims.print = 1:5,
  nfeatures.print = 30,
  reduction.name = "pls",
  reduction.key = "PLS_",
  seed.use = 42,
  eta = 0.5,
  threads = NULL,
  ...
)
# S3 method for Assay
RunPLS(
  object,
  assay = NULL,
  features = NULL,
  layer = "scale.data",
  ncomp = 20,
  Y = NULL,
  Y.add = NULL,
  pls.function = c("plsr", "spls", "cppls"),
  verbose = TRUE,
  ndims.print = 1:5,
  nfeatures.print = 30,
  reduction.name = "pls",
  reduction.key = "PLS_",
  seed.use = 42,
  eta = 0.5,
  threads = NULL,
  materialize = FALSE,
  materialize.dir = NULL,
  overwrite = FALSE,
  ...
)
# S3 method for StdAssay
RunPLS(
  object,
  assay = NULL,
  features = NULL,
  layer = "scale.data",
  ncomp = 20,
  Y = NULL,
  Y.add = NULL,
  pls.function = c("plsr", "spls", "cppls"),
  verbose = TRUE,
  ndims.print = 1:5,
  nfeatures.print = 30,
  reduction.name = "pls",
  reduction.key = "PLS_",
  seed.use = 42,
  eta = 0.5,
  threads = NULL,
  materialize = FALSE,
  materialize.dir = NULL,
  overwrite = FALSE,
  ...
)
# S3 method for Seurat
RunPLS(
  object,
  assay = NULL,
  features = NULL,
  ncomp = 20,
  Y = NULL,
  Y.add = NULL,
  pls.function = c("plsr", "spls", "cppls"),
  verbose = TRUE,
  ndims.print = 1:5,
  nfeatures.print = 30,
  reduction.name = "pls",
  reduction.key = "PLS_",
  seed.use = 42,
  eta = 0.5,
  threads = NULL,
  materialize = FALSE,
  materialize.dir = NULL,
  overwrite = FALSE,
  ...
)

Value

Returns a DimReduc object with PLS results

Arguments

object

An object to run PLS on

...

Additional arguments to be passed to the PLS function

assay

Name of Assay PLS is being run on

ncomp

Number of components to compute

Y

The response variable(s) for PLS regression. Accepted formats:

• A character vector of column names in the Seurat object metadata (Seurat method only).

• A data.frame, which is converted via model.matrix(~. + 0, data = Y).

• A numeric matrix (used as-is).

• A numeric vector (promoted to a single-column matrix).

The number of rows must match the number of cells/samples, and no cell can have a missing (NA) response.

Y.add

Additional response variable(s) containing relevant information about the observations. Only used for cppls. Accepts the same formats as Y.

pls.function

PLS function from pls package to run (options: plsr, spls, cppls)

verbose

Print progress messages, diagnostics (e.g. R2), and the top genes associated with high/low loadings for the components

ndims.print

components to print genes for

nfeatures.print

Number of genes to print for each component

reduction.name

the name of the DimReduc object

reduction.key

dimensional reduction key, specifies the string before the number for the dimension names.

seed.use

Set a random seed. Setting NULL will not set a seed.

eta

Thresholding parameter that controls the sparsity of the spls method (larger --> sparser). eta should be between 0 and 1.

threads

Integer; number of threads for BPCells parallel computation (IterableMatrix path only). NULL (default) uses the package-wide thread count set by setThreads (1 unless changed); 0 = auto-detect via parallel::detectCores(logical = FALSE); values \(\ge 1\) use that many threads. Ignored for in-memory data.

features

Features to compute PLS on

layer

The layer in assay to use when running PLS analysis. Sparse in-memory layers, such as an in-memory data layer, are not supported and raise an error.

materialize

Logical; for on-disk (BPCells) assays only. If TRUE, the feature-subsetted matrix is written once to a single contiguous BPCells store before PLS, instead of re-streaming a fragmented lazy chain on each of the ~2*ncomp+3 passes. This can substantially speed up PLS on a CellAnova-corrected assay whose on-disk root is a per-sample ColBindMatrices. Ignored for in-memory data. Default FALSE.

materialize.dir

Directory for the materialized matrix (only used when materialize = TRUE). NULL (default) writes to a temporary directory that is removed after PLS completes; supplying a path keeps the matrix there for reuse by downstream steps.

overwrite

Logical; only used when materialize = TRUE and a materialize.dir is supplied. Passed to BPCells::write_matrix_dir() to control whether an existing directory may be overwritten. Default FALSE so that a non-empty materialize.dir is never clobbered without explicit consent.

Examples

if (FALSE) {
# Run PLS on a Seurat object using metadata column names
seurat_obj <- RunPLS(seurat_obj, Y = "condition", ncomp = 10)

# Run PLS with a pre-built numeric design matrix
design_mat <- model.matrix(~ age + sex, data = seurat_obj[[]])
seurat_obj <- RunPLS(seurat_obj, Y = design_mat, ncomp = 10)
}