flowCut

flowCut is an R package that automatically removes outlier events in cytometry data.

This example shows how to run flowCut on all FCS files in a CellEngine experiment. The new files can either be uploaded to the same experiment or to a new experiment. See code comments for options regarding this behavior.

library("cellengine")
library("flowCut")
library("flowCore")

cellengine::authenticate("username") # prompts for password
experimentId <- "6243c57bf83b21038c59a4dd" # replace with your experiment ID

workingDir <- file.path(tempdir(), "flowCut")
dir.create(workingDir, recursive=T, showWarnings=F)

# Get all non-deleted FCS files
fcsFiles <- getFcsFiles(experimentId, params=list("query"="eq(deleted,null)"))
# Get the scaleset for the experiment
scaleSet <- getScaleSets(experimentId)[1,]

# Loop through all FCS files
for (fileI in 1:nrow(fcsFiles)) {
  fcsFile <- fcsFiles[fileI,]
  print(paste0("Processing ", fcsFile$filename, "..."))

  # Download the FCS file from CellEngine.
  tempFileName <- file.path(workingDir, paste0(fcsFile$filename , ".fcs"))
  getEvents(experimentId,
            fcsFile$`_id`,
            destination=tempFileName,
            overwrite=TRUE)

  # Read it as a flowFrame.
  data <- read.FCS(tempFileName)

  # Store the raw values for later.
  rawData <- exprs(data)

  # flowCut needs transformed (scaled) data. Apply the CellEngine scaleset.
  exprs(data) <- data.matrix(applyScaleSet(scaleSet, rawData))

  # Run flowCut. Note that this step is slow. See flowCut documentation for
  # additional options.
  result <- flowCut(data, Directory=workingDir, FileID=fcsFile$filename)

  # Remove the outliers from the raw data matrix.
  exprs(data) <- rawData[-result$ind,]

  # Save the result as a new FCS file.
  destFileName <- sub("(.*)\\.(.*)$", "\\1_flowcut.\\2", tempFileName)
  write.FCS(data,
            destFileName,
            endian="little") # (small performance optimization)

  # Upload it back to the same CellEngine experiment.
  uploadFcsFile(experimentId, destFileName)

  # At this point, the original file could be marked as a Control to exclude it
  # from CellEngine analyses or deleted.
  # TODO marking it as a control requires https://github.com/cellengine/cellengine-r-toolkit/issues/78

  # The images generated by flowCut (stored in workingDir) could also be
  # uploaded as attachments using uploadAttachment().
}

# R will delete the working directory on exit, but you can also delete it
# manually:
unlink(workingDir, recursive=T, force=T)