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)