merge: Merging two FCS objects

In tchitchek-lab/CytoBackBone: Merging of phenotype information from different cytometric profiles

Description

Perfomrs a merging of two FCS objects. CytoBackBone uses a k Nearest Neighbor distances algorithm, based on k-d tree space partitioning, to identify cells that are acceptable and non-ambiguous nearest neighbors.

To be acceptable neighbors, the phenotypic distance between two cells must be lower than a specific threshold, defined by the user, which corresponds to a Euclidian distance computed as the square root of the sum of the squared expression differences for each pair of common markers.

To be defined as non-ambiguous nearest neighbors, two cells from two different profiles must be reciprocally the closest neighbors. First, the algorithm identifies the closest cells in cytometric profile #2 for each cell from cytometric profile #1. Then, the algorithm identifies the closest cells in cytometric profile #1 for each cell from cytometric profile #2. Merging is possible if two cells from different cytometric profiles are identified as mutual non-ambiguous nearest neighbors.

Usage

merge(FCS1, FCS2, BBmarkers = NULL, th = length(BBmarkers) * 0.2,
  normalize = TRUE, leftout = FALSE)

Arguments

FCS1	a first FCS object to merge
FCS2	a second FCS object to merge
BBmarkers	a character indicating the markers to use as backbone markers
th	a numerical value indicating the threshold distance to use to consider two cells as acceptable neighbors
normalize	a logical indicating if the expressions of backbone markers must be quantile-normalized
leftout	a logical indicating if left-out cells (cells not merged during the merging procedure) must also be extracted in the output results. If set to TRUE then the output will be a named list containing the merged cytometric profile (named "merged"), the cells specific to the first profile (named "specific.FCS1"), the cells specific to the second profile (named "specific.FCS2"), and the cells specific to both profiles (named "specific").

Details

More precisely, the algorithm works as follows: (i) cells of each cytometric profile with no acceptable neighbors are first excluded from the two input profiles; (ii) all acceptable and non-ambiguous nearest neighbor cells remaining in the two profiles are merged into a new profile and are discarded from the two input profiles; (iii) the previous step of this procedure is repeated until no more acceptable and non-ambiguous neighbor cells can be found; and (iv) finally, all excluded and remaining cells are stored in supplementary cytometric profiles for information purposes. These successive iterations ensure that the algorithm finds a new set of acceptable and non-ambiguous neighbor cells at each step. The number of iteration performed by the algorithm varies depending on the dataset used, but usually ranges from 2 to 30 interactions.

A distance threshold defining acceptable nearest neighbors needs to be specified to avoid merging data between two cells that have very different levels for the backbone markers: the lower the threshold, the more accurate the merging. However, the threshold must not be too stringent as, by definition, cells cannot have exactly the same phenotype. On the contrary, merging can result in a significant loss of cells. Thus, the threshold must be carefully set to allow CytoBackBone to merge data from cells with similar levels of the backbone markers within a reasonable error range. The Euclidean distance between cells increases with the number of backbone markers. Therefore, the threshold value must be adjusted according to the length of this backbone.

Cells discarded (having no acceptable and not-ambiguous neighbours) during the merging procedure (i.e., cells specific to the two cytometric profiles to merge) can be extracted using the 'leftout' argument.

Value

a S4 object of class FCS

tchitchek-lab/CytoBackBone documentation built on May 28, 2019, 7:52 a.m.