Create dimension-reduced maps of cytometry data

cyto_map is a convenient wrapper to produce dimension-reduced maps of cytometry data using PCA, tSNE, FIt-SNE, UMAP and EmbedSOM. These dimensionality reduction functions are called using the default settings, but can be altered by passing relvant arguments through cyto_map. To see a full list of customisable parameters refer to the documentation for each of these functions by clicking on the links below.

cyto_map(x, ...)

# S3 method for GatingSet
cyto_map(
  x,
  parent = "root",
  select = NULL,
  channels = NULL,
  display = 1,
  type = "UMAP",
  merge_by = "all",
  split = TRUE,
  names = NULL,
  save_as = NULL,
  inverse = FALSE,
  trans = NULL,
  plot = TRUE,
  seed = NULL,
  ...
)

# S3 method for flowSet
cyto_map(
  x,
  select = NULL,
  channels = NULL,
  display = 1,
  type = "UMAP",
  merge_by = "all",
  split = TRUE,
  names = NULL,
  save_as = NULL,
  inverse = FALSE,
  trans = NULL,
  plot = TRUE,
  seed = NULL,
  ...
)

# S3 method for flowFrame
cyto_map(
  x,
  channels = NULL,
  display = 1,
  type = "UMAP",
  split = TRUE,
  names = NULL,
  save_as = NULL,
  inverse = FALSE,
  trans = NULL,
  plot = TRUE,
  seed = NULL,
  ...
)

Arguments

x	object of class `flowFrame` or `flowSet`.
...	additional arguments passed to the called dimension reduction function. Links to the documentation for these functions can be found below.
parent	name of the parent population to extract from `GatingHierarchy` or `GatingSet` objects for mapping, set to the `"root"` node by default.
select	designates which samples should be used for mapping when a `flowSet` or `GatingSet` object is supplied. Filtering steps should be comma separated and wrapped in a list. Refer to `cyto_select`.
channels	vector of channels names indicating the channels that should be used by the dimension reduction algorithm to compute the 2-dimensional map, set to all channels with assigned markers by default. Restricting the number of channels can greatly improve processing speed and resolution.
display	total number of events to map, all events in the combined data are mapped by default.
type	dimension reduction type to use to generate the map, supported options include "PCA", "tSNE", "FIt-SNE", "UMAP" and "EmbedSOM". Users can also supply the name of a function to perform custom mappings.
merge_by	vector of experimental variables to split and merge samples into groups prior to mapping, set to "all" by default to create a single consensus map.
split	logical indicating whether samples merged using `cyto_merge_by` should be split prior to writing fcs files, set to FALSE by default.
names	original names of the samples prior to merging using `cyto_merge_by`, only required when split is TRUE. These names will be re-assigned to each of split flowFrames and included in the file names.
save_as	passed to `cyto_save` to indicate a folder where the mapped FCS files should be saved, set to NULL by default to turn off saving of FCS files.
inverse	logical indicating whether the data should be inverse transformed prior to writing FCS files, set to FALSE by default. Inverse transformations of `flowFrame` or `flowSet` objects requires passing of transformers through the `trans` argument.
trans	object of class `transformerList` containing the transformation definitions applied to the supplied data. Used internally when `inverse_transform` is TRUE, to inverse the transformations prior to writing FCS files.
plot	logical indicating whether the constructed map should be plotted using `cyto_plot`.
seed	integer to set seed prior to mapping to ensure more consistent results between runs.

Value

flowFrame, flowSet, GatingHierarchy or GatingSet containing the mapped projection parameters.

Details

If you use cyto_map to map your cytometry data, be sure to cite the publication that describes the dimensionality reduction algorithm that you have chosen to use. References to these publications can be found in the references section of this document.

References

N. B. Erichson, S. Voronin, S. L. Brunton and J. N. Kutz. 2019. Randomized Matrix Decompositions Using R. Journal of Statistical Software, 89(11), 1-48. http://doi.org/10.18637/jss.v089.i11.

N. Halko, P. Martinsson, and J. Tropp. "Finding structure with randomness: probabilistic algorithms for constructing approximate matrix decompositions" (2009). (available at arXiv http://arxiv.org/abs/0909.4061).

Gabriel K. (1971). The biplot graphical display of matrices with application to principal component analysis. Biometrika 58, 453–467. doi:10.1093/biomet/58.3.453.

Maaten, L. van der, & Hinton, G. (2008). Visualizing Data using t-SNE. Journal of Machine Learning Research 9, 2579–2605. http://www.jmlr.org/papers/volume9/vandermaaten08a/.

Linderman, G., Rachh, M., Hoskins, J., Steinerberger, S., Kluger., Y. (2019). Fast interpolation-based t-SNE for improved visualization of single-cell RNA-seq data. Nature Methods. https://www.ncbi.nlm.nih.gov/pmc/articles/PMC6402590/.

McInnes, L., & Healy, J. (2018). UMAP: uniform manifold approximation and projection for dimension reduction. Preprint at https://arxiv.org/abs/1802.03426.

Kratochvíl, M., Koladiya, A., Balounova, J., Novosadova, V., Fišer, K., Sedlacek, R., Vondrášek, J., and Drbal, K. (2018). Rapid single-cell cytometry data visualization with EmbedSOM. Preprint at https://www.biorxiv.org/content/10.1101/496869v1.

Author