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

1.0.1

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.

1.0.0

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)

0.9.3

Patch release 0.9.3

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

0.9.2

Patch release 0.9.2

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

0.9.1

Dependencies:

• FlowIO requirement updated to v1.0.1 (fixes issue exporting some FCS files)

API changes:

• new GatingStrategy method find_matching_gate_paths to find gate paths given a gate name
• new Session method find_matching_gate_paths & get_child_gate_ids

Bug fixes:

• Corrected error types (several instances of ValueError changed to TypeError)
• BUGFIX: Fixed issue where adding new gates to a Session where a WSP was imported would cause an error (issue #110)

Documentation:

• Several docstrings updated and fixed for ReadTheDocs
• Example notebooks moved to docs folder & added to ReadTheDocs

0.9.0

New features:

• Support for Python 3.10 (drops support for Python 3.6)
• All C extensions moved to FlowUtils (and FlowUtils now provides pre-built wheels - should avoid the need for a compiler for most users)
• New function extract_wsp_sample_data to parse FlowJo 10 wsp & extract Sample metadata (keywords) to a Python dictionary
• New GatingStrategy method get_max_depth to get max depth of gate tree
• New Session method summary for a quick summary of what the session contains
• Sample class now supports exporting new FCS files with metadata (#89)

API changes:

• Sample attribute channel_lin_log removed, lin / log metadata now available as "pne" column in Sample.channels attribute
• Sample class: export method has new kwarg include_metadata for including all key/value pairs in self.metadata in the output FCS file

Bug fixes:

• Fixed typo in FCS_STANDARD_KEYWORDS for 'date' keyword
• Fixed parsing of FlowJo workspaces where sample groups have "gate-less" samples (#91)
• Replace special quote characters that caused a UnicodeDecodeError on some Windows installs (#97)

Dependencies:

• FlowIO requirement updated to 1.0.0
• FlowUtils requirement updated to 1.0.0 (with pre-built binaries for most platforms)
• NumPy minimum requirement of 1.20 when using pre-built FlowUtils binaries (required for NumPy C API compatibility)
• Fix deprecation warnings from Pandas 1.4 (squeeze kwarg removed from read_csv)

Acknowledgements:

• Special thanks to @sbenz for help testing this release on arm64 Macs (Apple Silicon)

0.8.2

• Sample Class
  • Error is raised when retrieving compensated or transformed events prior to applying a compensation matrix or a transform (used to issue just a warning)
  • plot_scatter_matrix argument order changed to be more consistent with other plot methods
• Session Class
  • Analyzing multiple samples using multiprocessing now uses a more conservative estimate of memory to avoid running out of system memory
• BUGFIX: Fixed failure to properly parse FlowJo workspaces containing an ellipse gate.
• Documentation was updated to include a table of contents with links to methods for the complex classes: Sample, GatingStrategy, GatingResults, & Session

0.8.1

• GatingResults get methods now accept a gate_path argument to disambiguate re-used gates
• BUGFIX: fixed issue parsing FlowJo 10 wsp files with reused gates that contain a child gate (issue #84)
• Suppressed output for analyzing Session samples when verbose=False
• Suppress FlowKit generated warnings when running tests