phyloannot

Generate annotation files for phylogenetic visualization from a metadata table.

Overview

phyloannot is a Python command-line tool that automatically infers metadata types and generates annotation files for phylogenetic visualization platforms, including iTOL, Microreact, and ggtree.

Instead of manually creating annotation files for each visualization platform, phyloannot automatically infers metadata types, creates an editable annotation configuration, and exports platform-specific annotation files from a single metadata table.

Workflow

                    metadata.tsv
                         │
                         ▼
               phyloannot --init-config
                         │
                         ▼
                 annotation_config.tsv
                         │
                   (review and edit)
                         │
                         ▼
                     phyloannot
                         │
        ┌────────────────┼────────────────┐
        ▼                ▼                ▼
      iTOL          Microreact         ggtree

Features

• Automatic metadata type inference
• Editable annotation configuration
• Native export for iTOL
• Native export for Microreact
• Metadata export for ggtree
• Automatic colour palette generation
• Support for categorical, binary, continuous and date variables
• Automatic legend generation
• Reproducible annotation workflow

Installation

Requirements

• Python ≥3.10

Clone the repository and install phyloannot in editable mode:

git clone https://github.com/irvink182/phyloannot.git
cd phyloannot
pip install -e .

Quick start

The repository includes a synthetic example dataset in the examples/ directory.

Step 1. Generate the annotation configuration

Infer metadata variable types and create the annotation configuration file:

phyloannot \
    --metadata examples/metadata.tsv \
    --init-config \
    --outdir results

This command creates:

results/
└── annotation_config.tsv

Step 2. Review the annotation configuration

Inspect annotation_config.tsv and modify any annotation settings as needed.

For each metadata variable, you can customise:

• Variable type
• Representation
• Colour palette
• Display order
• Legend visibility
• Export dataset

The inferred annotation configuration can be reviewed and edited before exporting.

Column	Type	Representation	Palette
Host	categorical	colorstrip	Glasbey
Collection date	date	gradient	Viridis
...

Step 3. Generate annotation files

Generate annotation files for all supported platforms:

phyloannot \
    --metadata examples/metadata.tsv \
    --config results/annotation_config.tsv \
    --itol \
    --microreact \
    --ggtree \
    --outdir results

The output directory will contain:

results/

├── annotation_config.tsv
├── itol/
├── microreact/
└── ggtree/

Input metadata

Column	Description
Taxon	Tree tip identifier (required)
Sample ID	Sample identifier
Host	Host species
Collection date	Sampling date
Country	Geographic origin

The only required column is Taxon, which must exactly match the tip labels in the phylogenetic tree.

Automatic metadata inference

phyloannot automatically infers the metadata type of each variable and assigns sensible default annotation settings. These defaults can be edited in annotation_config.tsv before exporting the annotation files.

Metadata type	Description	Default representation	Default palette
Identifier	Tree tip identifiers	Ignore	—
Text	Sample names or free text	Text	—
Binary	Two-level categorical variables	Color strip	Set1
Categorical	Discrete variables	Color strip	Glasbey
Continuous	Numeric variables	Gradient	Viridis
Date	Sampling or temporal variables	Gradient	Viridis

Annotation configuration

The annotation_config.tsv file is automatically generated by phyloannot and defines how each metadata variable will be represented in the exported annotation files. Before exporting, users can review and modify these settings to customise the final visualisation.

Column	Description
Column	Name of the metadata variable.
Data type	Data type detected from the input metadata (string, numeric, or date).
Type	Metadata type inferred by phyloannot (identifier, text, binary, categorical, continuous, or date).
Unique entries	Number of distinct values present in the metadata column.
Missing	Number of missing values detected.
Palette	Colour palette assigned to the variable (e.g. Glasbey, Set1, Viridis).
Order	Display order of the annotation in the exported files.
Legend	Whether a legend will be generated for the variable (True or False).
Representation	Graphical representation used for the variable (e.g. colorstrip, gradient, label, text, or ignore).
Dataset	Export dataset type used by the selected platform (e.g. DATASET_COLORSTRIP, DATASET_GRADIENT, TREE_COLORS).

Note: The inferred configuration is intended as a starting point rather than a fixed annotation scheme. Users can freely modify variable types, graphical representations, colour palettes, display order, legends, and dataset types to suit the requirements of their analysis.

Exporters

Supported exporters

Platform	Output	Description
iTOL	Annotation datasets	Generate DATASET_COLORSTRIP, DATASET_GRADIENT and TREE_COLORS files.
Microreact	Metadata table	Generate a metadata table compatible with Microreact, including optional geographic coordinates.
ggtree	Metadata table	Generate a metadata table ready to be merged with phylogenetic trees in R using ggtree.

iTOL

iTOL supported datasets:

• DATASET_COLORSTRIP
• DATASET_GRADIENT
• TREE_COLORS

Microreact

phyloannot exports a metadata table compatible with Microreact.

Geographic coordinates

Microreact can display samples on an interactive map.

Coordinates can be added using:

--location
--location-file

The coordinate file must contain three columns:

location    latitude    longitude

Built-in coordinate resources

phyloannot includes coordinate tables for Spain:

• spanish_communities.tsv
• spanish_provinces.tsv

These files can be used directly with --location-file

phyloannot \
    --metadata metadata.tsv \
    --config annotation_config.tsv \
    --microreact \
    --location Country \
    --location-file coordinates.tsv

Note: Geographic coordinates are optional. If no coordinates are provided, the metadata table is still fully compatible with Microreact.

ggtree

phyloannot exports a metadata table ready to be merged with phylogenetic trees using ggtree.

Example dataset

The repository contains a fully synthetic example dataset:

examples/

├── metadata.tsv
└── tree.nwk

The example demonstrates all metadata types supported by phyloannot.

Output structure

results/

├── annotation_config.tsv
├── itol/
│   ├── Host.txt
│   ├── Country.txt
│   ├── Collection_date.txt
│   └── ...
├── microreact/
│   └── microreact_metadata.tsv
└── ggtree/
    └── ggtree_metadata.tsv

License

This project is distributed under the MIT License.