Phylogeny Embedding &
Approximate Representation
Goldman Group - European Bioinformatics Institute 
PEAR can:
- Compute the distance matrix given a set of phylogenetic trees;
- 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.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pear_ebi-1.1.2.tar.gz.
File metadata
- Download URL: pear_ebi-1.1.2.tar.gz
- Upload date:
- Size: 2.4 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c80d70c813947e9a3029835cd6d18cf8eaf04ac075969a33467366ad340b4dd8
|
|
| MD5 |
b1fa4ad3c5d84e22832930d0884191fc
|
|
| BLAKE2b-256 |
3ca0b9d51762de69e61ca69bab88d9c94645ff2db604cabc89481552151bbb88
|
Provenance
The following attestation bundles were made for pear_ebi-1.1.2.tar.gz:
Publisher:
release.yml on AndreaRubbi/Pear-EBI
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pear_ebi-1.1.2.tar.gz -
Subject digest:
c80d70c813947e9a3029835cd6d18cf8eaf04ac075969a33467366ad340b4dd8 - Sigstore transparency entry: 2604358890
- Sigstore integration time:
-
Permalink:
AndreaRubbi/Pear-EBI@d379343e3e8024d299541870fa73eba4f0baa6dc -
Branch / Tag:
refs/heads/pear_ebi - Owner: https://github.com/AndreaRubbi
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@d379343e3e8024d299541870fa73eba4f0baa6dc -
Trigger Event:
push
-
Statement type:
File details
Details for the file pear_ebi-1.1.2-py3-none-any.whl.
File metadata
- Download URL: pear_ebi-1.1.2-py3-none-any.whl
- Upload date:
- Size: 2.5 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e727373d11c619742ddafacc42b52b027cbd1a337a765aee9bb197af826b477a
|
|
| MD5 |
1a58180684a83d30c87d4030f9ce5006
|
|
| BLAKE2b-256 |
0bd9cf897bcd65d3bfc9e39db0c89e0477fe4694e041b2ec17d422c29e767bed
|
Provenance
The following attestation bundles were made for pear_ebi-1.1.2-py3-none-any.whl:
Publisher:
release.yml on AndreaRubbi/Pear-EBI
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pear_ebi-1.1.2-py3-none-any.whl -
Subject digest:
e727373d11c619742ddafacc42b52b027cbd1a337a765aee9bb197af826b477a - Sigstore transparency entry: 2604358900
- Sigstore integration time:
-
Permalink:
AndreaRubbi/Pear-EBI@d379343e3e8024d299541870fa73eba4f0baa6dc -
Branch / Tag:
refs/heads/pear_ebi - Owner: https://github.com/AndreaRubbi
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@d379343e3e8024d299541870fa73eba4f0baa6dc -
Trigger Event:
push
-
Statement type:
