PrepareSampleObject: Perform preprocessing procedures for a Seurat object to prepare for the sample-level analysis

Description

This is a wrapper function to apply landmark sketching, training data sketching (optional), PLS learning, and a nearest neighbor workflow to a single-cell Seurat object to get the necessary components for sample-level analyses later. The output object can be directly used by GenerateSampleObject to obtain a sample-level matrix.

Usage

PrepareSampleObject(
  object = NULL,
  assay = NULL,
  add.hvg = TRUE,
  group.by.CorTest = NULL,
  Y = NULL,
  sketch.training = TRUE,
  group.by.Sketch = NULL,
  ncells.per.group = 1000,
  training.assay.name = "TRAINING",
  training.sketch.method = "Uniform",
  ncells.landmark = 2000,
  landmark.assay.name = "LANDMARK",
  landmark.sketch.method = "LeverageScore",
  ncomp = 10,
  pls.function = c("plsr", "spls", "cppls"),
  pls.reduction.name = "pls",
  modality = c("multi", "single"),
  k.nn = 5,
  knn.range = 200,
  l2.norm = TRUE,
  name.reduction.1 = "pca",
  dims.reduction.1 = 1:30,
  nn.name = "weighted.nn",
  weighted.nn.name = NULL,
  fix.wnn.weights = c(0.5, 0.5),
  rm.training.assay = FALSE,
  verbose = TRUE
)

Value

return a Seurat object that contains a weighted.nn Neighbor object between the landmark cells and all the other cells. the Seurat object will also contain a landmark assay (and a training assay if sketch.training == TRUE).

Arguments

object: a Seurat object.
assay: the assay to perform the analyses on
add.hvg: a boolen to specify whether the function runs additional correlation test between features and response (Y) to obtain more response-relevant features to be included in VariableFeatures and used for PLS learning. See QuickCorTest for details. Default is TRUE.
group.by.CorTest: A metadata column name to group cells by before QuickCorTest. If NULL, falls back to QuickCorTest without grouping. Default is NULL.
Y: A metadata column name of responses. Will also be used as the responses for PLS learning. No cell in 'assay' can have a missing (NA) response, including cells that would not be sketched into the training subset.
sketch.training: a boolen to specify whether the function performs sketching for the Seurat object to get a training subset for PLS learning (the PLS learned from subset will be projected to the full data). For efficiency, it is recommended to do so when the Seurat object is very large. If the 'assay' being specified for this Seurat object is an on-disk assay, this parameter must be set to TRUE. Default is TRUE.
group.by.Sketch: A metadata column name to group cells by before sketching. If NULL, falls back to standard sketching without grouping. Default is NULL.
ncells.per.group: A positive integer, named vector, or list specifying the number of cells to sample. Default is 1000 per category in 'group.by.Sketch'. See SketchDataByGroup for detailed usage.
training.assay.name: The assay name of the training data.
training.sketch.method: Sketching method to use for the training subset. Can be 'LeverageScore' or 'Uniform'. Default is 'Uniform' because for training we want to obtain an unbiased subset of the original data. See LeverageScore for details.
ncells.landmark: A positive integer specifying the number of 'landmark cells'. The function will generate a new assay for these 'landmark cells' (please do not confuse it with the training subset). The landmark cells should be a subset that covers the diverse cell types and cell states of the data. Default is 2000.
landmark.assay.name: The assay name of the landmark cells. Default is "LANDMARK".
landmark.sketch.method: Sketching method to use for the landmark cells. Can be 'LeverageScore' or 'Uniform'. Default is 'LeverageScore' because we want the landmark cells to be as diverse/representative as possible. See LeverageScore for details.
ncomp: Number of components to compute
pls.function: PLS function from pls package to run (options: plsr, spls, cppls)
pls.reduction.name: PLS dimensional reduction name
modality: Whether to build the neighbor graph from two modalities or one. "multi" (default) combines name.reduction.1 with the PLS embedding via WNN (FindmmNN); "single" uses the PLS embedding alone (FindsmNN). In "single" mode, name.reduction.1, dims.reduction.1, knn.range, and fix.wnn.weights are ignored.
k.nn: The number of nearest neighbors to compute for each modality
knn.range: Range parameter for nearest neighbor search. Passed to FindmmNN, which clamps it to the number of landmark cells if it exceeds that. Default is 200. Ignored when modality = "single".
l2.norm: Perform L2 normalization on the cell embeddings during the nearest neighbor process. Default is TRUE.
name.reduction.1: The name of the DimReduc to use as the 1st embedding (the 2nd is the PLS embedding) in the WNN process. Ignored when modality = "single".
dims.reduction.1: The dimensions for reduction.1 to use during the WNN process. Ignored when modality = "single".
nn.name: Name of the output neighbor object. Defaults to "weighted.nn" for modality = "multi", and to "single.nn" for modality = "single" (unless set explicitly).
weighted.nn.name: Deprecated. Use nn.name instead.
fix.wnn.weights: Pre-specified modality weights. If provided, skips the calculation and uses these weights directly. Should be a list with the same length as reduction.list. Ignored when modality = "single".
rm.training.assay: Whether to remove the training assay after running PrepareSampleObject(). This is used to reduce the memory usage when the seurat object is large (e.g., a large on-disk object). Default is FALSE.
verbose: Print progress and diagnostic messages

Details

Two modalities are supported (see the modality argument). The default multi-modal path combines an existing reduction (e.g. PCA, via name.reduction.1) with the PLS embedding using the weighted nearest neighbor (WNN) workflow (FindmmNN). The single-modal path builds the neighbor graph from the PLS embedding alone (FindsmNN), which is useful when no complementary reduction is available or desired.