notebook-exploration

Scaffold read-only exploration notebooks for single-cell analysis results using jscatter or Quarto.

1|Updated Nov 20, 2025
One-click install
npx skills add https://github.com/tony-zhelonkin/scio --skill notebook-exploration-tony-zhelonkin
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: notebook-exploration
Source: https://github.com/tony-zhelonkin/scio/tree/main/skills/notebook-exploration
Command: npx skills add https://github.com/tony-zhelonkin/scio --skill notebook-exploration-tony-zhelonkin

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires scanpy, pandas, numpy, pyyaml, jupyter-scatter, and includes assets (resource) and references (resource) components.

What problem does it solve? After a computational-biology stage finishes, someone must visually inspect what it produced — checking whether a cluster is real, whether a threshold holds, or how conditions compare — and summary tables alone cannot answer these questions. This Skill provides a disciplined, read-only notebook pattern for that inspection so exploration never corrupts authoritative pipeline outputs. ## Core Features & Use Cases - Two exploration flavors: a live-kernel Python notebook with jscatter linked panels for brushing and lassoing cells, or a rendered Quarto/R notebook that re-plots stage results into committed, GitHub-shareable markdown and HTML. - OOM-safe widget lifecycle: enforces a grid()/close_panels() contract so re-running jscatter panels never leaks ipywidgets and kills the kernel, plus an export-first rule that loads compact parquet tables instead of multi-GB .h5ad checkpoints. - Durable conclusions: selections are saved as barcode-indexed CSVs and the analytical reading is recorded in a stage-keyed topic note, keeping evidence reproducible across sessions. - Use Case: After a QC stage flags a high-mitochondrial FOXP3 population, scaffold a live jscatter explorer to lasso the pocket, characterize it against the full dataset in pandas, save the barcodes, and write the verdict into a durable note. ## Quick Start Ask the user what they want to see and whether they prefer a live Python kernel or a rendered Quarto notebook, then scaffold the matching template from the bundled assets.

Frequently Asked Questions about notebook-exploration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I interactively explore single-cell embeddings in a Jupyter notebook?▼

Use jscatter linked panels driven through a grid() helper that builds a 2-4 panel layout from a CHANNELS list you edit and re-run. Brush or lasso cells in any panel, then pull the selection into pandas with first_selection() to characterize it on the spot.

Should I use a live Python kernel or a rendered Quarto notebook for data exploration?▼

Choose the live Python kernel when you need to brush, lasso, and recolor cells interactively; choose rendered Quarto/R when you need a committed, GitHub-shareable document that re-plots the stage's numbers. Mixing both is common: explore in Python, then write the Quarto notebook to share findings.

Why does my Jupyter kernel run out of memory with jscatter panels?▼

jscatter panels are ipywidgets that stay alive until .widget.close() is called, so re-running a cell that builds panels with a raw loop accumulates dead widgets and OOMs the kernel. Build panels only through grid(), which closes all prior panels first, and keep a standalone close_panels() cell as an escape hatch.

Can I load a large h5ad file directly in an exploration notebook?▼

No — opening a multi-GB .h5ad checkpoint in the explorer kernel causes memory spikes. Run an exporter script first to materialize compact parquet tables with x,y coordinates plus a few obs and marker columns under 03_results/interactive/, which the notebook loads instantly.

Why do my Quarto figures render as SVG or broken images on GitHub?▼

On headless systems R's default Xlib bitmap type fails and knitr falls back to SVG, while base64 data-URI images are stripped by GitHub. Set dev = "ragg_png" and options(bitmapType = "cairo"), and render the GFM target so PNGs are written to _files/figure-gfm/ and committed.

When should I not use an exploration notebook?▼

Do not use it for multi-session relabelling campaigns, which need a selection manifest and rounds, or for computing anything a downstream stage consumes — authoritative outputs belong in numbered pipeline stages. Conclusions should be recorded in a durable topic note, not left in a notebook cell.