1.3.0

FlowKit 1.3.0 is finally released! Major updates include support for NumPy 2+, OLS spectral compensation, and continuing to make the API more consistent. Please update your code if you rely on the Sample.get_channel_events() method to ensure you are retrieving the correct channel events. This method was changed to take channel label (or number) and not the channel index, consistent with other Sample methods.

Thanks to everyone who contributed to this release!

New features:

• Added new SpectralMatrix class for OLS spectral compensation.
• The Workspace class now supports OLS spectral compensation matrices for FlowJo 10 .wsp files.
• Added Workspace method archive_results() for exporting analyzed data
  to Feather files (see method docstring for more details).
• Added Workspace constructor keyword argument filename_as_id for using FCS filesystem names for the sample id instead of the FCS $FIL metadata keyword (the default).
• New keyword argument col_order added to Sample.get_events() method for specifying the column order and/or the subset of columns of channel data returned.
• Added Sample constructor keyword argument use_flowjo_labels to convert PnN labels to FlowJo compatible labels (FlowJo substitutes any '/' characters for '_').
• Added keyword argument use_flowjo_labels to utility function load_samples() as a pass-through to the Sample class (see above description).
• Added keyword argument compensation to utility function load_samples() as a pass-through to the Sample class for specifying a compensation matrix to be applied to all loaded FCS files.
• Added keyword argument null_channel_list to utility function load_samples() as a pass-through to the Sample class for specifying a list of null channels to be applied to all loaded FCS files.
• Support pathlib Path objects in utility function load_samples().
• All relevant plot methods now take additional keyword arguments width and height for controlling figure size.
• Added hist_bins option to plot_gate() method in both Session & Workspace classes to control histogram bins (thanks to @takashi-yamanashi for the suggestion, see #249).
• Added utility function extract_fcs_metadata for retrieving FCS metadata without parsing event data, significantly speeds up loading files for this use case (thanks to @salmansamson for the suggestion, see #270).

API changes:

• The Sample class constructor keyword argument cache_original_events was replaced by the preprocess argument. The preprocess argument controls whether preprocessing is applied to the 'raw' data (retrievable via the Sample.get_events() method with source='raw'). See the Sample class docstring for more information.
• The value orig for retrieving events in various Sample methods via the source argument is no longer valid. To retrieve unprocessed events set the Sample keyword argument preprocess to False and use the source='raw' option for event retrieval methods.
• New Sample attribute is_preprocessed for determining whether a Sample instance was loaded with or without preprocessing.
• Changed the Sample method get_channel_events() to take channel label (or number) and not the channel index, consistent with other Sample methods. Please update your code if you rely on this method to ensure you are retrieving the correct channel events.
• The utility function read_multi_dataset_fcs() option cache_original_events was replaced with preprocess. This reflects the same change in the Sample class described above.
• Renamed Workspace keyword argument ignore_missing_files to load_missing_file_data (thanks to @ksebby for the suggestion, see #230).
• Changed column name in GatingResults DataFrames from 'sample' to 'sample_id' (avoids confusion with the Pandas DataFrame.sample() method)
• Revert FlowKit version 1.2 GatingResults report 'level', now indexed at 1, not 0 (base level of 1 is not root, but an actual gate).

Bug fixes:

• Fixed renaming a Quadrant of a QuadrantGate. This previously failed to update the Quadrant 'id' and QuadrantGate 'quadrant' key (see #243)
• Raise ValueError in Sample class if channel_labels keyword argument is not specified when creating a Sample instance from a NumPy array (thanks to @chillerb for PR #263)

Documentation:

• Updated the tutorial notebooks, with the transforms notebook getting an overhaul to better explain the transform parameters.
• The utility function generate_transforms() is now included in the ReadTheDocs documentation.

Dependencies:

• Added support for Python 3.13 & 3.14
• Drop support for Python 3.9 (EOL as of Oct 2025)
• Support for NumPy 2+
• Updated FlowIO version to 1.4.0
• Updated FlowUtils version to 1.2.2
• Added dependency PyArrow for exporting analyzed Workspace results to Feather files.
• Other dependencies updated to versions supporting Python 3.9+ (see requirements.txt for details)

1.2.3

API: Add filename_as_id kwarg option to Sample constructor to set the id attribute from the FCS file name (as it is currently on the filesystem) (see #236).
BUGFIX: Fix possible None value for Sample id attribute (see #237).

1.2.2

BUGFIX: Fixed issue where renaming a gate with children can result in a GateReferenceError (see #231)

1.2.1

BUGFIX: Fixes regression in loading resources, dropping pkg_resources and using importlib (thanks to @tristan-ranff for PR #224)

1.2.0

FlowKit 1.2.0 is out! Major updates include support for Boolean gates in FlowJo workspaces, renaming Sample channels and making the API more user-friendly. Thanks to everyone who contributed to this release, keep the bug reports and suggestions coming!

New features:

• Workspace class now supports Boolean gates when parsing a FlowJo workspace (see #179).
• Added get_keywords method to Workspace for getting sample keywords stored in a FlowJo workspace (see #210).
• Workspace method get_gate_events now supports source kwarg to control pre-processing of returned events (see #196).
• Session & GatingStrategy classes now support renaming gates via the rename_gate method (see @219).
• Session & GatingStrategy classes now support removing custom sample gates via the sample_id kwarg in the remove_gate method (see #221).
• Sample class now supports renaming channels via a new rename_channel method (see #198).
• Sample class methods get_events, get_channel_events and as_dataframe support event_mask kwarg for filtering events using a Boolean array (see #218).
• Sample class method as_dataframe supports new col_multi_index option to control column index type.
• Matrix class now supports comparison operator for determining if 2 Matrix instances are the same (see #200).
• New utils module function generate_transforms to generate a set of transforms for a Sample (see #162).

API changes:

• Transform class: removed id attribute. This allows more convenient use of independently using transforms outside of a GatingStrategy (see #191).
• GatingStrategy class: added transform_id arg to add_transform method.
• Session class: added transform_id arg to add_transform method.
• Workspace class: get_transforms now returns a dictionary LUT of transform IDs and transform instances.
• Matrix class: removed id attribute. This allows more convenient use of independently using matrices outside of a GatingStrategy (see #199).
• Session class: get_comp_matrices now returns a dictionary LUT of matrix IDs and Matrix instances.
• GatingResults class: the 'level' column of the report is now indexed at 0 (for root level).

Bug fixes:

• Ensure exporting of QuadrantGate raises NotImplementedError (see #209).
• Fixed plot_scatter error with 0 or 1 points (and 2 points with extent) (see #197).
• Better error for invalid gate names '.' & '..' (see #220).

Documentation:

• Added more informative docstrings for transforms
• Testing code reorganized to factor constants to new test config file (Thanks @ksebby for PR #213).

Dependencies:

• Drops Python 3.8 support (EOL as of Oct 2024).
• Updated dependency versions for compatibility w/ Python 3.9 - 3.12 (see requirements.txt for details).

1.1.2

• BUGFIX: Fix typo in Matrix.fluorochromes attribute. Thanks to @okolupaev for reporting #206!

1.1.1

• BUGFIX: Fix ModuleNotFoundError for pkg_resources package in newer Python versions. Now using importlib when available for loading non-code resources. Thanks to @tristan-ranff for PR #192!

1.1.0

Hey FlowKit community! Lots of changes in this release, including support for Python 3.11 & 3.12. The major updates: we've moved to a src based structure using pyproject.toml and finally converted all plotting functions to Bokeh (dropping matplotlib and Seaborn as requirements). Read the notes below for all the changes.

Special thanks to @hbhargava7 and @laserson for their contributions to this release!

New features:

• New utility function read_multi_dataset_fcs for reading FCS files with multiple data sets (returns a list of Sample instances).
• Workspace class now has an option to load FCS files from the URI parameter embedded in the WSP file (Many thanks to @hbhargava7 for PR #168).
• Sample.plot_scatter_matrix now displays histograms along the diagonal (Thanks @laserson for the suggestion in #169).
• Exporting FlowJo 10 workspaces now supports the WSPBiexTransform.
• Sample.plot_scatter adds event_mask option to filter the plotted events.
• Sample.plot_contours & Sample.plot_channel methods now use Bokeh.
• Custom heatmap color palette was improved (it's subtle but has better visual contrast between density levels).

API changes:

• Sample.plot_histogram method adds data_min, data_max, and x_range kwargs for filtering data ranges and controlling the view range.
• Removed argument ignore_transforms in parse_wsp utility function.
• Transforms from a GatingML document are no longer imported as undocumented "GML" sub-classes, instead using the documented Transform sub-classes.
• Added kwarg gate_path to plot_scatter method in both Session & Workspace.
• sample_id argument now required for GatingStrategy.is_custom_gate method.
• Rename plot_scatter argument highlight_indices to highlight_mask (since it takes a Boolean array and not a list of indices).
• plot_scatter argument dim_ids split to x_label & y_label for specifying axis labels.
• plot_gate argument dim_ids split to x_label & y_label for specifying axis labels.

Bug fixes:

• Fixed KeyError in Workspace.summary method when a sample has no gates (see #155).
• Fixed WSP export of "range" RectangleGate instances (see #157).
• Fix ValueError thrown when compensating a Sample specifying null channels via null_channel_list (see #175).
• Fix Session.plot_scatter method where mixed compensations are specified for x & y channels (rare).

Documentation:

• Switched to ReadTheDocs theme for documentation.
• Clarify docstrings for null channel usage (see Sample & Matrix constructor docs).
• All notebooks validated and updated for the new release.

Dependencies:

• Dropped support for Python 3.7, added support for Python 3.11 & 3.12.
• FlowIO updated to >=1.3.0,<1.4
• FlowUtils updated to >=1.1.0,<1.2
• Matplotlib & Seaborn removed as dependencies. All plotting now uses the Bokeh library (>=3.1).
• Pandas updated to >=2.0
• Added new dependency contourpy (the library matplotlib uses).
• Other dependency minimum versions updated for Python 3.8 - 3.12 support (See requirements.txt for details).

1.0.1

BUGFIX: GatingStrategy instances using gate dimensions referencing built-in FCS compensation would return uncompensated events. This scenario would occur for GatingML 2.0 documents where the reserved 'FCS' value was used to reference the built-in FCS compensation matrix defined in the metadata keywords $SPILLOVER or $SPILL. Special thanks to @strategist333 for finding this issue and submitting PR #153.

1.0.0

Version 1.0.0 is a major milestone for the FlowKit project. This release adds support for custom sample gates in FlowJo 10 workspaces. As a major release, this version has significant API changes. Please read the release notes below and review the documentation for all the API changes.

New features:

• New dedicated Workspace class for importing FlowJo 10 workspaces. This class is essentially a read-only class for easily importing & extracting gating information from .wsp files.
• Importing .wsp files now supports 'eventsInside' flag for FlowJo gates (see #135)
• Session & GatingStrategy classes now support custom gates by specifying a sample_id when adding a gate to the gate tree.
• Session & GatingStrategy classes now support removing gates from the gate tree via a new remove_gate method. The method includes an option to retain downstream (descendant) gates.
• Sample class adds method get_index_sorted_locations for FACs Diva index sorted files (see #112)
• Sample class adds id attribute, allowing identification of samples created from NumPy arrays or pandas DataFrames.
• Sample class supports sorting (samples will be sorted by id attribute)
• Sample class constructor supports new arguments for controlling behavior in cases where there is a discrepancy in the data offset location (see #136)
• Sample method plot_scatter adds highlight_indices option for highlighting events using a Boolean array.
• Transform classes now support comparison for determining if 2 transforms are equivalent (i.e. have the same parameters).

Removed features:

• Removed calculate_compensation_from_beads, the function was moved to the flowkit_extras package (see #123)
• Session class no longer imports FlowJo 10 workspaces, this functionality now lives in the dedicated Workspace class
• Session class no longer uses sample groups, simplifying the API. Sample groups were needed for FlowJo workspaces.

API changes:

• New exceptions module containing custom FlowKit exceptions and warnings. This module also imports FlowIO exceptions so users can import all of them from one source.
• Session method get_group_samples was removed. group_name option removed from all Session methods.
• Session and GatingStrategy method get_child_gates was removed. A new method get_child_gate_ids was added. Gate instances are only available via get_gate.
• Session and GatingStrategy method get_parent_gate was removed. A new method get_parent_gate_id was added. Gate instances are only available via get_gate.
• GatingStrategy now has a is_custom_gate method for determining whether a Gate ID, Sample ID combination has a custom gate or the template gate.
• Session & Sample plot_scatter methods now take an optional bin_width argument to control the smoothness of the color density
• Gate classes no longer take the parent_gate_name argument. Gate relationships are handled completely by the GatingStrategy class.
• Gate classes have a new get_dimension_ids for retrieving Dimension IDs.
• Vertex class was removed. PolygonGate vertices are now just tuples of floats.

Bug fixes:

• Fix sample export of orig data for FCS files with data type int
• Fixed case where adding gates directly under QuadrantGate was possible. Adding a child gate to a QuadrantGate directly is not allowed, they must be added a one of the Quadrant instances.
• Fix parsing of FlowJo workspaces where a sample has no gate data.
• Fixed color density in scatter plots to correct missing 1st bin & poor coloring for data sets with outliers (see #139)

Documentation:

• Docstring for Sample method subsample_events corrected to reflect that the method does not return anything (see #129)
• Top-level functions & exceptions were added to the documentation
• All tutorial & advanced notebooks were updated for compatibility with the new API.

Dependencies:

• FlowIO requirement updated to 1.1.1
• Removed statsmodels dependency (see #123)
• Other dependency minimum versions updated for Python 3.7 - 3.10 support (See requirements.txt for details)