recountCells {cydar} | R Documentation |
Count the number of cells in hyperspheres across a specified marker space, nested within pre-defined groups of cells.
recountCells(x, markers, tol=0.5)
x |
A CyData object containing cell assignments into hyperspheres, such as that produced by |
markers |
A vector specifying the markers for which hyperspheres should be constructed. |
tol |
A numeric scalar proportional to the hypersphere radius. |
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.
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:
counts
, intensities
and cellAssignments
contain the relevant values for the nested hyperspheres.
The used
field in markerData
is set to all markers used in both the original and re-counting.
The tol
value in the metadata
is set to the (effective) tolerance used in re-counting.
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.
Aaron Lun
### 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