RNASeqNGSHPVDetect (rshpvdetect)

A Bioconda-ready Python package that wraps a Nextflow workflow for detecting Human Papillomavirus (HPV) from paired-end RNA-seq NGS data.

Pipeline Overview

1. FASTQ discovery — parse paired-end FASTQ files by sample / lane / direction.
2. fastp — adapter trimming, deduplication, poly-G trimming, paired-end correction.
3. FastQC + MultiQC — quality control reports.
4. NextGenMap (NGM) — align reads against the human reference (GRCh38).
5. Samtools — extract unmapped (host-subtracted) reads.
6. DIAMOND blastx — search unmapped reads against an HPV protein database.
7. Reporting — aggregate DIAMOND hits into HPV type/protein summaries.

The HPV reference database can be built from:

• A user-supplied PAVE/RefSeq protein CSV (human_reference_clones.csv).
• NCBI Protein esearch + efetch for Human Papillomavirus records.

Installation

Quick install with Bioconda

# Once the recipe is merged into Bioconda
mamba create -n rshpvdetect -c conda-forge -c bioconda rshpvdetect
mamba activate rshpvdetect
rshpvdetect --help

Install from source

git clone https://github.com/rossfox-agent/rshpvdetect.git
cd rshpvdetect
mamba env create -f environment.yml
mamba activate rshpvdetect
pip install -e .

Install from the local Forgejo registry

The package is published to the Forgejo package registry on git.rossfox.xyz. You can install the conda package directly from the ross channel:

# Add the rossfox Forgejo conda channel (one-time)
# Packages are available at https://git.rossfox.xyz/api/packages/ross/conda

mamba create -n rshpvdetect \
  -c https://git.rossfox.xyz/api/packages/ross/conda \
  -c conda-forge \
  -c bioconda \
  rshpvdetect

mamba activate rshpvdetect
rshpvdetect --help

Or install the PyPI package from the same Forgejo registry:

pip install --extra-index-url https://git.rossfox.xyz/api/packages/ross/pypi/simple/ rshpvdetect

Manual dependency setup

If you already have Python 3.10+ and Nextflow 23.04+, install the Python package and bioconda tools separately:

mamba install -c conda-forge -c bioconda \
  nextflow fastp fastqc multiqc nextgenmap samtools diamond
pip install -e .

Required external tools (also listed in environment.yml):

Tool	Purpose
nextflow	Workflow engine
fastp	FASTQ trimming
fastqc	Per-read QC
multiqc	Aggregate QC reports
ngm	Host alignment (NextGenMap)
samtools	BAM manipulation
diamond	Protein similarity search

Configuration precedence

1. CLI arguments
2. Environment variables (NCBI_API_KEY, ENTREZ_EMAIL)
3. YAML config file (--config)
4. Internal defaults

Set the NCBI API key as an environment variable to avoid committing it to files:

export NCBI_API_KEY="your_ncbi_api_key"
export ENTREZ_EMAIL="your@email.edu"

CLI usage

--resource is required on every run. Resources are given per stage as stage=key=value and can be repeated:

rshpvdetect run FASTQs/NGS_Proteomic_HPV_Detection \
  --outdir ./run_2026_07_10 \
  --human-reference /data/references/GRCh38.fa \
  --diamond-db /data/references/hpv_references.dmnd \
  --profile standard \
  --resource fastp=cpus=16 --resource fastp=mem=32.GB \
  --resource ngm=cpus=64 --resource ngm=mem=64.GB \
  --resource diamond=cpus=16 --resource diamond=mem=16.GB \
  --resource samtools=cpus=8 --resource samtools=mem=8.GB \
  --resource fastqc=cpus=8 --resource fastqc=mem=8.GB \
  --resource multiqc=cpus=4 --resource multiqc=mem=8.GB

Build the HPV protein database

rshpvdetect build-hpv-db \
  --outdir ./hpv_db \
  --resource build_db=cpus=8 --resource build_db=mem=16.GB

Use --no-ncbi to skip the NCBI fetch and build only from a local PAVE CSV.

Aggregate reports

The report command can produce TSV, JSON, HTML, or all three at once:

# Default tab-separated report
rshpvdetect report diamond_results/ -o hpv_summary

# HTML report with an interactive HPV type pie chart
rshpvdetect report diamond_results/ -o hpv_summary --format html

# All formats
rshpvdetect report diamond_results/ -o hpv_summary --format all

# Filter by DIAMOND quality metrics
rshpvdetect report diamond_results/ -o hpv_summary --format html \
  --min-pident 80.0 --max-evalue 1e-5 --min-bitscore 50

HTML reports include a styled read-level hits table and a pie chart of reads per HPV type.

Dry run

Generate the sample sheet and Nextflow params.json without launching the workflow:

rshpvdetect run ./data --dry-run \
  --resource fastp=cpus=4 --resource fastp=mem=8.GB

SLURM execution

Switch to the slurm Nextflow profile and pass resources appropriate for your cluster:

rshpvdetect run FASTQs/ \
  --outdir ./slurm_out \
  --human-reference /scratch/GRCh38.fa \
  --diamond-db /scratch/hpv_references.dmnd \
  --profile slurm \
  --resource fastp=cpus=16 --resource fastp=mem=32.GB --resource fastp=time=2h \
  --resource ngm=cpus=64 --resource ngm=mem=128.GB --resource ngm=time=24h \
  --resource diamond=cpus=16 --resource diamond=mem=32.GB

Edit src/rshpvdetect/nextflow/nextflow.config to set your Slurm account/queue and partition defaults.

Nextflow usage (advanced)

The Python CLI is the recommended entry point, but you can also invoke Nextflow directly once the CLI has generated the sample sheet and params.json:

nextflow run /path/to/rshpvdetect/nextflow/main.nf \
  -params-file params.json \
  -profile standard \
  -resume

E2E test data

A helper script is provided to fetch a small public RNA-seq subset from ENA:

python scripts/download_e2e_data.py /tmp/rshpvdetect_e2e

This downloads run ERR6458091 from study PRJEB40416 and subsets it to 10,000 read pairs for a fast local test. The full FASTQ files are not committed to the repository.

License

MIT