Metadata-Version: 2.4
Name: pear_ebi
Version: 1.1.1
Summary: Embeds phylogenetic tree distances and produce representations
License-Expression: MIT
License-File: LICENSE
Keywords: phylogenetics,phylogenetic-trees,embedding,robinson-foulds,newick
Author: Andrea Rubbi
Author-email: andrea.rubbi.98@gmail.com
Maintainer: Andrea Rubbi
Maintainer-email: andrear@ebi.ac.uk
Requires-Python: >=3.10,<3.14
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
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: Topic :: Scientific/Engineering :: Bio-Informatics
Provides-Extra: notebook
Requires-Dist: anywidget (>=0.9)
Requires-Dist: ipykernel (>=6.17) ; extra == "notebook"
Requires-Dist: ipython (>=8.6) ; extra == "notebook"
Requires-Dist: ipywidgets (>=7.7,<9)
Requires-Dist: jupyter (>=1.0) ; extra == "notebook"
Requires-Dist: jupyterlab (>=4.0) ; extra == "notebook"
Requires-Dist: kaleido (>=1.0)
Requires-Dist: matplotlib (>=3.4)
Requires-Dist: notebook (>=7.0) ; extra == "notebook"
Requires-Dist: numpy (>=1.21)
Requires-Dist: pandas (>=1.3)
Requires-Dist: plotly (>=6.1)
Requires-Dist: pyDRMetrics (==0.0.7)
Requires-Dist: rich (>=12,<15)
Requires-Dist: scikit-learn (>=1.0)
Requires-Dist: scipy (>=1.7)
Requires-Dist: toml (>=0.10,<0.11)
Requires-Dist: tqdm (>=4.60)
Project-URL: Documentation, https://andrearubbi.github.io/Pear-EBI/index.html
Project-URL: Homepage, https://github.com/AndreaRubbi/Pear-EBI
Project-URL: Repository, https://github.com/AndreaRubbi/Pear-EBI
Description-Content-Type: text/markdown


 <h1> Phylogeny Embedding  & <br>  Approximate Representation </h1>
 <img src="https://github.com/AndreaRubbi/Pear-EBI/raw/pear_ebi/logos/LOGO_PEAR.png" width="100" height="100" alt="PEAR logo">

 <img src="https://img.shields.io/github/license/AndreaRubbi/Pear-EBI?color=red&label=License&style=plastic"> <img src="https://img.shields.io/pypi/v/pear_ebi?color=purple&label=version&style=plastic"> <img src="https://img.shields.io/pypi/implementation/pear_ebi?style=plastic"> <img src="https://img.shields.io/pypi/pyversions/pear_ebi?color=green&style=plastic">



## Goldman Group - European Bioinformatics Institute <img src="https://github.com/AndreaRubbi/Pear-EBI/raw/pear_ebi/logos/goldman_logo.png" width="30" height="30">

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 <a href="https://andrearubbi.github.io/Pear-EBI/index.html"> autogenerated documentation </a> and <a href="https://pypi.org/project/pear-ebi/"> PyPI </a>.

PEAR usage
==========
Pear is both a python software and library. It can be installed with `python -m pip install pear_ebi` or downloaded from <a href="https://github.com/AndreaRubbi/Pear-EBI">Github</a>. 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 <a href="https://python-poetry.org/">Poetry</a>. 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). <a href="https://github.com/conda-forge/miniforge#install">Miniforge</a>
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 <a href='https://github.com/AndreaRubbi/Pear-EBI/tree/pear_ebi/examples_tree_sets'>examples</a>.

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 <a href='https://doi.org/10.1016/0025-5564(81)90043-2'>Robinson Foulds</a> 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](https://code.google.com/archive/p/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 <a href='https://github.com/AndreaRubbi/Pear-EBI/tree/pear_ebi/examples_tree_sets'>examples</a> 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 <a href='https://github.com/AndreaRubbi/Pear-EBI/tree/pear_ebi/examples_tree_sets'>this link</a> for a complete set of basic and advanced guides and tutorials to use PEAR on the command line and as a python library.

 <!--- ### Additional Dependencies
 In order to get the complete report on the quality of embeddings, it may be necessary to
 run the following command to install additional dependencies:

 `sudo apt-get install '^libxcb.*-dev' libx11-xcb-dev libglu1-mesa-dev libxrender-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev`

 It may be necessary to also install `libgcc` and remove old versions of `libstdc++` from the interpreter libraries. --->
________________________

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

