Releases: whitews/FlowKit
1.1.2
1.1.1
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
addsevent_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 addsdata_min
,data_max
, andx_range
kwargs for filtering data ranges and controlling the view range.- Removed argument
ignore_transforms
inparse_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
toplot_scatter
method in both Session & Workspace. sample_id
argument now required forGatingStrategy.is_custom_gate
method.- Rename
plot_scatter
argumenthighlight_indices
tohighlight_mask
(since it takes a Boolean array and not a list of indices). plot_scatter
argumentdim_ids
split tox_label
&y_label
for specifying axis labels.plot_gate
argumentdim_ids
split tox_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 vianull_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
addshighlight_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 methodget_child_gate_ids
was added. Gate instances are only available viaget_gate
. - Session and GatingStrategy method
get_parent_gate
was removed. A new methodget_parent_gate_id
was added. Gate instances are only available viaget_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 optionalbin_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
0.9.2
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 kwarginclude_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