Phylo Runner

Data model & I/O specification

What your data looks like as it moves through the framework, and what biology each method asks for and gives back. If you work with B-cell receptor repertoires, this is the page that maps your sequences and clones onto trees, ancestral sequences, and the evolutionary analyses you can read off them.

How your data is organised

The framework works in the same units you already think in — a repertoire of sequences, grouped into clonal lineages, each reconstructed as a lineage tree.

Conceptual data flow. Your dataset is a B-cell receptor repertoire: an AIRR or Change-O table of aligned antibody sequences. Sequences are grouped into clonal lineages (clones) — each clone is one B-cell lineage. One of the four methods (Dowser, GCtree, BrepPhylo, ClonalTree) performs phylogenetic inference to build a lineage tree per clone, with the germline at the root, the observed sequences at the tips, and inferred ancestral sequences at the internal nodes. From each tree the framework produces reconstructed sequences (germline and ancestral), evolutionary analyses (isotype or class switching, selection, measurable evolution over time), and figures and tables (lineage-tree plots, per-clone tables, downloadable bundles).
Your dataset is a repertoire of aligned BCR sequences. Sequences are grouped into clones (clonal lineages). Each clone becomes a lineage tree — germline at the root, your observed sequences at the tips, and inferred ancestral sequences at the internal nodes — from which the framework derives reconstructed sequences, evolutionary analyses, and figures. The four methods differ in how they build that tree, but they share this shape.

What each method takes in and gives back

All four start from the same kind of data — clonally-related, aligned BCR sequences — and return a lineage tree per clone, but they emphasise different biology. The exact input columns are on the Data requirements page; here is the biology.

Dowser

B-cell receptor phylogenetics in the Immcantation framework

Dowser is an R package in the Immcantation framework for reconstructing and analysing B-cell receptor (BCR) phylogenies. It builds lineage trees from BCR sequences, reconstructs germline and intermediate (internal-node) sequences, and statistically tests for evidence of B-cell evolution, migration and differentiation.

Takes in

CSVTSVRDARDS

Clonally-related, aligned BCR sequences with their clone assignments (and, where the method uses them, germline references and V/J calls).

Gives back

  • Lineage trees, one per clone (Newick)
  • Per-tree detail — tip labels, node table, reconstructed sequences
  • Rendered lineage-tree figures
  • Per-tip annotations for plotting
  • Clone summary (clone id + sequence count)
  • Run summary statistics
  • Input quality-control summary
  • Data provenance (transformations applied to your data)
  • Discrete trait analysis — trait switching along the tree (e.g. isotype, tissue)
  • Measurable-evolution / time-resolved analysis
  • IgPhyML selection parameters
  • Heavy / light chain QC

Notable analyses

Multiple tree builders: pratchet, pml, dnapars, dnaml, IgPhyML and RAxMLGermline and intermediate (internal-node) sequence reconstructionDiscrete trait analysis (migration, differentiation, isotype switching)Measurable-evolution / time-resolved analysisPaired heavy/light chain supportPublication-quality lineage visualisations

GCtree

Abundance-aware maximum-parsimony B-cell lineage trees

GCtree is a command-line utility and Python package that uses sequence abundance information in phylogenetic inference. It reconstructs genotype-collapsed B-cell lineage trees by combining PHYLIP/dnapars maximum-parsimony analysis with a branching-process ranking that breaks ties between equally parsimonious trees using observed clonal abundances.

Takes in

FASTACSVTSVZIP

Clonally-related, aligned BCR sequences with their clone assignments (and, where the method uses them, germline references and V/J calls).

Gives back

  • Lineage trees, one per clone (Newick)
  • Display Newick
  • Rendered lineage-tree figures
  • Per-tip annotations for plotting
  • Observed abundance per node
  • Tip-label ↔ sequence-id map
  • Clone summary (clone id + sequence count)
  • Run summary statistics

Notable analyses

Phylogenetic inference that incorporates sequence abundancePHYLIP/dnapars parsimony combined with branching-process rankingGenotype-collapsed lineage-tree representationRe-ranking and re-rendering from a saved forest pickleIsotype annotation and customisable tree rendering / output formats

BrepPhylo

B-cell repertoire lineage trees with class-switch analysis

BrepPhylo is an R package that reconstructs evolutionary lineages of B-cell clonotypes from high-throughput immunoglobulin sequencing data. It wraps established phylogenetic tools so researchers can build lineage trees, identify Class-Switch Recombination (CSR) events, and generate interpretable outputs.

Takes in

CSVTSV

Clonally-related, aligned BCR sequences with their clone assignments (and, where the method uses them, germline references and V/J calls).

Gives back

  • Lineage trees, one per clone (Newick)
  • Rendered lineage-tree figures
  • Per-tip annotations for plotting
  • Clone summary (clone id + sequence count)
  • Analysis — germline distance, class-switch (CSR) events, arborescence
  • Per-row / per-clone diagnostics (dropped, rejected, unmapped rows)
  • Run summary statistics

Notable analyses

Tree construction via simple parsimony, DNAPARS or IgPhyMLClass-Switch Recombination (CSR) / arborescence analysisSpecies-specific germline reference handling (with custom germline sets)Handles both raw sequences (MSA) and IMGT-gapped alignmentsPer-clone and gathered phylogeny plots in several styles

ClonalTree

Minimum-spanning-tree B-cell lineage reconstruction

ClonalTree reconstructs B-cell receptor lineage trees from clonally related sequences. It uses a minimum-spanning-tree algorithm combined with genotype abundance information to infer parsimonious trees representing the evolutionary relationships within a clone.

Takes in

TSVCSV

Clonally-related, aligned BCR sequences with their clone assignments (and, where the method uses them, germline references and V/J calls).

Gives back

  • Lineage trees, one per clone (Newick)
  • Rendered lineage-tree figures
  • Per-tip annotations for plotting
  • Observed abundance per node
  • Tip-label ↔ sequence-id map
  • Clone summary (clone id + sequence count)
  • Full clone catalog
  • Data tables (e.g. clonotype / repertoire info)
  • Data provenance (transformations applied to your data)
  • Run summary statistics

Notable analyses

Minimum-spanning-tree lineage reconstruction with abundance weightingAIRR/IMGT formatting, clustering and refinement pipelineConfigurable distance methods (V, J, CDR3) and clonotype grouping (L1–L5)Optional tree revisionNewick output plus parent-relationship / cost tables

Outputs you can download

Every run keeps its outputs so you can revisit, compare and export them. Beyond the on-screen trees, a run produces files of these kinds:

  • image — rendered lineage-tree plots (PNG/SVG/PDF)
  • newick — the trees themselves, for use in other tools
  • fasta — germline and reconstructed ancestral sequences
  • table — per-clone / per-node data tables (TSV/CSV)
  • json — structured node metadata and statistics
  • zip — a bundle of everything for one run

(Full set of artifact kinds: image, newick, table, fasta, json, log, zip, other.) You download or preview these from the run in the dashboard — the framework serves the files to you; you never touch the storage layer directly.

See the full input-column matrix

Under the hood: database schema

For developers and reproducibility: the persistent entities that record every dataset, run and output. A biologist can safely skip this — it is the storage counterpart of the conceptual model above, not new biology.

Entity-relationship diagram of the PostgreSQL schema. A users table (id, email, username) has one-to-many relationships to runs, files and upload_sessions. A runs table (id, user_id, input_file_id, method_id, status, stage, params JSONB, result JSONB) has one-to-many relationships to run_trees (tree_index, tree_id, newick), run_artifacts (object_key, artifact_kind, artifact_role, is_previewable, storage_state), job_queue (job_id, status), and to files as run outputs. A run references its input dataset via runs.input_file_id, and an upload_session references its committed file via final_file_id.
In scope: the persistent entities and their foreign-key relationships (key columns only). runs.result is a lightweight summary; the actual sequences, trees and figures are stored as files (run_artifacts), while run_trees holds the per-clone Newick and node metadata used to draw and trace lineages.