quick_reference

Quick Reference

One-page cheat sheet for common SQANTI-browser tasks.

---

How to Run

• python -m sqanti_browser — Recommended. Uses your active Python (e.g. conda).
• sqanti_browser — After pip install -e . with the correct Python.
• python sqanti_browser.py — From project root; set PYTHONPATH=. if needed.

---

⚡ Installation

Conda (Easy)

wget https://github.com/ConesaLab/SQANTI-browser/releases/download/v1.1.1/sqanti_browser-1.1.1.tar.gz
tar -xzvf sqanti_browser-1.1.1.tar.gz
cd sqanti_browser-1.1.1
conda env create -f environment.yml
conda activate sqanti-browser
pip install -e .

Example runs

# Basic conversion
python -m sqanti_browser \
    --gtf corrected.gtf \
    --classification classification.txt \
    --output my_hub \
    --genome hg38

# With all validation tracks
python -m sqanti_browser \
    --gtf corrected.gtf \
    --classification classification.txt \
    --output my_hub \
    --genome hg38 \
    --star-sj SJ.out.tab \
    --CAGE-peak CAGE_peaks.bed \
    --polyA-peak polyA_peaks.bed \
    --refGTF reference.gtf \
    --tables

# Custom genome (.2bit)
python -m sqanti_browser \
    --gtf corrected.gtf \
    --classification classification.txt \
    --output my_hub \
    --genome my_species_v1 \
    --twobit genome.2bit

---

📤 Upload to UCSC (3 Steps)

Step 1: Upload to GitHub

# In your output directory
git init
git add .
git commit -m "Add SQANTI track hub"
git remote add origin https://github.com/username/repo.git
git push -u origin main

Step 2: Get Raw URL

https://raw.githubusercontent.com/username/repo/main/hub.txt

Step 3: Load in UCSC

1. Go to genome.ucsc.edu
2. My Data → Track Hubs → My Hubs
3. Paste your raw URL
4. Click Add Hub

---

🔧 Common Options

Flag	What it does	When to use
--tables	Generate HTML reports	Always recommended
--sort-by	Sort isoforms	basic (default), none (GTF order), or metric (FL, iso_exp, etc.)
--no-category-tracks	Skip category tracks	Faster, simpler hub
--category-tracks FSM,ISM,NIC	Only these categories	Custom subset of tracks
--hub-name NAME	Prefix for hub and track labels	Compare multiple hubs (e.g. SQANTI-reads samples)
--no-highlight	Disable highlighted isoforms	Uniform category colors
--star-sj FILE	Add junction track	You have STAR output
--CAGE-peak FILE	Validate TSS	Assess 5' accuracy
--polyA-peak FILE	Validate TTS	Assess 3' accuracy
--refGTF FILE	Show reference	Compare with annotation
--twobit FILE	Custom genome	Non-model organism
--trix	True	Explicitly enable Trix index generation (default behavior; requires ixIxx in PATH)
--no-trix	False	Disable Trix index generation (skip creating trix.ix/trix.ixx)

---

🚨 Quick Troubleshooting

Problem	Quick Fix
Tools not found	bash install_ucsc_tools.sh
Hub not loading	Use raw GitHub URL (raw.githubusercontent.com)
Tracks not updating	Add udcTimeout=5 to URL after hgTracks?
Filters not working	Right-click track → Configure
Search returns nothing	Use prefixed terms: structural_category_novel_in_catalog

---

📊 Performance Expectations

Dataset Size	Processing Time	Memory Needed
~1,000 transcripts	1-2 minutes	500MB
~10,000 transcripts	5-10 minutes	1GB
~100,000 transcripts	30-60 minutes	4GB

---

🔎 Search Cheat Sheet

# Find specific gene
BRCA1

# Find FSM isoforms
structural_category_full-splice_match

# Find coding NIC on plus strand
structural_category_novel_in_catalog strand_plus coding_coding

# Find validated novel isoforms
structural_category_novel_in_catalog within_CAGE_peak_True

# Find potential NMD targets
predicted_NMD_True

---

🎯 Validation Before Upload

# Test your setup
python tests/test_sqanti_browser.py

# Validate inputs only
python -m sqanti_browser ... --validate-only

# Validate hub structure (run from output directory)
hubCheck hub.txt

# Dry run (test without creating hub)
python -m sqanti_browser ... --dry-run

# Run example workflow
python example/example_usage.py

---

📁 Expected Output Structure

my_hub/
├── hub.txt                    ← Main entry point
├── genomes.txt
└── hg38/
    ├── hg38_sqanti3.bb        ← Main track (all transcripts)
    ├── hg38_sqanti3_*.bb      ← Category tracks
    ├── trackDb.txt
    └── trix.ix/ixx            ← Search indexes (big file)

---

💡 Pro Tips

1. Always use --tables for interactive HTML reports
2. Add --refGTF to compare with reference annotation
3. Use hubCheck before uploading to catch errors early
4. Sort by FL to see highest expressed isoforms first
5. Keep your hub small - use --no-category-tracks if you have >50K transcripts

---

📚 Need More Details?

• Installation: Installation Guide
• All options: Command Line Reference
• Filtering: Filtering in UCSC
• Problems: Troubleshooting
• Multi-sample: SQANTI-reads Integration

---