Get statistics

Retrieves statistics from FCS files, returning the results as a data frame.

getStatistics(
  experimentId,
  fcsFileIds = NULL,
  fcsFiles = NULL,
  channels = c(),
  statistics,
  compensationId,
  populationIds = NULL,
  populations = NULL,
  q = 0.5,
  percentOf = NULL,
  includeAnnotations = TRUE,
  layout = "medium"
)

Arguments

experimentId

ID of experiment.

fcsFileIds

IDs of FCS files. If specified, do not specify fcsFiles.

fcsFiles

Names of FCS files. An attempt will be made to find the files by name. If zero or more than one file exists with a given filename, an error will be thrown. If specified, do not specify fcsFileIds.

channels

Names of channels (for statistic types "mean", "median", "quantile", "stddev", "cv" and "mad"). Use channel short names, not reagents.

statistics

Statistics to export. Valid options: "mean", "median", "quantile", "stddev", "cv", "eventcount", "percent", "mad", "geometricmean".

compensationId

Compensation to apply. May be an ID, cellengine::UNCOMPENSATED or cellengine::FILE_INTERNAL.

populationIds

IDs of populations. If specified, do not specify populations.

populations

Names of populations. An attempt will be made to find the population by name. If zero or more than one population exists with the name, an error will be thrown. If specified, do not specify populationIds.

q

Quantile to calculate for "quantile" statistic, in the range 0 to 1.

percentOf

Single population ID or name, or list of population IDs or names.

• If omitted or the string "PARENT", then the percent of parent will be calculated for each population.

• If a single ID or name is provided, then the percent of that population will be calculated for each population specified in populations or populationIds (useful for calculating e.g. percent of singlets or leukocytes).

• If an array of IDs, "PARENT" or names is provided, then the percent of each of those populations will be calculated.

In the latter two cases, if a name or list of names instead of IDs are provided, an attempt will be made to find those populations by name. IDs are detected as matching a 24-character string comprised of the characters A-Fa-f0-9.

includeAnnotations

Includes FCS file annotations in the returned data frame.

layout

One of the following:

• "tall-skinny": One row/object per combination of FCS file, population, statistic and channel.

• "medium": (default) One row/object per combination of FCS file, population and channel. Separate column/property for each statistic.

• "short-wide": One row/object per FCS file. One column/property per combination of population, statistic and channel. This format is not readily machine-readable and does not include

Value

Statistics as a data frame, including file annotations and information about the statistics such as the channel name and population.

Details

The quick syntax accepts FCS files and populations by names. This is often easier to use, but is slower to execute because additional API requests and validation logic must be run. Thus, for performance-critical applications, provide IDs instead of names in the fcsFileIds, populationIds and percentOf parameters. IDs are also guaranteed to reference unique files and populations, while names may be non-unique, in which case an error will be raised.

Specify neither fcsFileIds nor fcsFiles to calculate statistics for all non-control FCS files.

Examples

if (FALSE) { # \dontrun{
# Quick syntax, using population names and file names instead of IDs:
fcsFiles <- c("file1.fcs")
channels <- c("SSC-A", "YG780/60-A")
statistics <- c("median", "mean", "quantile", "percent")
populations <- c("Leukocytes")
stats <- getStatistics(experimentId,
  fcsFiles = fcsFiles, channels = channels,
  statistics = statistics, populations = populations, q = 0.95,
  compensationId = cellengine::FILE_INTERNAL
)
# Returns a data.frame of statistics, including the file annotations.
# Because percentOf is not specified, "percent" will be percent of parent.

# Explicit syntax, using IDs instead of population and file names:
fcsFileIds <- c("9ab5c6d7a8cf24a5c4f9a6c2")
statistics <- c("percent")
populationIds <- c("9ab5c6d7a8cf24a5c4f9face")
stats <- getStatistics(experimentId,
  fcsFileIds = fcsFileIds,
  statistics = statistics, populationIds = populationIds,
  compensationId = cellengine::UNCOMPENSATED
)

# Percent of ungated:
getStatistics(experimentId,
  fcsFileIds = fcsFileIds, statistics = statistics,
  populationIds = populationIds, compensationId = cellengine::UNCOMPENSATED,
  percentOf = cellengine::UNGATED
)
} # }