---
title: "Steady-state analysis of flow cytometry data"
author: "R Clay Wright"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Steady-state analysis of flow cytometry data}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r, echo = FALSE, message=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", tidy = TRUE)
library(flowCore)
library(flowTime)
library(ggplot2)
```
This vignette will guide you through analysis of an example flow cytometry data set from an experiment examining the fluorescent reporter levels of a synthetic biological circuit in liquid cultures of budding yeast. Here, we analyze a circuit in which a florescent reporter is fused to a protein that is degraded over time after addition of an inducer molecule. At some time post-induction (as optimized by the experimenter) fluorescence of these cultures is analyzed by flow cytometry. Here we demonstrate how to import the resulting .fcs files into R, annotate this data with experimental metadata (e.g. the `strain` and `treatment` for each sample), and compile the relevant events and measurements.

#Importing and annotating data
Import your flow cytometry data using `read.flowset`. Here, we will import an example flowSet.
```{r}
plate1<-read.flowSet(path=system.file("extdata", "ss_example", 
                        package = "flowTime"), alter.names = TRUE)
# add plate numbers to the sampleNames
sampleNames(plate1)<-paste("1_", sampleNames(plate1), sep = "")
dat<-plate1
```
If you have several plates this code can be repeated and each plate can be combined to assemble the full data set.
```{r, eval = F}
plate2 <- read.flowSet(path = paste(experiment, "_2/", sep = ""), 
                        alter.names = TRUE)
sampleNames(plate2) <- paste("2_", sampleNames(plate2), sep = "")
dat <- rbind2(plate1, plate2)
```
For this example, we will import the table of metadata. The `sampleNames` of the assembled `flowSet` (`dat` in this example) must match that of a unique identifier column of `annotation`. 
```{r}
annotation <- read.csv(system.file("extdata", "ss_example.csv", 
                        package = "flowTime"))
head(annotation)
sampleNames(dat) 
sampleNames(dat) == annotation$name 
```
We can also create this column from our data set and attach the annotation columns. Alternatively one can use the `createAnnotation` function to create a data frame with the appropriate `name` column that can then be filled in via R-code or saved as a csv file and filled via a spreadsheet editor. The order of the entries in `annotation` does not matter, so long as each entry in `sampleNames(dat)` is represented. The `annotateFlowSet` function will match entries by the `mergeBy` column  
```{r, eval = F}
annotation <- cbind(annotation, 'name' =  sampleNames(dat)) 
# or
annotation <- createAnnotation(yourFlowSet = dat)
write.csv(annotation, file = 'path/to/yourAnnotation.csv')
```
Finally we can attach this metadata to the flowSet using the `annotateFlowSet` function. 
```{r}
adat <- annotateFlowSet(yourFlowSet = dat, annotation_df = annotation, 
                        mergeBy = 'name')
head(rownames(pData(adat)))
head(pData(adat))
```
Now we can save this flowSet and anyone in perpetuity can load and analyze this annotated flowSet with ease!
```{r, eval = F}
write.flowSet(adat, outdir = 'your/favorite/directory')

# Read the flowSet with the saved experimental meta data
read.flowSet('flowSet folder', path = 'your/flow/directory', 
                        phenoData = 'annotation.txt', alter.names = TRUE)
```
#Compiling and plotting data
Now we are ready to analyze the raw data in this `flowSet`. First we load the set of gates that will be used to subset our data. To analyze this steady-state or single time point experiment we will use the `steadyState` function. This function will gate each `flowFrame` in the `flowSet` and compile and return a `dataframe` of the relevant data and metadata for each event. This `dataframe` can then be used to visualize the full data set. 
```{r, fig.width = 4, fig.height = 4}
loadGates() # use the default included gateSet
dat.SS <- steadyState(flowset = adat, ploidy = 'diploid', only = 'singlets')

p <- ggplot(dat.SS, aes(x = as.factor(treatment), y = FL2.A, fill = AFB)) + 
  geom_boxplot(outlier.shape = NA) + facet_grid(IAA~AFB) + 
  theme_classic(base_family = 'Arial', base_size = 16) + ylim(c(-1000,10000)) +
  xlab(expression(paste('Auxin (',mu,'M)',sep = ""))) + 
  ylab('Fluorescence (AU)') + theme(legend.position="none")
p
```