FlowIO API

FlowData Class

class flowio.FlowData(filename_or_handle, ignore_offset_error=False, ignore_offset_discrepancy=False, use_header_offsets=False, only_text=False, nextdata_offset=None)

Object representing a Flow Cytometry Standard (FCS) file. FCS versions 2.0, 3.0, and 3.1 are supported.

Note on ignore_offset_error:

Some FCS files incorrectly report the location of the last data byte as the last byte exclusive of the data section rather than the last byte inclusive of the data section. Technically, these are invalid FCS files but these are not corrupted data files. To attempt to read in these files, set the ignore_offset_error option to True.

Note on ignore_offset_discrepancy and use_header_offset:

The byte offset location for the DATA segment is defined in 2 places in an FCS file: the HEADER and the TEXT segments. By default, FlowIO uses the offset values found in the TEXT segment. If the HEADER values differ from the TEXT values, a DataOffsetDiscrepancyError will be raised. This option allows overriding this error to force the loading of the FCS file. The related use_header_offset can be used to force loading the file using the data offset locations found in the HEADER section rather than the TEXT section. Setting use_header_offset to True is equivalent to setting both options to True, meaning no error will be raised for an offset discrepancy.

Variables:

  • analysis – dictionary of key/value pairs from the ANALYSIS section (if present)

  • channel_count – number of channels of event data

  • channels – a dictionary of channel information, with key as channel number and value is a dictionary of the PnN and PnS text

  • event_count – number of events

  • events – 1-D array of event data

  • file_size – file size of the imported FCS file

  • header – dictionary of key/value pairs from the HEADER section

  • name – file name of the imported FCS file

  • text – dictionary of key/value pairs from the TEXT section

Parameters:

  • filename_or_handle – a path string or a file handle for an FCS file

  • ignore_offset_error – option to ignore data offset error (see above note), default is False

  • ignore_offset_discrepancy – option to ignore discrepancy between the HEADER and TEXT values for the DATA byte offset location, default is False

  • use_header_offsets – use the HEADER section for the data offset locations, default is False. Setting this option to True also suppresses an error in cases of an offset discrepancy.

  • only_text – option to only read the “text” segment of the FCS file without loading event data, default is False

  • nextdata_offset – an integer indicating the byte offset for a data set, used for reading a data set from FCS file contain multiple data sets

write_fcs(filename, metadata=None)

Export FlowData instance as a new FCS file.

By default, the output FCS file will include the $cyt, $date, and $spill keywords (and values) from the FlowData instance. To exclude these keys, specify a custom metadata dictionary (including an empty dictionary for the bare minimum metadata).

Parameters:

  • filename – name of exported FCS file

  • metadata – an optional dictionary for adding metadata keywords/values

Returns:

None

Reading FCS Files with Multiple Data Sets

flowio.read_multiple_data_sets(filename_or_handle, ignore_offset_error=False, ignore_offset_discrepancy=False, use_header_offsets=False, only_text=False)

Utility function for reading all data sets contained in an FCS file.

Parameters:

  • filename_or_handle – a path string or a file handle for an FCS file

  • ignore_offset_error – option to ignore data offset error (see above note), default is False

  • ignore_offset_discrepancy – option to ignore discrepancy between the HEADER and TEXT values for the DATA byte offset location, default is False

  • use_header_offsets – use the HEADER section for the data offset locations, default is False. Setting this option to True also suppresses an error in cases of an offset discrepancy.

  • only_text – option to only read the “text” segment of the FCS file without loading event data, default is False

Returns:

List of FlowData instances for each found data set

Creating New FCS Files

flowio.create_fcs(file_handle, event_data, channel_names, opt_channel_names=None, metadata_dict=None)

Create a new FCS file from a list of event data.

Note:

A proper spillover matrix shall have the first value corresponding to the number of compensated fluorescence channels followed by the $PnN names which should match the given channel_names argument. All values in the spill text string should be comma delimited with no newline characters.

Parameters:

  • file_handle – file handle for new FCS file

  • event_data – list of event data (flattened 1-D list)

  • channel_names – list of channel labels to use for PnN fields

  • opt_channel_names – optional list of channel labels to use for PnS fields

  • metadata_dict – an optional dictionary for adding extra metadata keywords/values

Returns:

FlowIO Exceptions

flowio.exceptions

This module contains custom FlowIO exception and warning classes.

exception flowio.exceptions.FlowIOWarning

Generic FlowIO warning

exception flowio.exceptions.PnEWarning

Warning for invalid PnE values when creating FCS files

exception flowio.exceptions.FlowIOException

Generic FlowIO exception

exception flowio.exceptions.FCSParsingError

Errors relating to parsing an FCS file

exception flowio.exceptions.DataOffsetDiscrepancyError

Raised when an FCS file’s HEADER & TEXT section provide different byte offsets for the DATA section.

exception flowio.exceptions.MultipleDataSetsError

Raised for errors related to FCS files containing more than one dataset, indicated by the ‘nextdata’ keyword.