| Name | StripeSankey JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Interactive Sankey diagram widget for topic modeling analysis with sample flow tracing |
| upload_time | 2025-08-04 11:14:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| 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. |
| keywords |
anywidget
interactive
jupyter
microbiome
sankey
topic-modeling
visualization
widget
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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)
Raw data
{
"_id": null,
"home_page": null,
"name": "StripeSankey",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Peiyang Huo <peiyang.huo@kuleuven.be>",
"keywords": "anywidget, interactive, jupyter, microbiome, sankey, topic-modeling, visualization, widget",
"author": null,
"author_email": "Peiyang Huo <peiyang.huo@kuleuven.be>",
"download_url": "https://files.pythonhosted.org/packages/f0/f9/bbf3cd763ee932f6149ebb2fd4bf9050466435760fba4fb20153bfb4d240/stripesankey-0.1.0.tar.gz",
"platform": null,
"description": "# Stripe Sankey Widget\n\nAn 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.\n\nLDA 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.\n\nWe designed this StripeSankey diagram to make LDA results more accessible and integrated two widely used metrics\u2014perplexity and coherence score\u2014into novel visual encodings.\n\nOverview of StripeSankey diagram:\n<img src=\"fig/StripeSankey_metic.jpeg\" alt=\"Description\" width=\"600\">\n\nLegend of metrics coour: \n<img src=\"fig/legend.png\" alt=\"Description\" width=\"200\">\n\nAfter click one flow:\n<img src=\"fig/StripeSankey_click.jpg\" alt=\"Description\" width=\"600\">\n\n\n\n## Installation\n\n### From PyPI\n```bash\npip install StripeSankey\n```\n## Data Preprocessing\n\n## Quick Start\n\n```python\nimport stripe_sankey\nfrom stripe_sankey import StripeSankeyInline\n\n# Load your processed topic modeling data\nsankey_data = {\n \"nodes\": {\n \"K2_MC1\": {\n \"high_count\": 45,\n \"medium_count\": 23,\n \"model_metrics\": {\"perplexity\": 1.2},\n \"mallet_diagnostics\": {\"coherence\": -0.15}\n },\n # ... more nodes\n },\n \"flows\": [\n {\n \"source_segment\": \"K2_MC1_high\",\n \"target_segment\": \"K3_MC2_medium\", \n \"source_k\": 2,\n \"target_k\": 3,\n \"sample_count\": 15,\n \"samples\": [{\"sample\": \"doc_1\", \"source_prob\": 0.8, \"target_prob\": 0.6}]\n },\n # ... more flows\n ],\n \"k_range\": [2, 3, 4, 5]\n}\n\n# Create and display widget\nwidget = StripeSankeyInline(sankey_data=sankey_data)\nwidget\n```\n\n## Visualization Modes\n\n### Default Mode\nShows topic representations with high/medium probability segments:\n```python\nwidget = StripeSankeyInline(sankey_data=data, mode=\"default\")\n```\n\n### Metric Mode \nColor-codes topics by quality metrics (perplexity + coherence):\n```python\nwidget = StripeSankeyInline(sankey_data=data, mode=\"metric\")\n\n# Customize metric weights\nwidget.update_metric_config(red_weight=0.9, blue_weight=0.7)\n```\n\n## Interactive Features\n\n### Sample Flow Tracing\n- **Click any flow** to highlight sample trajectories across K values\n- **Orange trajectories** show where samples move between topics\n- **Count badges** display number of traced samples in each segment\n- **Line thickness** represents sample flow volume\n- **Click background** to clear selection\n\n### Visual Elements\n- **Stacked bars**: High (dark) and medium (light) probability representations\n- **Curved flows**: Proportional thickness based on sample counts\n- **Barycenter layout**: Optimized positioning to reduce visual complexity\n- **Hover tooltips**: Detailed information on flows and segments\n\n## Data Format\n\nYour data should follow this structure:\n\n```python\n{\n \"nodes\": {\n \"K{k}_MC{mc}\": {\n \"high_count\": int, # Samples with prob \u2265 0.67\n \"medium_count\": int, # Samples with prob 0.33-0.66\n \"total_probability\": float,\n \"model_metrics\": {\n \"perplexity\": float # Lower is better\n },\n \"mallet_diagnostics\": {\n \"coherence\": float # Higher (less negative) is better\n }\n }\n },\n \"flows\": [\n {\n \"source_segment\": \"K{k}_MC{mc}_{level}\",\n \"target_segment\": \"K{k+1}_MC{mc}_{level}\",\n \"source_k\": int,\n \"target_k\": int,\n \"sample_count\": int,\n \"average_probability\": float,\n \"samples\": [\n {\n \"sample\": str, # Sample identifier\n \"source_prob\": float, # Probability in source topic\n \"target_prob\": float # Probability in target topic\n }\n ]\n }\n ],\n \"k_range\": [2, 3, 4, 5] # Topic numbers analyzed\n}\n```\n\n## Configuration Options\n\n### Widget Parameters\n```python\nwidget = StripeSankeyInline(\n sankey_data=data,\n width=1200, # Canvas width\n height=800, # Canvas height \n mode=\"default\" # \"default\" or \"metric\"\n)\n```\n\n### Metric Mode Configuration\n```python\nwidget.update_metric_config(\n red_weight=0.8, # Perplexity influence (0-1)\n blue_weight=0.8, # Coherence influence (0-1) \n min_saturation=0.3 # Minimum color brightness\n)\n```\n\n### Color Schemes\n```python\nwidget.color_schemes = {\n 2: \"#1f77b4\", # Blue for K=2\n 3: \"#ff7f0e\", # Orange for K=3\n 4: \"#2ca02c\", # Green for K=4\n 5: \"#d62728\" # Red for K=5\n}\n```\n\n## Use Cases\n\n- **Topic Model Analysis**: Understand how topics evolve across different K values\n- **Sample Trajectory Tracking**: Follow samples through topic assignments\n- **Model Quality Assessment**: Visual comparison of perplexity and coherence metrics\n- **Flow Bottleneck Detection**: Identify where samples cluster or disperse\n- **Research Presentation**: Interactive demonstrations of topic modeling results\n\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n<!-- ## Citation\n\nIf you use this widget in your research, please cite:\n\n```bibtex\n@software{stripe_sankey,\n title = {Stripe Sankey Widget: Interactive Topic Flow Visualization},\n author = {Your Name},\n url = {https://github.com/Peiyangg/StripeSankey},\n year = {2024}\n}\n``` -->\n\n## Acknowledgments\n\n- Built with [anywidget](https://anywidget.dev/) - modern Jupyter widget framework\n- Visualization powered by [D3.js](https://d3js.org/)\n\n## Support\n\n- \ud83d\udcd6 [Documentation](https://github.com/Peiyangg/StripeSankey#readme)",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2025 peiyang\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Interactive Sankey diagram widget for topic modeling analysis with sample flow tracing",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Peiyangg/StripeSankey/issues",
"Documentation": "https://github.com/Peiyangg/StripeSankey#readme",
"Homepage": "https://github.com/Peiyangg/StripeSankey",
"Repository": "https://github.com/Peiyangg/StripeSankey.git"
},
"split_keywords": [
"anywidget",
" interactive",
" jupyter",
" microbiome",
" sankey",
" topic-modeling",
" visualization",
" widget"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "986b82b64abf22317de4c0446c688d3e6b9e6bfecf0416ce246a70a8466b6181",
"md5": "fd0ed45264b851694adb0c03cd212a63",
"sha256": "0b01ef6c8f939c0868f43420765dfe2c1fdd39e128f42624166dfb1f04cd2c71"
},
"downloads": -1,
"filename": "stripesankey-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd0ed45264b851694adb0c03cd212a63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15949,
"upload_time": "2025-08-04T11:14:37",
"upload_time_iso_8601": "2025-08-04T11:14:37.967457Z",
"url": "https://files.pythonhosted.org/packages/98/6b/82b64abf22317de4c0446c688d3e6b9e6bfecf0416ce246a70a8466b6181/stripesankey-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f0f9bbf3cd763ee932f6149ebb2fd4bf9050466435760fba4fb20153bfb4d240",
"md5": "ef0f3ae93f4632663a2fa7169178cc56",
"sha256": "e84e9cb3dce91a5a6ea1458541e25586109f593559aab2e82c6a34be8583431e"
},
"downloads": -1,
"filename": "stripesankey-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "ef0f3ae93f4632663a2fa7169178cc56",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5603769,
"upload_time": "2025-08-04T11:14:40",
"upload_time_iso_8601": "2025-08-04T11:14:40.078283Z",
"url": "https://files.pythonhosted.org/packages/f0/f9/bbf3cd763ee932f6149ebb2fd4bf9050466435760fba4fb20153bfb4d240/stripesankey-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 11:14:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Peiyangg",
"github_project": "StripeSankey",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "stripesankey"
}
