FlowIO API
FlowData Class
- class flowio.FlowData(fcs_file, ignore_offset_error=False, ignore_offset_discrepancy=False, use_header_offsets=False, only_text=False, nextdata_offset=None, null_channel_list=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 as a dictionary with ‘pne’, ‘png’, ‘pnn’, ‘pnr’, and ‘pns’ metadata
data_type – type of data in DATA segment (ASCII, integer, floating point)
event_count – number of events
events – 1-D array of unprocessed event data
file_size – file size of the imported FCS file
fluoro_indices – list of indices of fluorescent channels
header – dictionary of key/value pairs from the HEADER section
name – file name of the imported FCS file
null_channels – list of channel indices not intended for analysis
pnn_labels – list of names for parameters (required)
pnr_values – list of channel range values (required)
pns_labels – list of optional names for parameters
scatter_indices – list of indices of scatter channels
text – dictionary of key/value pairs from the TEXT section
time_index – index of the time channel
version – FCS version of the imported file
- Parameters:
fcs_file – a file path string, Path instance, or file handle to 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
null_channel_list – list of PnN labels corresponding to null channels. Null channels are omitted from fluoro_indices, scatter_indices, and time_index.
Public Methods:
__init__(fcs_file[, ignore_offset_error, ...])__repr__()Return repr(self).
as_array([preprocess])Retrieve the event data list as a 2-D NumPy array.
write_fcs(filename[, metadata])Export FlowData instance as a new FCS file.
- as_array(preprocess=True)
Retrieve the event data list as a 2-D NumPy array. Pre-processing is applied if requested and includes applying gain, log, and time scaling as necessary.
- Parameters:
preprocess – Boolean for whether to apply gain, log, and time scaling as necessary according the FCS metadata (default is True).
- Returns:
NumPy array of 2-D event data
- 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). Note: Any critical keywords related to the interpretation of the event data are defined and set internally, overriding those in the provided metadata dictionary. These keywords include: PnB, PnE, and PnG.
- 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
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception flowio.exceptions.PnEWarning
Warning for invalid PnE values when creating FCS files
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception flowio.exceptions.FlowIOException
Generic FlowIO exception
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception flowio.exceptions.FCSParsingError
Errors relating to parsing an FCS file
- args
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.