installation

Installation

Quick guide to installing SQANTI-browser and its dependencies.

---

Quick Decision

If you have...	Use this method	Time
Conda/Mamba	Option 1: Conda (easiest)	2-5 min
No conda	Option 2: Auto-install script	5 min
Want manual control	Option 3: Manual	5 min
Container	Option 4: Docker/Singularity	2-5 min

---

Option 1: Conda (Recommended)

Easiest method - installs everything with one command:

# Download latest release
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

# Create environment with all dependencies (including UCSC tools)
conda env create -f environment.yml

# Activate environment
conda activate sqanti-browser

# Install package in editable mode
pip install -e .

Done! Skip to Verify Installation. Use python -m sqanti_browser so the active Python (e.g. conda) is always used.

⚠️ If you get an error about libssl.so.1.0.0, you can fix it running these commands:

    # Link the newer libssl to the old name (hack for bioconda tools)
    ln -s $CONDA_PREFIX/lib/libssl.so.1.1 $CONDA_PREFIX/lib/libssl.so.1.0.0
    ln -s $CONDA_PREFIX/lib/libcrypto.so.1.1 $CONDA_PREFIX/lib/libcrypto.so.1.0.0

---

Option 2: Auto-Install Script

If you don't have conda - automated script downloads tools:

# Download latest release
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

# Run installer (downloads UCSC tools to ./bin)
bash install_ucsc_tools.sh

# Install Python package (recommended)
pip install -e .

# Or deps only: pip install -r requirements.txt (then use python -m sqanti_browser)
pip install -r requirements.txt

The script installs tools to ./bin/ and adds them to your PATH.

---

Option 3: Manual Installation

Click to expand manual installation

Download UCSC Tools

For Linux:

mkdir -p ~/bin
cd ~/bin
wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/gtfToGenePred
wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/genePredToBed
wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/bedToBigBed
wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/ixIxx
wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/hubCheck
wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/twoBitInfo
wget http://hgdownload.soe.ucsc.edu/admin/exe/linux.x86_64/faToTwoBit
chmod +x *

For macOS:

mkdir -p ~/bin
cd ~/bin
wget http://hgdownload.soe.ucsc.edu/admin/exe/macOSX.x86_64/gtfToGenePred
wget http://hgdownload.soe.ucsc.edu/admin/exe/macOSX.x86_64/genePredToBed
wget http://hgdownload.soe.ucsc.edu/admin/exe/macOSX.x86_64/bedToBigBed
wget http://hgdownload.soe.ucsc.edu/admin/exe/macOSX.x86_64/ixIxx
wget http://hgdownload.soe.ucsc.edu/admin/exe/macOSX.x86_64/hubCheck
wget http://hgdownload.soe.ucsc.edu/admin/exe/macOSX.x86_64/twoBitInfo
wget http://hgdownload.soe.ucsc.edu/admin/exe/macOSX.x86_64/faToTwoBit
chmod +x *

Add to PATH

echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc  # or source ~/.zshrc

Install Python Package

pip install -e .   # Recommended
# Or: pip install -r requirements.txt   # Dependencies only

---

Option 4: Docker / Singularity

If you prefer containerized execution, a docker container is available from version 1.1.0 onwards in dockerhub
docker pull anaconesalab/sqanti-browser
On the other hand, the dockerfile is available in the main branch of the git repository.

Docker:

# Build
docker build -t sqanti-browser:latest .

# Run
docker run -v $(pwd):/data sqanti-browser:latest \
    --gtf /data/corrected.gtf \
    --classification /data/classification.txt \
    --output /data/my_hub \
    --genome hg38

Singularity:
The dockerfile is available in the main branch of the git repository.

# Build
singularity build sqanti-browser.sif Singularity.def

# Run
singularity run sqanti-browser.sif \
    --gtf corrected.gtf \
    --classification classification.txt \
    --output my_hub \
    --genome hg38

---

Verify Installation

Test that everything works:

python tests/test_sqanti_browser.py

For a quick environment check (tools and Python deps only):

python tests/test_sqanti_browser.py --install-only

For checking it with singularity

singularity exec \
    --bind $(pwd):/data \
    sqanti-browser.sif \
    python /data/tests/test_sqanti_browser.py

Expected output: UCSC tools and Python dependencies should be reported as found.

---

Quick Test

Try the example to make sure everything works:

python -m sqanti_browser \
    --gtf example/SQANTI3_QC_output/example_corrected.gtf \
    --classification example/SQANTI3_QC_output/example_classification.txt \
    --output test_hub \
    --genome hg38

Should complete in ~1 minute without errors.

---

Troubleshooting

Problem	Solution
"command not found"	Tools not in PATH. Run: export PATH="$HOME/bin:$PATH"
Permission denied	Don't use sudo. Install to ~/bin instead of /usr/local/bin
Test script fails	Run python tests/test_sqanti_browser.py --install-only to see which tool is missing
wget not found	Install wget: brew install wget (macOS) or apt-get install wget (Linux)

Still having issues? See Troubleshooting for detailed solutions.

---

What Gets Installed?

Tool	Purpose	When Needed
gtfToGenePred	GTF → GenePred	Always
genePredToBed	GenePred → BED	Always
bedToBigBed	BED → bigBed	Always
ixIxx	Create search index	Always
hubCheck	Validate hub	Recommended
twoBitInfo	Extract chrom sizes	Custom genomes
faToTwoBit	Create .2bit files	Custom genomes
pandas	Data processing	Always

---

How to Run

You can use any of these:

Command	When it works
python -m sqanti_browser	Recommended. Uses whatever python is active (e.g. conda), avoiding wrong-Python / architecture issues.
sqanti_browser	After pip install -e ., if you installed with the correct Python.
python sqanti_browser.py	Uses the python in your PATH; run from project root; set PYTHONPATH=. if you get import errors.

---

Project Structure

Run commands from the project root. If you get ModuleNotFoundError: No module named 'src', set PYTHONPATH=.:

python -m sqanti_browser --help

Path	Description
sqanti_browser.py	Main converter
src/filter_isoforms.py	Standalone HTML report generator
example/example_usage.py	Example workflow script
tests/test_sqanti_browser.py	Test suite

---

Next Steps

✅ Installation complete! Now:

1. Quick Reference - See example commands
2. Usage Examples - Convert your data
3. Hosting Guide - Upload to UCSC

---