LZPgen stability improved, fixed bug in stop condition probability and fragility, also made simulating sequences more efficent via caching

Author: MuteJester

Examples/LZPgen Example.ipynb

@@ -22,7 +22,15 @@ from LZGraphs import (
     jensen_shannon_divergence,
     cross_entropy,
     kl_divergence,
-    mutual_information_genes
+    mutual_information_genes,
+    transition_predictability,
+    graph_compression_ratio,
+    repertoire_compressibility_index,
+    transition_kl_divergence,
+    transition_jsd,
+    transition_mutual_information_profile,
+    path_entropy_rate,
+    compare_repertoires,
 )
 ```
 
@@ -223,8 +231,151 @@ print(f"MI (V): {mi_v:.4f}, MI (J): {mi_j:.4f}")
 
 ---
 
+## Information-Theoretic Metrics
+
+### transition_predictability
+
+Measures how deterministic the graph transitions are relative to the maximum possible branching.
+
+```python
+from LZGraphs import transition_predictability
+
+tp = transition_predictability(graph)
+print(f"Transition predictability: {tp:.3f}")  # 0 to 1
+```
+
+!!! note "Function Signature"
+    `transition_predictability(lzgraph, base=2) -> float`
+
+    Returns a value in [0, 1]. Higher values indicate more deterministic transitions (restricted repertoire). Empirically stable at ~0.60 for AAPLZGraph across sample sizes.
+
+### graph_compression_ratio
+
+Measures how much the graph compresses repeated transitions into shared edges.
+
+```python
+from LZGraphs import graph_compression_ratio
+
+gcr = graph_compression_ratio(graph)
+print(f"Compression ratio: {gcr:.3f}")  # 0 to 1
+```
+
+!!! note "Function Signature"
+    `graph_compression_ratio(lzgraph) -> float`
+
+    Returns `n_edges / n_transitions`. Lower values indicate more path sharing. AAPLZGraph ~0.18, NaiveLZGraph ~0.05.
+
+### repertoire_compressibility_index
+
+Alias for `transition_predictability`, framed from a data compression perspective.
+
+```python
+from LZGraphs import repertoire_compressibility_index
+
+rci = repertoire_compressibility_index(graph)
+print(f"Compressibility: {rci:.3f}")  # 0 to 1
+```
+
+!!! note "Function Signature"
+    `repertoire_compressibility_index(lzgraph, base=2) -> float`
+
+    RCI = 1 means fully deterministic (compressible), RCI = 0 means maximally uncertain (incompressible).
+
+### path_entropy_rate
+
+Estimates the average information content per subpattern step across actual sequences.
+
+```python
+from LZGraphs import path_entropy_rate
+
+sequences = data['cdr3_amino_acid'].tolist()
+h = path_entropy_rate(graph, sequences)
+print(f"Entropy rate: {h:.3f} bits/step")
+```
+
+!!! note "Function Signature"
+    `path_entropy_rate(lzgraph, sequences, base=2) -> float`
+
+    Uses `walk_log_probability()` internally. AAPLZGraph ~2.5 bits/step, NaiveLZGraph ~3.5 bits/step.
+
+---
+
+## Transition-Level Divergence
+
+### transition_kl_divergence
+
+Transition-level KL divergence — compares the transition structure, not just node distributions.
+
+```python
+from LZGraphs import transition_kl_divergence
+
+kl = transition_kl_divergence(graph1, graph2)
+print(f"Transition KL: {kl:.4f}")
+```
+
+!!! note "Function Signature"
+    `transition_kl_divergence(lzgraph_p, lzgraph_q) -> float`
+
+    Asymmetric, can be infinite. Use `transition_jsd` for a bounded alternative.
+
+### transition_jsd
+
+Transition-level Jensen-Shannon divergence — always finite, symmetric.
+
+```python
+from LZGraphs import transition_jsd
+
+jsd_t = transition_jsd(graph1, graph2)
+print(f"Transition JSD: {jsd_t:.4f}")  # 0 to 1
+```
+
+!!! note "Function Signature"
+    `transition_jsd(lzgraph1, lzgraph2) -> float`
+
+    Symmetric and bounded [0, 1]. Recommended for comparing repertoire transition structures.
+
+### transition_mutual_information_profile
+
+Position-specific mutual information along the CDR3 sequence.
+
+```python
+from LZGraphs import transition_mutual_information_profile
+
+tmip = transition_mutual_information_profile(graph)
+for pos in sorted(tmip):
+    print(f"Position {pos}: MI = {tmip[pos]:.3f} bits")
+```
+
+!!! note "Function Signature"
+    `transition_mutual_information_profile(lzgraph) -> dict`
+
+    Returns `{position: mutual_information}`. Only works with positional graphs (AAPLZGraph, NDPLZGraph). Raises `MetricsError` for NaiveLZGraph.
+
+---
+
+## Convenience
+
+### compare_repertoires
+
+All-in-one repertoire comparison returning a pandas Series of metrics.
+
+```python
+from LZGraphs import compare_repertoires
+
+result = compare_repertoires(graph1, graph2)
+print(result)
+```
+
+!!! note "Function Signature"
+    `compare_repertoires(graph1, graph2) -> pd.Series`
+
+    Returns: `js_divergence`, `transition_jsd`, `cross_entropy_1_2`, `cross_entropy_2_1`, `kl_divergence_1_2`, `kl_divergence_2_1`, `node_entropy_1`, `node_entropy_2`, `edge_entropy_1`, `edge_entropy_2`, `transition_predictability_1`, `transition_predictability_2`, `shared_nodes`, `shared_edges`, `jaccard_nodes`, `jaccard_edges`.
+
+---
+
 ## See Also
 
 - [Tutorials: Diversity Metrics](../tutorials/diversity-metrics.md)
 - [How-To: Compare Repertoires](../how-to/repertoire-comparison.md)
 - [Concepts: Probability Model](../concepts/probability-model.md)
+- [Example: Information-Theoretic Analysis](https://github.com/MuteJester/LZGraphs/blob/master/Examples/Information-Theoretic%20Analysis.ipynb)

docs/api/metrics.md

@@ -54,6 +54,17 @@ Use NaiveLZGraph for consistent feature vectors and cross-repertoire analysis.
 [:material-notebook: View Notebook](https://github.com/MuteJester/LZGraphs/blob/master/Examples/NaiveLZGraph%20Example.ipynb){ .md-button }
 </div>
 
+<div class="example-card" markdown>
+
+### Information-Theoretic Analysis
+
+**Advanced repertoire characterization**
+
+Transition predictability, compression ratio, path entropy rate, transition JSD, mutual information profiles, and repertoire fingerprinting.
+
+[:material-notebook: View Notebook](https://github.com/MuteJester/LZGraphs/blob/master/Examples/Information-Theoretic%20Analysis.ipynb){ .md-button }
+</div>
+
 </div>
 
 ## Running Notebooks Locally
@@ -148,6 +159,7 @@ print(f"V: {v_gene}, J: {j_gene}")
 | NDPLZGraph | Nucleotide encoding, double positions, gene analysis |
 | Metrics | K-diversity, entropy, perplexity, JS divergence |
 | NaiveLZGraph | Fixed dictionaries, eigenvector centrality, ML features |
+| Information-Theoretic Analysis | Transition predictability, compression ratio, path entropy, TMIP, transition JSD |
 
 ## Next Steps
 

docs/examples/index.md

@@ -271,9 +271,49 @@ print("Top V gene differences:")
 print(v_comp.sort_values('diff', key=abs, ascending=False).head())
 ```
 
+## Transition-Level Comparison
+
+Standard JSD compares which subpatterns are used. **Transition JSD** compares how they connect, detecting structural differences even when subpattern frequencies are similar.
+
+```python
+from LZGraphs import transition_jsd, transition_kl_divergence
+
+# Symmetric, bounded [0, 1] — recommended for most use cases
+jsd_t = transition_jsd(graph1, graph2)
+print(f"Transition JSD: {jsd_t:.4f}")
+
+# Asymmetric — use when you have a reference model
+kl_t = transition_kl_divergence(graph1, graph2)  # Can be infinite
+print(f"Transition KL(1||2): {kl_t}")
+```
+
+!!! tip "When to use transition-level metrics"
+    Use `transition_jsd` instead of `jensen_shannon_divergence` when you suspect two repertoires use the same subpatterns but connect them differently, e.g. after clonal expansion creates dominant transition paths without changing overall subpattern frequencies.
+
+## Quick Comparison with compare_repertoires
+
+The `compare_repertoires` function computes all relevant metrics in one call:
+
+```python
+from LZGraphs import compare_repertoires
+
+result = compare_repertoires(graph1, graph2)
+print(result)
+# Returns a pandas Series with 16 metrics including:
+# js_divergence, transition_jsd, cross_entropy, kl_divergence,
+# node/edge entropy, transition_predictability, Jaccard similarity
+```
+
 ## Complete Comparison Pipeline
 
 ```python
+from LZGraphs import (
+    AAPLZGraph, K1000_Diversity,
+    node_entropy, jensen_shannon_divergence,
+    transition_jsd, transition_predictability,
+    compare_repertoires,
+)
+
 def full_repertoire_comparison(data1, data2, name1="Rep1", name2="Rep2"):
     """Complete comparison of two repertoires."""
 
@@ -282,6 +322,9 @@ def full_repertoire_comparison(data1, data2, name1="Rep1", name2="Rep2"):
     graph1 = AAPLZGraph(data1, verbose=False)
     graph2 = AAPLZGraph(data2, verbose=False)
 
+    # Quick comparison (all metrics at once)
+    result = compare_repertoires(graph1, graph2)
+
     # Basic stats
     print(f"\n{'='*50}")
     print("BASIC STATISTICS")
@@ -293,8 +336,15 @@ def full_repertoire_comparison(data1, data2, name1="Rep1", name2="Rep2"):
     print(f"\n{'='*50}")
     print("DIVERGENCE")
     print(f"{'='*50}")
-    jsd = jensen_shannon_divergence(graph1, graph2)
-    print(f"Jensen-Shannon Divergence: {jsd:.4f}")
+    print(f"Node-level JSD:       {result['js_divergence']:.4f}")
+    print(f"Transition-level JSD: {result['transition_jsd']:.4f}")
+
+    # Predictability
+    print(f"\n{'='*50}")
+    print("TRANSITION PREDICTABILITY")
+    print(f"{'='*50}")
+    print(f"{name1}: {result['transition_predictability_1']:.3f}")
+    print(f"{name2}: {result['transition_predictability_2']:.3f}")
 
     # Diversity
     print(f"\n{'='*50}")
@@ -307,17 +357,10 @@ def full_repertoire_comparison(data1, data2, name1="Rep1", name2="Rep2"):
     print(f"{name1} K1000: {k1:.1f}")
     print(f"{name2} K1000: {k2:.1f}")
 
-    # Entropy
-    print(f"\n{'='*50}")
-    print("ENTROPY")
-    print(f"{'='*50}")
-    print(f"{name1} node entropy: {node_entropy(graph1):.2f}")
-    print(f"{name2} node entropy: {node_entropy(graph2):.2f}")
-
-    return graph1, graph2, jsd
+    return graph1, graph2, result
 
 # Run comparison
-g1, g2, jsd = full_repertoire_comparison(data1, data2, "Healthy", "Disease")
+g1, g2, metrics = full_repertoire_comparison(data1, data2, "Healthy", "Disease")
 ```
 
 ## Next Steps

docs/how-to/repertoire-comparison.md

@@ -6,13 +6,38 @@ This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [Unreleased]
+## [2.1.0] - 2026
 
 ### Added
+- **Information-theoretic metrics** for advanced repertoire characterization:
+    - `transition_predictability` — measures transition determinism, stable across sample sizes (~0.60 for AAPLZGraph)
+    - `graph_compression_ratio` — quantifies path sharing efficiency (edge reuse)
+    - `repertoire_compressibility_index` — compression-framed alias for transition predictability
+    - `path_entropy_rate` — average bits per subpattern step via Monte Carlo
+    - `transition_kl_divergence` — transition-level KL divergence between two graphs
+    - `transition_jsd` — symmetric, bounded transition-level Jensen-Shannon divergence
+    - `transition_mutual_information_profile` — position-specific MI along the CDR3 sequence
+- `compare_repertoires` now includes `transition_jsd`, `transition_predictability_1`, and `transition_predictability_2`
+- New example notebook: **Information-Theoretic Analysis** with full walkthrough and visualizations
+
+---
+
+## [2.0.0] - 2026
+
+### Changed
+- **Breaking**: All internal modules renamed to snake_case (graphs/, metrics/, utilities/, mixins/, etc.)
+- Complete `EdgeData` refactor — raw counts as source of truth
+- `graph_union` rewritten to merge via `EdgeData.merge()` + `recalculate()`
+- Walk probability model consolidated into LZGraphBase
+- Laplace smoothing via `smoothing_alpha` parameter
+
+### Added
+- `remove_sequence()` method on LZGraphBase
+- `recalculate()` method to recompute all derived state from raw counts
+- `to_networkx()` for external tool compatibility
+- `walk_log_probability` on all graph types
 - Professional documentation with MkDocs Material theme
-- Comprehensive tutorials and how-to guides
-- API reference documentation
-- FAQ and troubleshooting guide
+- Comprehensive tutorials, how-to guides, and API reference
 
 ---
 
@@ -67,9 +92,15 @@ For the complete version history, see the [GitHub Releases](https://github.com/M
 
 ## Migration Guides
 
-### Upgrading to 1.1.x
+### Upgrading to 2.1.x
+
+No breaking changes from 2.0. New information-theoretic metrics are additive.
+
+### Upgrading from 1.x to 2.0
 
-No breaking changes. New features are additive.
+- All internal module paths changed to snake_case (e.g., `LZGraphs.graphs.amino_acid_positional`)
+- Edge data now uses `EdgeData` objects: access via `graph[a][b]['data'].weight`
+- Public class/function names unchanged — imports like `from LZGraphs import AAPLZGraph` still work
 
 ### Upgrading from Pre-1.0