In bjreisman/cytotidyr: A Package for Creating Tidy Cytometry Data via the CytobankAPI

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  cache = FALSE,
  dev = "png",
  dpi = 150,
  fig.path = "figures/",
  fig.width = 4,
  fig.height = 3.5,
  fig.align = 'center',
  output_file = "./minimalexample.md")
library(cytotidyr)
library(flowCore)
library(CytobankAPI)
library(scico)
library(tidyverse)
library(flowWorkspace)
library(CytoML)

What is Cytotidyr?

The goal of cytotidyr is to integrate data-preprocessing done in cytobank with downstream analysis in R.

The cytobankAPI package provides a method for importing cytobank endpoints into R, but applying those endpoints to raw data to reproduce the data preprocessing done in cytobank is less than straight forward.

Cytotidyr provides a set of function for applying the following preprocessing steps from cytobank:

• Data scaling
• Panel assignment
• Compensation
• Gating on populations
• Sample tagging

With the exception of sample tagging, all of these steps can be applied to flowFrame objects to integrate with analysis pipelines based on flowCore. Alternatively, all steps except for compensation and gating can be applied to tibbles to generate tidy data for integration with tidyverse based analysis pipelines.

Disclaimer

Cytotidyr is currently in development phase. While we have validated it on a number of cytobank experiments, it may not always perform as expected. Please make sure to validate that cytotidyr provides the output you expect by comparing any outputs (cell counts, medians, biaxial plots, etc...) to what you see on cytobank.

Experiment Info

All functions within cytotidyr rely on the theget_experimentinfo function, which calls multiple internal functions to obtain the scales, compensations, panels, gates, population hierarchy, and sample tags from cytobank for a given experiment.

Let's see the package in action on the "Welcome to Cytobank - U937 dataset", which is publicly available at "community.cytobank.org", as experiment.id = 61.

Note that to actually connect run this code, you would need a valid authorization token and access to the specified experiment. In this case, I needed to clone the experiment to my cytobank community account. For the purposes of this vignette, I've saved the output of the experiment.info function so that it accessible. In practice, it may be worthwhile to save the experiment info object for reproducability purposes.

token <- "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI3YjYyMzIyYmMwZGZiZmFmYzI0ZWQ5NTg2ZDdlOGMzMyIsImV4cCI6MTU1MzE5OTk2MiwidXNlcl9pZCI6MTQ3LCJhdWQiOiJjeXRvYmFua19hcGlfdjFfdXNlcnMiLCJpYXQiOjE1NTMxNzExNjIsImlzcyI6Imh0dHBzOi8vdmFuZGVyYmlsdC5jeXRvYmFuay5vcmcvIiwibmJmIjoxNTUzMTcxMTYyLCJzdWIiOiJjeXRvYmFua19hcGlfdjEifQ.T1Wn-aHTUxppSPw_NODalWgZ2heZL9ALM2g5EhJbSew"
cyto_session <- authenticate("vanderbilt", auth_token = token)
experiment.id <- 29564

exp_info <- fetchCytobankExperiment(cyto_session = cyto_session, experiment.id)
saveRDS(exp_info, "exp_info_sample.rds")

fcspath <- fcs_files.download_zip(cyto_session, experiment.id, exp_info$fcs_files$originalId)
fcspath_unzipped <- unzip(fcspath)
myflowset <- read.flowSet(fcspath_unzipped)
#saveRDS(exp_info, system.file("extdata", "exp_info_sample.rds", package = "cytotidyr"))

exp_info <- readRDS(system.file("extdata", "exp_info_sample.rds", package = "cytotidyr"))
#exp_info$transforms
#exp_info$transforms
myflowset <- read.flowSet(system.file("extdata",
                         c("Donor 2 mem post-sort.fcs", "Donor 2 pre-sort.fcs" ),
                         package = "cytotidyr"))

mygatingset <- GatingSet(myflowset) # convert to a gatingset to use flowWorkspace
mygatingset <- flowWorkspace::transform(mygatingset, exp_info$transforms) #transform the data
markernames(mygatingset) <- exp_info$panels$`Panel 1` #apply the panels
CytoML::gating(exp_info$gates, mygatingset) #run gating 
myflowset_preprocessed <- flowWorkspace::getData(mygatingset, "singles") #back to a flowSet
myflowset_tagged <- tagFlowSet(myflowset_preprocessed, exp_info$sampletags) #apply sampletags

mytidydata <- as.data.frame(myflowset_tagged)

str(mytidydata)

bjreisman/cytotidyr documentation built on Nov. 22, 2020, 9:30 p.m.