Skip to content

README.md

Latest commit

 

History

History
231 lines (162 loc) · 7.15 KB

README.md

File metadata and controls

231 lines (162 loc) · 7.15 KB
Raw

PyFuse logo

PyFuse (Python Fusion Annotator) is a command-line tool for annotating gene fusion breakpoints with exon context, frame status, optional sequence context, and report outputs (Excel, HTML, VCF).

Full Documentation

Detailed documentation available at PyFuse-Documentation.

Quick Start

pyfuse resources install --genome grch37
pyfuse annotator -i /path/to/fusions.tsv -o /path/to/output -f star -g grch37

Installation

Quick install from GitHub (latest source)

We recommend using a virtual environment to avoid dependency conflicts:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade git+https://github.com/gopisiva1616/PyFuse.git

Note: PyPI and Conda packages are not yet available. The commands below will be updated when the packages are published.

Install from PyPI

pip install pyfuse

Conda install

conda install -c conda-forge pyfuse

Requirements

  • Python >=3.10.0
  • bedtools available on PATH (required by pybedtools workflows)

CLI overview

pyfuse -h

Top-level modes:

  • annotator: run complete fusion annotation
  • resources: build/install and manage resource bundles

Annotator mode

pyfuse annotator \
  -i /path/to/breakpoints.tsv \
  -o /path/to/output_dir \
  -f star \
  -g grch38

Common options:

  • -i, --fusion-breakpoints: input breakpoint file (required)
  • -o: output directory (required)
  • -f, --input-format: one of input caller format default, star, arriba, tophat, fusion_catcher, longgf, fusion_inspector (required)
  • -g, --genome: one of grch37, grch38 (default: grch37)
  • --resource-path: exact resource bundle directory to use for this run; default chooses from inbuilt resource bundle directory
  • -t, --target-bed: BED file used for filtering
  • -r, --reference: FASTA file for fusion sequence annotation
  • -s, --settings: optional custom settings YAML
  • -d: enable debug logs

Notes:

  • For normal usage, install bundles with pyfuse resources install and run pyfuse annotator without resource flags.
  • Use --resource-path only when you want to pin an exact bundle directory for a run.
  • Advanced managed-root control is via PYFUSE_RESOURCE_ROOT env var or resource_root in settings.

Resource mode

annotator mode requires a resource bundle per genome (grch37 or grch38). Use resources mode to install, list, verify, and inspect these bundles.

  • First install is a one-time setup per genome.
  • Re-running install creates a new version after confirmation.
  • If multiple versions exist, annotator uses the latest installed version by default.
  • You can pin an exact bundle for a run with --resource-path in annotator mode and --resource-root in resources mode.

Basic resource commands:

pyfuse resources list
pyfuse resources install --genome grch38
pyfuse resources verify --genome grch38
pyfuse resources path --genome grch37

Help menus:

pyfuse resources -h
pyfuse resources install -h

install subcommand has additional options:

pyfuse resources install \
  --genome {grch37,grch38} \
  [--source {refseq-gtf,ucsc-gtf}] \
  [--gtf <local_path_or_url>] \
  [--annot-summary <local_path_or_url>] \
  [--mane-file <local_path_or_url>] \
  [--cache-dir <path>] \
  [--resource-root <path>]

What each install option does:

  • --genome: required target genome for bundle creation.
  • --source: source mode used during bootstrap (refseq-gtf default).
  • --gtf: override default GTF with local file or URL.
  • --annot-summary: override default assembly summary with local file or URL.
  • --mane-file / --mane-url: optional MANE input override (file or URL).
  • --cache-dir: temporary/cache location for bootstrap/download assets.
  • --resource-root: persistent managed resource root.

If default source URLs become unavailable, override them directly during install:

# Override with custom URLs
pyfuse resources install --genome grch38 \
  --gtf https://example.org/custom_grch38.gtf.gz \
  --annot-summary https://example.org/custom_grch38_assembly_report.txt \
  --mane-file https://ftp.ncbi.nlm.nih.gov/refseq/MANE/MANE_human/current/

# Or use local files (no download for these inputs)
pyfuse resources install --genome grch37 \
  --gtf /data/ref/GRCh37_latest_genomic.gtf.gz \
  --annot-summary /data/ref/GRCh37_latest_assembly_report.txt

Notes:

  • install is the primary setup command. It builds and installs a local bundle using defaults from settings or user-provided URLs/files.
  • annotator uses --resource-path if provided; otherwise it uses installed bundles under managed resource storage.
  • Packaged default resource fallback is disabled. If a bundle is missing, run pyfuse resources install --genome <grch37|grch38>.
  • Managed resource root precedence is: --resource-root > PYFUSE_RESOURCE_ROOT env var > resource_root in settings file > platform default data dir.
  • Temporary build/download staging uses cache storage (--cache-dir), while installed resources are kept in persistent resource storage.

Output files

For each run, PyFuse writes a timestamped output folder containing:

  • pyfuse_output.xlsx
  • pyfuse_fusion_annotation.html
  • pyfuse_output.vcf
  • pyfuse_fusion_summary.txt
  • excluded_breakpoints.txt
  • pyfuse_<timestamp>.log

License and attribution

  • PyFuse code: GNU GPLv3 (see LICENSE.md)
  • Bundled third-party web/font assets: see THIRD_PARTY_NOTICES.md
  • Resource provenance and use restrictions depend on upstream data providers

Attribution request:

  • PyFuse is open source under GPLv3 copyleft.
  • If PyFuse contributes to your analysis, manuscript, report, presentation, or derivative tool, please credit the project and acknowledge the contributing author/institution .
  • Citation is strongly encouraged for academic and scientific use.

Testing

Run tests with HTML report generation:

pyfuse-test

Integration tests accept runtime environment variables:

  • INPUT_BKPT, TRUTH_OUTPUT, INPUT_FORMAT, REFERENCE_GENOME, OUTPUT_PATH
  • CACHE_DIR, RESOURCE_PATH, GENOME, FUSION2VCF, perl

Example:

INPUT_FORMAT=star REFERENCE_GENOME=/data/ref/genome.fa pyfuse-test -m integration

If pyfuse-test is not found, reinstall in your active environment:

pip install -e .[dev]

Fallback invocation:

python -m pyfuse.test_cli -m integration

Citation

If PyFuse contributes to your analysis or publication, please cite it. Use machine-readable citation metadata in CITATION.cff. Repository URL: https://github.com/gopisiva1616/PyFuse.git

Data and Compliance Notes

  • Prefer default NCBI RefSeq-based resource generation for a conservative compliance posture.
  • Treat optional external datasets (for example COSMIC/GTEx or custom UCSC-derived inputs) as user-managed licensing responsibility.
  • Keep provenance records (source URL, date, checksum) for generated resource files.

For practical release guidance and checklists, see docs/publishing-and-compliance.md. For bundled asset licenses/notices, see THIRD_PARTY_NOTICES.md.