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:

- `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.

### 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]