1.3.0

[whitews]

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_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 Feature Request: Custom Bin Settings for plot_gate Function #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 "only_text" import of FCS metadata in FlowKit? #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 Rename Workspace kwarg ignore_missing_files to load_missing_file_data #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 Error when Renaming Quadrant in FlowKit #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 add channel_labels check for creating Sample from ndarray #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)

---

This discussion was created from the release 1.3.0.