Metadata-Version: 2.5
Name: grapetree
Version: 3.0.0
Summary: Web interface of GrapeTree, which is a program for phylogenetic analysis.
Project-URL: Homepage, https://github.com/achtman-lab/GrapeTree
Project-URL: Bug Reports, https://github.com/achtman-lab/GrapeTree/issues
Project-URL: Source, https://github.com/achtman-lab/GrapeTree
Author-email: EnteroBase development team <zhemin.zhou@warwick.ac.uk>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: MLST,bioinformatics,genomics,microbial,visualisation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: ete3
Requires-Dist: flask
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: psutil
Requires-Dist: requests
Requires-Dist: standard-cgi; python_version >= '3.13'
Requires-Dist: unidecode
Description-Content-Type: text/markdown

# GrapeTree

[![CI](https://github.com/achtman-lab/GrapeTree/actions/workflows/ci.yml/badge.svg)](https://github.com/achtman-lab/GrapeTree/actions/workflows/ci.yml)
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Docs Status](https://readthedocs.org/projects/enterobase/badge/)](http://enterobase.readthedocs.io/en/latest/grapetree/grapetree-about.html)

**[Launch a local version of GrapeTree!](https://achtman-lab.github.io/GrapeTree/MSTree_holder.html)**

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](https://www.google.com/chrome/index.html) for best results.

**For detailed help please see: [http://enterobase.readthedocs.io/en/latest/grapetree/grapetree-about.html](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
](https://doi.org/10.1101/gr.232397.117
)**

## Installing and Running GrapeTree
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`.

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

**Running on Mac: Download GrapeTree-macOS-Intel.zip**

Unzip the archive and drag `GrapeTree.app` into the Applications folder. This
build currently targets Intel Macs. It can run on Apple silicon through Rosetta
2, but a native Apple-silicon release requires native builds of all three
bundled tree executables. Published applications are not yet code-signed 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.
1. 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](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.

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

Developers may wish to look at the [JavaScript documentation](https://achtman-lab.github.io/GrapeTree/documentation/developer/index.html) (JSDoc).

### Tests

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

```
python -m pip install . pytest
python -m pytest
```

### Building distributions

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
```

### Docker

Build and run the supported container from the repository root:

```bash
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.

## Usage - Command line module for generating Trees

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:

```bash
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.

### Compatibility changes in 3.0.0

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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/achtman-lab/GrapeTree/blob/master/documentation/asymmetricDistances.pdf),
[`--recraft`](https://github.com/achtman-lab/GrapeTree/blob/master/documentation/branchRecrafting.pdf),
and
[`--heuristic`](https://github.com/achtman-lab/GrapeTree/blob/master/documentation/tiebreak.pdf).

### SNP-only alignments

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:

```bash
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.

### Ridom SeqSphere+

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`](documentation/ridom-seqsphere.md).

## Inputs
#### profile
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. 

#### Aligned FASTA
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.  

#### metadata
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.

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

#### distance matrix
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

## Command line examples
#### MSTree V2
```
python grapetree.py -p examples/simulated_data.profile -m MSTreeV2
```
#### NJ tree
```
python grapetree.py -p examples/simulated_data.profile -m NJ
```
#### distance matrix
```
python grapetree.py -p examples/simulated_data.profile -m distance
```

## License
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/>.

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

## Citation
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](https://doi.org/10.1101/gr.232397.117)
