GCtree

Abundance-aware maximum-parsimony B-cell lineage trees

Accepts:FASTACSVTSVZIP

What it does

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.

It natively expects an aligned FASTA with a root/germline plus abundance information (or a dnapars outfile and abundance bundle, or a previously computed GCtree forest pickle for re-ranking/re-rendering).

Phylogenetic inference that incorporates sequence abundance
PHYLIP/dnapars parsimony combined with branching-process ranking
Genotype-collapsed lineage-tree representation
Re-ranking and re-rendering from a saved forest pickle
Isotype annotation and customisable tree rendering / output formats

Accepted input types

Input type	What the framework does with it
Aligned FASTA	Aligned sequences with a root/germline ID; converted to PHYLIP and run through dnapars, then ranked by GCtree.
CSV / TSV	Tabular AIRR/Change-O-style input. The framework converts the aligned-sequence column to FASTA before inference — enabling GCtree on tabular data it cannot natively read.
ZIP	A pre-built bundle described by a manifest.json — used to run GCtree ranking, re-render a saved forest, or apply isotype annotation directly, skipping the FASTA/dnapars steps. See “ZIP bundle format” below for the exact layout and the mandatory / optional files for each scenario.

ZIP bundle format

Because GCtree natively takes several different inputs (an aligned FASTA, a dnapars outfile + abundances, or a saved forest pickle), a ZIP upload is not just a folder of files — it is a self-describing bundle. A manifest.json at the top declares which scenario the bundle is for and maps each named role to a filename, so the framework knows exactly how to run GCtree without guessing.

This is the input to use when you already have the intermediate artifacts and want to re-rank, re-render, or apply isotype annotation without re-running the parsimony search from scratch.

Archive layout

The archive must contain exactly one manifest.json, either at the archive root or inside a single top-level folder that also holds the data files (a common folder wrapper from zipping a directory is fine). Multiple manifest.json files, or none, are rejected.
manifest.json has two keys: "scenario" (one of the four values below) and "files" (an object mapping each role name to a filename, resolved relative to the manifest's own folder).
Every filename listed under "files" must actually exist in the archive next to the manifest; a missing file for any declared role fails the upload. Extra files not referenced by the manifest are ignored. macOS __MACOSX / dotfile entries are skipped automatically.

Example manifest.json

{
  "scenario": "dnapars_outfile_with_abundance",
  "files": {
    "dnapars_outfile": "outfile",
    "abundances_csv": "abundances.csv",
    "idmapfile": "idmap.txt",
    "isotype_mapfile": "isotypemap.csv",
    "idmapfile_isotype": "idmap_isotype.txt"
  }
}

Scenarios & their mandatory files

The manifest's scenario must be one of these values. Each row lists the roles that must appear under files for that scenario.

Scenario	Use it when	Mandatory files
aligned_fasta_with_root	You have an aligned FASTA (including the root/germline sequence) and want the framework to run dnapars and GCtree ranking for you.	`aligned_fasta` — Aligned sequences with the root/germline included; the starting point for parsimony inference.
airr_or_changeo_table_adapter	Same as above, but your sequences originate from an AIRR / Change-O table that has already been converted to an aligned FASTA for the bundle.	`aligned_fasta` — The aligned FASTA (with root) produced from the tabular data.
dnapars_outfile_with_abundance	You already ran PHYLIP/dnapars and want GCtree to rank the equally-parsimonious trees using your abundances — no re-inference.	`dnapars_outfile` — The raw dnapars `outfile` containing the parsimony trees. `abundances_csv` — Per-genotype abundances: two columns per line (sequence label, abundance ≥ 0), comma- or tab-separated, no header required.
gctree_forest_pickle	You have a previously computed GCtree forest and only want to re-rank, re-render, or annotate it (e.g. change the figure format or add isotypes).	`gctree_forest_pickle` — The saved GCtree forest pickle (.p) to re-load.

Optional files & their formats

These roles may be added to any scenario's files map. To apply isotype annotation, include isotype_mapfile (and an idmap).

idmapfile — Optional in any scenario. Maps dnapars/tree tip labels to your original sequence IDs — two columns per line (label, sequence_id), separated by whitespace, comma, or tab. Used to label nodes and as the default idmap for isotype annotation.
positionmapfile / positionmapfile2 — Optional site-position maps passed to GCtree's mutation annotation (`--positionmapfile` / `--positionmapfile2`); the `2` variant is for the second chain in paired-chain workflows.
isotype_mapfile — Required to apply isotype annotation. Maps each observed sequence ID to its isotype; consumed by the `gctree isotype` utility when the Apply isotype option is on.
idmapfile_isotype — Optional idmap used specifically for isotype annotation. If omitted, the run falls back to `idmapfile`, and then to the idmap GCtree generates internally.

Form fields

Every field shown in this method's form, generated from the package's field definitions so it always matches the live form. The mapping column is filled only where a field corresponds clearly to a native method parameter.

Input & Mapping

Field	What it is / used for	Allowed values	Default	Maps to method parameter	Visible when
Input scenario`input_scenario`Required	How GCtree is invoked: aligned FASTA (or FASTA from tabular adapter), DNAPARS outfile + abundances bundle (see upload guidance), or GCtree forest pickle re-ranking.	aligned_fasta_with_root, airr_or_changeo_table_adapter, dnapars_outfile_with_abundance, gctree_forest_pickle	aligned_fasta_with_root	—	Always
Enable input column mapping`doMapping`	When true and a CSV/TSV input is selected, map source table headers to canonical GCtree tabular keys before conversion.	Yes / No	No	N/A (wrapper-specific)	Shown when Input file format is one of csv, tsv
FASTA ID column`column_map.sequence_id`	—	text	—	N/A (wrapper-specific)	Shown when Enable input column mapping is enabled and Input file format is one of csv, tsv
Aligned sequence column`column_map.sequence_alignment`	—	text	—	N/A (wrapper-specific)	Shown when Enable input column mapping is enabled and Input file format is one of csv, tsv
Root sequence ID`root`	Original uploaded ID of the germline / outgroup sequence in the input FASTA alignment (FASTA-derived scenarios). It may be remapped internally to a short PHYLIP/GCtree-safe ID.	text	GL	—	Shown when Input scenario = aligned_fasta_with_root or Input scenario = airr_or_changeo_table_adapter

Inference & Ranking

Field	What it is / used for	Allowed values	Default	Maps to method parameter	Visible when
Coding frame (1–3)`frame`	Reading frame for amino-acid mutation annotation in GCtree (GCtree CLI --frame).	1, 2, 3	1	GCtree CLI `--frame` (reading frame for amino-acid mutation annotation).	Always
Number of trees to return`top_n`	Maximum top ranked trees to extract from GCtree output. GCtree normally renders/ranks a limited set of representative top trees.	integer (1–10)	3	Number of top-ranked trees extracted from GCtree output.	Always
Ranking strategy expression`ranking_strategy`	GCtree ranking expression using non-experimental/simple criteria only: B = branching process log loss, A = number of alleles, R = sitewise reversions to the naive/root sequence. Lexicographic examples: B,A or B,R,A. Linear examples: B+0.01A or B+0.1R+0.01A. Experimental criteria I, C, and M are not accepted.	text	B,A	GCtree ranking expression (B = branching-process log-loss, A = alleles, R = reversions).	Always
Quick parsimony search`quick`	If true, pass --quick to mkconfig/dnapars for a faster but less exhaustive parsimony search.	Yes / No	No	`--quick` passed to mkconfig/dnapars for a faster parsimony search.	Shown when Input scenario = aligned_fasta_with_root or Input scenario = airr_or_changeo_table_adapter
DNAPARS jumble replicates`jumble`	If set, pass --jumble N to mkconfig so DNAPARS searches N random permutations of the input sequences.	integer (≥ 0)	0	`--jumble N` passed to mkconfig (DNAPARS random input orderings).	Shown when Input scenario = aligned_fasta_with_root or Input scenario = airr_or_changeo_table_adapter

Output Rendering

Field	What it is / used for	Allowed values	Default	Maps to method parameter	Visible when
Image file type`img_type`	Image format for GCtree output figures (CLI --img_type).	svg, png, pdf	svg	GCtree CLI `--img_type` (output figure format).	Always
Output basename`outbase`	Basename for GCtree outputs (CLI --outbase). Files like '<outbase>.inference.1.svg' will be created.	text	gctree.out	GCtree CLI `--outbase` (output basename).	Always
Label nodes with sequence IDs`idlabel`	Pass --idlabel so tree images are labeled with unique sequence IDs and a FASTA alignment of inferred sequences is written.	Yes / No	No	GCtree CLI `--idlabel` (label nodes with sequence IDs; writes inferred-sequence FASTA).	Always
Show nucleotide mutations on branches`show_nucleotide_mutations`	If true, pass --show_nucleotide_mutations to annotate rendered trees with nucleotide changes.	Yes / No	No	GCtree CLI `--show_nucleotide_mutations`.	Always
Summarize forest`summarize_forest`	If true, pass --summarize_forest and write a forest summary log for all trees in the parsimony forest.	Yes / No	No	GCtree CLI `--summarize_forest`.	Always
Compute detailed tree statistics`tree_stats`	If true, pass --tree_stats and generate per-tree statistics and pairplot figures (can be slow for large forests).	Yes / No	No	GCtree CLI `--tree_stats`.	Always
Apply coloring settings`apply_coloring_settings`	—	Yes / No	No	—	Always
Coloring mode`color_mode`	Extra simplified coloring on the top-ranked GCtree tree: abundance (linear, viridis) or local branching index LBI (log, viridis). none skips extra colored render.	none, abundance, LBI	none	—	Shown when Apply coloring settings is enabled

Advanced

Field	What it is / used for	Allowed values	Default	Maps to method parameter	Visible when
Coding frame for second chain (advanced)`frame2`	When set, passed as --frame2 to GCtree for paired-chain workflows.	1, 2, 3	—	GCtree CLI `--frame2` (second-chain frame, paired-chain workflows).	Always
Chain split (advanced)`chain_split`	When greater than 0, passed as --chain_split to GCtree.	integer (≥ 0)	0	GCtree CLI `--chain_split`.	Always
Add isotype annotation/rendering`apply_isotype`	After a successful inference, run the GCtree isotype utility when idmap and isotype map files are provided (zip bundle). This can change tree rendering when resolving isotype conflicts; it is not simple coloring.	Yes / No	No	Invokes GCtree's isotype-annotation utility (idmap + isotype map bundle).	Always

Conditional fields & behaviour

Fields that appear or change based on other inputs

The column-mapping toggle and fields appear only for CSV/TSV input (the FASTA-conversion path).
Root sequence ID, quick search and jumble apply only to the FASTA-derived scenarios; the extra coloring mode appears only when coloring settings are enabled.