getEvents: Get FCS File Events

In primitybio/cellengine-r-toolkit: 'CellEngine' API Toolkit

Get FCS File Events

Description

Retrieves events from an FCS file or gated population as either an FCS or TSV file. Optionally transfers directly to S3-compatible storage.

Usage

getEvents(
  experimentId,
  fcsFileId,
  populationId = NULL,
  compensation = NULL,
  compensatedQ = FALSE,
  headerQ = TRUE,
  format = "FCS",
  destination = NULL,
  overwrite = FALSE,
  subsampling = list(),
  addEventNumber = FALSE
)

Arguments

experimentId	ID of experiment or a byName expression.
fcsFileId	ID of FCS file or a byName expression.
populationId	Optional ID of population or a byName expression, for gated events.
compensation	ID of compensation or special compensation type (UNCOMPENSATED or FILE_INTERNAL) to use for gating. This should generally match what you used to create your gates. Not required if compensatedQ is FALSE and exporting ungated files.
compensatedQ	If TRUE, applies the compensation specified in compensation to the exported events. For TSV format, the numerical values will be the compensated values. For FCS format, the numerical values will be unchanged, but the file header will contain the compensation as the spill string (file-internal compensation).
headerQ	for TSV format only: if true, file will contain a header row.
format	One of "TSV" or "FCS".
destination	Optional destination for the file. If omitted, the result will be returned as a binary blob (if format is "FCS") or a data.frame (if format is "TSV"). If a string, the result will be written to disk. If a list with a host value, transfer the file to S3-compatible storage. S3 transfers occur "in the cloud," directly from CellEngine to the S3 provider, without transferring the file to your local computer. S3 transfer specifications accept the following: host Required. The full S3 host, including the bucket and region as applicable. For example, for AWS, this would look like "mybucket.s3.us-east-2.amazonaws.com". \item \code{path} The path prefix for the object. This is concatenated directly with the file name. Use a trailing "/" to specify a "directory" in S3. For example, if the path is \code{"/Study001/"} and the file is called \code{"Specimen01.fcs"}, the object key will be \code{"/Study001/Specimen01.fcs"}. Use no trailing slash to specify a file prefix. For example, if the path is \code{"/transfer1_"}, the object key will be \code{"/transfer1_Specimen01.fcs"}. Note that S3 object keys must start with "/"; a path of "" will result in an \code{Invalid URI} response. Defaults to "/". \item \code{accessKey} Required for private buckets. The S3 access key. Must be associated with an account with appropriate S3 permissions (e.g. \code{PutObject}). \item \code{secretKey} Required for private buckets. The S3 secret key. \item \code{headers} Custom headers to include in the S3 request. Common examples are \code{x-amz-storage-class}/\code{x-goog-storage-class} and \code{x-amz-server-side-encryption}. Some headers, such as \code{Content-Length}, \code{Content-MD5} and \code{Content-Type}, cannot be modified. Refer to https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html for AWS header documentation and https://cloud.google.com/storage/docs/migrating#custommeta regarding compatibility with Google Cloud Platform.
overwrite	Optional, if a destination is a string, allows destination file to be overwritten.
subsampling	Optional, subsampling parameters in the form list(preSubsampleN = number, preSubsampleP = number, postSubsampleN = number, postSubsampleP = number, seed = number). Subsample-N options specify absolute subsampling values, and subsample-P options specify a fractional subsampling value (0 to 1); specify only one pre- and/or one post-subsample option. Specify a seed for reproducible downsampling.
addEventNumber	Optional. Add an event number column to the exported file. When a populationId is specified (when gating), this number corresponds to the index of the event in the original file.

Details

Tip: FCS files are more compact than TSV files. Use that format for faster downloads. Use a library such as flowCore to parse FCS files.

Examples

## Not run: 
# Returns the FCS file as a binary blob (requires parsing before use):
getEvents(experimentId, fcsFileId)

# Returns a data.frame:
getEvents(experimentId, fcsFileId, populationId, format = "TSV")

# Saves as an FCS file to disk:
getEvents(experimentId, fcsFileId, destination = "/path/to/output.fcs")

# Saves as a TSV file to disk:
getEvents(experimentId, fcsFileId, destination = "/path/to/output.tsv", format = "TSV")

# Subsamples and gates to only contain events in the specified population:
subsampling <- list(preSubsampleN = 5000, seed = 1.5)
getEvents(experimentId, fcsFileId, populationId, subsampling = subsampling)

## End(Not run)

primitybio/cellengine-r-toolkit documentation built on Oct. 19, 2024, 1:17 a.m.