Documentation — PhyloCloud

1.Uploading Trees

PhyloCloud accepts phylogenetic trees in three formats. All trees are validated and parsed using the ETE4 library before storage.

Newick .nwk

Standard Newick format. Leaf names are required; internal node names and branch lengths are optional.

NHX .nhx

Extended Newick format with arbitrary key=value annotations embedded in square brackets.

ETE .ete

Pre-annotated ETE binary format. Upload this to restore a fully annotated tree from an earlier export.

Go to Upload via the navbar or the Upload button on My Trees. Paste Newick text directly or select a file from disk.

Give the tree a name and optional description. Names must be unique per account.

Click Upload. The tree is parsed and stored. Leaf count and basic statistics are computed immediately.

Large trees: trees with up to 500,000 leaves upload and parse without issue. For very large datasets, contact us about batch imports.

2.Annotating Leaves

Annotations attach typed properties to tree leaves. Open any tree and click Annotate to start the annotation wizard.

TSV format

The primary annotation input is a tab-separated values (TSV) file. The first column must be the leaf name (matching names in the Newick). Remaining columns become properties.

name	taxonomy	genome_size	is_pathogen	pfam_count
Ecoli_K12	Bacteria;Proteobacteria;Gammaproteobacteria	4641652	true	312
Bsubtilis	Bacteria;Firmicutes;Bacilli	4215606	false	289
Scerevisiae	Eukaryota;Fungi;Saccharomycetes	12157105	false	1024

PhyloCloud auto-detects column types when you click Scan in the annotation form. You can override any detected type before running the annotation.

Property types

Type	Description	Example values	Layouts available
categorical	Discrete string categories	Bacteria, Fungi, Archaea	Text labels, Symbol, Categorical frequency
numeric	Integer or float scalar value	4641652, 3.14	Heatmap, Bar plot, Dot matrix, Gradient text, Branch colour
boolean	Bit-packed presence/absence matrix	true / false / 0 / 1	PA matrix, Presence count
num_array	Comma-separated numeric vector per leaf	0.1,0.4,0.9,0.2	Heatmap, Dot matrix, Range bar
free_text	Arbitrary text string	Gene function description…	Text labels
taxonomy	Semicolon-delimited lineage string	Bacteria;Proteobacteria;…	Taxonomy (majority-vote colouring)
sequence	Aligned or unaligned amino-acid / nucleotide sequence	MKVLQALGD…	Sequence (SeqFace)
pfam	Pfam domain hit table (TSV with start, end, accession columns)	separate file upload	Domain track

Additional input files can be attached per annotation run:

Alignment file — FASTA or Stockholm multiple-sequence alignment
Pfam file — domain hit table (separate from the main TSV)

Open a tree → click Annotate.

Upload your TSV (and optional alignment / Pfam files). Click Scan to auto-detect column types.

Review and adjust detected types, then click Run Annotation. The job runs in the background; progress is shown in real time.

When complete, click View to open the interactive viewer with all properties loaded.

3.Expand to Matrix

A categorical property can be expanded into a binary presence/absence (PA) matrix. Each unique category value becomes a boolean column: 1 if the leaf belongs to that category, 0 otherwise.

Before (categorical)

name      phylum
Ecoli     Proteobacteria
Bsubtilis Firmicutes
Hpylori   Proteobacteria

After (PA matrix)

name      Proteo  Firm
Ecoli     1       0
Bsubtilis 0       1
Hpylori   1       0

To expand a property:

Open a tree → go to the Annotations panel.
Find the categorical property and click Expand to matrix.
The new boolean columns appear immediately and can be used in PA matrix layouts.

Expanded columns are automatically propagated to internal nodes using the any/all method, giving you clade-level presence/absence summaries.

4.Propagation to Internal Nodes

Leaf annotations are propagated to internal nodes using a postorder traversal. Each internal node receives a summary value computed from its descendant leaves. This makes it possible to colour and visualise clades, not just leaves.

Method	Applies to	Result on internal node
`mean`	numeric	Average of all descendant leaf values
`min / max`	numeric	Minimum or maximum among descendants
`freq`	categorical	Frequency dict of category counts (used for pie/bar layouts)
`any`	boolean	`1` if any descendant is true
`all`	boolean	`1` only if every descendant is true
`stderr`	numeric	Standard error across descendant values

Propagation runs automatically after every annotation job. Propagated properties appear in the Annotations panel with a Propagated label and can be selected in any layout that supports internal node rendering.

Propagated properties are computed from leaf data; they are not independently editable. Re-annotating a property replaces both the leaf values and the propagated summaries.

5.Collections

Collections group related trees for a project, publication, or dataset. A tree can belong to multiple collections simultaneously.

Create a collection from My Collections or inline from the tree list (the button in the Collections column).
Add or remove a tree from a collection using the dropdown next to the tree row — no page reload required.
Collections can be set to public so others can browse all trees inside them without an account.
The collection detail page shows all trees, sortable by date, name, or leaf count.

6.Sharing & Privacy

Each tree has a visibility setting:

Private

Visible only to you. Default for all uploads.

Unlisted

Anyone with the direct URL can view the tree, but it won't appear in public listings.

Public

Visible in public collections and browseable by anyone without an account.

Toggle visibility from the tree list using the Public switch, or from the tree detail page via the Share button.

7.Interactive Viewer

The viewer renders trees using ETE4 SmartView — a WebGL-accelerated phylogenetic viewer that handles trees with hundreds of thousands of leaves without performance degradation.

Navigation

Scroll to zoom in/out
Click and drag to pan
Click any node to see its properties
Double-click to collapse or expand a clade

Controls

Layout editor — configure annotation panels
Reset view — fit the full tree on screen
Save config — store the current layout as a named preset
Download — export the current view as SVG or PNG

The viewer opens in a panel below the tree detail page. Use the full-screen button to expand the viewer to fill the browser window.

8.Layout Editor

The layout editor lets you attach annotation panels to the tree — one panel per property. Open it by clicking Layout Editor below the viewer. Changes are applied live without reloading the page.

Adding a layout

Click Add Layout to open the layout gallery.
Select a layout type (see table below). The gallery shows only types compatible with the properties on your tree.
Choose the property to visualise and configure display options (colour scale, width, label, etc.).
Click Apply. The panel appears immediately to the right of the leaf names.

Drag panels to reorder them. Click the icon to remove one. Click Save config to store the current setup as a named preset you can reload later.

Available layout types

Heatmap

Colour-coded cells for scalar or array properties. Supports per-column colour scales.

Bar plot

Horizontal bars proportional to a numeric value.

Dot matrix

Proportional circles; radius encodes value magnitude.

PA matrix

Binary presence/absence grid for boolean properties.

Range bar

Two-column array rendered as a min–max range bar.

Gradient text

Leaf name text coloured by a numeric value.

Text labels

Aligned text column for categorical or free-text properties.

Symbol

Colour-coded circle or square per leaf, one per category value.

Categorical frequency

Pie, donut, or stacked bar showing category proportions on internal nodes.

Branch colour

Colours tree branches by a numeric or categorical property value.

Taxonomy

Majority-vote lineage colouring on branches from a semicolon-delimited lineage string.

Sequence

Aligned sequence visualisation (SeqFace) for MSA properties.

Presence count

Integer count of how many boolean columns are true per node (popcount).

Using propagated properties in layouts

Propagated properties appear in the property selector with a Propagated tag. They can be used in any layout that renders internal nodes:

Categorical frequency layout uses the freq-propagated version of a categorical property to draw pie or bar charts on internal nodes, showing the distribution of categories within each clade.
Heatmap / bar plot / dot matrix use mean-propagated numeric properties to colour internal nodes by average descendant value.
PA matrix uses any-propagated boolean properties to fill cells on internal nodes when at least one descendant is positive.
Taxonomy layout automatically uses propagated lineage data to assign the majority lineage label to each clade.

If a propagated property does not appear in the selector, re-run annotation with propagation enabled. This happens automatically for all annotation jobs; it can also be triggered manually from the Annotations panel.

9.Exporting Data

Every tree can be exported in multiple formats from the tree list () or the tree detail page.

Format	Contents	Use case
`.nwk` Newick	Topology + branch lengths only	Input to external phylogenetic tools (RAxML, IQ-TREE, etc.)
`.ete` ETE binary	Full annotated tree including all properties	Re-upload to PhyloCloud; load locally with ETE4
`.nhx` NHX	Topology + key/value properties in NHX format	Import into tools that support NHX annotations
`.tsv` TSV	Leaf property table (all annotated columns)	Analysis in R, Python, spreadsheet tools