# Set conda channels first (required)
conda config --add channels defaults
conda config --add channels bioconda
conda config --add channels conda-forge
 
# Option A — Bioconda
conda create -n aviary -c bioconda aviary
# OR into an existing environment:
conda install -c bioconda aviary
 
# Option B — Pip (create environment from admin/requirements.txt first)
pip install aviary-genome
 
# Option C — Source with pixi (recommended for development)
git clone https://github.com/rhysnewell/aviary.git
cd aviary
pixi run postinstall     # installs all dependencies
 
# Editable install for development
pip install -e .

aviary --version            # show installed version
aviary --help               # top-level help
aviary <subcommand> --help  # help for a specific subcommand

export GTDBTK_DATA_PATH=/path/to/gtdb/db/
export EGGNOG_DATA_DIR=/path/to/eggnog/
export SINGLEM_METAPACKAGE_PATH=/path/to/singlem.smpkg/
export CHECKM2DB=/path/to/checkm2db/
export CONDA_ENV_PATH=/path/to/conda/envs/

aviary configure \
  -o logs/ \
  --eggnog-db-path /path/to/eggnog/ \
  --gtdb-path /path/to/gtdb/ \
  --checkm2-db-path /path/to/checkm2/ \
  --singlem-metapackage-path /path/to/singlem/ \
  --metabuli-db-path /path/to/metabuli/ \    # optional, for taxvamb
  --download                                  # auto-download missing databases
 
# Also set a persistent tmpdir via configure
aviary configure --tmpdir /scratch/tmp/

# Short-read only (metaSPAdes by default)
aviary assemble \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16
 
# Short-read only with MEGAHIT (faster, lower memory than metaSPAdes)
aviary assemble \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --use-megahit
 
# Long-read only (myloasm assembler, default)
aviary assemble \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16
 
# Long-read only with Flye
aviary assemble \
  -l sample.fastq.gz \
  -z ont \
  --long-read-assembler flye \
  -o output_dir/ \
  --n-cores 16
 
# Hybrid (short + long reads)
aviary assemble \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16
 
# Host contamination removal before assembly
aviary assemble \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -r host_genome.fasta \
  -o output_dir/ \
  --n-cores 16
 
# Co-assembly of multiple samples
aviary assemble \
  -1 s1_R1.fq.gz s2_R1.fq.gz \
  -2 s1_R2.fq.gz s2_R2.fq.gz \
  --coassemble \
  -o output_dir/ \
  --n-cores 16

assembly/
  final_contigs.fasta        # assembled contigs (use this as --assembly for recover)
www/
  assembly_stats.txt         # assembly summary statistics
  rastqc/                    # RastQC short-read QC reports
  nanoplot/                  # NanoPlot long-read QC reports

# Short reads only
aviary recover \
  --assembly assembly.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --max-threads 32
 
# With long reads for coverage (improves binning)
aviary recover \
  --assembly assembly.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16
 
# GPU-accelerated binners (taxvamb, comebin, semibin use CUDA)
aviary recover \
  --assembly assembly.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --max-threads 32 \
  --request-gpu
 
# Add extra binners beyond defaults
aviary recover \
  --assembly assembly.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --extra-binners taxvamb comebin
 
# Skip specific binners
aviary recover \
  --assembly assembly.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --skip-binners vamb semibin
 
# Binning only (skip annotation — useful for quick MAG recovery)
aviary recover \
  --assembly assembly.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --binning-only
 
# Target a specific snakemake rule (run only up to this step)
aviary recover \
  --assembly assembly.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  -w rosella \
  --max-threads 12

bins/
  final_bins/                  # final consensus MAG FASTA files (use these downstream)
  bin_info.tsv                 # taxonomy, QC (completeness/contamination), size, N50 for all MAGs
  checkm_minimal.tsv           # minimal CheckM2 summary
  coverm_abundances.tsv        # CoverM relative abundance of each MAG per sample
diversity/
  singlem_out/                 # SingleM read-based community profiling output
taxonomy/                      # GTDB-tk raw output
benchmarks/                    # Snakemake rule benchmarks (time, memory per rule)
logs/                          # Rule-level logs — check here first on errors

aviary annotate \
  -d recover/bins/final_bins/ \
  -o output_dir/ \
  --n-cores 16

annotation/
  eggnog/                      # EggNOG-mapper functional annotation output
  gtdbtk/                      # GTDB-tk taxonomic classification output

# Short reads only
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16
 
# Hybrid with myloasm (default)
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16
 
# Hybrid with Flye
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  --long-read-assembler flye \
  -o output_dir/ \
  --n-cores 16
 
# With GPU binners
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16 \
  --request-gpu
 
# Preview the workflow without running
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --dry-run

aviary cluster \
  -i run1/ run2/ run3/ \
  -o cluster_output/ \
  --n-cores 16

dereplicated_bins/             # final dereplicated representative MAG FASTA files

isolate/completed_assembly.fasta    ← use this as the final assembly

# Hybrid (long + short reads) — recommended
aviary isolate \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16
 
# Long reads only
aviary isolate \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16
 
# Run only up to dnaapler (reorientation) step
aviary isolate \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16 \
  -w dnaapler

aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --snakemake-cmds '--unlock'

# Inline qsub submission
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --snakemake-cmds '--cluster "qsub -V" '
  # NOTE: space after the closing quote is required (argparse quirk)
 
# Using a named Snakemake profile (e.g. ~/.config/snakemake/aqua/config.yaml)
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --snakemake-profile aqua \
  --cluster-retries 2

cluster: qsub
cluster-status: qstat
jobs: 10000
cluster-cancel: qdel

aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16 \
  --snakemake-profile /path/to/slurm-profile/

#!/bin/bash
#SBATCH --job-name=aviary
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=16
#SBATCH --mem=64G
#SBATCH --time=48:00:00
#SBATCH --output=aviary_%j.log
 
conda activate aviary
aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -o output_dir/ \
  --n-cores 16

sbatch submit_aviary.sh

# Step 1 — Configure databases (once per system)
aviary configure \
  -o logs/ \
  --eggnog-db-path /path/to/db/eggnog/ \
  --gtdb-path /path/to/db/gtdb/ \
  --checkm2-db-path /path/to/db/checkm2/ \
  --singlem-metapackage-path /path/to/db/singlem/ \
  --download
 
# Step 2 — QC + Assembly
aviary assemble \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o 01_assemble/ \
  --n-cores 16
 
# Step 3 — MAG Recovery
aviary recover \
  --assembly 01_assemble/assembly/final_contigs.fasta \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o 02_recover/ \
  --n-cores 16 \
  --max-threads 32 \
  --request-gpu       # only if GPU node available
 
# Step 4 — Annotate MAGs
aviary annotate \
  -d 02_recover/bins/final_bins/ \
  -o 03_annotate/ \
  --n-cores 16
 
# Step 5 — Dereplicate across all samples (run once all samples processed)
aviary cluster \
  -i 02_recover/ run2/ run3/ \
  -o 04_cluster/ \
  --n-cores 16

aviary complete \
  -1 sample_R1.fastq.gz \
  -2 sample_R2.fastq.gz \
  -l sample.fastq.gz \
  -z ont \
  -o output_dir/ \
  --n-cores 16 \
  --request-gpu
 
# Then run cluster (step 5) separately after all samples are done
aviary cluster -i output_dir/ run2/ run3/ -o cluster/ --n-cores 16

# After assemble:
output_dir/assembly/final_contigs.fasta     ← use as --assembly in recover
 
# After recover:
output_dir/bins/final_bins/*.fna            ← final MAG FASTA files (use these downstream)
output_dir/bins/bin_info.tsv                ← taxonomy, completeness, contamination, size, N50
output_dir/bins/checkm_minimal.tsv          ← minimal CheckM2 QC summary
output_dir/bins/coverm_abundances.tsv       ← relative abundance per MAG per sample
output_dir/diversity/singlem_out/           ← SingleM community profiling
output_dir/taxonomy/                        ← raw GTDB-tk output
output_dir/benchmarks/                      ← per-rule resource benchmarks
output_dir/logs/                            ← per-rule logs — always check here first on errors
 
# After annotate:
output_dir/annotation/eggnog/               ← EggNOG-mapper functional annotation
output_dir/annotation/gtdbtk/              ← GTDB-tk taxonomic annotation
 
# After cluster:
output_dir/dereplicated_bins/               ← final dereplicated representative MAGs

# Recommended — via pixi task
pixi run -e web server
 
# Or pin to a specific output directory
python -m aviary.web.server --output-dir /path/to/aviary/output

ssh -L 8090:localhost:8090 <username>@<hpc-address>

python -m aviary.web.server --output-dir /path/to/aviary/output --port 8090

@software{aviary,
  author  = {Newell, Rhys J. P. and Aroney, Samuel T. N. and Zaugg, Julian and
             Sternes, Peter and Tyson, Gene W. and Woodcroft, Ben J.},
  title   = {Aviary: Hybrid assembly and genome recovery from metagenomes with Aviary},
  year    = {2024},
  doi     = {10.5281/zenodo.10806928},
  url     = {https://doi.org/10.5281/zenodo.10806928}
}