liger-class: liger class

In rliger: Linked Inference of Genomic Experimental Relationships

liger class

Description

liger object is the main data container for LIGER analysis in R. The slot datasets is a list where each element should be a ligerDataset object containing dataset specific information, such as the expression matrices. The other parts of liger object stores information that can be shared across the analysis, such as the cell metadata.

This manual provides explanation to the liger object structure as well as usage of class-specific methods. Please see detail sections for more information.

For liger objects created with older versions of rliger package, please try updating the objects individually with convertOldLiger.

Usage

datasets(x, check = NULL)

datasets(x, check = TRUE) <- value

dataset(x, dataset = NULL)

dataset(x, dataset, type = NULL, qc = TRUE) <- value

cellMeta(
  x,
  columns = NULL,
  useDatasets = NULL,
  cellIdx = NULL,
  as.data.frame = FALSE,
  ...
)

cellMeta(
  x,
  columns = NULL,
  useDatasets = NULL,
  cellIdx = NULL,
  inplace = FALSE,
  check = FALSE
) <- value

defaultCluster(x, useDatasets = NULL, ...)

defaultCluster(x, name = NULL, useDatasets = NULL, ...) <- value

dimReds(x)

dimReds(x) <- value

dimRed(x, name = NULL, useDatasets = NULL, cellIdx = NULL, ...)

dimRed(x, name = NULL, useDatasets = NULL, cellIdx = NULL, ...) <- value

defaultDimRed(x, useDatasets = NULL, cellIdx = NULL)

defaultDimRed(x) <- value

varFeatures(x)

varFeatures(x, check = TRUE) <- value

varUnsharedFeatures(x, dataset = NULL)

varUnsharedFeatures(x, dataset, check = TRUE) <- value

commands(x, funcName = NULL, arg = NULL)

## S4 method for signature 'liger'
show(object)

## S4 method for signature 'liger'
dim(x)

## S4 method for signature 'liger'
dimnames(x)

## S4 replacement method for signature 'liger,list'
dimnames(x) <- value

## S4 method for signature 'liger'
datasets(x, check = NULL)

## S4 replacement method for signature 'liger,logical'
datasets(x, check = TRUE) <- value

## S4 replacement method for signature 'liger,missing'
datasets(x, check = TRUE) <- value

## S4 method for signature 'liger,character_OR_NULL'
dataset(x, dataset = NULL)

## S4 method for signature 'liger,missing'
dataset(x, dataset = NULL)

## S4 method for signature 'liger,numeric'
dataset(x, dataset = NULL)

## S4 replacement method for signature 'liger,character,missing,ANY,ligerDataset'
dataset(x, dataset, type = NULL, qc = TRUE) <- value

## S4 replacement method for signature 'liger,character,ANY,ANY,matrixLike'
dataset(x, dataset, type = c("rawData", "normData"), qc = FALSE) <- value

## S4 replacement method for signature 'liger,character,missing,ANY,NULL'
dataset(x, dataset, type = NULL, qc = TRUE) <- value

## S3 method for class 'liger'
names(x)

## S3 replacement method for class 'liger'
names(x) <- value

## S3 method for class 'liger'
length(x)

## S3 method for class 'liger'
lengths(x, use.names = TRUE)

## S4 method for signature 'liger,NULL'
cellMeta(
  x,
  columns = NULL,
  useDatasets = NULL,
  cellIdx = NULL,
  as.data.frame = FALSE,
  ...
)

## S4 method for signature 'liger,character'
cellMeta(
  x,
  columns = NULL,
  useDatasets = NULL,
  cellIdx = NULL,
  as.data.frame = FALSE,
  ...
)

## S4 method for signature 'liger,missing'
cellMeta(
  x,
  columns = NULL,
  useDatasets = NULL,
  cellIdx = NULL,
  as.data.frame = FALSE,
  ...
)

## S4 replacement method for signature 'liger,missing'
cellMeta(x, columns = NULL, useDatasets = NULL, cellIdx = NULL, check = FALSE) <- value

## S4 replacement method for signature 'liger,character'
cellMeta(
  x,
  columns = NULL,
  useDatasets = NULL,
  cellIdx = NULL,
  inplace = TRUE,
  check = FALSE
) <- value

## S4 method for signature 'liger'
rawData(x, dataset = NULL)

## S4 replacement method for signature 'liger,ANY,ANY,matrixLike_OR_NULL'
rawData(x, dataset = NULL, check = TRUE) <- value

## S4 replacement method for signature 'liger,ANY,ANY,H5D'
rawData(x, dataset = NULL, check = TRUE) <- value

## S4 method for signature 'liger'
normData(x, dataset = NULL)

## S4 replacement method for signature 'liger,ANY,ANY,matrixLike_OR_NULL'
normData(x, dataset = NULL, check = TRUE) <- value

## S4 replacement method for signature 'liger,ANY,ANY,H5D'
normData(x, dataset = NULL, check = TRUE) <- value

## S4 method for signature 'liger,ANY'
scaleData(x, dataset = NULL)

## S4 replacement method for signature 'liger,ANY,ANY,matrixLike_OR_NULL'
scaleData(x, dataset = NULL, check = TRUE) <- value

## S4 replacement method for signature 'liger,ANY,ANY,H5D'
scaleData(x, dataset = NULL, check = TRUE) <- value

## S4 replacement method for signature 'liger,ANY,ANY,H5Group'
scaleData(x, dataset = NULL, check = TRUE) <- value

## S4 method for signature 'liger,character'
scaleUnsharedData(x, dataset = NULL)

## S4 method for signature 'liger,numeric'
scaleUnsharedData(x, dataset = NULL)

## S4 replacement method for signature 'liger,ANY,ANY,matrixLike_OR_NULL'
scaleUnsharedData(x, dataset = NULL, check = TRUE) <- value

## S4 replacement method for signature 'liger,ANY,ANY,H5D'
scaleUnsharedData(x, dataset = NULL, check = TRUE) <- value

## S4 replacement method for signature 'liger,ANY,ANY,H5Group'
scaleUnsharedData(x, dataset = NULL, check = TRUE) <- value

## S4 method for signature 'liger,ANY,ANY,ANY'
getMatrix(
  x,
  slot = c("rawData", "normData", "scaleData", "scaleUnsharedData", "H", "V", "U", "A",
    "B", "W", "H.norm"),
  dataset = NULL,
  returnList = FALSE
)

## S4 method for signature 'liger,ANY'
getH5File(x, dataset = NULL)

## S3 replacement method for class 'liger'
x[[i]] <- value

## S3 method for class 'liger'
x$name

## S3 replacement method for class 'liger'
x$name <- value

## S4 method for signature 'liger'
defaultCluster(x, useDatasets = NULL, droplevels = FALSE, ...)

## S4 replacement method for signature 'liger,ANY,ANY,character'
defaultCluster(x, name = NULL, useDatasets = NULL, ...) <- value

## S4 replacement method for signature 'liger,ANY,ANY,factor'
defaultCluster(x, name = NULL, useDatasets = NULL, droplevels = TRUE, ...) <- value

## S4 replacement method for signature 'liger,ANY,ANY,NULL'
defaultCluster(x, name = NULL, useDatasets = NULL, ...) <- value

## S4 method for signature 'liger'
dimReds(x)

## S4 replacement method for signature 'liger,list'
dimReds(x) <- value

## S4 method for signature 'liger,missing_OR_NULL'
dimRed(x, name = NULL, useDatasets = NULL, cellIdx = NULL, ...)

## S4 method for signature 'liger,index'
dimRed(x, name = NULL, useDatasets = NULL, cellIdx = NULL, ...)

## S4 replacement method for signature 'liger,index,ANY,ANY,NULL'
dimRed(x, name = NULL, useDatasets = NULL, cellIdx = NULL, ...) <- value

## S4 replacement method for signature 'liger,character,ANY,ANY,matrixLike'
dimRed(
  x,
  name = NULL,
  useDatasets = NULL,
  cellIdx = NULL,
  asDefault = NULL,
  inplace = FALSE,
  ...
) <- value

## S4 method for signature 'liger'
defaultDimRed(x, useDatasets = NULL, cellIdx = NULL)

## S4 replacement method for signature 'liger,character'
defaultDimRed(x) <- value

## S4 method for signature 'liger'
varFeatures(x)

## S4 replacement method for signature 'liger,ANY,character'
varFeatures(x, check = TRUE) <- value

## S4 method for signature 'liger,ANY'
varUnsharedFeatures(x, dataset = NULL)

## S4 replacement method for signature 'liger,ANY,ANY,character'
varUnsharedFeatures(x, dataset, check = TRUE) <- value

## S3 method for class 'liger'
fortify(model, data, ...)

## S3 method for class 'liger'
c(...)

## S4 method for signature 'liger'
commands(x, funcName = NULL, arg = NULL)

## S4 method for signature 'ligerDataset,missing'
varUnsharedFeatures(x, dataset = NULL)

## S4 replacement method for signature 'ligerDataset,missing,ANY,character'
varUnsharedFeatures(x, dataset = NULL, check = TRUE) <- value

Arguments

x, object, model	A liger object
check	Logical, whether to perform object validity check on setting new value. Users are not supposed to set FALSE here.
value	Metadata value to be inserted
dataset	Name or numeric index of a dataset
type	When using dataset<- with a matrix like value, specify what type the matrix is. Choose from "rawData", "normData" or "scaleData".
qc	Logical, whether to perform general qc on added new dataset.
columns	The names of available variables in cellMeta slot. When as.data.frame = TRUE, please use variable names after coercion.
useDatasets	Setter or getter method should only apply on cells in specified datasets. Any valid character, numeric or logical subscriber is acceptable. Default NULL works with all datasets.
cellIdx	Valid cell subscription to subset retrieved variables. Default NULL uses all cells.
as.data.frame	Logical, whether to apply as.data.frame on the subscription. Default FALSE.
...	See detailed sections for explanation.
inplace	For cellMeta<- method, when columns is for existing variable and useDatasets or cellIdx indicate partial insertion to the object, whether to by default (TRUE) in-place insert value into the variable for selected cells or to replace the whole variable with non-selected part left as NA.
name	The name of available variables in cellMeta slot or the name of a new variable to store.
funcName, arg	See Command records section.
use.names	Whether returned vector should be named with dataset names.
slot	Name of slot to retrieve matrix from. Options shown in Usage.
returnList	Logical, whether to force return a list even when only one dataset-specific matrix (i.e. expression matrices, H, V or U) is requested. Default FALSE.
i	Name or numeric index of cell meta variable to be replaced
droplevels	Whether to remove unused cluster levels from the factor object fetched by defaultCluster(). Default FALSE.
asDefault	Whether to set the inserted dimension reduction matrix as default for visualization methods. Default NULL sets it when no default has been set yet, otherwise does not change current default.
data	fortify method required argument. Not used.

Value

See detailed sections for explanetion.

Input liger object updated with replaced/new variable in cellMeta(x).

Slots

datasets

list of ligerDataset objects. Use generic dataset, dataset<-, datasets or datasets<- to interact with. See detailed section accordingly.

cellMeta

DFrame object for cell metadata. Pre-existing metadata, QC metrics, cluster labeling and etc. are all stored here. Use generic cellMeta, cellMeta<-, $, [[]] or [[]]<- to interact with. See detailed section accordingly.

varFeatures

Character vector of names of variable features. Use generic varFeatures or varFeatures<- to interact with. See detailed section accordingly.

W

iNMF output matrix of shared gene loadings for each factor. See runIntegration.

H.norm

Matrix of aligned factor loading for each cell. See alignFactors and runIntegration.

commands

List of ligerCommand objects. Record of analysis. Use commands to retrieve information. See detailed section accordingly.

uns

List for unstructured meta-info of analyses or presets.

version

Record of version of rliger package

Dataset access

datasets() method only accesses the datasets slot, the list of ligerDataset objects. dataset() method accesses a single dataset, with subsequent cell metadata updates and checks bonded when adding or modifying a dataset. Therefore, when users want to modify something inside a ligerDataset while no cell metadata change should happen, it is recommended to use: datasets(x)[[name]] <- ligerD for efficiency, though the result would be the same as dataset(x, name) <- ligerD.

length() and names() methods are implemented to access the number and names of datasets. names<- method is supported for modifying dataset names, with taking care of the "dataset" variable in cell metadata.

Matrix access

For liger object, rawData(), normData, scaleData() and scaleUnsharedData() methods are exported for users to access the corresponding feature expression matrix with specification of one dataset. For retrieving a type of matrix from multiple datasets, please use getMatrix() method.

When only one matrix is expected to be retrieved by getMatrix(), the matrix itself will be returned. A list will be returned if multiple matrices is requested (by querying multiple datasets) or returnList is set to TRUE.

Cell metadata access

Three approaches are provided for access of cell metadata. A generic function cellMeta is implemented with plenty of options and multi-variable accessibility. Besides, users can use double-bracket (e.g. ligerObj[[varName]]) or dollor-sign (e.g. ligerObj$nUMI) to access or modify single variables.

For users' convenience of generating a customized ggplot with available cell metadata, the S3 method fortify.liger is implemented. With this under the hook, users can create simple ggplots by directly starting with ggplot(ligerObj, aes(...)) where cell metadata variables can be directly thrown into aes().

Special partial metadata insertion is implemented specifically for mapping categorical annotation from sub-population (subset object) back to original experiment (full-size object). For example, when sub-clustering and annotation is done for a specific cell-type of cells (stored in subobj) subset from an experiment (stored as obj), users can do cellMeta(obj, "sub_ann", cellIdx = colnames(subobj)) <- subobj$sub_ann to map the value back, leaving other cells non-annotated with NAs. Plotting with this variable will then also show NA cells with default grey color. Furthermore, sub-clustering labels for other cell types can also be mapped to the same variable. For example, cellMeta(obj, "sub_ann", cellIdx = colnames(subobj2)) <- subobj2$sub_ann. As long as the labeling variables are stored as factor class (categorical), the levels (category names) will be properly handled and merged. Other situations follow the R default behavior (e.g. categories might be converted to integer numbers if mapped to numerical variable in the original object). Note that this feature is only available with using the generic function cellMeta but not with the `[[` or `$` accessing methods due to syntax reasons.

The generic defaultCluster works as both getter and setter. As a setter, users can do defaultCluster(obj) <- "existingVariableName" to set a categorical variable as default cluster used for visualization or downstream analysis. Users can also do defaultCluster(obj, "newVarName") <- factorOfLabels to push new labeling into the object and set as default. For getter method, the function returns a factor object of the default cluster labeling. Argument useDatasets can be used for requiring that given or retrieved labeling should match with cells in specified datasets. We generally don't recommend setting "dataset" as a default cluster because it is a preserved (always existing) field in metadata and can lead to meaningless result when running analysis that utilizes both clustering information and the dataset source information.

Dimension reduction access

Currently, low-dimensional representaion of cells, presented as dense matrices, are all stored in dimReds slot, and can totally be accessed with generics dimRed and dimRed<-. Adding a dimRed to the object looks as simple as dimRed(obj, "name") <- matrixLike. It can be retrieved back with dimRed(obj, "name"). Similar to having a default cluster labeling, we also constructed the feature of default dimRed. It can be set with defaultDimRed(obj) <- "existingMatLikeVar" and the matrix can be retrieved with defaultDimRed(obj).

Variable feature access

The varFeatures slot allows for character vectors of gene names. varFeatures(x) returns this vector and value for varFeatures<- method has to be a character vector or NULL. The replacement method, when check = TRUE performs checks on gene name consistency check across the scaleData, H, V slots of inner ligerDataset objects as well as the W and H.norm slots of the input liger object.

Command records

rliger functions, that perform calculation and update the liger object, will be recorded in a ligerCommand object and stored in the commands slot, a list, of liger object. Method commands() is implemented to retrieve or show the log history. Running with funcName = NULL (default) returns all command labels. Specifying funcName allows partial matching to all command labels and returns a subset list (of ligerCommand object) of matches (or the ligerCommand object if only one match found). If arg is further specified, a subset list of parameters from the matches will be returned. For example, requesting a list of resolution values used in all louvain cluster attempts: commands(ligerObj, "louvainCluster", "resolution")

Dimensionality

For a liger object, the column orientation is assigned for cells. Due to the data structure, it is hard to define a row index for the liger object, which might contain datasets that vary in number of genes.

Therefore, for liger objects, dim and dimnames returns NA/NULL for rows and total cell counts/barcodes for the columns.

For direct call of dimnames<- method, value should be a list with NULL as the first element and valid cell identifiers as the second element. For colnames<- method, the character vector of cell identifiers. rownames<- method is not applicable.

Subsetting

For more detail of subsetting a liger object or a ligerDataset object, please check out subsetLiger and subsetLigerDataset. Here, we set the S4 method "single-bracket" [ as a quick wrapper to subset a liger object. Note that j serves as cell subscriptor which can be any valid index refering the collection of all cells (i.e. rownames(cellMeta(obj))). While i, the feature subscriptor can only be character vector because the features for each dataset can vary. ... arugments are passed to subsetLiger so that advanced options are allowed.

Combining multiple liger object

The list of datasets slot, the rows of cellMeta slot and the list of commands slot will be simply concatenated. Variable features in varFeatures slot will be taken a union. The W and H.norm matrices are not taken into account for now.

Examples

# Methods for base generics
pbmcPlot
print(pbmcPlot)
dim(pbmcPlot)
ncol(pbmcPlot)
colnames(pbmcPlot)[1:5]
pbmcPlot[varFeatures(pbmcPlot)[1:10], 1:10]
names(pbmcPlot)
length(pbmcPlot)

# rliger generics
## Retrieving dataset(s), replacement methods available
datasets(pbmcPlot)
dataset(pbmcPlot, "ctrl")
dataset(pbmcPlot, 2)

## Retrieving cell metadata, replacement methods available
cellMeta(pbmcPlot)
head(pbmcPlot[["nUMI"]])

## Retrieving dimemtion reduction matrix
head(dimRed(pbmcPlot, "UMAP"))

## Retrieving variable features, replacement methods available
varFeatures(pbmcPlot)

## Command record/history
pbmcPlot <- scaleNotCenter(pbmcPlot)
commands(pbmcPlot)
commands(pbmcPlot, funcName = "scaleNotCenter")

# S3 methods
pbmcPlot2 <- pbmcPlot
names(pbmcPlot2) <- paste0(names(pbmcPlot), 2)
c(pbmcPlot, pbmcPlot2)

library(ggplot2)
ggplot(pbmcPlot, aes(x = UMAP_1, y = UMAP_2)) + geom_point()
cellMeta(pbmc)
# Add new variable
pbmc[["newVar"]] <- 1
cellMeta(pbmc)
# Change existing variable
pbmc[["newVar"]][1:3] <- 1:3
cellMeta(pbmc)

rliger documentation built on Oct. 30, 2024, 1:07 a.m.