AAVision

A Nextflow workflow for quality control and characterization of recombinant adeno-associated virus (rAAV) preparations from Oxford Nanopore sequencing.

It aligns reads to the vector and reference sequences, classifies them (rAAV / hybrid / impurity), quantifies truncation hotspots and read-length distributions, optionally performs taxonomic classification of unmapped reads with Kraken2/Bracken, and produces an interactive HTML report. View an example report

Requirements

• Nextflow (DSL2; developed against 26.04)
• Docker (the workflow runs each process in a container; the image bundles minimap2, samtools, seqkit, kraken2, bracken and the Python analysis code)

No other local installation is required — the tools live in the container.

Quick start

You need Nextflow and Docker installed and running (see Requirements). Everything else — the pipeline code and the analysis container — is fetched automatically.

Create a samplesheet (see Samplesheet), then run the pipeline straight from GitHub:

nextflow run Iclah/AAVision -r v1.0.2 -profile docker \
  --input samplesheet.csv \
  --outdir results \
  --kraken_db /path/to/kraken2_db \
  --min-length 50

-r v1.0.2 pins a specific release. On the first run, Nextflow downloads the pipeline and pulls the container image (ghcr.io/iclah/aavision:1.0.2) automatically; there is no build or manual install step. The interactive report is written to results/<sample>/analysis_report.html.

Running from a local clone

If you prefer to clone the repository (or want to modify the workflow), run main.nf directly instead:

git clone https://github.com/Iclah/AAVision.git
cd AAVision
nextflow run main.nf -profile docker \
  --input samplesheet.csv --outdir results --min-length 300

Developing against a local image

By default the workflow uses the published image. To build and use a local image instead, override the container:

docker build -t aavision:dev -f AAV_analyzer.dockerfile .
nextflow run main.nf -profile docker --input samplesheet.csv \
  --outdir results --min-length 300 --container aavision:dev

Test the installation

nextflow run Iclah/AAVision -r main -profile test,docker

Runs a small bundled dataset (test_data/) without taxonomy and writes results_test/test/analysis_report.html.

Samplesheet

A comma-separated file with one row per sample. The fastq column points at a directory of FASTQ files (e.g. an ONT fastq_pass folder); they are merged automatically. Reference columns are explicit per row.

sample,fastq,vector,backbone,helper,host,rep_cap,spike_in
sample1,/data/run1/sample1/fastq_pass,/data/refs/vector.fasta,/data/refs/backbone.fasta,/data/refs/helper.fasta,/data/refs/host.fasta,/data/refs/rep_cap.fasta,

Column	Required	Description
sample	yes	Unique sample identifier
fastq	yes	Directory containing the sample's FASTQ files
vector	yes	rAAV vector reference FASTA
backbone	yes	Plasmid backbone reference FASTA
helper	yes	Helper plasmid reference FASTA
host	yes	Host genome reference FASTA
rep_cap	no	Rep/Cap reference FASTA (leave blank to skip)
spike_in	no	Spike-in reference FASTA (leave blank to skip)

Paths can be absolute or relative to the directory you launch Nextflow from. A literal ${projectDir} in a path is replaced with the pipeline directory; the bundled test_data/samplesheet.csv uses this so it works from anywhere.

The file must be comma-separated. Some spreadsheet applications export semicolon-separated CSVs on non-US locales — check the delimiter if the samplesheet fails to parse.

Parameters

Parameter	Default	Description
--input	(required)	Path to the samplesheet CSV
--outdir	results	Directory for published outputs
--quality	90	Minimum read coverage (%) by the vector alignments (primary + supplementary) for high-quality vector reads
--snapback-overlap	200	Reads with two vector alignments on opposite strands overlapping by at least this many bp are snapbacks and count as low-quality
--hybrid-min-unique	100	A low-quality read counts as a hybrid with a reference only if at least this many read bases align to it outside the regions it shares with the vector and outside the read's vector alignment
--homology-preset	asm20	minimap2 preset used to find the regions each reference shares with the vector
--min-length	0	Minimum read length filter in bp (0 = off)
--kraken_db	null	Path to a Kraken2 database directory. If unset, taxonomy is skipped
--kraken_confidence	0.05	Kraken2 confidence threshold
--bracken_level	S	Bracken taxonomic level (D/P/C/O/F/G/S)
--bracken_threshold	10	Bracken minimum read count per taxon
--bracken_read_length	null	Bracken read length (-r). Must match a length the Bracken DB was built for. If unset, the DB maximum is used
--kraken_memory	auto	TAXONOMY memory request. auto sizes it from the DB .k2d files; override with an explicit value (e.g. 128.GB)
--kraken_cpus	8	Threads for Kraken2
--kraken_time	12.h	Time limit for the taxonomy step

Resource limits

By default the workflow uses whatever the machine provides. To cap resources (e.g. on a laptop or a memory-limited VM), uncomment and set resourceLimits in nextflow.config. This is documented inline in that file.

Alignment memory scales with reference size: a human host genome needs about 17 GB, so on smaller machines set resourceLimits to the available memory.

Taxonomy (optional)

Taxonomic classification of unmapped reads runs only when --kraken_db is supplied. Kraken2 memory-maps the entire database into RAM, so this step requires a machine sized to the database (a standard database is 100+ GB). The memory request is sized automatically from the database; on a machine that cannot provide it the step fails clearly rather than silently under-provisioning.

Prebuilt Kraken2 databases can be downloaded from the Kraken2 index collection (e.g. Standard, PlusPF, PlusPFP; the capped -8 and -16 variants fit in 8 or 16 GB of RAM at some loss of sensitivity). Unpack the archive and pass the directory to --kraken_db. The archives also contain the Bracken databaseXmers.kmer_distrib files the Bracken step needs.

To reproduce a specific read length (e.g. matching the read-length peak of your data), set --bracken_read_length to a value the Bracken database was built for.

Output

results/<sample>/
├── analysis_report.html          # interactive report — start here
├── fastq/                        # classified reads
│   ├── prepared.fastq.gz         # merged + length-filtered input
│   ├── vector_HQ.fastq           # high-quality vector reads
│   ├── vector_LQ.fastq           # low-quality vector reads
│   ├── hybrid_*.fastq            # hybrid reads by reference
│   ├── hybrid_shared_only.tsv    # LQ reads not called hybrid: aligned only in vector-shared regions
│   ├── hybrid_filter_stats.json  # counts for the shared-region filter
│   └── impurity_*.fastq          # impurity reads by reference
├── bam/                          # alignments (IGV-compatible)
├── homology/                     # regions of each reference shared with the vector (BED, 0-based)
└── stats/                        # JSON/CSV statistics, coverage, truncation,
                                  # read lengths, and taxonomy (if enabled)

The report

The HTML report includes overall classification statistics (rAAV / hybrid / impurity), a read-distribution table and pie chart, read-length histograms, per-reference coverage, a truncation-hotspot plot, and — when taxonomy is enabled — a taxonomic breakdown of unmapped reads. Charts render client-side with Plotly, so viewing the report requires an internet connection. An example report is available at iclah.github.io/AAVision/example_report.html.

Method

1. Vector alignment — reads are aligned to the vector reference with minimap2; mapped and unmapped reads are separated.
2. Quality classification — mapped reads are split into high- and low-quality by how much of the read the vector alignments cover, primary and supplementary combined (default ≥90%). Snapbacks (a vector region followed by its own reverse complement) are low-quality.
3. Hybrid detection — low-quality vector reads are aligned to the other references and assigned to the best-matching one. Regions a reference shares with the vector (found by aligning the vector to it) are ignored, so a read only counts as a hybrid if at least --hybrid-min-unique read bases align to it outside those regions and outside the read's vector alignment.
4. Impurity detection — unmapped reads are aligned to all references and classified by best alignment.
5. Truncation analysis — read termini are counted, normalized by coverage, smoothed, and reported as enrichment along the vector genome.
6. Read-length analysis — length distributions are binned per category.
7. Taxonomy (optional) — unmapped reads are classified with Kraken2 and abundances re-estimated with Bracken.

Repository layout

main.nf                  # workflow entry point
nextflow.config          # parameters and configuration
modules/                 # one Nextflow process per file
assets/                  # samplesheet example, placeholder files
test_data/               # bundled test dataset for -profile test
env.yaml                 # pinned container dependencies
AAV_analyzer.dockerfile  # container definition
aav_analyze.py           # CLI the processes invoke inside the container
aav_analyzer/            # analysis library (alignment, classification,
                         # truncation, taxonomy, report)

License

MIT — see the LICENSE file.