recountCells {cydar}R Documentation

Recount cells in each group

Description

Count the number of cells in hyperspheres across a specified marker space, nested within pre-defined groups of cells.

Usage

recountCells(x, markers, tol=0.5)

Arguments

x

A CyData object containing cell assignments into hyperspheres, such as that produced by countCells.

markers

A vector specifying the markers for which hyperspheres should be constructed.

tol

A numeric scalar proportional to the hypersphere radius.

Details

Each row of x corresponds to an existing hypersphere across some high-dimensional space, to which a set of cells are assigned. This function extends the hypersphere into the dimensions specified by markers. Thus, each new hypersphere is “nested” within the existing hypersphere in x. Only the cells in the latter are assigned into the former (though obviously, some cells will not be assigned if they are too distant from the centre in the new dimensions).

This function allows for fast recounting in situations where the markers have different purposes. For example, x could be constructed using cell type-specific markers to define cell types. recountCells can then be applied with markers that define, e.g., the activation status within each cell type. In general, it is most interesting to use markers that were not used to construct x. Otherwise, by definition, all the cells in each hypersphere would have similar marker intensities.

Also see medIntensities for a discussion of strategies to use when markers can be separated into two distinct sets.

Value

A CyData object containing counts and cell assignments for nested hyperspheres. This follows the same format as the output from countCells, i.e., each row is a hypersphere and each column is a sample. Some fields are modified:

Note on the radius calculation

The output of this function is designed to be equivalent to directly running countCells with both new and old markers. However, to speed up the counting, only the cells already assigned to each hypersphere in x are considered for re-counting. This has some consequences for the results, as the radius scales with respect to tol and the number of markers.

Specifically, when new markers are specified in markers, the radius must increase to accommodate the increase in dimensions. However, the cells were originally counted with a radius proportional to the (square root of the) old number of markers and metadata(x)$tol. If the radius now increases, but only pre-assigned cells are used for re-counting, then there will be cells that are missed in the re-counts.

Thus, to preserve equivalence with countCells output, tol is decreased so that the radius does not change with new markers. This shows up as a warning specifying the effective tolerance that was used in during re-counting. Users can also avoid this problem by using a higher radius when constructing x, such that the radius calculated from the tol here will be smaller.

Author(s)

Aaron Lun

See Also

countCells, medIntensities

Examples

### Mocking up some data: ###
nmarkers <- 20
marker.names <- paste0("X", seq_len(nmarkers))
nsamples <- 8
sample.names <- paste0("Y", seq_len(nsamples))

x <- list()
for (i in sample.names) {
    ex <- matrix(rgamma(nmarkers*1000, 2, 2), ncol=nmarkers, nrow=1000)
    colnames(ex) <- marker.names
    x[[i]] <- ex
}

### Processing it beforehand with one set of markers: ###
cd <- prepareCellData(x, markers=marker.names[1:10])
cnt <- countCells(cd, filter=5)

### Processing it afterwards with another set of markers: ###
rcnt <- recountCells(cnt, markers=marker.names[11:12])
rcnt

[Package cydar version 1.4.0 Index]