How guignardlab/lineagetree works
Purpose and public entry points
LineageTree is a Python 3.10+ library for importing, representing, analyzing, comparing, modifying, and visualizing cell lineage trees. The principal public object is LineageTree, with LineageTreeManager supporting multi-tree workflows. Package exports are rooted at src/lineagetree/__init__.py; object orchestration resides in src/lineagetree/lineage_tree.py and src/lineagetree/lineage_tree_manager.py.
Canonical lineage-tree model
LineageTree represents a directed lineage structure with node identity, successor/predecessor relations, temporal assignments, and optional spatial positions. Construction accepts graph-like mappings (e.g., successor, time, pos), then derives/queryable tree properties such as roots, leaves, time bounds, and chains. Core invariants and common internals are concentrated in:
• src/lineagetree/lineage_tree.py
• src/lineagetree/_core/_properties.py
• src/lineagetree/_core/validation.py
Composed behavior via mixins
The main tree class is behaviorally assembled from domain-specific mixins rather than placing all operations in one module. This creates a stable object-facing API across navigation, graph modification, I/O, analysis, plotting, properties, and spatial operations. Key boundaries are:
• src/lineagetree/_mixins/navigation_mixin.py
• src/lineagetree/_mixins/modifier_mixin.py
• src/lineagetree/_mixins/spatial_mixin.py
Import/export boundary
Format-specific loaders convert external tracking and morphology formats into the canonical LineageTree; writers serialize/export the internal model to native pickle (.lT), SVG, and Tulip formats. Consumers should keep format parsing at this boundary and operate on LineageTree thereafter.
• src/lineagetree/_io/_loaders.py
• src/lineagetree/_io/_writers.py
• src/lineagetree/_mixins/io_mixin.py
Legacy interoperability adapters are intentionally isolated from the primary path:
• src/lineagetree/_legacy/to_lineajea.py
• src/lineagetree/_legacy/to_motile.py
Tree traversal and mutation flow
Navigation operations traverse successors/predecessors to expose subtrees, time slices, and unbroken lineage chains. Mutation operations change lineage topology or trajectory-associated data; derived properties must remain consistent with the graph afterward. The core implementation split is:
• src/lineagetree/_core/_navigation.py
• src/lineagetree/_core/_modifier.py
• src/lineagetree/_core/utils.py
Analysis and comparison
Analysis is tree- and trajectory-centric: unordered tree edit distance compares subtrees, while dynamic time warping compares trajectories and returns an alignment path. Spatial measurements build time-specific geometric relationships (KD-tree indexing, nearest-neighbor queries, Gabriel graphs, density) from node positions.
• src/lineagetree/measure/uted.py
• src/lineagetree/measure/dynamic_time_warping.py
• src/lineagetree/measure/spatial.py
LineageTreeManager coordinates cross-lineage comparisons rather than merging tree state:
• src/lineagetree/lineage_tree_manager.py
Presentation and approximation
Visualization is an output layer over the tree and analysis results, including lineage/subtree drawings and DTW-oriented plots. Tree approximation is a separate transformation/analysis capability, not part of base ingestion.
• src/lineagetree/plot.py
• src/lineagetree/_mixins/plot_mixin.py
• src/lineagetree/tree_approximation.py
Delivery and documentation
The package is distributed through Python packaging metadata in pyproject.toml. CI runs test/deploy automation through .github/workflows/test_and_deploy.yml; published documentation is built from docs/.
Main entry points: lineage_tree.py LineageTree · __init__.py Package exports · lineage_tree_manager.py LineageTreeManager · _modifier.py Mutation engine
Components 18
Public API
- Package exports · Public library entry point.
src/lineagetree/__init__.py - LineageTree · Canonical directed lineage-tree model and object API.
src/lineagetree/lineage_tree.py - LineageTreeManager · Coordinates comparisons across separate trees.
src/lineagetree/lineage_tree_manager.py
Canonical Tree Core
- Tree properties · Derives roots, leaves, time bounds, and chains.
src/lineagetree/_core/_properties.py - Validation · Enforces canonical lineage consistency.
src/lineagetree/_core/validation.py - Traversal engine · Traverses predecessors and successors.
src/lineagetree/_core/_navigation.py - Mutation engine · Changes topology and trajectory data.
src/lineagetree/_core/_modifier.py - Domain mixins · Composes navigation, mutation, spatial, I/O, and plotting APIs.
src/lineagetree/_mixins/navigation_mixin.py
Import / Export
- Format loaders · Converts external tracking and morphology data into trees.
src/lineagetree/_io/_loaders.py - Format writers · Exports native pickle, SVG, and Tulip formats.
src/lineagetree/_io/_writers.py - Legacy adapters · Isolated LineaJEa and Motile conversion path.
src/lineagetree/_legacy/to_lineajea.py
Analysis & Presentation
- Tree edit distance · Compares subtrees with unordered tree edit distance.
src/lineagetree/measure/uted.py - Trajectory DTW · Aligns trajectories and returns an alignment path.
src/lineagetree/measure/dynamic_time_warping.py - Spatial measurements · Builds geometric relationships from time-specific positions.
src/lineagetree/measure/spatial.py - Tree approximation · Separate tree transformation and analysis capability.
src/lineagetree/tree_approximation.py - Visualization · Draws lineage trees, subtrees, and DTW-oriented plots.
src/lineagetree/plot.py
Other components
- Package delivery · Python distribution metadata.
pyproject.toml - Documentation · Published package documentation source.
Connections 20
- Package exports → LineageTree: exports
- Package exports → LineageTreeManager: exports
- LineageTree → Domain mixins: composes behavior
- LineageTree → Tree properties: derives properties
- LineageTree → Validation: enforces invariants
- Domain mixins → Traversal engine: delegates traversal
- Domain mixins → Mutation engine: delegates mutation
- Mutation engine → Validation: preserves consistency
- Mutation engine → Tree properties: updates derived state
- Format loaders → LineageTree: constructs canonical model
- LineageTree → Format writers: serializes
- Legacy adapters → LineageTree: converts via isolated path
- LineageTreeManager → Tree edit distance: coordinates comparisons
- LineageTreeManager → Trajectory DTW: coordinates comparisons
- LineageTree → Spatial measurements: provides positions and time
- LineageTree → Tree approximation: input tree
- LineageTree → Visualization: visualization input
- Trajectory DTW → Visualization: alignment plots
- Package delivery → Package exports: distributes
- Documentation → Package exports: documents