# guignardlab/lineagetree architecture

> Architecture diagram of the GitHub repository guignardlab/lineagetree, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guignardlab/lineagetree
- Repository: https://github.com/guignardlab/lineagetree

## Overview

#### 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: [`src/lineagetree/lineage_tree.py`](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/lineage_tree.py) (LineageTree), [`src/lineagetree/__init__.py`](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/__init__.py) (Package exports), [`src/lineagetree/lineage_tree_manager.py`](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/lineage_tree_manager.py) (LineageTreeManager), [`src/lineagetree/_core/_modifier.py`](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/_modifier.py) (Mutation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_package["Package exports<br/>Python package<br/>[__init__.py]"]
  node_tree{{"LineageTree<br/>primary object<br/>[lineage_tree.py]"}}
  node_manager["LineageTreeManager<br/>multi-tree coordinator"]
end

subgraph group_core["Canonical Tree Core"]
  node_properties["Tree properties<br/>core properties<br/>[_properties.py]"]
  node_validation["Validation<br/>core invariants<br/>[validation.py]"]
  node_navigation["Traversal engine<br/>core navigation<br/>[_navigation.py]"]
  node_modifier["Mutation engine<br/>core modification<br/>[_modifier.py]"]
  node_mixins["Domain mixins<br/>object behavior"]
end

subgraph group_io["Import / Export"]
  node_loaders["Format loaders<br/>input adapters<br/>[_loaders.py]"]
  node_writers["Format writers<br/>output adapters<br/>[_writers.py]"]
  node_legacy["Legacy adapters<br/>interoperability<br/>[to_lineajea.py]"]
end

subgraph group_analysis["Analysis &amp; Presentation"]
  node_uted["Tree edit distance<br/>comparison<br/>[uted.py]"]
  node_dtw["Trajectory DTW<br/>comparison"]
  node_spatial["Spatial measurements<br/>spatial analysis<br/>[spatial.py]"]
  node_approximation["Tree approximation<br/>transformation"]
  node_plotting["Visualization<br/>presentation<br/>[plot.py]"]
end

node_packaging["Package delivery<br/>packaging<br/>[pyproject.toml]"]
node_docs["Documentation"]

node_package -->|"exports"| node_tree
node_package -->|"exports"| node_manager
node_tree -->|"composes behavior"| node_mixins
node_tree -->|"derives properties"| node_properties
node_tree -->|"enforces invariants"| node_validation
node_mixins -->|"delegates traversal"| node_navigation
node_mixins -->|"delegates mutation"| node_modifier
node_modifier -->|"preserves consistency"| node_validation
node_modifier -->|"updates derived state"| node_properties
node_loaders -->|"constructs canonical model"| node_tree
node_tree -->|"serializes"| node_writers
node_legacy -.->|"converts via isolated path"| node_tree
node_manager -->|"coordinates comparisons"| node_uted
node_manager -->|"coordinates comparisons"| node_dtw
node_tree -->|"provides positions and time"| node_spatial
node_tree -->|"input tree"| node_approximation
node_tree -->|"visualization input"| node_plotting
node_dtw -->|"alignment plots"| node_plotting
node_packaging -->|"distributes"| node_package
node_docs -.->|"documents"| node_package

click node_package "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/__init__.py"
click node_tree "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/lineage_tree.py"
click node_manager "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/lineage_tree_manager.py"
click node_properties "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/_properties.py"
click node_validation "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/validation.py"
click node_navigation "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/_navigation.py"
click node_modifier "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/_modifier.py"
click node_mixins "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_mixins/navigation_mixin.py"
click node_loaders "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_io/_loaders.py"
click node_writers "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_io/_writers.py"
click node_legacy "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_legacy/to_lineajea.py"
click node_uted "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/measure/uted.py"
click node_dtw "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/measure/dynamic_time_warping.py"
click node_spatial "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/measure/spatial.py"
click node_approximation "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/tree_approximation.py"
click node_plotting "https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/plot.py"
click node_packaging "https://github.com/guignardlab/lineagetree/blob/v3.x/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package,node_tree,node_manager toneBlue
class node_properties,node_validation,node_navigation,node_modifier,node_mixins toneAmber
class node_loaders,node_writers,node_legacy toneMint
class node_uted,node_dtw,node_spatial,node_approximation,node_plotting toneRose
class node_packaging,node_docs toneNeutral
```

## Components

### Public API

- [Package exports](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/__init__.py): Python package · Public library entry point. · `src/lineagetree/__init__.py`
- [LineageTree](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/lineage_tree.py): primary object · Canonical directed lineage-tree model and object API. · `src/lineagetree/lineage_tree.py`
- [LineageTreeManager](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/lineage_tree_manager.py): multi-tree coordinator · Coordinates comparisons across separate trees. · `src/lineagetree/lineage_tree_manager.py`

### Canonical Tree Core

- [Tree properties](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/_properties.py): core properties · Derives roots, leaves, time bounds, and chains. · `src/lineagetree/_core/_properties.py`
- [Validation](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/validation.py): core invariants · Enforces canonical lineage consistency. · `src/lineagetree/_core/validation.py`
- [Traversal engine](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/_navigation.py): core navigation · Traverses predecessors and successors. · `src/lineagetree/_core/_navigation.py`
- [Mutation engine](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_core/_modifier.py): core modification · Changes topology and trajectory data. · `src/lineagetree/_core/_modifier.py`
- [Domain mixins](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_mixins/navigation_mixin.py): object behavior · Composes navigation, mutation, spatial, I/O, and plotting APIs. · `src/lineagetree/_mixins/navigation_mixin.py`

### Import / Export

- [Format loaders](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_io/_loaders.py): input adapters · Converts external tracking and morphology data into trees. · `src/lineagetree/_io/_loaders.py`
- [Format writers](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_io/_writers.py): output adapters · Exports native pickle, SVG, and Tulip formats. · `src/lineagetree/_io/_writers.py`
- [Legacy adapters](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/_legacy/to_lineajea.py): interoperability · Isolated LineaJEa and Motile conversion path. · `src/lineagetree/_legacy/to_lineajea.py`

### Analysis & Presentation

- [Tree edit distance](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/measure/uted.py): comparison · Compares subtrees with unordered tree edit distance. · `src/lineagetree/measure/uted.py`
- [Trajectory DTW](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/measure/dynamic_time_warping.py): comparison · Aligns trajectories and returns an alignment path. · `src/lineagetree/measure/dynamic_time_warping.py`
- [Spatial measurements](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/measure/spatial.py): spatial analysis · Builds geometric relationships from time-specific positions. · `src/lineagetree/measure/spatial.py`
- [Tree approximation](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/tree_approximation.py): transformation · Separate tree transformation and analysis capability. · `src/lineagetree/tree_approximation.py`
- [Visualization](https://github.com/guignardlab/lineagetree/blob/v3.x/src/lineagetree/plot.py): presentation · Draws lineage trees, subtrees, and DTW-oriented plots. · `src/lineagetree/plot.py`

### Other components

- [Package delivery](https://github.com/guignardlab/lineagetree/blob/v3.x/pyproject.toml): packaging · Python distribution metadata. · `pyproject.toml`
- **Documentation**: documentation · Published package documentation source.

## Connections

- 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
