PseudotimeOrdering: The PseudotimeOrdering class

In LTLA/TrajectoryUtils: Single-Cell Trajectory Analysis Utilities

The PseudotimeOrdering class

Description

The PseudotimeOrdering class defines a two-dimensional object where rows represent cells and columns represent paths through a trajectory (i.e., “lineages”). It is expected to contain a numeric matrix of pseudotime orderings for each cell (row) in each path (column). If a cell is on a path, it should have a valid pseudotime for the corresponding column; otherwise its entry should be set to NA. Cells may lie on multiple paths if those paths span shared regions of the trajectory.

Constructor

PseudotimeOrdering(pathStats, cellData=NULL, pathData=NULL, metadata=list() will construct a PseudotimeOrdering object given:

• pathStats, a (usually numeric) matrix-like object of pseudotime orderings as described above. Alternatively, a list of such matrices can be supplied if multiple statistics are associated with each cell/path combination. By convention, the first matrix in such a list should contain the pseudotime orderings.

• cellData, a DataFrame of cell-level metadata. This should have number of rows equal to the number of cells.

• pathData, a DataFrame of path-level metadata. This should have number of rows equal to the number of paths.

• metadata, a list of any additional metadata to be stored in the object.

Getting/setting path statistics

In the following code chunks, x is a PseudotimeOrdering object.

pathStat(x, i=1L, withDimnames=TRUE):

Returns a (usually numeric) matrix-like object containing some path statistics. The default of i=1L will extract the first matrix of path statistics - by convention, this should contain the pseudotime orderings. i may also be a string if the path statistics in x are named. The dimnames of the output matrix are guaranteed to be the same as dimnames(x) if withDimnames=TRUE.

pathStat(x, i=1L, withDimnames=TRUE) <- value:

Replaces the path statistics at i in x with the matrix value. This should have the same dimensions as x, and if withDimnames=TRUE, it should also have the same dimnames.

pathStats(x, withDimnames=TRUE):

Returns a list of matrices containing path statistics. The dimnames of each matrix are guaranteed to be the same as dimnames(x) if withDimnames=TRUE.

pathStats(x, withDimnames=TRUE) <- value:

Replaces the path statistics in x with those in the list value. Each entry of value should have the same dimensions as x. The dimnames of each matrix should also be the same as dimnames(x) if withDimnames=TRUE.

pathStatNames(x):

Returns a character vector containing the names for each matrix of path statistics.

pathStatNames(x) <- value:

Replaces the names of the path statistics with those in the character vector value.

Getting/setting path metadata

In the following code chunks, x is a PseudotimeOrdering object.

npaths(x):

Returns an integer scalar containing the number of paths in x. This is the same as ncol(x).

pathnames(x):

Returns a character vector containing the names of paths in x (or NULL, if no names are available). This is the same as colnames(x).

pathnames(x) <- value:

Replaces the path names in x with those in the character vector value (or NULL, to unname the paths). This is the same as colnames(x) <- value.

pathData(x, use.names=TRUE):

Returns a DataFrame containing the path-level metadata of x. This has the same number of rows as the number of columns in x. Row names are guaranteed to be equal to pathnames(x) if use.names=TRUE.

pathData(x) <- value:

Replaces the path-level metadata of x with a DataFrame value containing the same number of rows.

Getting/setting cell metadata

In the following code chunks, x is a PseudotimeOrdering object.

ncells(x):

Returns an integer scalar containing the number of cells in x. This is the same as nrow(x).

cellnames(x):

Returns a character vector containing the names of cells in x (or NULL, if no names are available). This is the same as rownames(x).

cellnames(x) <- value:

Replaces the cell names in x with those in the character vector value (or NULL, to unname the cells). This is the same as rownames(x) <- value.

cellData(x, use.names=TRUE):

Returns a DataFrame containing the cell-level metadata of x. This has the same number of rows as x. Row names are guaranteed to be equal to cellnames(x) if use.names=TRUE.

cellData(x) <- value:

Replaces the cell-level metadata of x with a DataFrame value containing the same number of rows.

Further operations

In the following code chunks, x is a PseudotimeOrdering object.

x$name and x$name <- value will get and set, respectively, the named field of the cellData. This is primarily provided for convenience.

Subsetting operations (e.g., x[i, j]) and combining operations (rbind(x, ...), cbind(x, ...)) will return the expected PseudotimeOrdering object.

metadata(x) and metadata(x) <- value will get and set, respectively, the metadata of x.

Comments on advanced usage

The PseudotimeOrdering class is actually just a reskin of the widely-used SummarizedExperiment class. We re-use the same underlying data structure and simply rename row and col to cell and path, respectively. This means that any method that operates on a SummarizedExperiment can also - in theory - be applied to PseudotimeOrdering.

We chose to do this reskinning to provide a clear conceptual break between the two classes. The PseudotimeOrdering's dimensions do not follow the SummarizedExperiment's conventional “samples as columns” philosophy, as each row instead represents a cell/sample. Similarly, it is hard to argue that the paths are really interpretable as “features” in any meaningful sense. By reskinning, we hide the SummarizedExperiment implementation from the end-user and avoid any confusion with the interpretation of PseudotimeOrdering's dimensions.

Of course, we could just transpose the inputs to get them to fit into a SummarizedExperiment. However, the use of rows as cells is convenient as we often have many cells but few paths; it is easier to inspect the pseudotime ordering matrix with this orientation. It also allows us to store the PseudotimeOrdering as a column in the colData of a SummarizedExperiment. In this manner, datasets can be easily annotated with pseudotime orderings from trajectory reconstruction methods.

Author(s)

Aaron Lun

Examples

# Make up a matrix of pseudotime orderings.
ncells <- 200
npaths <- 5
orderings <- matrix(rnorm(1000), ncells, npaths)

# Default constructor:
(pto <- PseudotimeOrdering(orderings))
(pto <- PseudotimeOrdering(list(ordering=orderings)))

# Adding some per-cell metadata:
pto$cluster <- sample(LETTERS, ncells, replace=TRUE)
table(pto$cluster)

# Adding some per-path metadata:
pathData(pto)$description <- c("EMT", "differentiatoin", "activation", "other", "?")
pathData(pto)

# Subsetting and combining works fine:
rbind(pto, pto)
cbind(pto, pto)
pto[1:10,]
pto[,1:2]

LTLA/TrajectoryUtils documentation built on Feb. 5, 2024, 11:56 a.m.