Flowkit

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

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)

* Fixes import issue where XMLSchemaParseError is raised if FlowKit is installed in paths containing special characters (see 106, 122)

* Fixes parsing of ellipse gates in FlowJo 10 workspace files (see 120)