Merge pull request #37 from Adamtaranto/copilot/update-dash-app-network-plots

[WIP] Update Dash app with haplotype mapping and features

Author: Adamtaranto

README.md

@@ -7,7 +7,7 @@
 
 ## Features
 
-- **Multiple Network Algorithms**: MST, MSN, TCS (Statistical Parsimony), and Median-Joining
+- **Multiple Network Algorithms**: MST, MSN, TCS (Statistical Parsimony), Median-Joining, and TSW (Parsimony Network)
 - **Distance Metrics**: Hamming, Jukes-Cantor, Kimura 2-parameter, Tamura-Nei
 - **Comprehensive Analysis**: Network statistics, topology analysis, population genetics measures
 - **Rich Visualization**: Static (matplotlib) and interactive (Plotly) network plots
@@ -188,6 +188,16 @@ pypopart network sequences.fasta -a mjn -e 0 -o network.graphml
 
 **Use when**: You want to infer ancestral haplotypes and show complex evolutionary relationships. The epsilon parameter controls network complexity (0 = maximum simplification).
 
+### Tight Span Walker (TSW) - Parsimony Network
+
+Constructs networks using the tight span of the distance matrix, preserving all metric properties.
+
+```bash
+pypopart network sequences.fasta -a tsw -o network.graphml
+```
+
+**Use when**: You need accurate metric-preserving networks for complex evolutionary relationships with reticulation. Best for small to medium datasets (n < 100). Automatically infers ancestral/median sequences.
+
 ## Distance Metrics
 
 - **hamming**: Simple count of differences (fastest)

docs/algorithms/tsw.md

@@ -0,0 +1,61 @@
+# Tight Span Walker (TSW) - Parsimony Network Algorithm
+
+## Overview
+
+The Tight Span Walker (TSW) algorithm constructs haplotype networks using parsimony principles by computing the **tight span** of a distance matrix. The tight span is the smallest metric space that contains all optimal paths between sequences, making it ideal for representing complex evolutionary relationships with reticulation events.
+
+## Algorithm Details
+
+### How It Works
+
+1. **Compute dT Distances (Tree Metric)**
+   - For each pair of sequences (i, j), calculate: `dT(i,j) = max over all k of |d(i,k) - d(j,k)|`
+   - This represents the minimum distance if sequences were constrained to a tree structure
+
+2. **Build Geodesic Paths**
+   - For each pair of haplotypes, construct the geodesic (shortest) path
+   - Compare the actual distance with the dT distance
+   - If `actual_distance - dT_distance > epsilon`, infer intermediate median vertices
+
+3. **Infer Median Vertices**
+   - When needed, create intermediate (ancestral) nodes
+   - Medians represent hypothetical ancestral or intermediate sequences
+
+4. **Construct Network**
+   - Connect all haplotypes through geodesic paths
+   - Include inferred median vertices to maintain metric properties
+
+### Key Features
+
+- **Metric Preservation**: Maintains all distance relationships from original data
+- **Reticulate Networks**: Can represent complex relationships
+- **Ancestral Inference**: Automatically infers hypothetical ancestral sequences
+- **Parsimony-Based**: Uses parsimony principles
+
+## Parameters
+
+- **epsilon** (float, default=1e-6): Tolerance for metric comparisons
+- **distance_method** (str, default='hamming'): Distance calculation method
+
+## When to Use TSW
+
+✓ Complex evolutionary relationships with reticulation  
+✓ Small to medium datasets (n < 100)  
+✓ Accurate metric representation needed  
+✓ Ancestral sequence inference desired
+
+## Usage Example
+
+```python
+from pypopart.algorithms import TightSpanWalker
+from pypopart.io import load_alignment
+
+alignment = load_alignment('sequences.fasta')
+tsw = TightSpanWalker(distance_method='hamming')
+network = tsw.construct_network(alignment)
+```
+
+## References
+
+1. Dress, A. W., & Huson, D. H. (2004). Constructing splits graphs. IEEE/ACM Transactions on Computational Biology and Bioinformatics, 1(3), 109-115.
+2. Bryant, D., & Moulton, V. (2004). Neighbor-Net. Molecular Biology and Evolution, 21(2), 255-265.

src/pypopart/algorithms/__init__.py

@@ -10,21 +10,25 @@
 from .msn import MinimumSpanningNetwork
 from .mst import MinimumSpanningTree
 from .tcs import TCS
+from .tsw import TightSpanWalker
 
 # Convenient aliases
 MSTAlgorithm = MinimumSpanningTree
 MSNAlgorithm = MinimumSpanningNetwork
 TCSAlgorithm = TCS
 MJNAlgorithm = MedianJoiningNetwork
+TSWAlgorithm = TightSpanWalker
 
 __all__ = [
     'NetworkAlgorithm',
     'MinimumSpanningTree',
     'MinimumSpanningNetwork',
     'TCS',
     'MedianJoiningNetwork',
+    'TightSpanWalker',
     'MSTAlgorithm',
     'MSNAlgorithm',
     'TCSAlgorithm',
     'MJNAlgorithm',
+    'TSWAlgorithm',
 ]