How to use PhyloFlask

A complete, plain-language guide — written so a biologist who has never coded and a programmer who has never opened a genome can both run the whole analysis. Read top-to-bottom the first time; after that, jump to the tool you need.

For biologists

You bring the biological question and the BLAST file. We explain every button and what the numbers mean — no programming required. Everything runs in your browser.

For programmers

You know files and matrices. We explain the biology — genomes, domains, homology, profiles — so the inputs, outputs and “why” make sense.

§1The 30-second idea

Some genes/proteins tend to appear and disappear together across species through evolution. If two proteins are almost always present in the same organisms and absent in the same organisms, they are probably doing related jobs (same pathway or molecular machine). PhyloFlask measures these presence/absence patterns across many species and turns them into interactive trees, clusters and heatmaps so you can spot those relationships and form hypotheses.

BLAST file Matrix (species × domains) Tree Clusters Heatmaps

§2Background — the biology (for programmers)

Just enough biology

Genome — all the DNA of an organism. Proteome — all the proteins it can make.
Protein domain — a reusable functional “part” of a protein (like a function in code). Proteins are built from domains.
Homology / BLAST — BLAST is a search tool that finds, for one query sequence, the similar (homologous) sequences in other species’ proteomes. A good match (low E-value) means “this species also has this domain”.
Phylogenetic profile — for one domain, the row of yes/no (1/0) across all species: present or absent. That row is the profile.
Why it works — functionally linked proteins are usually gained/lost together, so their profiles look alike.

§3Background — the computing (for biologists)

Just enough computing

CSV file — a plain spreadsheet saved as text (commas separate columns). You can open it in Excel.
Matrix — just a table. Here: rows = species, columns = domains, each cell = how many hits / a 0.
Upload — you pick a file from your computer; it is sent to the app, which reads it and draws the result. Nothing is installed.
Where results go — downloads (CSV, tree files, PNG images) save to your computer’s Downloads folder.
You don’t need a terminal — everything here is point-and-click in the browser.

§4Quick start (5 steps)

Open BLAST Analysis and drop in your BLAST file (or the bundled example). Choose Correlation matrix and click Start analysis. Download the CSV.
Build a tree: open Tree builder, upload that correlation CSV, start construction, and download the .nw tree.
Explore the tree: open Tree viewer, upload the .nw, click nodes to expand, search a species.
Find domain modules: open All-vs-all, upload the same correlation CSV; explore the cluster network and the linked heatmap.
Inspect patterns: open Heatmap with a feature/correlation CSV; pick a feature, filter, zoom, click cells.

§5Every tool, in detail

BLAST Analysis

What it is

Reads a BLAST results file and turns it into a species × domain table.

When to use

First — every other tool needs the matrix it produces.

Input

A BLAST tabular file (-outfmt 6; .blastp/.tsv/.txt). Each line is one hit: a query domain matched a species’ protein.

Controls

Drop-zone — drag a file in or click to browse.
Analysis type — Correlation matrix (presence/abundance counts, the usual choice) or Feature matrix (each cell holds extra numbers: %identity, bitscore, e-value, #hits).
Start analysis — builds and offers the CSV to download.

What you see

A progress message, then a Download button.

Why this way

A hit only counts as “present” when its E-value ≤ 1e-5, so weak/random matches don’t pollute the profiles.

Tree builder

What it is: Builds a species tree from how similar the species’ domain profiles are.
Input: The correlation matrix CSV from BLAST Analysis.
Controls: Drop-zone + Start construction. A progress bar runs while it works (large trees take a while), then a Download .nw link appears.
What you see: A 3-step workflow indicator and the download link for the Newick tree.
How to read it: Species that sit close together share most of their domain content. Open the file in the Tree viewer to explore it.
Why this way: Distance = Jaccard distance between presence/absence profiles; the tree is grown by Neighbour-Joining. It reflects shared gene content, which is related to (but not identical to) the classic species phylogeny.

Tree viewer

What it is

An interactive radial viewer for any Newick (.nw) tree.

You can do & edit

Click a node to collapse/expand its branch.
Expand-to-depth slider, Expand all, Collapse.
Search a species → it highlights the path from the root to that leaf.
Scroll to zoom, drag to pan; hover a node for its descendant count.

Colours

Leaves are coloured by genus; blue dots mark collapsed branches you can open.

Why this way

Real trees have hundreds of leaves — collapsing keeps it readable; genus colours show at a glance whether relatives group together.

All-vs-all (domain clustering)

What it is

Groups domains that share a profile into clusters (candidate functional modules) and shows them as a network.

Input

The correlation matrix CSV.

You can do & edit

Hover a node → tooltip (domain, cluster, #links); click → isolate its cluster.
Min-similarity slider → hide weak links to reveal structure.
Layout switcher (force / concentric / circle / grid).
Co-cluster heatmap below is linked: click a cell to jump to that domain in the network, click a node to highlight its row/column.

How to read it

Node colour = cluster, size = number of links. The result note reports cluster count and modularity (see §6).

Why this way

Edges connect domains with Jaccard similarity ≥ threshold, then Markov Clustering finds communities — domains that co-occur are likely functionally linked.

Heatmaps

What it is

A colour grid of the matrix — quickly see which domains are present/abundant in which species.

Input

A feature or correlation matrix CSV (processed in your browser).

You can do & edit

Pick a feature, filter by min hits.
Toggle log scale and ordering (group-similar / alphabetical).
Box-zoom a region, download a PNG, and click a cell to read its full numbers.

Why this way

Log scaling and ordering make broad patterns visible across hundreds of domains at once.

§6Reading the results

Tree distances

Short branches between two species = very similar domain content. Long branches = different repertoires.

Clusters

Domains in one colour co-occur across species — a hypothesis that they share a function.

Modularity Q

Q ≈ 0 → no real grouping (profiles too uniform). Q > 0.3 → clear, trustworthy modules.

If you see “little/no structure”, the data simply doesn’t separate into modules — try a stricter E-value cutoff or richer data. That’s an honest result, not an error. More in the FAQ.

§7Glossary (both languages)

Term	In biology	In computing
Domain	A functional part of a protein	A column in the matrix; a graph node
Species	An organism / proteome	A row in the matrix; a tree leaf
Profile	Presence/absence of a domain across species	A binary vector (row/column of 0s and 1s)
BLAST hit	A detected homolog	One line of the input file
Jaccard	How much two repertoires overlap	shared / union of two binary sets
Newick (.nw)	A tree of species	A text format like `(A,(B,C));`
Cluster	A candidate functional module	A community of connected graph nodes

§8Tips & troubleshooting

Local address is http://127.0.0.1:8000 — on macOS, port 5000 is taken by AirPlay.
Run BLAST Analysis first; most tools need its correlation matrix.
Big trees are slow to build (the method is O(n³)); the progress bar keeps you informed.
Stuck on a concept? The FAQ answers the common questions in depth.

Start with BLAST Analysis Read the FAQ