1.3.2

• BUGFIX: Fix KeyError when parsing FlowJo 10 workspace files when spilloverMatrix elements do not include the spectral attribute (see #278)

1.3.1

• BUGFIX: Ensure Sample.channels is sorted by channel number (see #274)
• Limit pandas version to < 3 due to incompatible API changes

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).