Reference-free Orthology-free Annotation-free DIscordance aware Estimation of Species tree (ROADIES)

Table of Contents

• Introduction
• Quick Install
• Quick Start
• Running ROADIES on your own data
• ROADIES_XP: Placement mode with GPU Acceleration
• Citing ROADIES

Introduction

ROADIES is a fully automated, scalable pipeline for inferring phylogenetic species trees directly from raw genomic assemblies, eliminating manual steps of gene annotation and orthology inference.

ROADIES_XP (ROADIES with eXtented Placer) adds placement mode for growing or updating an existing species tree with new genomes, without recomputing it from scratch — with an optional GPU-accelerated variant for faster alignment/tree-building — see ROADIES_XP below. It's opt-in; de novo tree inference (the original ROADIES) remains the default and CPU-only.

Requirements: Linux (tested on Ubuntu 20.04/22.04). GPU placement (ROADIES_XP, optional) additionally needs an NVIDIA GPU with CUDA.

🟡 For a detailed overview of ROADIES' features and configuration options, please visit our Wiki.

🟡 If you encounter issues while running the pipeline, please refer to this page for common errors and troubleshooting tips.

Figure: ROADIES Pipeline Stages

Quick Install

Four ways to install ROADIES — pick one. Full step-by-step instructions (including troubleshooting notes) for every option are on the Install wiki page.

Option 1: Bioconda (recommended)

conda create -n roadies_env -c bioconda -c conda-forge python=3.9 ete3 seaborn
conda activate roadies_env
conda install roadies=0.1.10
cd $CONDA_PREFIX/ROADIES   # the installed package contents live here

See Install: Bioconda for the remaining steps.

Option 2: DockerHub — pull and run the prebuilt image:

docker pull ang037/roadies:latest
docker run -it ang037/roadies:latest

Option 3: Local Docker build — clone this repo, then:

docker build -t roadies_image .
docker run -it roadies_image

Option 4: Install from source — clone this repo, install the system dependencies (Java, Python 3.9+, GCC, cmake, Boost, zlib), then:

source roadies_env.sh

This builds/activates the roadies_env conda environment with everything ROADIES (and ROADIES_XP) needs.

Once installed, jump to Quick Start.

Quick Start

1. Download the test dataset (11 Drosophila genomes, run from the repo root):

mkdir -p test/test_data && cat test/input_genome_links.txt | xargs -I {} sh -c 'wget -O test/test_data/$(basename {}) {}'

2. Run the pipeline. By default ROADIES runs multiple iterations for the most accurate tree; add --noconverge for a quick single-iteration test run:

python run_roadies.py --cores 16              # full run (default)
python run_roadies.py --cores 16 --noconverge # quick single-iteration test

3. Get the tree. The final (unrooted) species tree is written to OUT_DIR/roadies.nwk (OUT_DIR in config.yaml), kept up to date after every iteration — no need to hunt through ALL_OUT_DIR/iteration_<n> for the latest one. Reroot it yourself, or with the provided workflow/scripts/reroot.py (given a rooted reference tree).

Running ROADIES on your own data

1. Edit config/config.yaml: point GENOMES at a directory of .fa/.fa.gz assemblies, one species per file, named after the species (e.g. Aardvark.fa; split multi-species files first with faSplit byname <input_dir> <output_dir>). Adjust any other parameters — see the User Guide for the full list.
2. Run it, optionally picking a mode (accurate is the default) to trade off accuracy vs. runtime:

python run_roadies.py --cores 16 --mode accurate   # or: balanced, fast

Per-iteration trees land in ALL_OUT_DIR/iteration_<n>/; the final tree is always OUT_DIR/roadies.nwk (ALL_OUT_DIR/OUT_DIR in config.yaml).

For contributing to the code, or running on a SLURM cluster, see the User Guide and Contribution guide

ROADIES_XP: Placement mode with GPU Acceleration

ROADIES_XP adds placement mode: grow or update an existing ("backbone") species tree with new query genomes, instead of re-inferring the whole tree from scratch. It's opt-in — de novo mode (accurate / balanced / fast, CPU-only) remains ROADIES' default behavior, and nothing changes unless you opt into placement mode explicitly.

Placement mode runs in two variants:

• CPU placement (default)
• GPU placement (add --gpu N) — GPU-accelerated alignment and tree-building, needs an NVIDIA GPU with CUDA

De novo mode does not have a GPU variant.

Run in placement mode (add --mode placement, and point GENOMES/REF_DIR in config.yaml at your query genomes and existing backbone output directory respectively):

python run_roadies.py --cores 16 --mode placement

Run placement mode on GPU:

python run_roadies.py --cores 16 --mode placement --gpu 1

Grow vs. update an existing tree in placement mode: by default, placement mode re-infers the combined species tree freely from backbone + query gene trees ("update"). Add --grow to instead constrain the result to the existing backbone topology while attaching the new query taxa ("grow"):

python run_roadies.py --cores 16 --mode placement --grow

Building the GPU/placement dependencies is handled automatically by roadies_env.sh when the required build dependencies (CUDA, libpll) are available.

For full details on placement mode, GPU requirements, and new config.yaml parameters (REF_DIR, GROUP_CSV, BATCH_SIZE), refer to the ROADIES_XP Wiki page

Citing ROADIES

If you use ROADIES in your research or publications, please cite the following paper:

A. Gupta, S. Mirarab, & Y. Turakhia, Accurate, scalable, and fully automated inference of species trees from raw genome assemblies using ROADIES, Proc. Natl. Acad. Sci. U.S.A. 122 (19) e2500553122, https://doi.org/10.1073/pnas.2500553122 (2025).

A manuscript describing ROADIES_XP (placement mode with GPU acceleration) is in preparation as a separate publication. Citation details will be added here once available.

Accessing ROADIES output files

The output files with the gene trees and species trees generated by ROADIES in the manuscript are deposited to Dryad. To access it, please refer to the following:

Gupta, Anshu; Mirarab, Siavash; Turakhia, Yatish (2024). Accurate, scalable, and fully automated inference of species trees from raw genome assemblies using ROADIES [Dataset]. Dryad. https://doi.org/10.5061/dryad.tht76hf73.