downsampleFcsList: Downsample a set of FCS files reproducibly, to make the event...

In BenaroyaResearch/briDiscovr: Distribution analysis across clusters of a parent population overlaid with a rare subpopulation

Downsample a set of FCS files reproducibly, to make the event count more uniform and reduce memory usage

Description

This function downsamples a set of FCS cytometry data files to a maximum event count. For each FCS file representing a population in popsToDownsample, it checks whether the file exceeds the maximum event count, set by maxEvents. If the maximum event count is exceeded, it selects a random set of rows. These rows can either be stored as a list of vectors and passed to setupDiscovrExperiment, or new FCS files can be written out to a specified directory, with a new fcsInfoFile specifying the updated file paths. Results can be made reproducible by passing a non-NULL value for seed.

Usage

downsampleFcsList(
  fcsInfoFile,
  popsToDownsample = "all",
  maxEvents = 1e+05,
  downsampleMode = "storeVectors",
  outfileFcsInfoDownsampled,
  outdirFcsFilesDownsampled,
  seed = NULL,
  verbose = TRUE
)

Arguments

fcsInfoFile	a character string indicating the path to a file with information on FCS files to be used.
popsToDownsample	a character vector with the names of the cell populations to be downsampled. Allows the user to keep all events from certain populations even if the number of events exceed maxEvents, then maxEvents rows are selected from the FCS file for future use. For example, users may want to keep all events from antigen-specific populations, while downsampling the parent populations.
maxEvents	numeric, the maximum number of events to be kept for each FCS file. This cap is applied only to files matching populations in popsToDownsample.
downsampleMode	(default: "storeVectors") character, either "storeVectors" or "writeFiles" (or unique abbreviations thereof). For "storeVectors", a list of vectors is returned, with one element for each file listed in fcsInfoFile; this should be passed to setupDiscovrExperiment as downSampleRowList. For "writeFiles", you must specify a valid directory in outdirFcsFilesDownsampled to write new FCS files to, and a valid path for outfileFcsInfoDownsampled.
outfileFcsInfoDownsampled	character string, the location to write out the FCS info file with updated paths for the downsampled files. Used only if downsampleMode == "writeFiles".
outdirFcsFilesDownsampled	character string, the path for the directory to write out the the downsampled files. Used only if downsampleMode == "writeFiles".
seed	(default: NULL) numeric, the seed to be passed to set.seed to make the downsampling reproducible.
verbose	(default: TRUE) A logical specifying whether to display processing messages

Details

Files specified in fcsInfoFile are checked for a number of potential issues, including missing paths, no events, and byte offset issues.

Value

Depends on downsampleMode. If downsampleMode == "storeVectors", a list of vectors is returned, one for each row in the file at fcsInfoFile, with the row numbers of events to be included. This object should be passed to setupDiscovrExperiment via argument downsampleVectorList to enforce the downsampling. If downsampleMode == "writeFiles", NULL is returned.

Author(s)

Matthew J Dufort, [e-mail]

BenaroyaResearch/briDiscovr documentation built on March 15, 2024, 12:31 a.m.