Flowkit

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

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

* BUGFIX: Fix typo in `Matrix.fluorochromes` attribute. Thanks to okolupaev for reporting 206!

* 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!

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

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.