# ONT Ecosystem CLI Reference

> Auto-generated by `ont_docgen.py cli` - v3.0.0

This document provides a comprehensive reference for all CLI commands in the ONT Ecosystem.

## Quick Navigation

- [Core Commands](#core-commands)
- [Analysis Commands](#analysis-commands)
- [Utility Commands](#utility-commands)
- [Parameter Presets](#parameter-presets)
- [HPC Commands](#hpc-commands)

## Core Commands

| Command | Description |
|---------|-------------|
| `ont_experiments.py` | Main orchestrator - register, discover, run analyses |
| `ont_pipeline.py` | Run multi-step analysis pipelines |
| `ont_manuscript.py` | Generate figures and tables for manuscripts |

### ont_experiments.py

**Description:** Main orchestrator - register, discover, run analyses

**Examples:**

```bash
ont_experiments.py init --git
ont_experiments.py discover /path/to/data --register
ont_experiments.py run end_reasons exp-abc123
ont_experiments.py history exp-abc123
```

### ont_pipeline.py

**Description:** Run multi-step analysis pipelines

**Examples:**

```bash
ont_pipeline.py run pharmaco-clinical exp-abc123
ont_pipeline.py list
ont_pipeline.py resume exp-abc123
```

### ont_manuscript.py

**Description:** Generate figures and tables for manuscripts

**Examples:**

```bash
ont_manuscript.py list-figures
ont_manuscript.py figure fig_end_reason_kde exp-abc123
ont_manuscript.py export exp-abc123 ./paper --target latex
```

## Analysis Commands

| Command | Description |
|---------|-------------|
| `end_reason.py` | Analyze read end reasons (QC) |
| `ont_qc_advisor.py` | AI-powered QC recommendations and troubleshooting |
| `ont_align.py` | Alignment and edit distance calculations |
| `ont_dorado.py` | Unified dorado CLI with model management and indexing |
| `ont_sma.py` | SMA-seq analysis: registry, classification, library prep |
| `ont_qscore_calibration.py` | Q-score calibration analysis and comparison |
| `dorado_basecall.py` | Basecalling with Dorado (HPC clusters) |
| `ont_monitor.py` | Monitor sequencing runs |

### end_reason.py

**Description:** Analyze read end reasons (QC)

**Examples:**

```bash
end_reason.py /path/to/pod5 --json results.json
end_reason.py /path/to/bam --plot qc.png
```

### ont_qc_advisor.py

**Description:** AI-powered QC recommendations and troubleshooting

**Examples:**

```bash
ont_qc_advisor.py --json qc_results.json
ont_qc_advisor.py --json qc.json --compare-baseline --store-baseline
ont_qc_advisor.py --json qc.json --min-confidence 0.7 --output recommendations.json
```

### ont_align.py

**Description:** Alignment and edit distance calculations

**Examples:**

```bash
ont_align.py editdist ACGT ACTT --cigar
ont_align.py align reads.fastq --ref GRCh38 --output aligned.bam
```

### ont_dorado.py

**Description:** Unified dorado CLI with model management and indexing

**Examples:**

```bash
ont_dorado.py basecall /path/to/pod5 --model sup --output calls.bam --index
ont_dorado.py models list --available --chemistry r10.4.1
ont_dorado.py download dna_r10.4.1_e8.2_400bps_sup@v5.0.0
ont_dorado.py basecall /path/to/pod5 --model sup --local --output calls.bam
```

### ont_sma.py

**Description:** Unified SMA-seq analysis CLI with registry, classification, and library prep management

**Subcommands:**

| Subcommand | Description |
|------------|-------------|
| `ref` | Reference management (list, add, import, index, validate) |
| `prep` | Library preparation (wizard, targets, samplesheet, barcodes) |
| `run` | Run full pipeline (init, extract, ingest) |
| `classify` | Classify reads to targets by size/edit-distance |
| `registry` | Manage persistent registry (targets, barcodes, preps, experiments) |
| `browse` | Web browser for classification results |
| `export` | Export data (CSV, FASTA, JSON, read IDs) |
| `report` | Generate publication-quality figures |
| `compare` | Compare two SMA-seq experiments |

**Examples:**

```bash
# Reference management
ont_sma.py ref list --set sma_v04
ont_sma.py ref add --set custom --name V05 --sequence "ACGT..."

# Registry operations
ont_sma.py registry init
ont_sma.py registry stats
ont_sma.py registry targets --gene CYP2D6
ont_sma.py registry barcodes --source ont_v14
ont_sma.py registry preps --presets
ont_sma.py registry experiments --status active

# Calibration queries
ont_sma.py registry calibration                      # List all calibration runs
ont_sma.py registry calibration --exp exp-001        # Filter by experiment
ont_sma.py registry calibration --run cal_abc123     # Show run details
ont_sma.py registry calibration --min-dprime 2.0     # Filter by d-prime threshold
ont_sma.py registry calibration --max-eer 0.10       # Filter by max EER
ont_sma.py registry calibration --compare cal_1 cal_2  # Compare runs side-by-side
ont_sma.py registry calibration --delete cal_abc123  # Delete a calibration run

# Classification
ont_sma.py classify -b reads.bam -c config.yaml

# Full pipeline (with Q-score calibration flags)
ont_sma.py run -e exp-001 -b reads.bam -p pod5/ -c config.yaml -o output/
ont_sma.py run -e exp-001 -b reads.bam -p pod5/ -c config.yaml -o output/ --qscore       # With Q-score calibration
ont_sma.py run -e exp-001 -b reads.bam -p pod5/ -c config.yaml -o output/ --full         # All analysis steps
ont_sma.py run -e exp-001 -b reads.bam -p pod5/ -c config.yaml -o output/ --full --figures  # Include publication figures
ont_sma.py run -e exp-001 -b reads.bam -p pod5/ -c config.yaml -o output/ --full --skip-qscore  # Skip Q-score
ont_sma.py browse output/ --port 8051
ont_sma.py export output/ --format csv -o results.csv
ont_sma.py report output/ -o figures/

# Experiment comparison
ont_sma.py compare --exp1 /path/exp1/bam_pass --exp2 /path/exp2/bam_pass --ref ref.fa -o comparison/
```

### ont_qscore_calibration.py

**Description:** Q-score calibration analysis and multi-experiment comparison

**Subcommands:**

| Subcommand | Description |
|------------|-------------|
| `run` | Extract Q-score data and generate calibration plots |
| `compare` | Compare two or more Q-score profiles with statistics |

**Examples:**

```bash
# Run calibration analysis on aligned BAM
ont_qscore_calibration.py run -b aligned.bam -r reference.fa -o output/

# Generate profile JSON for comparison
ont_qscore_calibration.py run -b aligned.bam -r reference.fa -o output/ --profile

# Compare two experiments with statistical testing
ont_qscore_calibration.py compare exp1_profile.json exp2_profile.json -o comparison/

# Compare multiple experiments
ont_qscore_calibration.py compare exp1.json exp2.json exp3.json -o comparison/ --figures --report
```

**Output Files:**

| File | Description |
|------|-------------|
| `*_profile.json` | Per-position Q-score profile (run) |
| `*_per_position.png` | Per-position error rate plot (run) |
| `comparison.json` | Statistical comparison results (compare) |
| `comparison_overlay.png` | Profile overlay figure (compare) |
| `comparison_summary.png` | Summary bar chart (compare) |
| `comparison_report.md` | Markdown report with interpretation (compare) |

**Statistical Tests:**

- Mann-Whitney U test for error rate differences
- Effect size (Cohen's d) calculation
- Automatic interpretation of significance

### dorado_basecall.py

**Description:** Basecalling with Dorado (HPC clusters)

**Examples:**

```bash
dorado_basecall.py /path/to/pod5 --model sup@v5.0.0 --output calls.bam
dorado_basecall.py /path/to/pod5 --slurm job.sh --partition spgpu
```

### ont_monitor.py

**Description:** Monitor sequencing runs

**Examples:**

```bash
ont_monitor.py /path/to/run --live --interval 60
ont_monitor.py /path/to/run --plot metrics.png
```

## Utility Commands

| Command | Description |
|---------|-------------|
| `ont_stats.py` | Show ecosystem statistics |
| `ont_check.py` | Validate installation and dependencies |
| `ont_update.py` | Check for and apply updates |
| `ont_backup.py` | Backup and restore registry data |
| `ont_doctor.py` | Diagnose issues and suggest fixes |
| `ont_report.py` | Generate project summary reports |
| `ont_hooks.py` | Manage git hooks for development |
| `ont_version.py` | Version information and management |
| `ont_init.py` | Project initialization wizard |
| `ont_changelog.py` | Generate changelog from git commits |
| `ont_install_skills.py` | Install Claude Code skills for discovery |
| `ont_context.py` | Unified experiment context and equation execution |
| `experiment_db.py` | Database operations for experiments |

### ont_stats.py

**Description:** Show ecosystem statistics

**Examples:**

```bash
ont_stats.py
ont_stats.py --brief
ont_stats.py --json
```

### ont_check.py

**Description:** Validate installation and dependencies

**Examples:**

```bash
ont_check.py
ont_check.py --json
```

### ont_update.py

**Description:** Check for and apply updates

**Examples:**

```bash
ont_update.py
ont_update.py --apply
ont_update.py --status
```

### ont_backup.py

**Description:** Backup and restore registry data

**Examples:**

```bash
ont_backup.py create
ont_backup.py list
ont_backup.py restore backup.tar.gz
```

### ont_doctor.py

**Description:** Diagnose issues and suggest fixes

**Examples:**

```bash
ont_doctor.py
ont_doctor.py --fix
ont_doctor.py --quick
ont_doctor.py --json
```

### ont_report.py

**Description:** Generate project summary reports

**Examples:**

```bash
ont_report.py
ont_report.py --format markdown
ont_report.py --format json
ont_report.py --output report.md
```

### ont_hooks.py

**Description:** Manage git hooks for development

**Examples:**

```bash
ont_hooks.py install
ont_hooks.py status
ont_hooks.py list
ont_hooks.py run pre-commit
```

### ont_version.py

**Description:** Version information and management

**Examples:**

```bash
ont_version.py
ont_version.py --full
ont_version.py --skills
ont_version.py bump patch
```

### ont_init.py

**Description:** Project initialization wizard

**Examples:**

```bash
ont_init.py project my-project
ont_init.py project my-project --full
ont_init.py experiment EXP-001
ont_init.py config --type full
ont_init.py templates
```

### ont_changelog.py

**Description:** Generate changelog from git commits

**Examples:**

```bash
ont_changelog.py
ont_changelog.py --since v2.0.0
ont_changelog.py unreleased
ont_changelog.py stats
ont_changelog.py tags
```

### ont_install_skills.py

**Description:** Install Claude Code skills for discovery

**Examples:**

```bash
ont_install_skills.py
ont_install_skills.py --user
ont_install_skills.py --list
ont_install_skills.py --check
ont_install_skills.py --both --force
```

### ont_context.py

**Description:** Unified experiment context and equation execution

**Examples:**

```bash
ont_context.py load exp-abc123
ont_context.py compute QC.signal_positive_pct exp-abc123
```

### experiment_db.py

**Description:** Database operations for experiments

**Examples:**

```bash
experiment_db.py find --tag cyp2d6
experiment_db.py stats
```

## Parameter Presets

| Command | Description |
|---------|-------------|
| `ont_experiments.py preset list` | List available parameter presets |
| `ont_experiments.py preset show` | Show detailed preset information |
| `ont_experiments.py preset save` | Save parameter preset for reuse |
| `ont_experiments.py preset delete` | Delete user preset |
| `ont_experiments.py preset export` | Export presets to JSON file |
| `ont_experiments.py preset import` | Import presets from JSON file |

### ont_experiments.py preset list

**Description:** List available parameter presets

**Examples:**

```bash
ont_experiments.py preset list
ont_experiments.py preset list --skill basecalling
ont_experiments.py preset list --builtin-only
ont_experiments.py preset list --user-only
ont_experiments.py preset list --json
```

### ont_experiments.py preset show

**Description:** Show detailed preset information

**Examples:**

```bash
ont_experiments.py preset show @basecalling-sup
ont_experiments.py preset show my-preset
ont_experiments.py preset show @qc-quick --json
```

### ont_experiments.py preset save

**Description:** Save parameter preset for reuse

**Examples:**

```bash
ont_experiments.py preset save my-qc --skill end_reasons --param quick=true
ont_experiments.py preset save lab-standard --from-last
ont_experiments.py preset save fast-bc --skill basecalling --param model=fast --description 'Fast basecalling'
```

### ont_experiments.py preset delete

**Description:** Delete user preset

**Examples:**

```bash
ont_experiments.py preset delete my-preset --force
```

### ont_experiments.py preset export

**Description:** Export presets to JSON file

**Examples:**

```bash
ont_experiments.py preset export my-qc --output presets.json
ont_experiments.py preset export --all --output my-presets.json
ont_experiments.py preset export --all --builtin --output all-presets.json
```

### ont_experiments.py preset import

**Description:** Import presets from JSON file

**Examples:**

```bash
ont_experiments.py preset import presets.json
ont_experiments.py preset import presets.json --force
ont_experiments.py preset import presets.json --rename lab-
```

## HPC Commands

| Command | Description |
|---------|-------------|
| `ont_slurm.py` | SLURM job monitoring and recovery for HPC workflows |
| `calculate_resources.py` | Calculate GPU/memory resources for basecalling |
| `make_sbatch_from_cmdtxt.py` | Generate SLURM batch scripts |

### ont_slurm.py

**Description:** SLURM job monitoring and recovery for HPC workflows

**Examples:**

```bash
ont_slurm.py status --pending
ont_slurm.py watch --interval 10
ont_slurm.py diagnose --job-id 12345
ont_slurm.py recover --array 12345 --dry-run
ont_slurm.py recover --failed --confirm
ont_slurm.py health
```

### calculate_resources.py

**Description:** Calculate GPU/memory resources for basecalling

**Examples:**

```bash
calculate_resources.py /path/to/pod5 --model sup@v5.0.0
```

### make_sbatch_from_cmdtxt.py

**Description:** Generate SLURM batch scripts

**Examples:**

```bash
make_sbatch_from_cmdtxt.py commands.txt --partition spgpu
```