StripeSankey 0.1.0__tar.gz

stripesankey-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 peiyang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stripesankey-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: StripeSankey
+Version: 0.1.0
+Summary: Interactive Sankey diagram widget for topic modeling analysis with sample flow tracing
+Project-URL: Homepage, https://github.com/Peiyangg/StripeSankey
+Project-URL: Documentation, https://github.com/Peiyangg/StripeSankey#readme
+Project-URL: Repository, https://github.com/Peiyangg/StripeSankey.git
+Project-URL: Bug Tracker, https://github.com/Peiyangg/StripeSankey/issues
+Author-email: Peiyang Huo <peiyang.huo@kuleuven.be>
+Maintainer-email: Peiyang Huo <peiyang.huo@kuleuven.be>
+License: MIT License
+        
+        Copyright (c) 2025 peiyang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: anywidget,interactive,jupyter,microbiome,sankey,topic-modeling,visualization,widget
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Framework :: Jupyter :: JupyterLab
+Classifier: Framework :: Jupyter :: JupyterLab :: 3
+Classifier: Framework :: Jupyter :: JupyterLab :: 4
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.8
+Requires-Dist: anywidget>=0.9.0
+Requires-Dist: traitlets>=5.0.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=6.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Stripe Sankey Widget
+
+An interactive Sankey diagram widget for understanding how samples are represented by topics across different LDA models. This tool can also be applied to similar algorithms like NMF and LSA.
+
+LDA is a powerful tool for achieving soft clustering and finding latent groups beyond initial hypotheses. However, the challenge of applying LDA to 16S rRNA data is that sequence reads are less informative than human language when users want to evaluate a model's results. Even when metrics are applied, making decisions remains difficult.
+
+We designed this StripeSankey diagram to make LDA results more accessible and integrated two widely used metrics—perplexity and coherence score—into novel visual encodings.
+
+Overview of StripeSankey diagram:
+<img src="fig/StripeSankey_metic.jpeg" alt="Description" width="600">
+
+Legend of metrics coour: 
+<img src="fig/legend.png" alt="Description" width="200">
+
+After click one flow:
+<img src="fig/StripeSankey_click.jpg" alt="Description" width="600">
+
+
+
+## Installation
+
+### From PyPI
+```bash
+pip install StripeSankey
+```
+## Data Preprocessing
+
+## Quick Start
+
+```python
+import stripe_sankey
+from stripe_sankey import StripeSankeyInline
+
+# Load your processed topic modeling data
+sankey_data = {
+    "nodes": {
+        "K2_MC1": {
+            "high_count": 45,
+            "medium_count": 23,
+            "model_metrics": {"perplexity": 1.2},
+            "mallet_diagnostics": {"coherence": -0.15}
+        },
+        # ... more nodes
+    },
+    "flows": [
+        {
+            "source_segment": "K2_MC1_high",
+            "target_segment": "K3_MC2_medium", 
+            "source_k": 2,
+            "target_k": 3,
+            "sample_count": 15,
+            "samples": [{"sample": "doc_1", "source_prob": 0.8, "target_prob": 0.6}]
+        },
+        # ... more flows
+    ],
+    "k_range": [2, 3, 4, 5]
+}
+
+# Create and display widget
+widget = StripeSankeyInline(sankey_data=sankey_data)
+widget
+```
+
+## Visualization Modes
+
+### Default Mode
+Shows topic representations with high/medium probability segments:
+```python
+widget = StripeSankeyInline(sankey_data=data, mode="default")
+```
+
+### Metric Mode  
+Color-codes topics by quality metrics (perplexity + coherence):
+```python
+widget = StripeSankeyInline(sankey_data=data, mode="metric")
+
+# Customize metric weights
+widget.update_metric_config(red_weight=0.9, blue_weight=0.7)
+```
+
+## Interactive Features
+
+### Sample Flow Tracing
+- **Click any flow** to highlight sample trajectories across K values
+- **Orange trajectories** show where samples move between topics
+- **Count badges** display number of traced samples in each segment
+- **Line thickness** represents sample flow volume
+- **Click background** to clear selection
+
+### Visual Elements
+- **Stacked bars**: High (dark) and medium (light) probability representations
+- **Curved flows**: Proportional thickness based on sample counts
+- **Barycenter layout**: Optimized positioning to reduce visual complexity
+- **Hover tooltips**: Detailed information on flows and segments
+
+## Data Format
+
+Your data should follow this structure:
+
+```python
+{
+    "nodes": {
+        "K{k}_MC{mc}": {
+            "high_count": int,           # Samples with prob ≥ 0.67
+            "medium_count": int,         # Samples with prob 0.33-0.66
+            "total_probability": float,
+            "model_metrics": {
+                "perplexity": float      # Lower is better
+            },
+            "mallet_diagnostics": {
+                "coherence": float       # Higher (less negative) is better
+            }
+        }
+    },
+    "flows": [
+        {
+            "source_segment": "K{k}_MC{mc}_{level}",
+            "target_segment": "K{k+1}_MC{mc}_{level}",
+            "source_k": int,
+            "target_k": int,
+            "sample_count": int,
+            "average_probability": float,
+            "samples": [
+                {
+                    "sample": str,           # Sample identifier
+                    "source_prob": float,    # Probability in source topic
+                    "target_prob": float     # Probability in target topic
+                }
+            ]
+        }
+    ],
+    "k_range": [2, 3, 4, 5]  # Topic numbers analyzed
+}
+```
+
+## Configuration Options
+
+### Widget Parameters
+```python
+widget = StripeSankeyInline(
+    sankey_data=data,
+    width=1200,           # Canvas width
+    height=800,           # Canvas height  
+    mode="default"        # "default" or "metric"
+)
+```
+
+### Metric Mode Configuration
+```python
+widget.update_metric_config(
+    red_weight=0.8,       # Perplexity influence (0-1)
+    blue_weight=0.8,      # Coherence influence (0-1) 
+    min_saturation=0.3    # Minimum color brightness
+)
+```
+
+### Color Schemes
+```python
+widget.color_schemes = {
+    2: "#1f77b4",  # Blue for K=2
+    3: "#ff7f0e",  # Orange for K=3
+    4: "#2ca02c",  # Green for K=4
+    5: "#d62728"   # Red for K=5
+}
+```
+
+## Use Cases
+
+- **Topic Model Analysis**: Understand how topics evolve across different K values
+- **Sample Trajectory Tracking**: Follow samples through topic assignments
+- **Model Quality Assessment**: Visual comparison of perplexity and coherence metrics
+- **Flow Bottleneck Detection**: Identify where samples cluster or disperse
+- **Research Presentation**: Interactive demonstrations of topic modeling results
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+<!-- ## Citation
+
+If you use this widget in your research, please cite:
+
+```bibtex
+@software{stripe_sankey,
+  title = {Stripe Sankey Widget: Interactive Topic Flow Visualization},
+  author = {Your Name},
+  url = {https://github.com/Peiyangg/StripeSankey},
+  year = {2024}
+}
+``` -->
+
+## Acknowledgments
+
+- Built with [anywidget](https://anywidget.dev/) - modern Jupyter widget framework
+- Visualization powered by [D3.js](https://d3js.org/)
+
+## Support
+
+- 📖 [Documentation](https://github.com/Peiyangg/StripeSankey#readme)

stripesankey-0.1.0/README.md

@@ -0,0 +1,200 @@
+# Stripe Sankey Widget
+
+An interactive Sankey diagram widget for understanding how samples are represented by topics across different LDA models. This tool can also be applied to similar algorithms like NMF and LSA.
+
+LDA is a powerful tool for achieving soft clustering and finding latent groups beyond initial hypotheses. However, the challenge of applying LDA to 16S rRNA data is that sequence reads are less informative than human language when users want to evaluate a model's results. Even when metrics are applied, making decisions remains difficult.
+
+We designed this StripeSankey diagram to make LDA results more accessible and integrated two widely used metrics—perplexity and coherence score—into novel visual encodings.
+
+Overview of StripeSankey diagram:
+<img src="fig/StripeSankey_metic.jpeg" alt="Description" width="600">
+
+Legend of metrics coour: 
+<img src="fig/legend.png" alt="Description" width="200">
+
+After click one flow:
+<img src="fig/StripeSankey_click.jpg" alt="Description" width="600">
+
+
+
+## Installation
+
+### From PyPI
+```bash
+pip install StripeSankey
+```
+## Data Preprocessing
+
+## Quick Start
+
+```python
+import stripe_sankey
+from stripe_sankey import StripeSankeyInline
+
+# Load your processed topic modeling data
+sankey_data = {
+    "nodes": {
+        "K2_MC1": {
+            "high_count": 45,
+            "medium_count": 23,
+            "model_metrics": {"perplexity": 1.2},
+            "mallet_diagnostics": {"coherence": -0.15}
+        },
+        # ... more nodes
+    },
+    "flows": [
+        {
+            "source_segment": "K2_MC1_high",
+            "target_segment": "K3_MC2_medium", 
+            "source_k": 2,
+            "target_k": 3,
+            "sample_count": 15,
+            "samples": [{"sample": "doc_1", "source_prob": 0.8, "target_prob": 0.6}]
+        },
+        # ... more flows
+    ],
+    "k_range": [2, 3, 4, 5]
+}
+
+# Create and display widget
+widget = StripeSankeyInline(sankey_data=sankey_data)
+widget
+```
+
+## Visualization Modes
+
+### Default Mode
+Shows topic representations with high/medium probability segments:
+```python
+widget = StripeSankeyInline(sankey_data=data, mode="default")
+```
+
+### Metric Mode  
+Color-codes topics by quality metrics (perplexity + coherence):
+```python
+widget = StripeSankeyInline(sankey_data=data, mode="metric")
+
+# Customize metric weights
+widget.update_metric_config(red_weight=0.9, blue_weight=0.7)
+```
+
+## Interactive Features
+
+### Sample Flow Tracing
+- **Click any flow** to highlight sample trajectories across K values
+- **Orange trajectories** show where samples move between topics
+- **Count badges** display number of traced samples in each segment
+- **Line thickness** represents sample flow volume
+- **Click background** to clear selection
+
+### Visual Elements
+- **Stacked bars**: High (dark) and medium (light) probability representations
+- **Curved flows**: Proportional thickness based on sample counts
+- **Barycenter layout**: Optimized positioning to reduce visual complexity
+- **Hover tooltips**: Detailed information on flows and segments
+
+## Data Format
+
+Your data should follow this structure:
+
+```python
+{
+    "nodes": {
+        "K{k}_MC{mc}": {
+            "high_count": int,           # Samples with prob ≥ 0.67
+            "medium_count": int,         # Samples with prob 0.33-0.66
+            "total_probability": float,
+            "model_metrics": {
+                "perplexity": float      # Lower is better
+            },
+            "mallet_diagnostics": {
+                "coherence": float       # Higher (less negative) is better
+            }
+        }
+    },
+    "flows": [
+        {
+            "source_segment": "K{k}_MC{mc}_{level}",
+            "target_segment": "K{k+1}_MC{mc}_{level}",
+            "source_k": int,
+            "target_k": int,
+            "sample_count": int,
+            "average_probability": float,
+            "samples": [
+                {
+                    "sample": str,           # Sample identifier
+                    "source_prob": float,    # Probability in source topic
+                    "target_prob": float     # Probability in target topic
+                }
+            ]
+        }
+    ],
+    "k_range": [2, 3, 4, 5]  # Topic numbers analyzed
+}
+```
+
+## Configuration Options
+
+### Widget Parameters
+```python
+widget = StripeSankeyInline(
+    sankey_data=data,
+    width=1200,           # Canvas width
+    height=800,           # Canvas height  
+    mode="default"        # "default" or "metric"
+)
+```
+
+### Metric Mode Configuration
+```python
+widget.update_metric_config(
+    red_weight=0.8,       # Perplexity influence (0-1)
+    blue_weight=0.8,      # Coherence influence (0-1) 
+    min_saturation=0.3    # Minimum color brightness
+)
+```
+
+### Color Schemes
+```python
+widget.color_schemes = {
+    2: "#1f77b4",  # Blue for K=2
+    3: "#ff7f0e",  # Orange for K=3
+    4: "#2ca02c",  # Green for K=4
+    5: "#d62728"   # Red for K=5
+}
+```
+
+## Use Cases
+
+- **Topic Model Analysis**: Understand how topics evolve across different K values
+- **Sample Trajectory Tracking**: Follow samples through topic assignments
+- **Model Quality Assessment**: Visual comparison of perplexity and coherence metrics
+- **Flow Bottleneck Detection**: Identify where samples cluster or disperse
+- **Research Presentation**: Interactive demonstrations of topic modeling results
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+<!-- ## Citation
+
+If you use this widget in your research, please cite:
+
+```bibtex
+@software{stripe_sankey,
+  title = {Stripe Sankey Widget: Interactive Topic Flow Visualization},
+  author = {Your Name},
+  url = {https://github.com/Peiyangg/StripeSankey},
+  year = {2024}
+}
+``` -->
+
+## Acknowledgments
+
+- Built with [anywidget](https://anywidget.dev/) - modern Jupyter widget framework
+- Visualization powered by [D3.js](https://d3js.org/)
+
+## Support
+
+- 📖 [Documentation](https://github.com/Peiyangg/StripeSankey#readme)

stripesankey-0.1.0/StripeSankey/__init__.py

@@ -0,0 +1,4 @@
+from .widget import StripeSankeyInline
+
+__version__ = "0.1.0"
+__all__ = ["StripeSankeyInline"]