<!-- README.md is generated from README.Rmd. Please edit that file -->

CytoExploreR <img src="man/figures/logo.png" align="right" alt="" width="240"/>

CytoExploreR is comprehensive collection of interactive exploratory cytometry analysis tools designed under a unified framework. CytoExploreR has been specifically designed to integrate all existing cytometry analysis techniques (e.g. manual gating, automated gating and dimension reduction) in a format that makes these tools freely accessible to users with no coding experience. If you are new to CytoExploreR visit https://dillonhammill.github.io/CytoExploreR/ to get started.

Install R and RStudio

CytoExploreR has a minimal requirement for R 3.5.0. If necessary, newer versions of R can be installed by clicking on your operating system in this link and following the installation instructions. For the best user experience it is recommended that RStudio be installed as well. RStudio Desktop is free to download and can installed from the RStudio website.

Platform-Specific Requirements

After successfully installing R and RStudio, the following additional platform-specific tools are required:

Mac OS

• Install Xcode developer tools from the App Store. Restart your computer.
• Install command line tools by opening the terminal and running xcode-select --install
• Install macOS R toolchain by installing clang7 and gfortran here
• Check if XQuartz is listed in your installed Applications, it may be hiding in the utilities folder. If XQuartz is missing on your computer, it can be installed from the XQuartz website.
• Restart your computer so all these changes will take effect.

Windows OS

• Install the appropriate Rtools for your R installation.
• Follow these instructions to download protobuf Windows binary and set appropriate environment variable. Ignore the section to build protobuf from source.
• Follow these instructions to install and setup the additional C++ libraries required to successfully build flowWorkspace.
• Restart your computer.

CytoExploreR Dependencies

Now that all the setup is complete, let’s install all the necessary dependencies of CytoExploreR. From within RStudio, run the following in the console to install the latest versions of flowCore, flowWorkspace and openCyto from Bioconductor.

# Bioconductor
install.packages("BiocManager")
# Install flowCore, flowWorkspace and openCyto
library(BiocManager)
install(c("cytolib", "flowCore", "flowWorkspace", "flowWorkspaceData", "openCyto"))

Currently, CytoExploreR requires the development versions of these packages hosted on GitHub:

# Install & load devtools
tryCatch(library(devtools), error = function(e){
  install.packages("devtools")
  library(devtools)
})
# Install development versions from GitHub
install_github("DillonHammill/openCyto", force = TRUE)
install_github("DillonHammill/DataEditR")
install_github("DillonHammill/HeatmapR")

CytoExploreR

Now that all the dependencies are installed, let’s move on to installing CytoExploreR. To successfully install CytoExploreR users will first need to install CytoExploreRData which contains example datasets that will be used within CytoExploreR to demonstrate key features.

# CytoExploreRData 
devtools::install_github("DillonHammill/CytoExploreRData")
# CytoExploreR 
devtools::install_github("DillonHammill/CytoExploreR")

Design

To ease the transition from GUI oriented software, CytoExploreR has been designed to be a consistent and auto-complete friendly package for cytometry data analysis. All exported functions from CytoExploreR are prefixed with cyto_, followed by the name of the object you wish to change (e.g. cyto_gate_) and finally the action that you would like to perform (e.g. cyto_gate_draw). To see all available functions simply start typing cyto_ and you will be greeted with a complete list of exported functions that can be selected from the auto-complete dropdown list:

<img src="man/figures/README-CytoExploreR-Design.gif" width="95%" style="display: block; margin: auto;" />

Overview

Some of the key features of CytoExploreR are outlined below:

• load and annotate samples using cyto_setup
• user guided automatic compensation using cyto_spillover_compute
• interactively modify spillover matrices using cyto_spillover_edit
• compute spillover spreading matrices with cyto_spillover_spread_compute
• visualise compensation in all channels using cyto_plot_compensation
• customisable data transformations using cyto_transform which includes support for log, arcsinh, logicle and biexponential data transformations
• manual gate drawing using cyto_gate_draw
• ability to edit drawn gates using cyto_gate_edit
• remove gates using cyto_gate_remove
• rename gates using cyto_gate_rename
• gate saving directly to an openCyto gatingTemplate for future use
• support for using both manual and automated gating approaches through linking to openCyto
• exploratory visualisations of all existing cytometry data classes using cyto_plot
• visualisation of complete gating strategies with back-gating and/or gate tracking using cyto_plot_gating_scheme
• visualisation of gating trees using cyto_plot_gating_tree
• visualisation of marker expression profiles in all channels using cyto_plot_profile
• visualisation of populations in all possible bivariate plots using cyto_plot_explore
• produce dimension reduced maps (e.g. PCA, tSNE, UMAP and EmbedSOM) using cyto_map
• save samples and analyses to file using cyto_save
• export population level statistics tidyverse style using cyto_stats_compute

Usage

CytoExploreR is large package and we would not do it justice by demonstrating its usage here. Instead we will explore the use of CytoExploreR in a series of vignettes which tackle specific components of the cytometry data analysis pipeline. To work through these vignettes you will need to create a new R project (File -> New Project) and download the example datasets shipped with CytoExploreRData.

# Load required packages
library(CytoExploreR)
library(CytoExploreRData)

# Download Compensation FCS files
cyto_save(Compensation,
          save_as = "Compensation-Samples")

# Download Activation FCS files
cyto_save(Activation,
          save_as = "Activation-Samples")

These datasets will be used throughout the package vignettes to demonstrate the key features of CytoExploreR. A brief summary of each of the package vignettes is provided below:

• The CytoExploreR vignette outlines a basic flow cytometry data analysis pipeline, which includes steps to compensate for fluorescent spillover, transform data for visualisation and manually gate populations to export population level statistics. This vignette serves as a basic introduction to the package and users are encouraged to explore other vignettes which explore these aspects in a lot more detail.

• The Visualisations vignette will demonstrate the use of cyto_plot, a powerful data visualisation tool to explore cytometry data.

<img src="man/figures/README-2.png" width="98%" style="display: block; margin: auto;" />

• Flow cytometry users will find the Compensation vignette useful in describing the process of using compensation controls to correctly compensate for fluorescent spillover.

<img src="man/figures/README-3.png" width="98%" style="display: block; margin: auto;" />

• Data transformations are essential to appropriate visualisation of cytometry data. In the Transformations vignette we will explore the tools available in CytoExploreR to apply log, arcsinh, biexponential and/or logicle transformations to the data.

<img src="man/figures/README-4.png" width="80%" style="display: block; margin: auto;" />

• In Manual Gating vignette we will demonstrate the use of cyto_gate_draw to interactively draw gates around populations. In particular, we will focus on the different gate types that are supported and how they can be used to gate populations.

<img src="man/figures/README-1.png" width="98%" style="display: block; margin: auto;" />

• Dimensionality reduction is gaining popularity for analysis of high dimensional cytometry data. In the Dimensionality Reduction vignette we will demonstrate the use of cyto_map