flow_gates/
lib.rs

1//! # flow-gates
2//!
3//! A comprehensive Rust library for working with gates in flow cytometry data analysis.
4//!
5//! This library provides tools for creating, managing, and applying gates to flow cytometry
6//! data, supporting the GatingML 2.0 standard for gate definitions and hierarchies.
7//!
8//! ## Overview
9//!
10//! Flow cytometry gates define regions of interest in multi-dimensional data space,
11//! allowing researchers to identify and analyze specific cell populations. This library
12//! provides:
13//!
14//! - **Gate Types**: Polygon, Rectangle, and Ellipse geometries
15//! - **Gate Hierarchies**: Parent-child relationships for sequential gating
16//! - **Event Filtering**: Efficient spatial indexing and filtering of cytometry events
17//! - **Statistics**: Comprehensive statistics for gated populations
18//! - **GatingML Support**: Import/export gates in GatingML 2.0 XML format
19//! - **Thread-Safe Storage**: Concurrent gate management
20//!
21//! ## Quick Start
22//!
23//! ```rust
24//! use flow_gates::*;
25//! use flow_gates::geometry::*;
26//!
27//! # fn example() -> Result<(), Box<dyn std::error::Error>> {
28//! // Create a polygon gate
29//! let coords = vec![
30//!     (100.0, 200.0),
31//!     (300.0, 200.0),
32//!     (300.0, 400.0),
33//!     (100.0, 400.0),
34//! ];
35//! let geometry = create_polygon_geometry(coords, "FSC-A", "SSC-A")?;
36//!
37//! let gate = Gate::new(
38//!     "my-gate",
39//!     "My Gate",
40//!     geometry,
41//!     "FSC-A",
42//!     "SSC-A",
43//! );
44//!
45//! // Apply gate to FCS data
46//! // let event_indices = filter_events_by_gate(&fcs_file, &gate, None)?;
47//! # Ok(())
48//! # }
49//! ```
50//!
51//! ## Core Concepts
52//!
53//! ### Gates
54//!
55//! A [`Gate`] represents a region of interest defined by:
56//! - **Geometry**: The shape (polygon, rectangle, or ellipse)
57//! - **Parameters**: The two channels (x and y) the gate operates on
58//! - **Mode**: Whether the gate applies globally or to specific files
59//!
60//! ### Gate Hierarchies
61//!
62//! Gates can be organized in parent-child relationships, where child gates
63//! are applied to events that pass through their parent gates. Use [`GateHierarchy`]
64//! to manage these relationships.
65//!
66//! ### Event Filtering
67//!
68//! The library provides efficient event filtering using spatial indexing (R*-tree)
69//! for fast point-in-gate queries. Use [`EventIndex`] for repeated filtering operations
70//! on the same dataset.
71//!
72//! ## Examples
73//!
74//! See the [README](https://github.com/jrmoynihan/flow-gates) for detailed examples
75//! including:
76//! - Creating different gate types
77//! - Building gate hierarchies
78//! - Filtering events
79//! - Calculating statistics
80//! - Application integration patterns
81//!
82//! ## Error Handling
83//!
84//! The library uses [`GateError`] for all error conditions. Most operations return
85//! [`Result<T, GateError>`](GateResult).
86
87use std::sync::Arc;
88
89pub mod batch_filtering;
90pub mod ellipse;
91pub mod error;
92pub mod filtering;
93pub mod gatingml;
94pub mod geometry;
95pub mod hierarchy;
96pub mod linking;
97pub mod polygon;
98pub mod rectangle;
99pub mod scope;
100pub mod statistics;
101pub mod traits;
102pub mod traits_tests;
103pub mod transforms;
104pub mod types;
105
106#[cfg(test)]
107mod error_tests;
108
109/// Error types for gate operations
110pub use error::{GateError, Result as GateResult};
111
112/// Event filtering and spatial indexing
113pub use filtering::{
114    EventIndex, FilterCache, FilterCacheKey, GateResolver, combine_gates_and, combine_gates_not,
115    combine_gates_or, filter_events_boolean, filter_events_by_gate,
116    filter_events_by_gate_with_resolver, filter_events_by_hierarchy,
117    filter_events_by_hierarchy_with_resolver,
118};
119
120/// Geometry construction helpers
121pub use geometry::{create_ellipse_geometry, create_polygon_geometry, create_rectangle_geometry};
122
123/// Gate hierarchy management
124pub use hierarchy::GateHierarchy;
125
126/// Gate linking system
127pub use linking::GateLinks;
128
129/// Gate querying and filtering helpers
130pub use scope::{
131    GateQuery, filter_gates_by_parameters, filter_gates_by_scope, filter_gates_by_type,
132    filter_hierarchy_by_parameters,
133};
134
135/// Statistics for gated populations
136pub use statistics::GateStatistics;
137
138/// GatingML import/export
139pub use gatingml::{gates_to_gatingml, gatingml_to_gates};
140
141/// Core gate types and structures
142pub use types::{BooleanOperation, Gate, GateBuilder, GateGeometry, GateMode, GateNode};
143
144/// Gate geometry traits
145pub use traits::{GateBounds, GateCenter, GateContainment, GateGeometryOps, GateValidation};
146
147/// Type alias for parameter sets
148pub type ParameterSet = (Arc<str>, Arc<str>);
149
150// Note: FilterCache and GateStorage are application-specific and should be
151// implemented in the application crate, not in this library crate.
flow_gates/lib.rs

flow_gates/
lib.rs
