load_cytoframe_from_fcs {flowWorkspace} | R Documentation

## Read a single FCS file in to a cytoframe

### Description

Similar to `read.FCS`, this takes a filename for a single FCS file and returns a `cytoframe`.

### Usage

    load_cytoframe_from_fcs(
      filename,
      transformation = "linearize",
      which.lines = NULL,
      alter.names = FALSE,
      column.pattern = NULL,
      invert.pattern = FALSE,
      decades = 0,
      is_h5 = NULL,
      backend = get_default_backend(),
      uri = NULL,
      h5_filename = NULL,
      min.limit = NULL,
      truncate_max_range = TRUE,
      dataset = NULL,
      emptyValue = TRUE,
      num_threads = 1,
      ignore.text.offset = FALSE,
      text.only = FALSE
    )

### Arguments

`filename` | The filename of the single FCS file to be read
`transformation` | A character string that defines the type of transformation. Valid values are `linearize` (default), `linearize-with-PnG-scaling`, or `scale`. The `linearize` transformation applies the appropriate power transform to the data. The `linearize-with-PnG-scaling` transformation applies the appropriate power transform for parameters stored on log scale, and also a linear scaling transformation based on the "gain" (FCS $PnG keywords) for parameters stored on a linear scale. The `scale` transformation scales all columns to [0,10^{decades}]. defaulting to decades=0 as in the FCS4 specification. A logical can also be used: `TRUE` is equal to `linearize` and `FALSE`(or `NULL`) corresponds to no transformation. Also, when the transformation keyword of the FCS header is set to "custom" or "applied", no transformation will be used.
`which.lines` | Numeric vector to specify the indices of the lines to be read. If it is NULL, all the records are read. If it is of length 1, a random sample of the size indicated by `which.lines` is read in.
`alter.names` | Logical indicating whether or not we should rename the columns to valid R names using `make.names`. The default is FALSE.
`column.pattern` | An optional regular expression defining parameters we should keep when loading the file. The default is NULL.
`invert.pattern` | Logical. By default, `FALSE`. If `TRUE`, inverts the regular expression specified in `column.pattern`. This is useful for indicating the channel names that we do not want to read. If `column.pattern` is set to `NULL`, this argument is ignored.
`decades` | When scaling is activated, the number of decades to use for the output.
`is_h5` | Logical indicating whether the data should be stored in h5 format
`h5_filename` | String specifying a name for the h5 file if `is_h5` is TRUE
`min.limit` | The minimum value in the data range that is allowed. Some instruments produce extreme artifactual values. The positive data range for each parameter is completely defined by the measurement range of the instrument and all larger values are set to this threshold. The lower data boundary is not that well defined, since compensation might shift some values below the original measurement range of the instrument. This can be set to an arbitrary number or to `NULL` (the default value), in which case the original values are kept.
`truncate_max_range` | Logical. Default is TRUE. can be optionally turned off to avoid truncating the extreme positive value to the instrument measurement range, i.e. '$PnR'.
`dataset` | The FCS file specification allows for multiple data segments in a single file. Since the output of `load_cytoframe_from_cytoset` is a single `cytoframe` we can't automatically read in all available sets. This parameter allows the user to choose one of the subsets for import. Its value should be an integer in the range of available data sets. This argument is ignored if there is only a single data segment in the FCS file.
`emptyValue` | Logical indicating whether or not to allow empty values for keywords in TEXT segment. It affects how double delimiters are treated. If TRUE, double delimiters are parsed as a pair of start and end single delimiters for an empty value. Otherwise, double delimiters are parsed as one part of the string of the keyword value. The default is TRUE.
`num_threads` | Integer allowing for parallelization of the parsing operation by specifiying a number of threads
`ignore.text.offset` | Logical indicating whether to ignore the keyword values in TEXT segment when they don't agree with the HEADER. Default is FALSE, which throws the error when such a discrepancy is found. Users can turn it on to ignore the TEXT segment when they are sure of the accuracy of the HEADER segment so that the file still can be read.
`text.only` | whether to only parse text section of FCS (default is FALSE), it is sometime useful to skip loading data section for the faster loading meta data from FCS `read.AnnotatedDataFrame`, see details

### Details

The function `load_cytoframe_from_fcs` works with the output of the FACS machine software from a number of vendors (FCS 2.0, FCS 3.0 and List Mode Data LMD). However, the FCS 3.0 standard includes some options that are not yet implemented in this function. If you need extensions, please let us know. The output of the function is an object of class `cytoframe`.

For specifications of FCS 3.0 see http://www.isac-net.org and the file ../doc/fcs3.html in the `doc` directory of the package.

The `which.lines` arguments allow you to read a subset of the record as you might not want to read the thousands of events recorded in the FCS file. It is mainly used when there is not enough memory to read one single FCS (which probably will not happen). It will probably take more time than reading the entire FCS (due to the multiple disk IO).

### Value

An object of class `cytoframe` that contains the data, the parameters monitored, and the keywords and values saved in the header of the FCS file.

### See Also

Other cytoframe/cytoset IO functions: `cf_get_uri()`, `cf_write_disk()`, `cf_write_h5()`, `cf_write_tile()`, `cs_get_uri()`, `load_cytoframe()`, `load_cytoset_from_fcs()`

[Package flowWorkspace version 4.2.0 Index]