GrapeTree

Launch a local version of GrapeTree!

GrapeTree is an integral part of EnteroBase and we advise that you use GrapeTree through EnteroBase for the best results. However, many people have asked for a stand-alone GrapeTree version that they could use offline or integrate into the other applications.

The stand-alone version emulates the EnteroBase version through a lightweight webserver running on your local computer. You will be interacting with the program as you would in EnteroBase; through a web browser. We recommend Google Chrome for best results.

For detailed help please see: http://enterobase.readthedocs.io/en/latest/grapetree/grapetree-about.html

For a formal description, please see the accepted manuscript in Genome Research: https://doi.org/10.1101/gr.232397.117

There are number of different ways to interact with GrapeTree, for best results install via pip :

python -m pip install grapetree
grapetree

Use a virtual environment with Python 3.10 or newer. The grapetree command opens the local web application. The same installation also provides the tree-building command:

MSTrees.py --profile profiles.tsv --method MSTreeV2 > tree.nwk

On Windows, pip installs this command as MSTrees.exe; use MSTrees instead of MSTrees.py.

The bundled tree-building executables target Linux AMD64 (x86-64), Intel macOS (x86-64), Apple silicon macOS (ARM64), and Windows x64. Mac installations select the executables matching the Python architecture. Native ARM64 Linux executables are not yet provided.

We also have ready-made binaries for download here: https://github.com/achtman-lab/GrapeTree/releases

Running on Mac: Choose the AppleSilicon or Intel archive

Download GrapeTree-<version>-macOS-AppleSilicon.zip for an M-series Mac, or GrapeTree-<version>-macOS-Intel.zip for an Intel Mac. Unzip the archive and drag GrapeTree.app into the Applications folder. Both builds include native tree-building executables; the Apple-silicon build does not need Rosetta. Applications are not yet signed with an Apple Developer ID or notarised, so macOS may require explicitly allowing the application in Privacy & Security.

Running on Windows: Download GrapeTree-Windows.zip

Unzip the whole archive, keep its files together, and run GrapeTree.exe from the extracted folder. Unsigned development builds may trigger Windows SmartScreen; release signing remains a prerequisite for removing that warning.

Running from source code

GrapeTree supports Python 3.10 through 3.14. Install GrapeTree and its dependencies from the repository with pip:

python -m pip install .

For development, use an editable install with the test dependencies:

python -m pip install -e . pytest

On Linux or MacOSX you need to make sure the binaries in binaries/ can be executed. To run GrapeTree;

1. Navigate to the directory where you installed GrapeTree.
2. Run it through python as below.

\GrapeTree>python grapetree.py
 * Running on http://127.0.0.1:8000/ (Press CTRL+C to quit)

The program will automatically open your web browser and you will see the GrapeTree Splash Screen. If at anytime you want to restart the page you can visit http://localhost:8000 in your web browser. To view a tree (newick or Nexus) or create a tree from an allele profile, just drag and drop the file into the browser window.

Runtime behaviour can be configured in grapetree/module/config.py.

Developers may wish to look at the JavaScript documentation (JSDoc).

Install the package and pytest, then run the test suite from the top-level directory:

python -m pip install . pytest
python -m pytest

Package metadata and build configuration live in pyproject.toml. GrapeTree uses Hatchling as its build backend:

python -m pip install build
python -m build

A Bioconda-style recipe is available in conda/meta.yaml. It targets Linux and macOS on x86-64 because GrapeTree includes platform-specific tree-building binaries. With conda-build installed, render or build it using:

conda render conda -c conda-forge -c bioconda
conda build conda -c conda-forge -c bioconda

Build and run the supported container from the repository root:

docker build -t grapetree .
docker run --rm -p 8000:8000 grapetree

Then open http://localhost:8000. The image runs the same Flask-backed application under Gunicorn and includes the Linux MSTreeV2, NJ, and RapidNJ backends. It runs as an unprivileged user and does not include SSH or require mounting the source tree. To keep generated files outside the container, use the command-line wheel on the host or add an explicit bind mount for your own workflow; uploaded browser data is processed in the request and is not kept as a container volume.

Generate an MSTreeV2 Newick tree from a profile file:

grapetree --profile examples/simulated_data.profile > tree.nwk

Profiles can also be streamed on standard input by using - as the profile:

cat examples/simulated_data.profile | grapetree --profile - > tree.nwk

The supported methods are MSTreeV2 (default), MSTree, NJ, RapidNJ, ninja, and distance. Run grapetree --help for all current options and accepted values. Invalid methods, matrices, missing-data modes, heuristics, and profile paths are rejected before calculation with a concise command-line error.

The original tree-building entry point remains a single Python script. It can be run directly, or copied to another directory, with the Python dependencies installed:

python grapetree/module/MSTrees.py --profile examples/simulated_data.profile --method MSTreeV2 > tree.nwk

For NJ and RapidNJ, place the matching native executable in a binaries/ directory beside a copied script. Ninja also needs Ninja.jar there and a working Java installation. The installed grapetree command provides the additional JSON, network, and cluster export options.

The core script moved from module/MSTrees.py to grapetree/module/MSTrees.py. Update scripts that use the old source path or import module.MSTrees; the installed import is now from grapetree.module.MSTrees import backend. The calculation and its core CLI remain in one Python file. Python 3.10 or newer is required.

Two corrected options can change scientific results compared with older versions:

• --missing 1 (complete deletion) now retains only loci called in every sample. Previously it selected loci containing missing calls.
• --wgMLST now selects the weighted asymmetric distance calculation; previously the flag did not take effect.

Duplicate taxon IDs, including IDs that collide after sanitisation, now produce an error instead of ambiguous output. Ninja works with modern Java without the obsolete -d64 option. One-profile MSTree/MSTreeV2 failures and exclusion of completely missing profiles remain known limitations.

Create a reloadable GrapeTree visualisation document from an existing Newick tree and optional tab- or comma-delimited metadata:

grapetree --json --treefile tree.nwk --meta metadata.tsv > ms_tree.json

The metadata identifier column should be named ID; when it is absent, the first column is used. Duplicate or blank identifiers are rejected. The JSON can be dropped onto either the standalone or server-backed GrapeTree interface. An existing ms_tree.json saved from the interface is opened the same way: press Load Files and choose it, paste its contents into the load dialog, or drag it onto the graph. It already contains the tree, metadata, colours, and saved layout, so it must be loaded as a tree document rather than as metadata.

The GitHub Pages site is a static visualiser. It can load Newick, Nexus, and GrapeTree JSON documents, but it cannot calculate a tree from an allele/SNP profile because there is no Python/native backend behind /maketree. Use the standalone server, Docker image, or a precomputed tree. The separate browser-wasm/ track is intended to remove that limitation without changing the established Flask application.

Export the same tree as an undirected network for igraph, NetworkX, or other analysis tools:

grapetree --treefile tree.nwk --network-format graphml > tree.graphml
grapetree --treefile tree.nwk --network-format csv > edges.csv
grapetree --treefile tree.nwk --network-format json > network.json

These export flags also accept --profile instead of --treefile, calculating the selected tree method before serialising it.

To reproduce the interface's “collapse nodes” cluster memberships at several cutoffs, request all thresholds in one command:

grapetree --treefile tree.nwk --clusters 0 1 2 5 10 > clusters.tsv

For each cutoff, links with distance less than or equal to the value are joined into a component, exactly matching the UI rule. Cluster labels are stable and deterministic (C1, C2, …); the memberships, rather than the arbitrary label text, are the scientifically meaningful result. --profile can again replace --treefile to calculate and cluster in one call.

Detailed descriptions are available for --matrix, --recraft, and --heuristic.

A SNP-only alignment can reduce input size without changing ordinary Hamming distances when every omitted site is genuinely invariant and samples have no missing/ambiguous calls there. MSTreeV2's branch-recrafting model also uses the number of loci, however, so silently treating the SNP count as the original alignment length can change the topology. Supply the original alignment length to preserve that model:

grapetree --profile variable-sites.fasta --method MSTreeV2 \
  --total-loci 2849012 > tree.nwk

Do not remove constant sites if they contain missing calls, and do not treat a SNP-only tree as directly comparable when ascertainment/filtering differs. For memory-limited data, also consider --method MSTree, filtering samples with excessive missingness, or calculating on a machine with more memory; the pairwise distance matrix itself remains quadratic in sample count.

MSTreeV2's asymmetric missing-data model is directional: when technical replicates have different sets of uncalled loci, their directed distances can be much larger than the allele differences on their shared calls. That can separate otherwise close replicate runs, as in issue #82. This is expected for the published algorithm rather than a rendering error. Use --method MSTree when clustering should be based on pairwise-called overlap, and inspect/filter missingness before interpreting either tree.

Use SeqSphere+'s dedicated Export profile and metadata files for GrapeTree (TSV) action, not a generic comparison-table export. A complete two-file workflow, large-dataset checks, and the matching CLI commands are documented in documentation/ridom-seqsphere.md.

The profile file is a tab-delimited text file.

Follow an example here: https://github.com/achtman-lab/GrapeTree/blob/master/examples/simulated_data.profile

#Strain	Gene_1	Gene_2	Gene_3	Gene_4	Gene_5	Gene_6	Gene_7	...
0	1	1	1	1	1	1	1	...
1	1	1	1	1	1	1	1	...
2	1	2	2	2	2	2	2	...
...

The first row is required and represents column labels. It has to start with a '#'. Collumn labels that start with a '#' are treated as comments and will not be used in downstream analysis. The first column needs to be unique identifiers for strains. Each of the remaining rows presents a different strain.

Use '-' or '0' to represent missing alleles.

An aligned FASTA file contains multiple sequences of the same length in FASTA format. Many sequence alignment tools, e.g., MAFFT and MUSCLE, use FASTA as a default format for their outputs.

Find an example here: http://wwwabi.snv.jussieu.fr/public/Clustal2Dna/fastali.html

Note that GrapeTree supports only p-distance for the moment.

The metadata file is either a tab-delimited or a comma-delimited text file. This is only used for tree presentation in the standardalone version.

Follow an example here: https://github.com/achtman-lab/GrapeTree/blob/master/examples/simulated_data.metadata.txt

ID	Country	Year
0	China	1983
1	China	1984
...

The first row is required and describes the labels of the columns. If a column labeled with "ID" presents, it will be used to correlate metadata with profiles, otherwise the first column will be used.

The tree is described in NEWICK format. https://en.wikipedia.org/wiki/Newick_format

Use the option '--method distance' to generate a distance matrix without calculating the tree. The matrix is presented in PHYLIP format. http://evolution.genetics.washington.edu/phylip/doc/distance.html

python grapetree.py -p examples/simulated_data.profile -m MSTreeV2

python grapetree.py -p examples/simulated_data.profile -m NJ

python grapetree.py -p examples/simulated_data.profile -m distance

Copyright Warwick University This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Detailed information for the standard NJ implemented in FastME V2: http://www.atgc-montpellier.fr/fastme/

EnteroMSTree - GrapeTree has been formally accepted by Genome Research. Please use the citation:

Z Zhou, NF Alikhan, MJ Sergeant, N Luhmann, C Vaz, AP Francisco, JA Carrico, M Achtman (2018) "GrapeTree: Visualization of core genomic relationships among 100,000 bacterial pathogens", Genome Res; doi: https://doi.org/10.1101/gr.232397.117