Functions

flowkit.load_samples(fcs_samples, filename_as_id=False, compensation=None, null_channel_list=None, preprocess=True, use_flowjo_labels=False)

Returns a list of Sample instances from a variety of input types (fcs_samples), such as a file or: directory path string, Path object, a Sample instance, or a list of the previous types. Lists of mixed types are not supported.

Parameters:

fcs_samples – Sample, str, or list. Allowed types: a Sample instance, list of Sample instances, a directory or file path, or a list of directory or file paths. If a directory, any .fcs files in the directory will be loaded. If a list, then it must be a list of file paths or a list of Sample instances. Lists of mixed types are not supported.
filename_as_id – Boolean option for using the file name (as it exists on the filesystem) for the Sample’s ID, default is False. Only applies to file paths given to the ‘fcs_samples’ argument.
compensation – Compensation matrix. The matrix must be applicable to all samples in ‘fcs_samples’. Acceptable types include a Matrix instance, NumPy array, CSV file path, pathlib Path object to a CSV or TSV file, or a string of CSV text
null_channel_list – List of PnN labels for acquired channels that do not contain useful data. Note, this should only be used if no fluorochromes were used to target those detectors. Null channels do not contribute to compensation and should not be included in a compensation matrix for this sample. This option is ignored if fcs_path_or_data is a FlowData object. The null channel list must be applicable to all samples.
preprocess – Controls whether preprocessing is applied to the ‘raw’ data (retrievable via Sample.get_events() with source=’raw’). Binary events in an FCS file are stored unprocessed, meaning they have not been scaled according to channel gain, corrected for proper lin/log display, or had the time channel scaled by the ‘timestep’ keyword value (if present). Unprocessed event data is typically not useful for analysis, so the default is True. Preprocessing does not include compensation or transformation (e.g. biex, Logicle) which are separate operations.
use_flowjo_labels – FlowJo converts forward slashes (‘/’) in PnN labels to underscores. This option matches that behavior. Default is False.

Returns:

list of Sample instances

flowkit.read_multi_dataset_fcs(fcs_file, ignore_offset_error=False, ignore_offset_discrepancy=False, use_header_offsets=False, preprocess=True)

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

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 notes in Sample class docstring), 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.
preprocess – Original events are the unprocessed events as stored in the FCS binary, meaning they have not been scaled according to channel gain, corrected for proper lin/log display, or had the time channel scaled by the ‘timestep’ keyword value (if present). This option controls whether to perform these preprocessing steps. Unprocessed event data is typically not useful for analysis, so the default is True.

Returns:

list of Sample instances

flowkit.generate_transforms(sample, scatter_xform_class=<class 'flowkit._models.transforms._transforms.LinearTransform'>, fluoro_xform_class=<class 'flowkit._models.transforms._transforms.LogicleTransform'>, time_xform_class=<class 'flowkit._models.transforms._transforms.LinearTransform'>)

Generate a dictionary of transforms for channels in a given Sample instance.

A set of Transforms is generated for each type of channel: scatter channels, fluorescent channels, and the time channel. If given a class reference to a Transform, then a default set of parameters will be chosen.

For any transform, the top of scale parameter (e.g. T in Logicle) will be determined by the channel’s PnR value within the given Sample. The exception to is the Time channel, where the top of scale will be calculated as the max Time event value.

The available Transforms generated from a class reference are listed below along with their default parameter values for the Transform subclasses are:

LinearTransform(t: PnR_value, a: 0.0)
LogTransform(t: PnR_value, m: 4.0)
LogicleTransform(t: PnR_value, w: 0.5, m: 4.0, a: 0.0)
AsinhTransform(t: PnR_value, m: 3.5, a: 0.0)
HyperlogTransform(t: PnR_value, w: 0.5, m: 4.0, a: 0.0)
WSPBiexTransform(width: -10, neg: 0.0, pos: 4.41854, top: PnR_value)

NOTE: Each channel will have independent transform instances, not references to the same transform instance.

Parameters:

sample – Sample instance
scatter_xform_class – Transform subclass reference to use for scatter channels or a specific instance of a Transform subclass.
fluoro_xform_class – Transform subclass reference to use for fluorescent channels
time_xform_class – Transform subclass reference to use for time channel

Returns:

dictionary with PnN labels as keys, values are Transform instances

flowkit.parse_gating_xml(xml_file_or_path)

Parse a GatingML 20 document and return as a GatingStrategy.

Parameters:: xml_file_or_path – file handle or file path to a GatingML 2.0 document
Returns:: GatingStrategy instance

flowkit.export_gatingml(gating_strategy, file_handle, sample_id=None)

Exports a valid GatingML 2.0 document from given GatingStrategy instance. Specify the sample ID to use that sample’s custom gates in the exported file, otherwise the template gates will be exported.

Parameters:

gating_strategy – A GatingStrategy instance
file_handle – File handle for exported GatingML 2.0 document
sample_id – an optional text string representing a Sample instance

Returns:

None

flowkit.parse_wsp(workspace_file_or_path)

Converts a FlowJo 10 workspace file (.wsp) into a nested Python dictionary with the following structure:

wsp_dict = {
    'groups': {
        group_name: {
            'samples': sample list,
            'group_gates': list of common group gates (may not be the complete tree)
        },
        ...
    },
    'samples': {
        sample_name: {
            'keywords': dict of FJ sample keywords,
            'compensation': matrix,
            'transforms': dict of transforms (key is parameter name),
            'custom_gate_ids': set of gate IDs,
            'gating_strategy': {gate_id: gate_instance, ...}
        },
        ...
    }
}

Parameters:: workspace_file_or_path – A FlowJo .wsp file or file path
Returns:: dict

flowkit.extract_wsp_sample_data(workspace_file_or_path)

Parses a FlowJo 10 workspace file (.wsp) and extracts Sample metadata (keywords) into a Python dictionary with the following structure:

wsp_sample_dict[sample_name] = {
    'keywords': {gate_id: gate_instance, ...},
    'transforms': transforms_list,
    'compensation': matrix
}

Parameters:: workspace_file_or_path – A FlowJo .wsp file or file path
Returns:: dict