{"id":41221912,"url":"https://github.com/rnabioco/squiggy-positron","last_synced_at":"2026-04-02T12:44:31.011Z","repository":{"id":321218343,"uuid":"1083628573","full_name":"rnabioco/squiggy-positron","owner":"rnabioco","description":"Positron extension to visualize POD5 nanopore signals","archived":false,"fork":false,"pushed_at":"2026-03-25T18:54:11.000Z","size":19847,"stargazers_count":0,"open_issues_count":28,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T03:34:06.308Z","etag":null,"topics":["api","nanopore","positron","squiggle","visualization"],"latest_commit_sha":null,"homepage":"https://rnabioco.github.io/squiggy-positron/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rnabioco.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-26T12:18:07.000Z","updated_at":"2026-03-25T17:30:01.000Z","dependencies_parsed_at":"2025-10-28T14:49:21.272Z","dependency_job_id":null,"html_url":"https://github.com/rnabioco/squiggy-positron","commit_stats":null,"previous_names":["rnabioco/squiggy","rnabioco/squiggy-positron"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/rnabioco/squiggy-positron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnabioco%2Fsquiggy-positron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnabioco%2Fsquiggy-positron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnabioco%2Fsquiggy-positron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnabioco%2Fsquiggy-positron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rnabioco","download_url":"https://codeload.github.com/rnabioco/squiggy-positron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rnabioco%2Fsquiggy-positron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31306356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","nanopore","positron","squiggle","visualization"],"created_at":"2026-01-23T00:20:04.456Z","updated_at":"2026-04-02T12:44:31.002Z","avatar_url":"https://github.com/rnabioco.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Squiggy - Positron Extension\n\n🚧 **squiggy is under active development.** *Caveat emptor*. 🚧\n\nA Positron IDE extension for visualizing Oxford Nanopore sequencing data from POD5 files directly in your workspace.\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)\n[![OpenVSX](https://img.shields.io/open-vsx/v/rnabioco/squiggy-positron)](https://open-vsx.org/extension/rnabioco/squiggy-positron)\n[![codecov](https://codecov.io/gh/rnabioco/squiggy-positron/branch/main/graph/badge.svg)](https://codecov.io/gh/rnabioco/squiggy-positron)\n\n## Overview\n\nSquiggy is a Positron extension that integrates nanopore signal visualization into your data science workflow. Work with POD5 and BAM files directly in Positron, leveraging interactive Bokeh plots for data exploration.\n\n![Squiggy in action](resources/screenshot.png)\n\n**Key Features:**\n- **One-Step Installation**: Just install the extension - Python environment is set up automatically\n- **Interactive Visualization**: Bokeh-powered plots with zoom, pan, and hover tooltips\n- **Base Annotations**: Overlay base calls and modifications on signal data when using BAM files\n- **Read Filtering**: Search by read ID, reference region, or sequence motif\n- **Modification Analysis**: Filter and visualize base modifications (5mC, 6mA, etc.) with probability thresholds\n- **Aggregate Plots**: Multi-read visualizations with modification heatmaps, dwell time, and quality tracks\n\n## Installation\n\n### Prerequisites\n\n- **Positron IDE** (version 2025.6.0+)\n- **Python 3.12+** available on your system\n- **uv** - Fast Python package manager ([install uv](https://docs.astral.sh/uv/getting-started/installation/))\n\n### Install the Extension\n\n1. Download the latest `.vsix` file from [Releases](https://github.com/rnabioco/squiggy-positron/releases)\n2. In Positron: `Extensions` → `...` → `Install from VSIX...`\n3. Select the downloaded `.vsix` file\n\nOr install from the Open VSX Registry:\n- Search for \"Squiggy\" in Positron's Extensions panel\n\n### Automatic Python Setup\n\nWhen you first use Squiggy, it automatically:\n1. Creates a dedicated virtual environment at `~/.venvs/squiggy`\n2. Installs the bundled `squiggy` Python package using `uv`\n3. Configures a background kernel for extension operations\n\n**No manual Python package installation required!** The extension handles everything.\n\n\u003e [!NOTE]  \n\u003e The automatic setup requires `uv` to be installed. If `uv` is not found, you'll be prompted to install it.\n\n## Quick Start\n\n### 1. Load Data Files\n\nOpen the Squiggy sidebar (click the Squiggy icon in the activity bar):\n\n- **Open POD5 File**: Load your nanopore signal data\n- **Open BAM File** (optional): Add alignments for base annotations and advanced filtering\n\n### 2. Browse Reads\n\nThe **Reads** panel shows all reads in the POD5 file:\n- Grouped by reference if BAM file is loaded\n- Use the search bar to filter by read ID or reference name\n- Click any read to visualize\n\n### 3. Customize Plots\n\nThe **Plotting** panel provides three analysis workflows:\n\n#### Per-Read Plots\nView individual reads with overlay or stacked layouts:\n- **Overlay**: Alpha-blended signals on shared axes (good for pattern comparison)\n- **Stacked**: Vertically offset signals (squigualiser-style, best for ≤20 reads)\n- Configure max reads per sample (2-100)\n- Requires: POD5 file\n\n#### Composite Read Plots (Aggregate)\nMulti-read statistics aligned to a reference sequence:\n- Select reference sequence and max reads (10-500)\n- **View Style** (for 2+ samples):\n  - *Overlay*: Mean signals from all samples on one plot\n  - *Multi-Track*: Detailed 5-track view for each sample\n- **Visible Panels** (toggle individually):\n  - Base modifications - Heatmaps showing modification frequency and confidence\n  - Base pileup - Coverage and base composition\n  - Dwell time - Mean dwell with confidence bands\n  - Signal - Mean normalized signal with confidence bands\n  - Quality scores - Mean quality with confidence bands\n- **X-Axis Display**:\n  - Clip to consensus region (focus on high-coverage areas)\n  - Transform to relative coordinates (anchor position 1 to first reference base)\n- Requires: BAM file with alignments\n\n#### 2-Sample Comparisons\nCompare signal differences between exactly two samples:\n- Select exactly 2 samples from Sample Manager\n- Choose reference sequence\n- Generates delta plots showing signal differences (B - A)\n- Configure max reads per sample (10-500)\n- Requires: 2 samples with BAM files\n\n#### Common Options (All Plot Types)\n- **Normalization**: None, Z-score, Median, or MAD\n- **Sample Manager Integration**: Use eye icons in Sample Manager to select which samples to visualize\n\n\u003e [!TIP]\n\u003e For multi-sample workflows, enable the samples you want to visualize using the eye icons in the Sample Manager panel, then choose your analysis type in the Plotting panel.\n\n### 4. Explore Modifications (BAM with MM/ML tags)\n\nIf your BAM file contains base modifications:\n- The **Base Modifications** panel appears automatically\n- Filter by modification type (5mC, 6mA, etc.)\n- Set probability threshold to focus on high-confidence calls\n- Toggle coloring by dwell time vs modification probability\n\n### 5. Export Plots\n\n- **File → Export Plot** (Ctrl/Cmd+E)\n- Formats: HTML (interactive), PNG, SVG\n- Option to export at current zoom level\n\n## Python API for Notebooks\n\nSquiggy provides an object-oriented Python API for use in Jupyter notebooks and Python scripts. See [`examples/notebook_api_demo.ipynb`](examples/notebook_api_demo.ipynb) for a complete tutorial.\n\nTo use the API in your own environment, activate the Squiggy venv:\n\n```bash\nsource ~/.venvs/squiggy/bin/activate\npython -c \"import squiggy; print(squiggy.__version__)\"\n```\n\n## Architecture\n\nSquiggy uses the **Strategy Pattern** to make adding new plot types easy and maintainable:\n\n- **PlotFactory** - Creates the appropriate plotting strategy based on plot mode\n- **7 Plot Strategies** - Each plot type (SINGLE, OVERLAY, STACKED, EVENTALIGN, AGGREGATE, DELTA, SIGNAL_OVERLAY_COMPARISON) is a separate strategy class\n- **Reusable Components** - ThemeManager, BaseAnnotationRenderer, ModificationTrackBuilder shared across strategies\n- **Easy Extension** - Adding new plot types requires only creating a new strategy class\n\nThis design makes it straightforward to add new visualization types (like A/B comparison plots) without modifying existing code.\n\nSee the [Developer Guide](https://rnabioco.github.io/squiggy-positron/developer-guide/#strategy-pattern-architecture) for detailed architecture documentation.\n\n## Requirements\n\n- **Positron IDE** (version 2025.6.0+)\n- **Python 3.12+** available on your system\n- **uv** for automatic Python environment setup\n\n### Optional Requirements\n\n- **BAM file** with basecalls for advanced features (event-aligned plots, modifications)\n\n## Troubleshooting\n\n### Reset the Squiggy Environment\n\nIf you encounter issues with the Python environment, you can reset it:\n\n1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)\n2. Run: `Squiggy: Reset Virtual Environment`\n\nThis will delete `~/.venvs/squiggy` and recreate it on next use.\n\n### Manual Environment Setup\n\nIf automatic setup fails, you can manually create the environment:\n\n```bash\n# Install uv if needed\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create venv with Python 3.12\nuv venv ~/.venvs/squiggy --python 3.12\n\n# Activate and install squiggy from the extension\nsource ~/.venvs/squiggy/bin/activate\n# The extension will install the package on first use\n```\n\n## Documentation\n\n📚 **Full documentation available at [rnabioco.github.io/squiggy-positron](https://rnabioco.github.io/squiggy-positron/)**\n\n- [User Guide](https://rnabioco.github.io/squiggy-positron/user-guide/) - Complete usage guide\n- [Developer Guide](https://rnabioco.github.io/squiggy-positron/developer-guide/) - Extension development setup\n- [API Reference](https://rnabioco.github.io/squiggy-positron/api/) - Python API documentation\n\n## Contributing\n\nContributions are welcome! Please see the [Developer Guide](https://rnabioco.github.io/squiggy-positron/developer-guide/) for:\n- Development setup\n- Coding standards\n- Testing guidelines\n- Pull request process\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- **Positron Team** at Posit for the excellent IDE and extension API\n- **Oxford Nanopore Technologies** for POD5 format and libraries\n- **[Remora](https://github.com/nanoporetech/remora)** - Modified base calling toolkit\n- **[Squigualiser](https://github.com/hiruna72/squigualiser)** - Signal visualization inspiration\n\n## Citation\n\nIf you use Squiggy in your research, please cite:\n\n```\n[Citation information to be added]\n```\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/rnabioco/squiggy-positron/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/rnabioco/squiggy-positron/discussions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnabioco%2Fsquiggy-positron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frnabioco%2Fsquiggy-positron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frnabioco%2Fsquiggy-positron/lists"}