PEAR logo

Phylogeny Embedding &
Approximate Representation

Goldman Group - European Bioinformatics Institute ¶

PEAR can: 1. Compute the distance matrix given a set of phylogenetic trees; 2. Embed and represent the distance matrix in 2D or 3D.

See also the autogenerated documentation and PyPI .

PEAR usage¶

Pear is both a python software and library. It can be installed with python -m pip install pear_ebi or downloaded from Github. Pear requires Python 3.10 - 3.13 and runs on Linux (x86-64) and macOS (Apple silicon); it ships prebuilt HashRF and tqDist binaries for both.

Reproducible environments¶

Dependencies are managed with Poetry. From a checkout:

poetry install

installs the exact versions recorded in poetry.lock, which is the authoritative record of a known-good environment. Add --with docs for the documentation toolchain, or install the notebook extra (pip install "pear_ebi[notebook]") for Jupyter.

PEAR runs on both NumPy 1.x and 2.x. There used to be a numpy<2 pin and an import-time check enforcing it; the incompatibility it guarded against did not survive testing, so the scientific stack (NumPy, pandas, SciPy, scikit-learn) now floats and Python 3.13 is supported.

If you use conda, note that packages must come from conda-forge (EMBL-EBI is no longer licensed for Anaconda's defaults channel). Miniforge is configured that way by default.

PEAR as a python library¶

Once installed, Pear can be used to upload Newick trees in python and represent them in embedded spaces. We recommend to use it on either jupyter notebook or lab, as these tools allow for more interaction with the graphs. On these platforms, the user is allowed to interact with widgets that allows to modify several parameters of the plots. For specific uses and applications, see the examples.

PEAR as a program¶

Run pear_ebi --help to see the complete list of arguments and flags.

Simple usage¶

The commands below are written to be run from the root of a clone of this repository, because they reference files under examples_tree_sets/. That directory is part of the repository, not of the PyPI package, so if you installed with pip install pear_ebi you will need to either clone the repository as well or substitute your own Newick file.

Note that the notebooks under examples_tree_sets/ use different working directories: How to use pear_ebi.ipynb expects to be run from examples_tree_sets/, and the two notebooks under Advanced Examples/ expect to be run from that folder. Paths in the .toml config files are resolved relative to the config file's own directory.

pear_ebi examples_tree_sets/beast_trees/beast_run1.trees -m hashrf_RF

this script calculates the unweighted Robinson Foulds distances between the trees in the file "beast_run1.trees", which contains 1001 phylogenetic trees.

the flag -m indicates the method used to compute the dissimilarity between phylogenetic trees. In this case, HashRF has been used.

To embed these distances in a lower-dimensional space, we can use PCoA (MDS) or tSNE:

pear_ebi examples_tree_sets/beast_trees/beast_run1.trees -m hashrf_RF --pcoa 2

we therefore embedded the distance matrix in 2 dimensions. Using the flag -q / --quality one can assess the correlation between the distances in the N-dimensional space and in the embedding.

pear_ebi examples_tree_sets/beast_trees/beast_run1.trees -m hashrf_RF --pcoa 2 --plot

The flag -p / --plot indicates that PEAR has to plot the embeddings and show them, respectively. If an embedding method is specified the plots are produced anyway. Plotting doesn't require any indication on the number of dimensions as the embeddings are represented in 2 dimensions if the distances are embedded in 2 dimensions, while it plots on 2 and 3 dimensions in any other case.

One can specify any number of files containing trees. Moreover, it is possible to specify a single directory using --dir, and possibly a pattern using --pattern, in order to select multiple files.

Tree Set¶

It's possible to compute the distance matrix and re-use it in subsequent runs of PEAR by specifying the distance matrix file with the flag -d. Additionally, it's possible to define the name of the output file (-o).

If any additional metadata is available, this may be specified by indicating a .csv file containing a dataframe of compatible shape.

Output files¶

Every file PEAR writes is named as it is written, so a run tells you what it produced:

hashrf_RF | Done!
Distance matrix  -> beast_run1_distance_matrix.csv
pcoa | Done!
Embedding        -> beast_run1_PCOA_embedding.csv
Plot (2D)        -> beast_run1_PCOA_2D.html

Names are derived from the input file and resolved against the current working directory, so paths inside it are shown relative to it and anything elsewhere is shown in full. Use -o to choose the distance-matrix path yourself.

Add -v / --verbose to see what PEAR resolved before it starts: which files were actually picked up (useful with --dir, where a glob can be surprising), how many trees each contributed, and which HashRF or tqDist binary will run — a copy found on your PATH takes precedence over the bundled one.

Config file¶

A standard config toml file can be used for specific embeddings of multiple sets of trees. Instances of toml files are reported in the examples folder.

Using the config file allows one to use all the features of PEAR, including additional embedding methods and plot designs. The config file can also be used to specify lists of indexes of interesting trees in the sets, in order to highlight them in the final plots.

Interactive mode¶

pear_ebi -i : this script launches the program in the interactive mode. Once the program starts, it is going to guide you through its usage thanks to an intuitive interface.

Tutorials and Examples¶

Follow this link for a complete set of basic and advanced guides and tutorials to use PEAR on the command line and as a python library.

Contributing and releasing¶

CONTRIBUTING.md covers the development setup, the test conventions and the release process. In short: releases are cut by the Release workflow from the Actions tab, which bumps the version, verifies the artefacts, publishes to PyPI, tags the commit and redeploys this documentation. Every push to pear_ebi rebuilds and redeploys the documentation on its own, so the published site never lags the branch.

Versions are plain MAJOR.MINOR.PATCH. Publishing relies on PyPI Trusted Publishing, which has to be enabled once on PyPI before the first automated release; CONTRIBUTING.md says how.

How to cite¶

If you use PEAR in published work, please cite the software and the version you used. CITATION.cff in the repository root carries the metadata, and GitHub turns it into a ready-made citation -- BibTeX, APA or plain text -- behind the "Cite this repository" button in the sidebar.

Licensing¶

This project is released under the terms of the MIT Open Source License. View LICENSE for more information.

Phylogeny Embedding & Approximate Representation