1.2.1

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

1.2.0

FlowKit 1.2.0 is out! Major updates include support for Boolean gates in FlowJo workspaces, renaming Sample channels and making the API more user-friendly. Thanks to everyone who contributed to this release, keep the bug reports and suggestions coming!

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

1.1.2

• BUGFIX: Fix typo in Matrix.fluorochromes attribute. Thanks to @okolupaev for reporting #206!

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