Get FCS File Events — getEvents • cellengine

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

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

if (FALSE) { # \dontrun{
# 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)
} # }