In Close-your-eyes/fcexpr: Complement the manual analysis of flow cytometric experiments and organize your fcs files in a consistent way

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
options(knitr.kable.NA = '', width = 80)

Install necessary packages in RStudio:

install.packages("BiocManager")
BiocManager::install("flowCore")
install.packages("devtools")
devtools::install_github("Close-your-eyes/fcexpr")
library(fcexpr)

Please follow the steps of the vignette and observe what happens on your disk.

Initiate

Pick a directory on your disk and have a new template folder created using fcexpr::new_exp(). A respective folder appears in "path". It is prefixed with todays date as date_prefix = TRUE by default. It has a default structure and contains a few template folders and files.

dir <- "/Users/vonskopnik/Documents"
fcexpr::new_exp(path = dir, name = "my_experiment")
wd <- file.path(dir, paste0(base::gsub("-", "", base::Sys.Date()), "_my_experiment"))
print(wd)

Next, add FCS files to the FCS_files folder. You can use your own files, or use example files that come with this package.

# this command uses example files from the fcexpr package
utils::untar(base::system.file("extdata", "Part_1.tgz", package = "fcexpr"), exdir = file.path(wd, "FCS_files"))

list.files(file.path(wd, "FCS_files", "Part_1"))[1:5]

To initiate a sampledescription file call the sync_sampledescription function. The xlsx-file is always written to the parent folder of FCS.file.folder. By default it is named 'sampledescription.xlsx'.

fcexpr::sync_sampledescription(FCS.file.folder = file.path(wd, "FCS_files"), init.columns = c())

All FCS files have been entered as rows. The FileNames are prefixed with a continuous number to make them unique. The identity column is necessary for the function to identify the FCS unambiguously.
sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

Also the actual FCS files have a prefix now. The names of the FCS files and the entries in the xlsx-file have been synchronized.

list.files(file.path(wd, "FCS_files", "Part_1"))[1:5]

Add meta data

Additonal columns with meta data can be added. These columns serve to document the content of FCS files and one can use them group the data when plotting. They may also be used by another function to hard-code them into the FCS files if this is desired.

sd <- openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx"))
sd$Patient_ID <- sort(rep(1:5, 2))
sd$Staining <- rep(c("FMO", "full"), 5)
sd$Patient_sex <- c(rep("M",4),rep("F",6))
openxlsx::write.xlsx(sd, file.path(wd, "sampledescription.xlsx"), overwrite = T)

sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

Rename FCS files

When the names in the FileName column are altered and sync_sampledescription is run synchronization takes place.

sd <- openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx"))
sd[2,1] <- "File_2"
sd[5,1] <- "File_5"
openxlsx::write.xlsx(sd, file.path(wd, "sampledescription.xlsx"), overwrite = T)

sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

fcexpr::sync_sampledescription(FCS.file.folder = file.path(wd, "FCS_files"), write.log = F)

The prefixed continuous number is added automatically as well as the .fcs-suffix.
sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

FCS files have been renamed accordingly.

list.files(file.path(wd, "FCS_files", "Part_1"))

Note: When files are renamed, respective FlowJo Workspaces have to be opened once in order to adopt the changes in file names in the wsp-file. FlowJo recognizes FCS by other parameters than the file name.

Reorder

The FCS files have been added in chronological order of acquisition (see the date in identity column). If one is not happy with that, the row-order in the xlsx-file can be changed. When running sync_sampledescription the prefix-number will be adjusted. NOTE: Never change the content of the identity column and never mix up rows of FileName and identity!!!

sd <- openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx"))
sd <- sd[c(1,2,9,10,5,6,3,4,7,8),]
openxlsx::write.xlsx(sd, file.path(wd, "sampledescription.xlsx"), overwrite = T)

sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

fcexpr::sync_sampledescription(FCS.file.folder = file.path(wd, "FCS_files"), write.log = F)

list.files(file.path(wd, "FCS_files", "Part_1"))

Addition of new FCS files to the cohort or the experiment.

When FCS files are added to the FCS_files folder and sync_sampledescription is run, the xlsx-file will be appended by the new files (~synchronized).

# this command uses example files from the fcexpr package
utils::untar(base::system.file("extdata", "Part_2.tgz", package = "fcexpr"), exdir = file.path(wd, "FCS_files"))

list.files(file.path(wd, "FCS_files"))
fcexpr::sync_sampledescription(FCS.file.folder = file.path(wd, "FCS_files"), write.log = F)

sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

Exclude or remove samples

The function argument exclude.folders in sync_sampledescription specifies folder names that will be ignored for syncing with the xlsx-file. Such folders may contain controls like rainbow beads or compensation controls or similar - in general, files which do not contain biological information. If, by accident, one or more of these files end up in our xlsx-file since one forgot to copy them to a respective folder one can have them removed by deleting the FileName, but only the FileName, from the xlsx-file.

sd <- openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx"))
sd$FileName <- ifelse(grepl("comp", sd$FileName), NA, sd$FileName)
openxlsx::write.xlsx(sd, file.path(wd, "sampledescription.xlsx"), overwrite = T)

sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

fcexpr::sync_sampledescription(FCS.file.folder = file.path(wd, "FCS_files"), write.log = F)

The prefixed numbers are made continuous by renaming files accordingly. sampledescription.xlsx:

knitr::kable(openxlsx::read.xlsx(file.path(wd, "sampledescription.xlsx")))

The log file

By default a log file is written (write.log = T) which documents all changes to sampledescription.xlsx. On Mac/linux it is hidden, on Windows it is not.