diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 0000000..5ef111a --- /dev/null +++ b/.github/workflows/mkdocs.yml @@ -0,0 +1,56 @@ +# Build MkDocs and publish to GitHub Pages. +# Repo Settings → Pages → Build and deployment: Source = "GitHub Actions". +# +# You can list any branch(es) below. A push to any of them deploys to the same +# site URL for this repo (the latest successful run wins). For docs-only testing, +# use e.g. only `mkdocs`; for production after merge, use only `main` or both. + +name: Publish docs + +on: + push: + branches: + - main + - mkdocs + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: pip + cache-dependency-path: requirements-docs.txt + + - name: Install MkDocs + run: pip install -r requirements-docs.txt + + - name: Build site + run: mkdocs build --strict + + - uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/README.md b/README.md index 757e216..2206d4a 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ With **LITTLE JOHN**, ROBIN can run two PromethION flow cells simultaneously on Use **conda** so native and Python dependencies stay consistent. Create the environment from **`robin.yml`** (Python 3.12); older Python 3.9-era env files are removed. -For a step-by-step walkthrough, see [`docs/installation_guide.md`](docs/installation_guide.md). +For a step-by-step walkthrough, see [`docs/getting-started/installation.md`](docs/getting-started/installation.md). ### Prerequisites @@ -130,7 +130,7 @@ For a step-by-step walkthrough, see [`docs/installation_guide.md`](docs/installa After any of these, run **`pip install -e .`** again from the repository root with the env you intend to use. -More detail: [`docs/installation_guide.md` → If the `robin` environment already exists](docs/installation_guide.md#if-the-robin-environment-already-exists). +More detail: [`docs/getting-started/installation.md` → If the `robin` environment already exists](docs/getting-started/installation.md#if-the-robin-environment-already-exists). --- diff --git a/docs/cli/index.md b/docs/cli/index.md new file mode 100644 index 0000000..80058e1 --- /dev/null +++ b/docs/cli/index.md @@ -0,0 +1,39 @@ +# Command-line reference + +ROBIN exposes a **`robin`** CLI (Click). This section documents each command group. For a first run, see [Installation](../getting-started/installation.md) and [Quickstart](../getting-started/quickstart.md). + +## Command tree + +| Command | Purpose | +|---------|---------| +| [`robin workflow`](workflow.md) | Watch a directory of BAMs and run the selected analysis pipeline (Ray, NiceGUI optional). | +| [`robin list-job-types`](jobs.md) | Print job types and queue layout. | +| [`robin list-panels`](panels.md) / [`add-panel`](panels.md#robin-add-panel) / [`remove-panel`](panels.md#robin-remove-panel) | Manage target gene panels. | +| [`robin utils …`](utils.md) | Models, ClinVar, reference/panel staging, MGMT summaries. | +| [`robin password …`](password.md) | Set the NiceGUI login password. | + +Run **`robin --help`** and **`robin --help`** for the exact options shipped with your install. + +## Disclaimer prompt + +Many commands that change state or start processing show a **disclaimer** and require you to type **`I agree`** exactly (research-use acknowledgment). + +## Environment variables (selected) + +| Variable | Effect | +|----------|--------| +| `GITHUB_TOKEN` | Used by `robin utils update-models` when assets are fetched from private GitHub. | +| `ROBIN_PROCESS_LARGE_BAMS` | If enabled, warns that large-BAM mode must not be used alongside live runs. | +| `LJ_BAM_THREADS` | Optional tuning for multi-threaded BAM handling (see [README — Performance](https://github.com/LooseLab/littlejohn/blob/main/README.md#performance)). | + +## First-time startup experience + +When you run **`robin workflow`**, ROBIN performs model checks, optional reference validation, the **research disclaimer** (`I agree`), and (if the GUI is enabled) **GUI password** prompts. See **[What happens at startup](../getting-started/startup.md)**. + +## Web interface + +For a **browser user guide** (navigation, each screen, reading results), see **[Using ROBIN](../using-robin/index.md)**. + +## See also + +- [README — Command reference](https://github.com/LooseLab/littlejohn/blob/main/README.md#command-reference) (repo mirror of common invocations) diff --git a/docs/cli/jobs.md b/docs/cli/jobs.md new file mode 100644 index 0000000..2f3cfc7 --- /dev/null +++ b/docs/cli/jobs.md @@ -0,0 +1,60 @@ +# `robin list-job-types` and job model + +`robin list-job-types` prints the **job types** ROBIN knows about, grouped by **queue**. Understanding this helps you build `-w` / `--workflow` strings for [`robin workflow`](workflow.md). + +## Command + +```bash +robin list-job-types +``` + +You must complete the **disclaimer** (`I agree`). + +## Queues and job types + +The orchestration layer assigns each job type to a queue (simplified names here; internal Ray queue names may differ slightly): + +| Queue (concept) | Job types | Role | +|-----------------|-----------|------| +| **Preprocessing** | `preprocessing` | Read BAM headers/metadata; entry point for each new file. | +| **BED conversion** | `bed_conversion` | Prepare inputs for classifiers that need BED-level views. | +| **Analysis** | `mgmt`, `cnv`, `target`, `fusion` | Methylation (MGMT), copy number, targeted variant/fusion panels. | +| **Classification** | `sturgeon`, `nanodx`, `pannanodx` | Methylation / expression classifiers. | +| **Slow** | `random_forest` | Heavier or batched models. | + +## Automatic steps + +When you use the **simplified** workflow format (`-w mgmt,sturgeon`, …): + +1. **`preprocessing`** is prepended if you did not list it. +2. **`bed_conversion`** is inserted when any of **`sturgeon`**, **`nanodx`**, **`pannanodx`**, or **`random_forest`** appear — those jobs expect BED conversion upstream. + +You do not need to list `bed_conversion` manually for those classifiers unless you are hand-editing **legacy** queue-prefixed pipelines. + +## Valid job type names + +The CLI accepts only these **job** identifiers in workflow strings: + +`preprocessing`, `bed_conversion`, `mgmt`, `cnv`, `target`, `fusion`, `sturgeon`, `nanodx`, `pannanodx`, `random_forest` + +Unknown names produce warnings and are skipped. + +## Examples + +```bash +# Minimal classifier run (preprocessing + bed_conversion added as needed) +robin workflow /data/bams -w sturgeon --center Demo --target-panel rCNS2 -d /out --reference /ref/hg38.fa + +# Full stack (typical) +robin workflow /data/bams \ + -w target,cnv,fusion,mgmt,sturgeon,nanodx,pannanodx,random_forest \ + --center Sherwood \ + --target-panel rCNS2 \ + -d ~/results \ + --reference ~/references/hg38.fa +``` + +## Related + +- [`robin workflow`](workflow.md) +- [Quickstart](../getting-started/quickstart.md) diff --git a/docs/cli/panels.md b/docs/cli/panels.md new file mode 100644 index 0000000..b2e601f --- /dev/null +++ b/docs/cli/panels.md @@ -0,0 +1,93 @@ +# Panel commands + +Target **panels** define which genes/regions drive **target**, **CNV**, and **fusion** analyses and which packaged BED files ROBIN uses. Built-in panels ship with the install; you can add **custom** panels from BED files. + +Commands: + +- [`robin list-panels`](#robin-list-panels) +- [`robin add-panel`](#robin-add-panel) +- [`robin remove-panel`](#robin-remove-panel) + +All require the interactive **disclaimer** (`I agree`). + +--- + +## `robin list-panels` + +Lists **built-in** panels (`rCNS2`, `AML`, `PanCan`, …) and **custom** panels registered in `robin.resources`. + +```bash +robin list-panels +``` + +Use the printed names with **`robin workflow --target-panel`** and **`robin utils sequencing-files --panel`**. + +--- + +## `robin add-panel` + +Register a new panel from a BED file. + +```bash +robin add-panel /path/to/panel.bed MyPanelName +``` + +### BED format + +- At least **4 columns**: `chrom`, `start`, `end`, `gene` (or comma-separated genes). +- **6-column** BED is allowed (`score`, `strand`). +- Regions spanning multiple genes can list **comma-separated** gene symbols in the name column. + +### Options + +| Flag | Meaning | +|------|---------| +| `--validate-only` | Check the BED only; do not copy files into resources. | + +### Reserved names + +You **cannot** use `rCNS2`, `AML`, or `PanCan` as custom names. + +### What ROBIN stores + +- **Processed** unique-gene BED: `{PanelName}_panel_name_uniq.bed` under `robin.resources`. +- **Original upload** copy: `{PanelName}_panel_source.bed` (for traceability and [`sequencing-files`](utils.md#robin-utils-sequencing-files)). + +If a panel with the same name already exists, the command fails until you [`remove-panel`](#robin-remove-panel). + +--- + +## `robin remove-panel` + +Remove a **custom** panel (not built-ins). + +```bash +robin remove-panel MyPanelName +robin remove-panel MyPanelName --force +``` + +| Flag | Meaning | +|------|---------| +| `-f` / `--force` | Skip the `yes` confirmation (destructive). | + +Built-in panels **cannot** be removed. + +--- + +## Using panels in a workflow + +```bash +robin workflow /data/bams \ + -w target,cnv,fusion \ + --target-panel MyPanelName \ + --center Sherwood \ + -d ~/results \ + --reference ~/references/hg38.fa +``` + +--- + +## Related + +- [Utilities — `sequencing-files`](utils.md#robin-utils-sequencing-files) (copy panel BED + reference for MinKNOW) +- [`robin workflow`](workflow.md) diff --git a/docs/cli/password.md b/docs/cli/password.md new file mode 100644 index 0000000..35ac844 --- /dev/null +++ b/docs/cli/password.md @@ -0,0 +1,25 @@ +# `robin password` + +Configure the **NiceGUI** workflow monitor login password. + +For the full startup sequence (disclaimer, when the GUI prompts for a password), see **[What happens at startup](../getting-started/startup.md)**. + +## `robin password set` + +```bash +robin password set +``` + +- Prompts twice for the new password (no echo). +- Replaces any previously stored password. + +If the GUI password module fails to import (minimal install / broken env), the command prints an error and exits non-zero. + +## When it applies + +The password is used when the **[`robin workflow`](workflow.md)** GUI is enabled (`--with-gui`, default) and password protection is active in the GUI layer — see application logs and on-screen prompts if login is required. + +## Related + +- [`robin workflow` GUI options](workflow.md#gui-nicegui) +- [CLI overview](index.md) diff --git a/docs/cli/utils.md b/docs/cli/utils.md new file mode 100644 index 0000000..8afea98 --- /dev/null +++ b/docs/cli/utils.md @@ -0,0 +1,93 @@ +# `robin utils` + +Utility subcommands for **assets**, **reference/panel staging**, and **post-hoc** MGMT summaries. The group is separate from the live [`workflow`](workflow.md) so you can update models or prepare files without starting the orchestrator. + +```bash +robin utils --help +``` + +Subcommands documented below: + +| Command | Purpose | +|---------|---------| +| [`update-models`](#robin-utils-update-models) | Download or refresh model files from the assets manifest. | +| [`update-clinvar`](#robin-utils-update-clinvar) | Update ClinVar resources used for annotation paths. | +| [`sequencing-files`](#robin-utils-sequencing-files) | Copy panel BED(s) and download or link a GRCh38 FASTA for MinKNOW / alignment. | +| [`mgmt`](#robin-utils-mgmt) | Tabulate MGMT CpG methylation from existing `mgmt_sorted.bam` outputs. | + +--- + +## `robin utils update-models` + +Downloads or refreshes **model** files (checksums via the manifest). Typical after install or when assets change. + +```bash +robin utils update-models +robin utils update-models --overwrite +``` + +| Option | Description | +|--------|-------------| +| `--models-dir` | Override output directory (default: ROBIN models directory). | +| `--manifest` | Path to `assets.json` (default: packaged manifest or `ROBIN_ASSETS_MANIFEST`). | +| `--overwrite` | Replace existing files. | + +For **private** GitHub-hosted assets, set **`GITHUB_TOKEN`** before running. + +More context: [Installation — models](../getting-started/installation.md#step-4-download-models-and-clinvar). + +--- + +## `robin utils update-clinvar` + +Updates **ClinVar** in ROBIN’s resource tree (best-effort “newer NCBI drop” behaviour). + +```bash +robin utils update-clinvar +``` + +Pair with `update-models` when setting up a new environment. + +--- + +## `robin utils sequencing-files` + +Stages **panel BED** files and a **reference FASTA** into one folder for **MinKNOW** (adaptive sampling + alignment) and for passing the same path to **`robin workflow --reference`**. + +```bash +robin utils sequencing-files --panel rCNS2 --output-dir ~/references/robin_ref +``` + +| Option | Description | +|--------|-------------| +| `-p` / `--panel` | **Required.** Panel name (same as `--target-panel`). | +| `-r` / `--reference` | URL to download or local `.fa` / `.fa.gz`. Default: NCBI **GRCh38 no-alt** (large download). | +| `-o` / `--output-dir` | Output directory (default: `./reference_files`). | +| `-y` / `--yes` | Non-interactive confirmation. | + +The command copies packaged **`{panel}_panel_name_uniq.bed`** and, when present, **`{panel}_panel_source.bed`**, then materializes the reference. + +See also: [Quickstart — Reference and panel BEDs](../getting-started/quickstart.md#reference-and-panel-beds). + +--- + +## `robin utils mgmt` + +Summarises **MGMT** CpG methylation from **`mgmt_sorted.bam`** files already produced under a ROBIN output tree (offline inspection / QC). + +```bash +robin utils mgmt /path/to/robin_output --recursive -o mgmt_summary.tsv +``` + +| Option | Description | +|--------|-------------| +| `OUTPUT_DIR` | Root directory to search (required). | +| `-r` / `--recursive` | Find `mgmt_sorted.bam` recursively. | +| `-o` / `--out` | TSV path; default `-` (stdout). | + +--- + +## Related + +- [Installation](../getting-started/installation.md) +- [Quickstart](../getting-started/quickstart.md) diff --git a/docs/cli/workflow.md b/docs/cli/workflow.md new file mode 100644 index 0000000..e57f01b --- /dev/null +++ b/docs/cli/workflow.md @@ -0,0 +1,114 @@ +# `robin workflow` + +Run the **Little John** orchestrated pipeline on BAM files under a watched directory: preprocessing, optional BED conversion, analyses (MGMT, CNV, target, fusion), classifiers (Sturgeon, NanoDX, PanNanoDX, random forest), and optional **NiceGUI** monitoring. + +!!! info "Startup sequence" + When you run this command, ROBIN checks models, optionally validates `--reference`, asks you to type **`I agree`** to the research disclaimer, then (with the GUI enabled) may prompt for the **GUI password**. On the default **Ray** path, the browser UI is only started if **`--work-dir`** is set. Details: **[What happens at startup](../getting-started/startup.md)**. + +## Synopsis + +```bash +robin workflow -w --center --target-panel [OPTIONS] +``` + +| Argument / option | Required | Description | +|-------------------|----------|-------------| +| `PATH` | Yes | Directory containing (or receiving) BAM files. Must exist. | +| `-w` / `--workflow` | Yes | Comma-separated job types or legacy `queue:job` steps (see [Job types](jobs.md)). | +| `--center` | Yes | Site or study label (e.g. `Sherwood`, `Auckland`) — used in outputs and reports. | +| `--target-panel` | Yes | Panel name: built-in (`rCNS2`, `AML`, `PanCan`, …) or custom from `robin add-panel`. Run `robin utils sequencing-files --help` to see choices on your install. | +| `-d` / `--work-dir` | No | Base directory for all run outputs. | +| `-r` / `--reference` | No* | Path to reference **FASTA**. If provided, ROBIN validates the file and ensures an index (e.g. `.fai`). Required for analyses that need a reference. | + +\* Omit only if your chosen workflow truly does not need a reference; most real pipelines pass `--reference`. + +## Workflow string formats + +### Simplified (recommended) + +Comma-separated **job types** only — queues are assigned automatically: + +```bash +-w mgmt,sturgeon +-w target,cnv,fusion,mgmt,sturgeon,nanodx,pannanodx,random_forest +``` + +Behaviour: + +- **`preprocessing`** is always inserted as the first step if missing. +- **`bed_conversion`** is inserted **before** classification jobs when needed (`sturgeon`, `nanodx`, `pannanodx`, `random_forest`). + +### Legacy (explicit queues) + +Use `queue:job` steps, e.g.: + +```text +preprocessing:preprocessing,bed_conversion:bed_conversion,mgmt:mgmt,classification:sturgeon +``` + +## Execution engine + +| Mode | Flag | Notes | +|------|------|--------| +| **Ray** (default) | `--use-ray` | Distributed task execution; optional Ray dashboard (`--ray-dashboard` / `--no-ray-dashboard`). | +| Threading | `--no-use-ray` | Falls back to threaded workers; analysis worker counts apply per queue mode. | + +**Presets** (`--preset`): `p2i`, `standard` (default), `high` — adjust Ray actor grouping and CPU caps for different hardware (e.g. P2i vs server). + +## GUI (NiceGUI) + +| Option | Default | Description | +|--------|---------|-------------| +| `--with-gui` / `--no-gui` | GUI on | Launch workflow monitor in the browser. | +| `--gui-host` | `0.0.0.0` | Bind address. | +| `--gui-port` | `8081` | Port for the GUI. | + +## Logging and progress + +| Option | Description | +|--------|-------------| +| `--log-level` | Global level: `DEBUG`, `INFO`, `WARNING`, `ERROR` (default `ERROR`). | +| `--job-log-level` | Repeatable, e.g. `preprocessing:DEBUG`, `mgmt:WARNING`. | +| `--verbose` / `-v` | Verbose CLI and traces. | +| `--no-progress` | Disable file progress bars. | + +## File handling + +| Option | Description | +|--------|-------------| +| `--no-process-existing` | Only process BAMs that appear **after** startup (skip files already on disk). | +| `--no-watch` | Do not watch the directory for new files (advanced; default is to watch). | + +## Ray tuning + +| Option | Description | +|--------|-------------| +| `--ray-num-cpus` | Cap CPUs for Ray (auto if omitted). | +| `--queue-priority` | Repeatable, e.g. `preprocessing:10`, `mgmt:5` (Ray mode). | +| `--show-priorities` | Print queue priorities and exit. | +| `--analysis-workers` | Workers per analysis queue (default from code constant, often `1`). | +| `--preprocessing-workers`, `--bed-workers` | Workers for preprocessing and `bed_conversion`. | +| `--legacy-analysis-queue` | Single shared analysis queue instead of per-type queues (threading path). | + +## Deduplication + +`--deduplicate-jobs` (repeatable) — job types that should run **at most once per sample** even when multiple triggers fire (e.g. `sturgeon`, `mgmt`). + +## Custom per-job shell commands + +`--commands` / `-c` (repeatable) — optional mappings `job_type:shell_command` for custom steps (advanced; see `robin workflow --help`). + +## Inputs and sequencing assumptions + +ROBIN expects **real-time** BAMs with **≤ 50,000 reads per file** and **read-count–based** rollover in MinKNOW. See the [README](https://github.com/LooseLab/littlejohn/blob/main/README.md#bam-read-limit-and-minknow-settings). + +## Exit + +Stop with **Ctrl+C** — the runner attempts graceful shutdown; complex runs may not always exit instantly. + +## Related + +- [Job types and queues](jobs.md) +- [Panel commands](panels.md) +- [Utilities — reference files](utils.md#robin-utils-sequencing-files) +- [Quickstart](../getting-started/quickstart.md) diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 0000000..44412a2 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,143 @@ +# Installation + +This guide covers installing ROBIN and its dependencies from source for **this repository** ([littlejohn](https://github.com/LooseLab/littlejohn)). + +For **running** workflows (MinKNOW settings, BAM read limits, alignment, and CLI usage), see the repository **[README](https://github.com/LooseLab/littlejohn/blob/main/README.md)**—especially *BAM read limit and MinKNOW settings* and *Usage*. This page focuses on **installation**. + +--- + +## ROBIN with Little John + +### Prerequisites + +- Git and [Git LFS](https://git-lfs.com/) +- [Conda](https://docs.conda.io/) (Miniconda or Anaconda) +- Python **3.12** (supplied by the `robin` conda environment) + +Recommended: + +- **64 GB RAM** or more for production runs +- CPU/GPU per Oxford Nanopore guidance for your sequencer + +Docker is optional (some third-party or containerized toolchains may use it). + +### Step 1: Clone the repository + +Clone including submodules: + +```bash +git clone --recursive https://github.com/LooseLab/littlejohn.git +cd littlejohn +``` + +If you already cloned without submodules: + +```bash +git submodule update --init --recursive +``` + +### Step 2: Create the conda environment + +Use the environment file at the repository root: + +| File | Purpose | +|------|---------| +| **`robin.yml`** | Main environment: Python 3.12, scientific stack, bioinformatics tools, R/Bioconductor (Linux and macOS). | +| **`robin_linux_extras.yml`** | **Linux only**, optional: merge after creating the env if you hit `libstdc++` / `CXXABI_1.3.15` issues (see README *Common issues*). | + +```bash +conda env create -f robin.yml +conda activate robin +``` + +Notes: + +- `pyproject.toml` requires Python `>=3.12`; this environment matches that. +- Prefer a **fresh** environment for this codebase rather than reusing an older ROBIN env from past releases. + +#### If the `robin` environment already exists + +`robin.yml` sets **`name: robin`**. If `conda env create -f robin.yml` reports the environment already exists: + +**Option A — Update in place** + +```bash +conda env update -n robin -f robin.yml --prune +conda activate robin +``` + +**Option B — Remove and recreate** (clearest if the old env is stale or mixed) + +```bash +conda deactivate +conda env remove -n robin +conda env create -f robin.yml +conda activate robin +``` + +**Option C — New name** + +```bash +conda env create -f robin.yml -n robin_littlejohn +conda activate robin_littlejohn +``` + +On **Linux**, if you see `CXXABI_1.3.15` / wrong `libstdc++`: + +```bash +conda env update -n robin -f robin_linux_extras.yml +``` + +(See README *Common issues* for details.) + +### Step 3: Install ROBIN (editable) + +From the repository root: + +```bash +pip install -e . +``` + +This installs the `robin` CLI from your working tree. + +### Step 4: Download models and ClinVar + +After installation, fetch bundled assets (SHA256-verified; set `GITHUB_TOKEN` if assets are on private GitHub): + +```bash +robin utils update-models +robin utils update-clinvar +``` + +Private GitHub: + +```bash +export GITHUB_TOKEN=your_personal_access_token +robin utils update-models +``` + +Force re-download models if needed: + +```bash +robin utils update-models --overwrite +``` + +### Step 5: Verify + +```bash +robin --help +robin list-job-types +``` + +### Troubleshooting + +| Issue | What to do | +|-------|------------| +| Missing submodules | `git submodule update --init --recursive` | +| Model / ClinVar download failures | Set `GITHUB_TOKEN` if required; retry with `robin utils update-models --overwrite`; run `robin utils update-clinvar` | +| Wrong conda env | `conda env list` and activate the env you created from `robin.yml` | + +### Next steps + +- [Quickstart](quickstart.md) +- [README — Usage](https://github.com/LooseLab/littlejohn/blob/main/README.md#usage) diff --git a/docs/getting-started/library-preparation.md b/docs/getting-started/library-preparation.md new file mode 100644 index 0000000..3f867f4 --- /dev/null +++ b/docs/getting-started/library-preparation.md @@ -0,0 +1,41 @@ +# Library preparation + +This guide summarizes library preparation for sequencing analysed with ROBIN. + +## Overview + +ROBIN is designed for Oxford Nanopore (ONT) libraries. For CNS tumour work you can use either: + +1. The **ROBIN-specific** protocol on protocols.io, or +2. The standard **ONT LSK114** ligation workflow. + +## Input DNA + +Adaptive sampling works best with read lengths around **8–12 kb**; follow your chosen protocol to hit that range. + +## Options + +### ROBIN protocol + +[ROBIN: A Unified Nanopore-based Sequencing Assay](https://www.protocols.io/view/robin-a-unified-nanopore-based-sequencing-assay-in-bp2l6xepklqe/v3) — fragmentation, ligation, QC, and troubleshooting tuned for this use case. + +### Standard ONT LSK114 + +[ONT LSK114 product / documentation](https://store.nanoporetech.com/uk/ligation-sequencing-kit-v14.html) and [library preparation hub](https://nanoporetech.com/library-preparation). + +## DNA input + +- High-quality DNA (e.g. A260/A280 ~1.8–2.0) +- Minimum ~**100 ng**; optimal often **500 ng–1 µg** +- Elute in TE or nuclease-free water + +## Next steps + +1. Configure MinKNOW for your run — [MinKNOW configuration](minknow-configuration.md) +2. Start ROBIN — [Quickstart](quickstart.md) + +## Resources + +- [ROBIN protocol (protocols.io)](https://www.protocols.io/view/robin-a-unified-nanopore-based-sequencing-assay-in-bp2l6xepklqe/v3) +- [ONT library preparation](https://nanoporetech.com/library-preparation) +- [SQK-RAD114](https://store.nanoporetech.com/sqk-rad114.html) (where applicable) diff --git a/docs/getting-started/minknow-configuration.md b/docs/getting-started/minknow-configuration.md new file mode 100644 index 0000000..3384704 --- /dev/null +++ b/docs/getting-started/minknow-configuration.md @@ -0,0 +1,64 @@ +# MinKNOW configuration + +How to configure MinKNOW for real-time BAM output compatible with ROBIN. + +## Overview + +ROBIN expects: + +- Real-time **basecalling** (with **methylation** output as required by your ROBIN build) +- **Alignment** to the same reference you pass to ROBIN +- **BAM** output with sensible rollover (read-count–based, not hourly-only) +- Clear **sample** (and optionally **experiment**) IDs for output organisation + +## Basecalling + +Use **high-accuracy** basecalling with **5hmC / 5mc** methylation calling where ROBIN requires it. **Do not** disable methylation for off-target reads if your pipeline uses those signals. + +Example basecalling config (verify against your MinKNOW / kit release): + +- `dna_r10.4.1_e8.2_400bps_5khz_modbases_5hmc_5mc_cg_hac_prom.cfg` + +## Adaptive sampling + +If you use adaptive sampling: + +- Use the **BED** file specified for your ROBIN / panel build (e.g. `panel_11092024_5kb_pad.bed` for classic CNS panels — confirm path in your installed resources). +- Use the **same reference** as ROBIN and alignment. +- Mode typically **enrich** (per your assay design). + +## Alignment + +Produce **aligned BAMs** against the **same** reference genome files used in ROBIN (`--reference`). + +## BAM output + +- Prefer **read-count** rollover, not **time-only** hourly chunks (unsupported for real-time ROBIN processing). +- Keep each BAM **under the supported read count** (see [README](https://github.com/LooseLab/littlejohn/blob/main/README.md#bam-read-limit-and-minknow-settings)); a common target is **~20,000–50,000 reads per file** depending on workflow. +- You may disable **POD5** and **FASTQ** if you only need BAM. + +## Sample and experiment IDs + +- Set a **unique sample ID** per library — ROBIN uses this for output folders and to join analysis to the correct run. +- If you use ROBIN’s **[Sample ID generator](../using-robin/pages-and-routes.md#sample-id-generator)** (MD5 from test ID and optional patient fields), use that **generated sample ID** as the **MinKNOW sample ID** when you start the run. ROBIN will then **link** MinKNOW outputs, the on-disk manifest, and the web app **without** manual renaming. +- **Experiment ID** can group runs; you can point ROBIN at a subset of output directories if helpful. +- Set **run duration** appropriate to your clinical or research protocol (e.g. 24 h for many CNS assays). + +## Run workflow + +1. Apply the settings above in MinKNOW. +2. Start the run. +3. Start ROBIN with the directory MinKNOW writes BAMs into (`robin workflow …` for Little John, or legacy `robin …` for Original ROBIN). +4. Monitor progress in the CLI / NiceGUI (Little John) or legacy GUI (Original ROBIN). + +## Troubleshooting + +- **API errors** (`minknow_api`): install the Python `minknow-api` version that matches your MinKNOW install — see [Installation → MinKNOW API](installation.md). +- **Huge BAMs / missed processing**: reduce reads per file and avoid time-only rollover. +- **Reference mismatch**: alignment reference must match ROBIN’s `--reference`. + +## Next steps + +- [Quickstart](quickstart.md) +- [MinKNOW documentation](https://nanoporetech.com/minknow) +- [Adaptive sampling](https://nanoporetech.com/adaptive-sampling) diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md new file mode 100644 index 0000000..6384394 --- /dev/null +++ b/docs/getting-started/quickstart.md @@ -0,0 +1,183 @@ +# ROBIN Quickstart + +How to run ROBIN from this repository after [installation](installation.md): live BAM analysis with `robin workflow`, optional NiceGUI monitoring, and target panels. + +For **disclaimer, GUI password, and startup order**, see **[What happens at startup](startup.md)**. For a **step-by-step guide to the web interface**, see **[Using ROBIN](../using-robin/index.md)**. + +For deeper detail (CLI flags, MinKNOW, troubleshooting), use the **[README](https://github.com/LooseLab/littlejohn/blob/main/README.md)** and the **[command-line reference](../cli/index.md)**. + +--- + +## What ROBIN expects + +ROBIN consumes **aligned BAMs** from Oxford Nanopore sequencing (typically written in real time by MinKNOW): + +| Expectation | Notes | +|-------------|--------| +| Basecalling | **HAC** is sufficient; SUP not required. | +| Methylation | **5hmC / 5mC** calling enabled in MinKNOW if your analyses need methylation. | +| Alignment | Done **in MinKNOW** — ROBIN does not realign reads. | +| BAM rollover | **Read-count–based** chunks. **Each BAM must be ≤ 50,000 reads**; we recommend **~50,000 reads per file**. Do **not** rely on **time-only** (e.g. hourly) rollover — see [README — BAM read limit](https://github.com/LooseLab/littlejohn/blob/main/README.md#bam-read-limit-and-minknow-settings). | +| POD5 / FASTQ | Not required; you can turn them off if you only need BAM. | + +### Memory (≤ 64 GB RAM) + +On smaller machines, restart between long runs or after switching flow-cell positions. Dorado can hold GPU/host memory; restarting Dorado or the instrument after a run reduces out-of-memory risk. + +--- + +## Reference and panel BEDs + +Use **`robin utils sequencing-files`** to gather the **processed panel BED** (and optional **source BED** when packaged) plus a **GRCh38 reference FASTA** in one place for MinKNOW (adaptive sampling, alignment) and for **`robin workflow --reference`**. Run this after [installation](installation.md) when you need a consistent reference path. + +```bash +robin utils sequencing-files --panel rCNS2 --output-dir ~/references/robin_ref +``` + +| Option | Purpose | +|--------|---------| +| `-p` / `--panel` | **Required.** Same names as `--target-panel` (built-in panels such as `rCNS2`, `AML`, `PanCan`; run `robin utils sequencing-files --help` for the list on your install). | +| `-r` / `--reference` | **Reference FASTA:** either an **HTTPS URL** to download, or a **local path** to `.fa` / `.fa.gz`. If omitted, ROBIN uses the default **NCBI GRCh38 no-alt analysis set** (UCSC-style contig names) — a **large** download; use `-r` to point at an existing file if you already have GRCh38. | +| `-o` / `--output-dir` | Output folder (default: **`./reference_files`** in the current directory). | +| `-y` / `--yes` | Skip the confirmation prompt (for scripts). | + +The command copies the panel BED(s) from ROBIN resources and **materializes** the reference at the chosen location. Use the **same** reference file for **MinKNOW alignment** and for **`robin workflow --reference`**. + +### Other `robin utils` commands + +| Command | Purpose | +|---------|---------| +| `robin utils update-models` | Download or refresh **classification / model** assets (see [Installation](installation.md)). | +| `robin utils update-clinvar` | Download or refresh **ClinVar** under ROBIN resources for annotation paths. | +| `robin utils mgmt` | Summarise **MGMT** CpG methylation from existing `mgmt_sorted.bam` outputs (post-run inspection). | + +Run **`robin utils --help`** for the full list. + +--- + +## Run a workflow + +Typical command: + +```bash +robin workflow --work-dir \ + -w target,cnv,fusion,mgmt,sturgeon,nanodx,pannanodx,random_forest \ + --reference ~/references/hg38_simple.fa \ + --center +``` + +| Argument | Meaning | +|----------|---------| +| `` | Directory watched for incoming BAMs | +| `--work-dir` | Root directory for outputs | +| `-w` | Comma-separated analysis types | +| `--reference` | Reference FASTA (needed for most steps) | +| `--center` | Site label (e.g. `Sherwood`, `Auckland`) | +| `--target-panel` | Panel name, e.g. `rCNS2`, `PanCan` | + +### Examples + +```bash +# Broad workflow with a fixed panel +robin workflow ~/data/bam_files \ + --work-dir ~/results \ + -w target,cnv,fusion,mgmt,sturgeon,nanodx,pannanodx,random_forest \ + --reference ~/references/hg38_simple.fa \ + --center Sherwood \ + --target-panel rCNS2 + +# Smaller selection +robin workflow ~/data/bam_files \ + --work-dir ~/results \ + -w mgmt,sturgeon \ + --reference ~/references/hg38_simple.fa \ + --center Auckland \ + --target-panel PanCan + +# More logging +robin workflow ~/data/bam_files \ + --work-dir ~/results \ + -w mgmt,cnv,sturgeon \ + --reference ~/references/hg38_simple.fa \ + --center New_York \ + --target-panel rCNS2 \ + --verbose \ + --log-level INFO +``` + +Point `--reference` at the same **GRCh38** FASTA you use for MinKNOW — for example the file produced under your [`sequencing-files`](#reference-and-panel-beds) output directory — not a different assembly or naming scheme. + +--- + +## Commands + +### `list-job-types` + +```bash +robin list-job-types +``` + +Examples: preprocessing, bed_conversion, mgmt, cnv, target, fusion, sturgeon, nanodx, pannanodx, random_forest (see live output for your version). + +### `workflow` + +```bash +robin workflow /path/to/directory -w "" [OPTIONS] +``` + +Required: + +- `-w` / `--workflow` — e.g. `mgmt,sturgeon`, or queue-qualified plans (`robin workflow --help`). +- `--center` — site ID. + +Useful options (full list: `robin workflow --help`): + +- `--work-dir` — output directory +- `--reference` — reference FASTA +- `--verbose`, `--log-level`, `--job-log-level` +- `--no-process-existing` — only new files after start +- `--deduplicate-jobs` — dedupe selected job types by sample +- `--use-ray` / `--no-use-ray` — Ray execution +- `--with-gui` / `--no-gui` — NiceGUI workflow monitor + +--- + +## Panel management + +Built-in panels include **rCNS2**, **AML**, **PanCan**. Custom panels are registered from BED (at least four columns: chr, start, end, gene name(s)). + +```bash +robin list-panels +robin add-panel /path/to/panel.bed MyCustomPanel +robin add-panel /path/to/panel.bed MyCustomPanel --validate-only +robin remove-panel MyCustomPanel +robin remove-panel MyCustomPanel --force +``` + +You cannot reuse reserved names: `rCNS2`, `AML`, `PanCan`. + +--- + +## Behaviour and limitations + +- **CNV** — Heuristic calls; **review visually** before any clinical interpretation. +- **Stop with Ctrl+C** — Graceful shutdown is attempted but not guaranteed. +- **Bugs / questions** — [Open an issue](https://github.com/LooseLab/littlejohn/issues). + +### Performance + +- Batched processing on heavy paths +- Optional `LJ_BAM_THREADS` for BAM threading where supported +- Non-blocking GUI updates when the NiceGUI monitor is enabled + +### License and credits + +Research use only; see **LICENSE** in the repository. ROBIN integrates tools such as Sturgeon, Rapid-CNS2, Readfish, cnv_from_bam, methylartist — see the repo and papers for full attribution. + +--- + +## Next steps + +- [Library preparation](library-preparation.md) +- [MinKNOW configuration](minknow-configuration.md) +- [README — Usage](https://github.com/LooseLab/littlejohn/blob/main/README.md#usage) diff --git a/docs/getting-started/startup.md b/docs/getting-started/startup.md new file mode 100644 index 0000000..eea5ace --- /dev/null +++ b/docs/getting-started/startup.md @@ -0,0 +1,143 @@ +# What happens when you start ROBIN + +This page describes the **typical experience** when you run **`robin workflow`** from a terminal: checks, prompts, the **research disclaimer**, **GUI password**, and where the **NiceGUI** monitor appears. Behaviour matches the current codebase; always check **`robin workflow --help`** for your installed version. + +For install steps, see [Installation](installation.md). For command-line flags, see the [command-line reference](../cli/workflow.md). + +--- + +## 1. Model assets + +Before anything else, ROBIN verifies that **required model files** are present (same manifest as `robin utils update-models`). If files are missing, the process exits with a message telling you to run **`robin utils update-models`** (and set **`GITHUB_TOKEN`** if your assets are on private GitHub). + +--- + +## 2. Reference genome (if you pass `--reference` / `-r`) + +If you supply a reference **FASTA**, ROBIN validates it and ensures an index (e.g. `.fai`) can be created or found. On failure, it exits with an error — fix the path or omit `--reference` only if your workflow truly does not need it. + +--- + +## 3. Research disclaimer (`I agree`) + +ROBIN prints the **research-use disclaimer** and waits for you to type **`I agree`** exactly (case-sensitive). This is required before the workflow starts. + +--- + +## 4. Optional warning: large BAMs + +If **`ROBIN_PROCESS_LARGE_BAMS`** is enabled, ROBIN prints a **warning** that this mode must **not** be used together with live sequencing runs. + +--- + +## 5. Configuration summary + +The terminal prints a summary of your run: paths, **`--center`**, workflow steps (including automatic **`preprocessing`** / **`bed_conversion`** insertion), logging, Ray/threading mode, etc. + +--- + +## 6. Execution engine (Ray vs threading) + +- **Default (`--use-ray`)** — Ray is initialised (with optional dashboard, CPU limits, presets). The **Ray Core** workflow driver runs asynchronously. +- **`--no-use-ray`** — Falls back to threaded workers instead of Ray. + +--- + +## 7. NiceGUI workflow monitor (default: on) + +With **`--with-gui`** (the default), ROBIN starts a **web-based** workflow monitor (NiceGUI) so you can follow progress in a browser. + +### When the GUI actually starts + +| Mode | GUI behaviour | +|------|----------------| +| **Ray workflow (default)** | The GUI is started **inside** the Ray workflow driver **only if** you pass **`--work-dir`** (`-d`). If `--work-dir` is omitted, the driver may skip launching the GUI and print that **`--work-dir` was not provided**. | +| **`--no-use-ray`** | The CLI launches the GUI when **`--with-gui`** is set, using **`--work-dir`** if provided, otherwise the **watched BAM directory** as the monitored path. | + +So for the **default Ray** path, plan to pass **both** a data directory (positional `PATH`) **and** **`--work-dir`** if you want the browser UI. + +### URLs + +When the GUI starts, the terminal prints a base URL such as **`http://:`** (defaults: host **`0.0.0.0`**, port **`8081`**). Typical entry points include: + +- Welcome / root: `/` +- Workflow monitor: `/robin` +- Sample-oriented views: paths under `/live_data` (exact routes are printed at startup) + +Use **`--gui-host`** and **`--gui-port`** to change bind address and port; use **`--no-gui`** to disable the web UI entirely. + +### Disable the GUI + +```bash +robin workflow ... --no-gui +``` + +--- + +## 8. GUI password (terminal prompts) + +Access to the web UI is protected by a **password** (requires **`argon2-cffi`** for secure handling). ROBIN prompts in the terminal; passwords are **not** echoed. + +### First run (password not set yet) + +If no password has been set and **stdin is a TTY** (interactive terminal), ROBIN prompts: + +```text +Set GUI password: +Confirm GUI password: +``` + +You must enter the same password twice. The password is stored for future logins. + +If **no password has been set yet** and **stdin is not a TTY** (e.g. some automated contexts), startup **fails** with a message to run ROBIN from a terminal so the password can be set interactively. + +### Later runs (password already set) + +If stdin is a **TTY**, you are prompted once: + +```text +GUI password: +``` + +Enter the same password you set earlier. Wrong password → **Invalid password.** and the GUI does not start. + +### Setting or changing the password without a full workflow + +Use the dedicated command (see [GUI password](../cli/password.md)): + +```bash +robin password set +``` + +This can **replace** an existing password after confirmation. It uses the same mechanism as the first-run prompts. + +--- + +## 9. Workflow hooks (optional message) + +If the GUI starts successfully, ROBIN may install **workflow hooks** for live updates. If hook installation fails, you may see a message that the GUI will show **static** information only. + +--- + +## 10. Watching BAMs and shutting down + +After the above, the runner **watches** the input directory for **`*.bam`** files (subject to `--no-process-existing`, `--no-watch`, etc.) and schedules jobs. Use **Ctrl+C** to stop; ROBIN attempts a **graceful shutdown** (workflow manager, Ray, GUI), though complex runs may take a moment to exit. + +--- + +## Quick reference — order of prompts + +1. (Automatic) Model check +2. (If `-r`) Reference validation +3. **Type `I agree`** — research disclaimer +4. (If GUI enabled) **GUI password** — set twice first time, or single verify later +5. Browser → open printed URL to monitor + +--- + +## See also + +- [Quickstart](quickstart.md) +- [`robin workflow`](../cli/workflow.md) +- [GUI password command](../cli/password.md) +- [CLI overview](../cli/index.md) diff --git a/docs/images/Activity.png b/docs/images/Activity.png new file mode 100644 index 0000000..f3184fa Binary files /dev/null and b/docs/images/Activity.png differ diff --git a/docs/images/AllSamples.png b/docs/images/AllSamples.png new file mode 100644 index 0000000..97dbbe2 Binary files /dev/null and b/docs/images/AllSamples.png differ diff --git a/docs/images/Classification.png b/docs/images/Classification.png new file mode 100644 index 0000000..eca1953 Binary files /dev/null and b/docs/images/Classification.png differ diff --git a/docs/images/CopyNumber.png b/docs/images/CopyNumber.png new file mode 100644 index 0000000..1200815 Binary files /dev/null and b/docs/images/CopyNumber.png differ diff --git a/docs/images/CopyNumber1Mb.png b/docs/images/CopyNumber1Mb.png new file mode 100644 index 0000000..23ad745 Binary files /dev/null and b/docs/images/CopyNumber1Mb.png differ diff --git a/docs/images/CopyNumberChr8.png b/docs/images/CopyNumberChr8.png new file mode 100644 index 0000000..4404599 Binary files /dev/null and b/docs/images/CopyNumberChr8.png differ diff --git a/docs/images/GenerateSampleID.png b/docs/images/GenerateSampleID.png new file mode 100644 index 0000000..f45f34d Binary files /dev/null and b/docs/images/GenerateSampleID.png differ diff --git a/docs/images/IGVview.png b/docs/images/IGVview.png new file mode 100644 index 0000000..ac6f677 Binary files /dev/null and b/docs/images/IGVview.png differ diff --git a/docs/images/MGMT.png b/docs/images/MGMT.png new file mode 100644 index 0000000..2df376a Binary files /dev/null and b/docs/images/MGMT.png differ diff --git a/docs/images/MNPFlex.png b/docs/images/MNPFlex.png new file mode 100644 index 0000000..0a3bec5 Binary files /dev/null and b/docs/images/MNPFlex.png differ diff --git a/docs/images/OneSample.png b/docs/images/OneSample.png new file mode 100644 index 0000000..f3184fa Binary files /dev/null and b/docs/images/OneSample.png differ diff --git a/docs/images/ROBIN_logo_small.png b/docs/images/ROBIN_logo_small.png new file mode 100644 index 0000000..1e6fda4 Binary files /dev/null and b/docs/images/ROBIN_logo_small.png differ diff --git a/docs/images/RunSummary.png b/docs/images/RunSummary.png new file mode 100644 index 0000000..5263234 Binary files /dev/null and b/docs/images/RunSummary.png differ diff --git a/docs/images/SNPexample.png b/docs/images/SNPexample.png new file mode 100644 index 0000000..197e351 Binary files /dev/null and b/docs/images/SNPexample.png differ diff --git a/docs/images/SampleDetails.png b/docs/images/SampleDetails.png new file mode 100644 index 0000000..c94971d Binary files /dev/null and b/docs/images/SampleDetails.png differ diff --git a/docs/images/TargetCoverage.png b/docs/images/TargetCoverage.png new file mode 100644 index 0000000..020ca4f Binary files /dev/null and b/docs/images/TargetCoverage.png differ diff --git a/docs/images/WatchedFolders.png b/docs/images/WatchedFolders.png new file mode 100644 index 0000000..14f0674 Binary files /dev/null and b/docs/images/WatchedFolders.png differ diff --git a/docs/images/login.png b/docs/images/login.png new file mode 100644 index 0000000..9d0af66 Binary files /dev/null and b/docs/images/login.png differ diff --git a/docs/images/welcome.png b/docs/images/welcome.png new file mode 100644 index 0000000..66636d1 Binary files /dev/null and b/docs/images/welcome.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..c448996 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,112 @@ +# ROBIN + +![ROBIN Logo](images/ROBIN_logo_small.png) + +Rapid nanopOre Brain intraoperatIve classificatioN + +!!! warning "IMPORTANT" + ROBIN is currently for research use only. This technology is under active development and validation at this time. + +## Our Mission + +Currently in the UK, patients, families, and clinicians can wait 6 weeks or more for a complete molecular profile of a CNS tumour, delaying treatment decisions and causing significant uncertainty. + +ROBIN, and other related approaches, provide a solution that can reduce that wait time down to mere hours, enabling equitable access to rapid CNS tumour classification for all patients, regardless of their location or circumstances. This has been demonstrated in our [academic publication](https://academic.oup.com/neuro-oncology/advance-article/doi/10.1093/neuonc/noaf103/8139084?searchresult=1) in Neuro-Oncology. + +This results in faster access to appropriate treatments and trials, reduces uncertainty for patients, families and clinicians, and would dramatically reduce the overall cost of care. + +We are working with clinicians and surgeons in the UK and beyond to make this a reality as soon as possible. + +## The Scale of the Challenge + +
+ +
+12,700 +New cases of brain, other CNS and intracranial tumours every year in the UK (2017-2019) +
+ +
+35 +People diagnosed every day +
+ +
+100+ +Different types of brain tumours, each requiring specific treatment approaches +
+ +
+ +*Source: [Cancer Research UK Brain, other CNS and intracranial tumours statistics](https://www.cancerresearchuk.org/health-professional/cancer-statistics/statistics-by-cancer-type/brain-other-cns-and-intracranial-tumours) (2017-2019)* + +## The Challenge + +Every year, thousands of patients in the UK undergo surgery for suspected brain tumours. The molecular classification of these tumours is crucial for determining the most effective treatment strategy. However, the current process of obtaining this vital information is far from ideal: + +- Patients and families endure weeks of anxiety waiting for results +- Treatment decisions are delayed, potentially impacting patient outcomes +- Additional surgical procedures may be required if initial molecular results are inconclusive +- Limited access to rapid classification creates inequalities in care delivery + +## Key Features + +
+ +
+### Rapid Results +Complete molecular profiling available within hours of surgery, enabling immediate treatment planning. +
+ +
+### Better Patient Experience +Reduced anxiety and uncertainty for patients and families by providing same-day results. +
+ +
+### Improved Care Delivery +Enable clinicians to make informed treatment decisions quickly, potentially improving patient outcomes. +
+ +
+ +## The Impact + +By providing rapid molecular profiling, ROBIN has the potential to transform the patient journey: + +- Same-day molecular diagnosis following surgery +- Immediate treatment planning and faster access to appropriate therapies +- Reduced need for additional surgical procedures +- Equal access to rapid classification across different healthcare settings +- Improved patient and family experience through reduced waiting times + +## Join Us in Transforming CNS Tumour Classification + +We're working to make rapid molecular classification the standard of care for all CNS tumour patients. By implementing ROBIN, healthcare providers can offer their patients: + +- Faster time to appropriate treatment +- Reduced anxiety during the diagnostic process +- More efficient use of healthcare resources +- Improved patient outcomes through rapid molecular classification + +## Getting Started + +If you're interested in implementing rapid molecular classification at your institution, please visit our [GitHub repository](https://github.com/LooseLab/robin) or get in touch via [this form](https://forms.gle/kdX2eiPQPdDUpaBE9). + +## Information for Patients and Families + +If you or a family member are concerned about symptoms that might indicate a brain tumour, we recommend: + +- Contact your GP immediately to discuss your symptoms +- Visit [Cancer Research UK's brain tumour information](https://www.cancerresearchuk.org/about-cancer/brain-tumours) for comprehensive guidance +- Access support through [The Brain Tumour Charity](https://www.thebraintumourcharity.org/) for support and information +- Connect with [brainstrust](https://www.brainstrust.org.uk/), a specialist brain tumour support charity +- Learn about research progress at [Brain Tumour Research](https://www.braintumourresearch.org/) +- Check [MyBrainFirst.org](https://www.mybrainfirst.org/) for information about brain tumor symptoms and awareness + +!!! note "Important Note" + Early diagnosis and access to appropriate care are crucial. While rapid molecular classification is still being implemented across healthcare settings, these organizations can provide immediate support, guidance, and the latest information about brain tumour diagnosis and treatment. + +--- + +ROBIN is developed by the Loose Lab at the University of Nottingham and supported by Nottingham University Hospitals NHS Trust. View the project on [GitHub](https://github.com/LooseLab/robin). diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..c11248c --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,403 @@ +/* + MkDocs Material overrides — aligned with design.md (Editorial Bioinformatics). + Typography: Inter (body), Manrope (headlines), JetBrains Mono (code — set in mkdocs.yml). + Brand: Emerald shell gradients; content on white / slate-zinc gradients; semantic accents. +*/ + +/* Manrope for headlines; Inter is loaded by Material (mkdocs.yml font.text) */ +@import url("https://fonts.googleapis.com/css2?family=Manrope:wght@700;800&display=swap"); + +/* ----- Design tokens (design.md §4, §6) ----- */ +:root { + --robin-emerald-400: #34d399; + --robin-emerald-500: #10b981; + --robin-emerald-600: #16a34a; + --robin-emerald-700: #15803d; + --robin-emerald-800: #065f46; + --robin-emerald-900: #064e3b; + --robin-slate-50: #f8fafc; + --robin-slate-200: #e2e8f0; + --robin-slate-500: #64748b; + --robin-slate-600: #475569; + --robin-slate-900: #0f172a; + --robin-zinc-950: #09090b; + --robin-amber-500: #f59e0b; + --robin-red-600: #dc2626; + --robin-rose-400: #fb7185; +} + +/* Light scheme — professional lab surfaces */ +[data-md-color-scheme="default"] { + --md-primary-fg-color: var(--robin-emerald-700); + --md-primary-fg-color--light: var(--robin-emerald-600); + --md-primary-fg-color--dark: var(--robin-emerald-800); + --md-accent-fg-color: var(--robin-emerald-600); + --md-typeset-a-color: var(--robin-emerald-700); + --md-default-bg-color: #ffffff; + --robin-content-fg: var(--robin-slate-900); + --robin-content-fg-muted: var(--robin-slate-600); +} + +/* Dark scheme — midnight analysis */ +[data-md-color-scheme="slate"] { + --md-primary-fg-color: var(--robin-emerald-800); + --md-primary-fg-color--light: var(--robin-emerald-600); + --md-primary-fg-color--dark: var(--robin-emerald-900); + --md-accent-fg-color: var(--robin-emerald-400); + --md-typeset-a-color: var(--robin-emerald-400); + --md-default-bg-color: var(--robin-zinc-950); + --robin-content-fg: #f8fafc; + --robin-content-fg-muted: #94a3b8; +} + +/* ----- App shell: header (design.md §4.1) ----- */ +.md-header { + background: linear-gradient( + 90deg, + var(--robin-emerald-700) 0%, + var(--robin-emerald-600) 100% + ); + border-bottom: 1px solid rgba(255, 255, 255, 0.22); + box-shadow: 0 1px 0 rgba(0, 0, 0, 0.06); +} + +[data-md-color-scheme="slate"] .md-header { + background: linear-gradient( + 90deg, + var(--robin-emerald-800) 0%, + var(--robin-emerald-700) 100% + ); + border-bottom-color: rgba(255, 255, 255, 0.12); +} + +.md-header__title, +.md-header__topic, +.md-header__button { + color: #ffffff !important; +} + +.md-header__button svg, +.md-header__button .md-ellipsis { + color: inherit; +} + +.md-search__input { + background-color: rgba(255, 255, 255, 0.12); + border: 1px solid rgba(255, 255, 255, 0.2); + color: #ffffff; +} + +.md-search__input::placeholder { + color: rgba(255, 255, 255, 0.65); +} + +/* Tabs under header — translucent strip */ +.md-tabs { + background: linear-gradient( + 90deg, + rgba(21, 128, 61, 0.92) 0%, + rgba(22, 163, 74, 0.92) 100% + ); + border-bottom: 1px solid rgba(255, 255, 255, 0.15); +} + +[data-md-color-scheme="slate"] .md-tabs { + background: linear-gradient( + 90deg, + rgba(6, 95, 70, 0.95) 0%, + rgba(4, 120, 87, 0.95) 100% + ); +} + +.md-tabs__link { + color: rgba(255, 255, 255, 0.92) !important; + font-weight: 500; + font-family: "Inter", system-ui, sans-serif; +} + +.md-tabs__link--active { + color: #ffffff !important; + border-bottom-color: rgba(255, 255, 255, 0.85) !important; +} + +/* ----- App shell: footer (design.md §4.2) — mirrored gradient ----- */ +.md-footer { + background: linear-gradient( + 90deg, + var(--robin-emerald-600) 0%, + var(--robin-emerald-700) 100% + ); + color: #ffffff; + border-top: 1px solid rgba(255, 255, 255, 0.18); +} + +[data-md-color-scheme="slate"] .md-footer { + background: linear-gradient( + 90deg, + var(--robin-emerald-700) 0%, + var(--robin-emerald-800) 100% + ); +} + +.md-footer-meta { + background: transparent; +} + +.md-footer a { + color: rgba(255, 255, 255, 0.95) !important; + border-bottom: none; + text-decoration: underline; + text-underline-offset: 2px; +} + +.md-footer a:hover { + color: #ffffff !important; +} + +/* ----- Main content: subtle editorial depth (design.md §3, §6) ----- */ +.md-main__inner { + background: linear-gradient( + 180deg, + var(--robin-slate-50) 0%, + #ffffff 28rem + ); +} + +[data-md-color-scheme="slate"] .md-main__inner { + background: linear-gradient( + 180deg, + #0c0c0f 0%, + var(--robin-zinc-950) 32rem + ); +} + +.md-content { + font-family: "Inter", system-ui, sans-serif; +} + +.md-typeset { + font-size: 0.95rem; + line-height: 1.65; + color: var(--robin-content-fg); +} + +.md-typeset h1, +.md-typeset h2, +.md-typeset h3 { + font-family: "Manrope", "Inter", system-ui, sans-serif; + font-weight: 800; + letter-spacing: -0.02em; + color: var(--robin-slate-900); +} + +[data-md-color-scheme="slate"] .md-typeset h1, +[data-md-color-scheme="slate"] .md-typeset h2, +[data-md-color-scheme="slate"] .md-typeset h3 { + color: var(--robin-content-fg); +} + +.md-typeset h2 { + font-weight: 700; + margin-top: 2.25rem; + padding-bottom: 0.35rem; + border-bottom: 1px solid var(--robin-slate-200); +} + +[data-md-color-scheme="slate"] .md-typeset h2 { + border-bottom-color: rgba(51, 65, 85, 0.6); +} + +/* Sidebar nav — Inter, clear hierarchy */ +.md-nav { + font-family: "Inter", system-ui, sans-serif; +} + +.md-nav__link--active { + font-weight: 600; + color: var(--robin-emerald-700) !important; +} + +[data-md-color-scheme="slate"] .md-nav__link--active { + color: var(--robin-emerald-400) !important; +} + +/* ----- Links (semantic emerald, not default Material green) ----- */ +.md-typeset a { + color: var(--md-typeset-a-color); + text-decoration: none; + border-bottom: 1px dotted currentColor; + transition: color 0.15s ease, border-color 0.15s ease; +} + +.md-typeset a:hover { + color: var(--robin-emerald-600); + border-bottom-style: solid; +} + +[data-md-color-scheme="slate"] .md-typeset a:hover { + color: var(--robin-emerald-400); +} + +/* ----- Code: JetBrains Mono from theme; tighten chrome ----- */ +.md-typeset code, +.md-typeset pre > code { + font-feature-settings: "liga" 0; +} + +.md-typeset pre { + border: 1px solid var(--robin-slate-200); + border-radius: 0.5rem; + box-shadow: 0 1px 2px rgba(15, 23, 42, 0.06); +} + +[data-md-color-scheme="slate"] .md-typeset pre { + border-color: rgba(51, 65, 85, 0.8); + box-shadow: none; +} + +/* ----- Tables (clinical density) ----- */ +.md-typeset table:not([class]) { + border: 1px solid var(--robin-slate-200); + border-radius: 0.5rem; + overflow: hidden; + box-shadow: 0 1px 2px rgba(15, 23, 42, 0.04); +} + +[data-md-color-scheme="slate"] .md-typeset table:not([class]) { + border-color: rgba(51, 65, 85, 0.7); +} + +.md-typeset table:not([class]) th { + background: var(--robin-slate-50); + font-weight: 600; + font-size: 0.8rem; + text-transform: uppercase; + letter-spacing: 0.06em; + color: var(--robin-slate-600); +} + +[data-md-color-scheme="slate"] .md-typeset table:not([class]) th { + background: rgba(30, 41, 59, 0.5); + color: #94a3b8; +} + +/* ----- Admonitions — semantic colours (design.md §5.1) ----- */ +.md-typeset .admonition.note, +.md-typeset details.note { + border-color: var(--robin-slate-200); + border-left-width: 4px; + border-left-color: var(--robin-emerald-600); +} + +.md-typeset .admonition.warning, +.md-typeset details.warning { + border-color: rgba(245, 158, 11, 0.45); + border-left-width: 4px; + border-left-color: var(--robin-amber-500); +} + +.md-typeset .warning > .admonition-title, +.md-typeset .warning > summary { + background-color: rgba(245, 158, 11, 0.1); +} + +.md-typeset .admonition.danger, +.md-typeset details.danger { + border-left-color: var(--robin-red-600); +} + +[data-md-color-scheme="slate"] .md-typeset .admonition.danger { + border-color: rgba(251, 113, 133, 0.4); +} + +/* ----- Home page grid cards (design.md §6.1 cards) ----- */ +.md-typeset .grid { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 1rem; + margin: 1.25rem 0; + max-width: 100%; + width: 100%; + box-sizing: border-box; +} + +@media (max-width: 900px) { + .md-typeset .grid { + grid-template-columns: 1fr; + } +} + +.md-typeset .grid-item { + background: #ffffff; + padding: 1.5rem; + border-radius: 0.5rem; + text-align: center; + border: 1px solid var(--robin-slate-200); + box-shadow: 0 1px 3px rgba(15, 23, 42, 0.06); + transition: box-shadow 0.2s ease, transform 0.2s ease; +} + +[data-md-color-scheme="slate"] .md-typeset .grid-item { + background: rgba(30, 41, 59, 0.45); + border-color: rgba(51, 65, 85, 0.65); + box-shadow: none; +} + +.md-typeset .grid-item:hover { + box-shadow: 0 4px 12px rgba(21, 128, 61, 0.12); + transform: translateY(-1px); +} + +[data-md-color-scheme="slate"] .md-typeset .grid-item:hover { + border-color: rgba(52, 211, 153, 0.25); + box-shadow: 0 0 0 1px rgba(52, 211, 153, 0.12); +} + +.md-typeset .grid-item h3 { + font-family: "Manrope", "Inter", sans-serif; + font-size: 1.15rem; + font-weight: 800; + color: var(--robin-emerald-700); + margin-bottom: 0.5rem; + line-height: 1.25; +} + +[data-md-color-scheme="slate"] .md-typeset .grid-item h3 { + color: var(--robin-emerald-400); +} + +.md-typeset .stat-number { + display: block; + font-family: "Manrope", "Inter", sans-serif; + font-size: 2.35rem; + font-weight: 800; + color: var(--robin-emerald-700); + margin-bottom: 0.5rem; + letter-spacing: -0.03em; +} + +[data-md-color-scheme="slate"] .md-typeset .stat-number { + color: var(--robin-emerald-400); + text-shadow: 0 0 24px rgba(52, 211, 153, 0.15); +} + +/* ----- Logo ----- */ +.md-header__button.md-logo img { + height: 2rem; + filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.15)); +} + +/* ----- Secondary / attribution text ----- */ +.md-typeset em { + color: var(--robin-slate-600); + font-style: normal; + font-size: 0.88rem; +} + +[data-md-color-scheme="slate"] .md-typeset em { + color: var(--robin-content-fg-muted); +} + +.md-typeset ul li { + margin-bottom: 0.5rem; +} diff --git a/docs/using-robin/authentication-and-layout.md b/docs/using-robin/authentication-and-layout.md new file mode 100644 index 0000000..1bbd3e9 --- /dev/null +++ b/docs/using-robin/authentication-and-layout.md @@ -0,0 +1,64 @@ +# First steps and navigation + +## Opening ROBIN + +Paste the address you were given into your browser’s address bar. It usually looks like `http://127.0.0.1:8081` or `http://localhost:8081`. If ROBIN runs on another machine, use the address your administrator provided (it may use a **host name** and **port**). + +If nothing loads, see [Troubleshooting — I can’t open the page](troubleshooting.md#i-cant-open-the-page). + +## Signing in + +If your team enabled password protection, you’ll see a **Sign in** page with the ROBIN name and a short message: **Enter password to continue.** The screen includes the green header (**R.O.B.I.N**, menu, logo), the **Sign in** card with a lock icon, the **Password** field, the green **Log in** button, and the footer (**Links**, info, copyright). + +![ROBIN web sign-in: header, Sign in card with password field and Log in button, footer](../images/login.png) + +- Type the password your team uses for the web interface (often the same one set when ROBIN first asked for a **GUI password** in the terminal). +- Press **Log in** or Enter. + +After a successful sign-in, ROBIN takes you to the page you originally tried to open, or to the **Welcome** home page. + +## What’s at the top of every screen + +- **Menu (☰)** on the left — opens the main navigation (see below). +- **Title** — the full ROBIN name on large screens, or **R.O.B.I.N** on a phone. +- **Viewing:** … — shows which computer the browser is talking to. +- **CPU** and **RAM** — small gauges for a quick sense of load (they are **not** a full system monitor). +- **Logo** — ROBIN branding on the right. + +## Main menu (☰) + +Use these entries to jump around the app: + +| What you want to do | Choose | +|----------------------|--------| +| Go back to the home page | **Home** | +| See all samples in a table | **View Samples** | +| Build a new library ID from a test ID and optional details | **Generate Sample ID** | +| Add or remove folders that ROBIN should watch for new BAM files | **Watched Folders** *(may require your pipeline to be running in a specific mode—see the tour page)* | +| See whether the workflow is running and how jobs are progressing | **Activity Monitor** | +| Open published documentation in a new tab | **Documentation** | +| Make the whole app easier on the eyes at night | **Dark Mode** (toggle) | +| Allow remote access (advanced; your admin may use this) | **Allow Remote Access** | +| Leave the web session | **LOG OUT** | +| Fully quit ROBIN on this machine *(only on some setups)* | **Quit** — read the warning first; closing the **browser tab** often leaves analysis running, while **Quit** can stop it. | + +!!! tip "Which “workflow” button?" + Some menus list **Workflow** as a separate item. In the standard setup started from `robin workflow`, use **Activity Monitor** to see pipeline status and progress. If **Workflow** does nothing or shows an error, stick with **Activity Monitor**. + +**Close** simply closes the menu. + +## Footer: Links and info + +At the bottom you’ll find **Links** — a panel with shortcuts to GitHub, key papers, the lab protocol, Oxford Nanopore, and related sites. Use **Info** if your build shows extra footer help. + +## Quit vs closing the browser + +If you see **Quit R.O.B.I.N?**, read the text carefully: + +- **Cancel** — closes the dialog; analysis may continue. +- **Really quit** — can stop analysis on that machine. +- You can often **close the browser tab** and leave ROBIN running in the background—when in doubt, ask whoever operates the sequencer or server. + +## Next + +[Tour of the screens](pages-and-routes.md) walks through each page and what the buttons do. diff --git a/docs/using-robin/index.md b/docs/using-robin/index.md new file mode 100644 index 0000000..c096fd3 --- /dev/null +++ b/docs/using-robin/index.md @@ -0,0 +1,30 @@ +# Using ROBIN + +Welcome. This guide is for **anyone using the ROBIN web app in a browser**—whether you are new to the tool or only need a reminder of where things live. + +ROBIN’s interface shows how your sequencing run is progressing and surfaces **classification**, **coverage**, **CNV**, **MGMT**, **fusion**, and other results as they become available. You do **not** need to read code or command-line manuals to follow this guide; we link to technical docs only where it helps. + +## Before you start + +1. **ROBIN must already be running** on your computer or server (someone usually starts it with `robin workflow` from a terminal). When it starts, it prints a **web address**—for example `http://127.0.0.1:8081`. Open that address in **Chrome, Edge, Firefox, or Safari**. +2. You may be asked for a **password** in the browser or in the terminal first—see [First steps and navigation](authentication-and-layout.md). +3. The window title will show **ROBIN** so you can find the tab easily. + +## What you’ll learn here + +| Guide | You’ll learn how to… | +|-------|----------------------| +| [First steps and navigation](authentication-and-layout.md) | Sign in, use the menu, turn on **Dark mode**, find **Links** and **Log out**, and understand the top bar (CPU/RAM). | +| [Tour of the screens](pages-and-routes.md) | Move from the **Welcome** page to **samples**, the **workflow monitor**, **watched folders**, and the **sample ID** helper. | +| [Reading your results](sample-results.md) | Read the **Run summary**, **Classification**, **Analysis**, and **reports** on a sample page. | +| [Troubleshooting](troubleshooting.md) | Fix common problems (can’t connect, wrong sample, dark mode, reports). | + +## A simple workflow + +1. Open the link you were given → land on **Welcome** (or sign in first). +2. Open **View Samples** (or **View All Samples**) → click **View** on the row for your **library / sample** to open it. +3. Scroll through **Run summary**, then **Classification details**, then **Analysis details** as numbers appear. +4. Use **Generate report** when you need a **PDF** (and optional data export if your team enabled it). +5. To see overall pipeline health, open **Activity Monitor** from the menu. + +When you’re ready for installation, startup prompts, or command-line options, see [Quickstart](../getting-started/quickstart.md) and [What happens at startup](../getting-started/startup.md). diff --git a/docs/using-robin/pages-and-routes.md b/docs/using-robin/pages-and-routes.md new file mode 100644 index 0000000..cec3038 --- /dev/null +++ b/docs/using-robin/pages-and-routes.md @@ -0,0 +1,158 @@ +# Tour of the screens + +This page walks through **what you see** and **where to click**, in the order most people use during a run. Technical paths (for bookmarks or IT) are noted in *italics* at the end of each section. + +--- + +## Welcome (home) + +**What it is:** The landing page after you sign in. It introduces ROBIN in plain language and explains that it analyses nanopore BAM data in real time. + +![Welcome to R.O.B.I.N: welcome card, What is R.O.B.I.N, action buttons, and ROBIN News](../images/welcome.png) + +**What to do here:** + +- **View All Samples** — opens the big table of runs (see below). +- **Open Workflow Monitor** — opens the **Activity Monitor** view so you can see whether the pipeline is busy and how far it has progressed. +- **Manage watched folders** — for advanced users who need to add or remove input folders (see **Watched folders**). +- **Generate Sample ID** — opens a small form to create a **library ID** from a test ID and optional patient fields. +- **View Documentation** — opens the public documentation site in a new tab. + +You may also see a **News** area with updates from the team. + +*Bookmark path: home is the site root, e.g. `http://your-server:8081/`.* + +--- + +## All samples (sample list) + +**What it is:** A searchable table of **every sample** ROBIN is tracking—your main hub for finding a run. The browser title may read **Sample Tracking Overview**. + +![Sample Tracking Overview: filters, All tracked samples table, job progress, and actions](../images/AllSamples.png) + +*Example only: the library IDs in this screenshot are anonymised samples from a quality-control exercise; your own list will show your runs.* + +**What you’ll see:** + +- A short intro: *Tracked nanopore runs and workflow state in one place…* +- A heading **All tracked samples** and a legend such as **A=Active P=Pending T=Total C=Completed F=Failed** so you can read the status columns. +- Buttons like **Select all** / **Clear selection** if you need to run bulk actions (your team may use these for SNP or other batch jobs). +- In **Actions**, click **View** to open that sample’s **detail page** (clicking elsewhere on the row does not open it). + +If a sample never appears, check that MinKNOW is writing BAMs where ROBIN expects them and that the run has started—your bioinformatics contact can confirm. + +*Bookmark path: `/live_data`.* + +--- + +## Activity Monitor (workflow monitor) + +**What it is:** A dashboard for **overall pipeline health**: whether work is running, how long it has been up, and counts of completed or failed jobs. The browser title may read **Workflow Monitor**. + +![Workflow Monitor: workflow status, file processing, queue status, active jobs, and live logs](../images/Activity.png) + +**What you’ll see:** + +- **Workflow monitor** with the subtitle *Real-time workflow monitoring and control.* +- A **Workflow status** card with a status line (for example “Running”), **Started** and **Duration**, a **progress** bar, and **Run counts** (such as completed / failed / skipped). +- **File processing** — overall and per-sample progress when files are being handled. +- **Queue status** — counts for preprocessing, analysis, classification, and other queues. +- **Active jobs** — a searchable table of jobs when work is running (it can show “no data” when idle). +- **Live logs** — scrollable output with **Clear** and **Export** for monitoring or sharing with support. + +Use this when you want a quick “is ROBIN still working?” answer without opening a specific sample. + +*Bookmark path: `/robin`.* + +--- + +## One sample (detail page) + +**What it is:** The page for a **single library ID**—this is where **Run summary**, **Classification details**, **Analysis details**, optional **MNP-Flex** results, and **reports** appear. Deeper tools on a follow-on screen (`/details`) are shown in [Sample details (extra tools)](#sample-details-extra-tools) below. + +Open it from **All tracked samples** by clicking **View** on the row you want. That opens this **sample** page (`/live_data/`), not the **Workflow Monitor** (`/robin`); the monitor is described in [Activity Monitor](#activity-monitor-workflow-monitor) above. + +**`OneSample.png`:** this repo image is another capture of the **Workflow Monitor** (`/robin`)—the same layout as `Activity.png`—not the `/live_data/` page after **View**. The main sample screen is covered in [Reading your results](sample-results.md). + +![Workflow Monitor (`OneSample.png`): status, queues, active jobs, and live logs](../images/OneSample.png) + +If ROBIN doesn’t recognise an ID yet, you may see **Unknown sample** and a short message that the library hasn’t been seen this session; the app will send you back to the list after a few seconds, or you can use **Back to samples**. + +**Full walkthrough:** [Reading your results](sample-results.md). + +*Bookmark pattern: `/live_data/`.* + +--- + +## Sample details (extra tools) + +**What it is:** A secondary page with **deeper tools** for that sample: where files live on disk, links into **IGV**, **sample identifiers**, **SNP** tables, **fusion** pairs, and **target genes**, depending on your configuration. + +![Sample details page: extra tools, tables, and paths for one library](../images/SampleDetails.png) + +*Example only: any sample IDs or paths in this screenshot are from anonymised quality-control data; your page will reflect your run and configuration.* + +Use **Back to sample** to return to the main sample page. + +**What’s on the page:** step-by-step description of each block (paths, IGV, SNP, fusion pairs, target genes) is in [Reading your results → Sample details page](sample-results.md#sample-details-page-extra-tools). + +*Bookmark pattern: `/live_data//details`.* + +--- + +## Watched folders + +**What it is:** Lets you **add or remove directories** that contain BAM files so ROBIN can watch them for new data. The browser title may read **Watched Folders**. + +![Watched folders: currently watched paths, Remove, Add folder with Browse, and work directory](../images/WatchedFolders.png) + +*Example only: folder and work-directory paths in this screenshot are from a development machine; yours will match your deployment.* + +**What you’ll see:** + +- **Currently watched** — each path with **Remove** to stop watching it. +- **Add folder** — type a path or use **Browse**, then **Add folder**. +- **Work directory** — where ROBIN is using as the main output/work area (read-only context on this screen). + +**Note:** On some setups this only works when ROBIN was started in a mode that supports folder management. If you see a message that **Ray** or the workflow is required, ask your administrator—this is not something most clinical users change during a run. + +*Bookmark path: `/watched_folders`.* + +--- + +## Sample ID generator + +**What it is:** A form to build a **sample identifier** from: + +- **Test ID** (required) +- Optional: first name, last name, date of birth, hospital number + +**Use the same value in MinKNOW:** After you **Generate sample ID**, copy that **Sample ID (MD5)** and enter it as the **sample ID** for your sequencing run in **MinKNOW** (the field used to name the library and outputs). ROBIN expects BAMs and folders to use this identifier, so it can **match** the run to the manifest and tracking list **automatically**. Do not invent a different ID in MinKNOW if you already generated one here—use the **generated** ID verbatim. + +The browser title may read **Generate Sample Identifier**. + +![Sample ID generator: fields, generated MD5 identifier, Generate and Copy](../images/GenerateSampleID.png) + +**What you’ll see:** + +- Short help text explaining required vs optional fields. +- **Generate sample ID** — computes the identifier and fills the **Sample ID (MD5)** field. +- **Copy to clipboard** — copies the generated ID when one exists. + +**How it works:** + +1. **Identifier string** — ROBIN builds a single line by joining, in order, **Test ID**, **First name**, **Last name**, and **Date of birth**, separated by **pipe characters** (`|`). Any optional field you leave blank is treated as an empty string between the pipes. The date of birth is formatted as **YYYY-MM-DD** when you pick a date. +2. **MD5 hash** — The **Sample ID** is the **MD5** digest (hexadecimal) of that UTF-8 string. It is **deterministic**: the same inputs always produce the same ID. +3. **Hospital number** — This is **not** included in the MD5 string. It is stored separately when ROBIN writes a **sample identifier manifest** next to your sample output (see below). +4. **After generating** — If a **work directory** is configured, ROBIN creates a folder named with the new **sample ID** and writes a small manifest file there: **Test ID** is stored in plain text; **first name**, **last name**, **date of birth**, and **hospital number** (if provided) are stored **encrypted** so they can be recovered in a controlled way. If no work directory is set, you still get the MD5 ID, but the manifest step may not run—watch the on-screen notification. + +Use this when your lab’s workflow expects a consistent naming scheme before or during a run. + +*Bookmark path: `/sample_id_generator`.* + +--- + +## Next + +- [Reading your results](sample-results.md) — understand each block on the sample page. +- [Troubleshooting](troubleshooting.md) — if something doesn’t look right. diff --git a/docs/using-robin/sample-results.md b/docs/using-robin/sample-results.md new file mode 100644 index 0000000..ffca733 --- /dev/null +++ b/docs/using-robin/sample-results.md @@ -0,0 +1,263 @@ +# Reading your results + +This page explains **what each part of a sample page means** when you open a library from **All tracked samples** (use **View** on that row). The exact charts and numbers depend on which analyses your team enabled and how far the run has progressed. For a screenshot of the tracking table (with anonymised quality-control examples), see [All samples](pages-and-routes.md#all-samples-sample-list) in the tour. + +![Sample page: library header and actions, Run summary tiles, Classification details, Analysis details](../images/RunSummary.png) + +*Example only: the library ID and metrics in this screenshot are from anonymised quality-control data; your page will reflect your run.* + +--- + +## What you’ll see first: Run summary + +**Run summary** is a block of **tiles** at the top—think of it as a **run card** for the sequencer: + +- When the run started and how long it ran +- Which **device** and **flow cell** were used +- **Kit**, **basecalling** settings, and other technical metadata + +Use it to confirm you’re looking at the **right run** and **right patient** before you interpret biology below. + +Long values (e.g. a full basecall model name) may wrap across the full width so nothing is cut off. + +--- + +## Classification details + +**Classification details** shows how different **classifiers** (for example Sturgeon, NanoDX, PanNanoDX, Random Forest) rank possible tumour classes or methylation-based groups. + +**How to read it:** + +- Each **card** gives a **main call** and a **confidence** level (often with a coloured bar). +- **Higher confidence** usually means the model is more certain—but all results still need **clinical interpretation** by your team. +- **Click a card** to jump to the **expanded section** below with **charts** (bar charts of top classes, and sometimes confidence over time). +- Reference lines on charts may be labelled **Medium** and **High** to match your lab’s reporting thresholds. + +Not every classifier appears for every run; it depends on your pipeline settings. + +--- + +## Analysis details + +**Analysis details** summarises **coverage**, **copy number (CNV)**, **MGMT methylation**, and **fusion** candidates in a **row of cards**. + +**How to use it:** + +- Skim the **headline** on each card (depth, CNV status, MGMT level, fusion counts). +- **Click a card** to scroll to the **longer section** below with plots and tables for that topic. +- **Coverage** — whether targets are sequenced deeply enough; your lab may use coloured bands or thresholds (e.g. sufficient vs low). +- **CNV** — gains and losses; plots are for **visual review**—CNV calls are often heuristic. +- **MGMT** — methylation at the MGMT promoter region; interpretation depends on your clinical protocol. +- **Fusion** — candidate gene fusions; follow-up may use tables or genome views. + +--- + +## Detailed results (full sections) + +Below the **Classification details** and **Analysis details** cards, the sample page continues with larger blocks—each tied to the **same topic** as the card above. Your workflow may hide some blocks entirely. + +### Classification + +The heading **Classification** groups **Sturgeon**, **NanoDX**, **PanNanoDX**, and **Random Forest** in separate **expandable rows** (click to open). + +![Classification section: summary row, expanded Sturgeon with top-classes bar chart and confidence over time](../images/Classification.png) + +*Example only: calls and charts are from anonymised quality-control data.* + +- **Inside each tool:** a short **summary** (top call, confidence, probe or feature count where shown), then **charts**—typically a **bar chart of top classes** and, where available, **confidence over time** with **Medium** / **High** reference lines. +- Use this area when you need **more than the dashboard card** shows: full class rankings and how stable the call was as the run progressed. +- Which tools appear depends on your pipeline configuration. + +### Coverage + +The **Coverage** block starts with **Coverage Analysis**: an overall **quality** label plus **global** estimated coverage, **targets** estimated coverage, and **enrichment** (how much reads concentrate on targets vs genome-wide). + +Further down you will usually find: + +- **Per chromosome target coverage** — a chart comparing **on-target** vs **off-target** depth by chromosome. +- **Coverage over time** — **cumulative** estimated depth (×) as the run advances. +- **Target coverage over time** — mean target depth over time, with **outlier** highlighting (values beyond about **two standard deviations** from the mean per gene, as described on screen). + +Use this section to judge whether sequencing depth is **adequate overall** and whether any time window or gene looks **anomalously low or high**. + +### Target coverage + +**Target coverage** is the **gene- and region-level** view for your **panel** (for example rCNS2, AML, PanCan—whatever your run used). You should see the **panel name**, a note that targets come from the **gene panel BED**, and often an **info** expansion with panel and BED file details. + +![Target coverage: per-chromosome distribution with outliers and searchable targets table](../images/TargetCoverage.png) + +*Example only: panel and gene labels are from anonymised quality-control data.* + +**Gene amplifications:** this section is a good place to notice **suspected amplifications**—genes such as **MYC** or **EGFR** (when on your panel) may show up as **high-coverage outliers** on the per-chromosome plot (often **labelled** on the chart) and/or in the table’s **outlier** column (e.g. flagged relative to mean ± 2 SD). Treat these as **leads** to review alongside the **Copy number (CNV)** section and your lab’s clinical rules; unusually high target depth alone is **not** necessarily proof of amplification. + +Typical contents include: + +- **Per-chromosome** and **per-gene** views (including scatter, box-style, or bar plots of depth by region). +- A **searchable table** of targets with coordinates, coverage (×), and outlier flags. +- **Coverage distribution by gene** and any **threshold** bands your site uses to label sufficient vs low coverage. + +Use it when you need **which genes or regions** drove the headline coverage number, not just the genome-wide average. + +### MGMT methylation + +**MGMT methylation** focuses on the **MGMT promoter** on chromosome 10. + +![MGMT methylation: promoter summary, locus plot, latest results, and per-CpG table](../images/MGMT.png) + +*Example only: percentages and status are from anonymised quality-control data.* + +- **Promoter summary** — **status** (for example methylated vs unmethylated), **average methylation** (%), **prediction score** where shown, and a short note that results come from **per-site** data. +- **Locus visualization** — a plot of methylation along the promoter region. +- Often a **table** of individual **CpG** sites with strand-specific coverage. + +Interpretation is **protocol-specific**; treat this as supporting information alongside pathology and other assays. + +### Copy number (CNV) + +The UI uses the heading **Copy number (CNV)** for genome-wide copy-number views. + +**Default (genome-wide):** with **Chromosome** and **Gene** set to **All**, you see the full genome on the **CNV scatter** (ploidy) and **difference** (relative) plots, plus sliders to pan and zoom. The **CNV events** table below lists segments (gain/loss, arms or whole chromosomes, affected genes, confidence). + +![Copy number (CNV): default genome-wide scatter and difference plots, events summary](../images/CopyNumber.png) + +*Example only: events and gene names are from anonymised quality-control data.* + +**Plot bin:** the **Plot bin** menu (for example **Data default**, **500 kb**, **1 Mb**, …) **re-bins** the points used for plotting. Choosing a **larger** bin (such as **1 Mb**) often **smooths** noisy regions so **gains and losses** are easier to see at a glance; a **finer** bin can show more detail when you need it. Try a few settings while reviewing the same sample. + +![Copy number (CNV): same profile with plot bin set to 1 Mb for clearer smoothing](../images/CopyNumber1Mb.png) + +*Example: 1 Mb plot bin for visual inspection; your run may differ.* + +**Single chromosome:** set **Chromosome** to one chromosome (for example **chr8**) to fill the plots with that chromosome only—**cytobands** and position on the X-axis make it easier to relate calls to **bands** and genes. Turn **Breakpoints** to **Show** when you want vertical guides at called **breakpoints** on the difference track. + +![Copy number (CNV): chromosome 8 only with breakpoints visible](../images/CopyNumberChr8.png) + +*Example: focused chr8 view; anonymised QC data.* + +**Also on screen:** + +- **Genome-wide profile** card — **genetic sex**, **bin width**, **variance**, and **gained** / **lost** counts (aligned with the dashboard card). +- **Controls** — **Colour by** chromosome vs up/down, **linear** or **log** Y-axis, **Plot bin**, **Breakpoints** show/hide when available. +- **Main plots** — **CNV scatter** (ploidy) and **difference** (relative deviation) share genomic position; use together with the **events** table. + +CNV here is for **rapid visual screening**; it is **not** a replacement for certified copy-number assays or expert review. + +### Fusion analysis + +**Fusion analysis** summarises candidates from reads with **supplementary alignments** (split mappings suggestive of rearrangements). + +- **Candidate summary** — counts for **target panel** vs **genome-wide** pairs and groups. +- **Target panel** — tables (and often plots) restricted to fusions involving your **assay panel**. +- **Genome-wide** — broader fusion calls outside the panel, if configured. + +Use the tables to inspect **gene pairs**, support, and grouping; follow your lab’s rules for **confirming** interesting events. + +--- + +## Sample details page (extra tools) + +This is a **separate URL** from the main sample dashboard: `/live_data//details`. Open it from **More details** on the main sample page (when shown) or via the [tour → Sample details](pages-and-routes.md#sample-details-extra-tools). The page focuses on **disk paths**, **IGV**, **identifiers**, and **tabular** SNP / fusion / target-gene views—not the large classification and analysis storyboards on `/live_data/`. + +### Page header + +- **Sample details** heading with **library ID**; **Test ID** appears when ROBIN can read it from the sample’s **identifier manifest** on disk. +- Intro line listing **IGV**, **sample identifiers**, **SNP** tables, **fusion pairs**, and **target genes**. +- **View sample identifiers** — opens a modal with manifest-derived identifier fields (where configured). +- **Back to sample** — returns to the main sample page (`/live_data/`). + +### Output location + +- **Sample output directory** — full server path to this library’s folder under the ROBIN work directory; status shows **Directory found** or **not found** (with the expected path if missing). + +### Analysis center + +- On some installs, an **Analysis center** / **Deployment** card shows which ROBIN **center** or deployment label the browser session is using. + +### IGV browser + +- Embedded **IGV.js** genome browser (**Genome: hg38**): ruler, ideogram, reference sequence, gene annotations, coverage histogram, and read alignments. +- **target.bam** must exist in the sample output folder for ROBIN to build the interactive viewer; otherwise you see **IGV requires target.bam** and a reminder to run **target analysis** first. When tracks load, ROBIN uses **target-scoped** indexed BAMs—typically **`target.bam`**, or (when present) files such as **`sorted_targets_exceeding.bam`** / **`sorted_targets_exceeding_rerun.bam`** under **`clair3/`**, or **`igv_ready.bam`** under **`igv/`**. **Only alignments from those target-region BAMs are shown**—this is **not** a whole-genome alignment view. +- **SNP table**, **indel table** (when present), and **fusion pairs** table each offer **View in IGV** and/or **row clicks** that **move the browser** to the variant, indel, or fusion breakpoints so you can **inspect pileups** in the loaded BAM. The **Target genes** table does the same for each gene interval. + +![IGV browser: hg38 tracks and alignments at a locus opened from the SNP table (View in IGV)](../images/IGVview.png) + +*Example only: coordinates, gene, and BAM file name are from anonymised quality-control data.* + +### SNP analysis + +- Appears when SNP processing has written **`clair3/snpsift_output_display.json`**. +- **Summary** text may include total variants and counts of **pathogenic** variants. +- **Filters:** **PASS only** (keep rows with `FILTER` = PASS), **Pathogenic only**, optional **Min QUAL**, and **Reset** to clear filters. A **search** box filters the visible rows. The footer may show how many variants match (e.g. “Showing *n* of *N*”). +- The **table** lists columns such as chromosome, position, **REF** / **ALT**, gene, **HGVS.p**, annotation, annotation impact, **ClinVar** significance (**CLNSIG**), **FILTER**, **QUAL**, genotype (**GT**), whether the row is **pathogenic**, **Details** (expand full fields), and **View in IGV**. + +![SNP analysis: PASS only and Pathogenic only enabled, filtered table and summary counts](../images/SNPexample.png) + +*Example only: variant shown is from anonymised quality-control data; your counts and rows will differ.* + +- **View in IGV** centres the embedded **IGV browser** (above on the page) on that variant for **pileup review**. +- A separate **indel** table may appear when indel display rows exist, with the same filters; **View in IGV** there jumps the browser to the indel locus in the **same target-scoped BAM**. +- If SNP analysis has not finished or the JSON is missing, you see a short **data not found** message instead of the table. + +### Fusion pairs + +- Built from processed fusion pickles (**`fusion_candidates_master_processed.pkl`** for the panel first, otherwise **`fusion_candidates_all_processed.pkl`** for genome-wide data). +- **Table:** fusion pair name, both chromosomes, **breakpoint** coordinates, **supporting reads**, and **View in IGV**. **Click a row** or the action icon to jump the **IGV browser** to both breakpoint neighbourhoods (with padding) so you can **inspect supporting reads** in the **target BAM** (same embedded view as SNPs/indels). +- Footer text may show **total fusions** and **total supporting reads**. Empty or missing data shows a clear **no pairs** / **run fusion first** style message. + +### Target genes + +- Data comes from **`target_coverage.csv`** if present, else **`bed_coverage_main.csv`**. +- **Table:** gene name, chromosome, start, end, **coverage (×)** with colour **badges** by depth band, optional **search**, sortable columns, and **View in IGV**. **Click a row** to open that gene’s interval in IGV (with padding). +- If neither file exists, this block is omitted. + +Sections appear **only when** the underlying files exist and your **workflow** enables the relevant steps. + +--- + +## MNP-Flex (if your site uses it) + +**MNP-Flex** is provided commercially by **[Heidelberg Epignostix GmbH](https://epignostix.com/)**. You can only use it under an **agreement with Epignostix**; they supply the **account credentials** ROBIN needs to call their service. + +Some sites show an **MNP-Flex results** block in the sample page. It may include: + +- When results were last updated +- **Classifier** name and version +- A **hierarchical summary** (class / family / superfamily) and **quality** or **MGMT** side panels + +![MNP-Flex results: toolbar, classifier line, hierarchical summary, QC, and MGMT](../images/MNPFlex.png) + +*Example of a successful test output: classifier metadata, hierarchy scores, QC status, and MGMT; your run will show its own values.* + +A toolbar may show whether the integration is **idle**, **busy**, or **running**. If you never see this block, your deployment may not use MNP-Flex, or credentials may not be configured. + +**Applying your Epignostix credentials in ROBIN:** The ROBIN process that runs the workflow and web UI reads **environment variables** on the **server** (not in the browser). Set the username and password Epignostix gave you before starting ROBIN, for example: + +- **`MNPFLEX_USERNAME`** — your Epignostix user name +- **`MNPFLEX_PASSWORD`** — your Epignostix password + +If either variable is missing, ROBIN does not show the MNP-Flex block and will not run the integration. + +How you set them depends on your setup: typically export them in the shell before `robin …` - whoever operates the sequencing machine or server should make them **persistent** and **secure** (never commit them to git). + +Your administrator may also tune optional settings (for example **`MNPFLEX_BASE_URL`**, **`MNPFLEX_WORKFLOW_ID`**, OAuth **`MNPFLEX_CLIENT_ID`** / **`MNPFLEX_CLIENT_SECRET`**, **`MNPFLEX_SCOPE`**) if Epignostix instructs you to; defaults match the standard Epignostix app integration. + +--- + +## Reports and downloads + +When analysis is far enough along, you can usually **generate a PDF report** for the sample. The file name is typically based on the **sample ID** and is saved under that sample’s output folder. + +Your team may also offer **CSV** or **ZIP** exports of **tabular data**—if enabled, follow the on-screen options and wait for notifications to finish before closing the tab. + +If a download fails, check the **notification** area and ask your administrator to confirm disk space and permissions. + +--- + +## Important reminder + +ROBIN is for **research use** and **support** to clinical decision-making. **Classification**, **CNV**, and **fusion** outputs are **not** a substitute for full pathological and molecular review by qualified staff. + +## See also + +- [Tour of the screens](pages-and-routes.md) +- [Troubleshooting](troubleshooting.md) diff --git a/docs/using-robin/troubleshooting.md b/docs/using-robin/troubleshooting.md new file mode 100644 index 0000000..02a76e3 --- /dev/null +++ b/docs/using-robin/troubleshooting.md @@ -0,0 +1,61 @@ +# Troubleshooting + +## I can’t open the page + +- **Check the address** — copy it exactly from the terminal or the note your administrator gave you (`http://…` and the correct **port**, often `8081`). +- **Same network** — if ROBIN runs on another computer, you may need to be on the hospital network or VPN. +- **Firewall** — IT may need to allow the port through. +- **Workflow still running** — ROBIN only serves the web UI while the `robin workflow` process is active. If someone stopped it, restart the workflow or ask your admin. +- **Work directory** — in some setups the main browser dashboard only appears if the workflow was started with an output **work directory** set; see [What happens at startup](../getting-started/startup.md). + +--- + +## I can’t sign in + +- Use the **same password** your team agreed for the web browser (often set the first time ROBIN asked for a **GUI password** in the terminal). +- **Caps Lock** off; try again after a short delay. +- If you never set a password, run ROBIN **from a terminal** once so it can prompt you—see [At startup](../getting-started/startup.md). +- Ask your administrator to **reset** or **re-set** the password if needed (`robin password set`). + +--- + +## It says “Unknown sample” + +ROBIN only knows about samples it has **seen in this session** (or that are already in its tracking list). If you opened a link with the wrong ID, or data hasn’t arrived yet: + +- Wait for **BAM files** to appear in the watched folder. +- Go back to **All samples** and click **View** on the correct row in the **table**. +- Confirm the **library ID** matches MinKNOW. + +--- + +## “Watched folders” says something about Ray or the workflow + +That page is for **adding or removing input folders**. It only works when ROBIN was started in a configuration that supports it. **Clinical users** rarely need this during a run—ask your bioinformatics team if you see an error here. + +--- + +## Dark mode looks wrong + +Toggle **Dark Mode** in the menu off and on. If a **chart** still looks wrong, **refresh the page** or leave the sample and open it again—plots sometimes catch up after a moment. + +--- + +## The “Workflow” menu item doesn’t work + +Use **Activity Monitor** instead. That’s the **workflow monitor** screen in the standard setup. + +--- + +## Report or download failed + +- Wait for any **spinner** or **notification** to finish. +- Try again; large PDFs can take a minute. +- Ask your admin to check that the **output folder** has space and that you have **permission** to write there. + +--- + +## Still stuck + +- [README — Common issues](https://github.com/LooseLab/littlejohn/blob/main/README.md#common-issues) +- [Command-line reference](../cli/index.md) (for staff who run ROBIN) diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..0d0b951 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,90 @@ +site_name: ROBIN +site_description: Rapid nanopore brain intraoperative classification +site_author: Matt Loose +# GitHub Pages project URL = https://.github.io// +# Must match the repo that runs Actions (here: LittleJohn test docs, not production ROBIN). +site_url: https://looselab.github.io/LittleJohn/ +repo_url: https://github.com/looselab/LittleJohn +repo_name: looselab/LittleJohn + +theme: + name: material + features: + - navigation.tabs + - navigation.sections + - navigation.expand + - search.highlight + - search.share + - content.code.copy + palette: + # Editorial Bioinformatics (design.md): emerald shell, slate content in dark mode + - scheme: default + primary: custom + accent: custom + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: custom + accent: custom + toggle: + icon: material/brightness-4 + name: Switch to light mode + logo: images/ROBIN_logo_small.png + favicon: images/ROBIN_logo_small.png + font: + text: Inter + code: JetBrains Mono + +extra_css: + - stylesheets/extra.css + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - admonition + - footnotes + - toc: + permalink: true + - pymdownx.arithmatex: + generic: true + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + - attr_list + - md_in_html + +plugins: + - search + - minify: + minify_html: true + +nav: + - Home: index.md + - Getting Started: + - Installation: getting-started/installation.md + - ROBIN Quickstart: getting-started/quickstart.md + - At startup (disclaimer, GUI, password): getting-started/startup.md + - Library Preparation: getting-started/library-preparation.md + - MinKNOW Configuration: getting-started/minknow-configuration.md + - Command-line reference: + - Overview: cli/index.md + - workflow command: cli/workflow.md + - Job types: cli/jobs.md + - Panel commands: cli/panels.md + - Utilities (utils): cli/utils.md + - GUI password: cli/password.md + - Using ROBIN: + - Overview: using-robin/index.md + - First steps and navigation: using-robin/authentication-and-layout.md + - Tour of the screens: using-robin/pages-and-routes.md + - Reading your results: using-robin/sample-results.md + - Troubleshooting: using-robin/troubleshooting.md \ No newline at end of file diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..60e3342 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,3 @@ +# MkDocs site (GitHub Pages). Install: pip install -r requirements-docs.txt +mkdocs-material>=9.5,<10 +mkdocs-minify-plugin>=0.8