knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)

CytoExploreR

Project Status: Active – The project has reached a stable, usable state and is being actively developed. Travis build status AppVeyor build status Coverage status lifecycle Last-changedate

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

Windows OS

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 the cytoverse packages from Bioconductor.

# Bioconductor
install.packages("BiocManager")
# Install cytoinstaller
remotes::install_github("RGLab/cytoinstaller")
# Install cytoverse packages
cytoinstaller::install_cyto(bioc_ver = "devel")

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")
library(CytoExploreR)
library(CytoExploreRData)

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:

knitr::include_graphics('man/figures/README-CytoExploreR-Design.gif')

Overview

Some of the key features of CytoExploreR are outlined below:

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")
library(CytoExploreR)

# Activation GatingSet
gs <- cyto_load(
  system.file(
    "extdata/Activation-GatingSet",
    package = "CytoExploreRData"
  )
)

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:

cyto_plot_save("README-2.png",
               height = 6,
               width = 12)
cyto_plot_custom(c(1,2))
cyto_plot(gs[[32]],
          parent = "T Cells",
          alias = c("CD4 T Cells", "CD8 T Cells"),
          channels = c("CD4", "CD8"),
          contour_lines = 15,
          title = "T Cells")
cyto_plot(gs[c(8,16,24,32)],
          parent = "CD4 T Cells",
          alias = "CD69+ CD4 T Cells",
          channels = "CD69",
          density_stack = 0.5)
cyto_plot_complete()
knitr::include_graphics('man/figures/README-2.png')
# Compensation GatingSet
gs_comp <- cyto_load(
  system.file(
    "extdata/Compensation-GatingSet",
    package = "CytoExploreRData"
  )
)
cyto_spillover_edit(gs_comp,
                    parent = "Single Cells",
                    point_size = 4)
knitr::include_graphics('man/figures/README-3.png')
cyto_plot_save("README-4.png",
               height = 7, 
               width = 9)
cyto_plot_profile(gs[[32]],
                  parent = "Single Cells",
                  channels = cyto_fluor_channels(gs),
                  header = NA)
cyto_plot_complete()
knitr::include_graphics('man/figures/README-4.png')
cyto_plot_save("README-1.png",
               height = 10,
               width = 10)
cyto_plot_gating_scheme(gs[[32]],
                        back_gate = TRUE,
                        gate_track = TRUE,
                        border_fill = "black",
                        label_text_col = "white",
                        label_fill_alpha = 0,
                        header = "Gating Scheme")
cyto_plot_complete()
knitr::include_graphics('man/figures/README-1.png')
#knitr::include_graphics('man/figures/README-5.png')

News

There is a changelog for the GitHub master branch which will reflect any updates made to improve the stability, usability or plenitude of the package. Users should refer to the Changelog prior to installing new versions of the package.

Credits

CytoExploreR would not be possible without the existing flow cytometry infrastructure developed by the RGLab. CytoExploreR started out as simple plugin for openCyto to facilitate gate drawing but has evolved into a fully-fledged cytometry analysis package thanks to the support and guidance of members of the RGLab. Please take the time to check out their work on GitHub.

Development

CytoExploreR is a maturing package which will continue to be sculpted by the feedback and feature requests of users. The GitHub master branch will always contain the most stable build of the package. New features and updates will be made to a separate branch and merged to the master branch when stable and tested. The Changelog will reflect any changes made to the master branch.

Getting help

The Get Started and Reference sections on the CytoExploreR website are your first port of call if you require any help. For more detailed workflows refer the Articles tab. If you encounter any issues with the functioning of the package refer to these issues to see if the problem has been identified and resolved. Feel free to post new issues on the GitHub page if they have not already been addressed.

Code of conduct

Please note that the CytoExploreR project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Citation

A CytoExploreR publication is on the way, but in the meantime if you use CytoExploreR for your work please cite the package as follows:

citation("CytoExploreR")


DillonHammill/CytoExploreR documentation built on March 2, 2023, 7:34 a.m.