Metadata-Version: 2.1
Name: clld-phylogeny-plugin
Version: 1.6.0
Summary: A clld plugin to support language phylogenies
Home-page: https://github.com/clld-phylogeny-plugin
Author: Robert Forkel and Hans-Jörg Bibiko
Author-email: dlce.rdm@eva.mpg.de
License: Apache 2.0
Keywords: linguistics
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: newick
Requires-Dist: attrs (>=18.1)
Requires-Dist: clld (>=4.0.3)
Requires-Dist: sqlalchemy
Requires-Dist: zope.interface
Provides-Extra: dev
Requires-Dist: tox ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: wheel (>=0.36) ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-clld ; extra == 'test'
Requires-Dist: pytest (>=5) ; extra == 'test'
Requires-Dist: pytest-mock ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: coverage (>=4.2) ; extra == 'test'
Requires-Dist: webtest ; extra == 'test'

# clld-phylogeny-plugin

Plugin for the [clld](https://github.com/clld/clld) framework providing
support for phylogenetic trees in clld apps.

This plugin includes the [phylotree](https://github.com/veg/phylotree.js/tree/master)
library to render phylogenetic trees in the browser.

[![Build Status](https://github.com/clld/clld-phylogeny-plugin/workflows/tests/badge.svg)](https://github.com/clld/clld-phylogeny-plugin/actions?query=workflow%3Atests)
[![PyPI](https://img.shields.io/pypi/v/clld-phylogeny-plugin.svg)](https://pypi.python.org/pypi/clld-phylogeny-plugin)


## Introduction

While plotting cross-linguistic data on a map serves as quick visualization of the correlation between the data and geography, plotting the data on a phylogenetic tree allows inspection of the correlation between the data and some theory about language relatedness, embodied in the tree.

The `clld-phylogeny-plugin` package supports this kind of visualization by
- adding [database models](https://github.com/clld/clld-phylogeny-plugin/blob/master/src/clld_phylogeny_plugin/models.py) to store phylogenetic trees (and how the tree labels correspond to `Language` objects)
- adding a [`Tree` component](https://github.com/clld/clld-phylogeny-plugin/blob/f98e83681e7464d3abfb05eae2f1a3c74fdabc1f/src/clld_phylogeny_plugin/tree.py#L34), allowing simple rendering of a tree on a page
- adding support for "plotting" `Parameter` objects on a tree, i.e. plotting the value for a given (`Parameter`, `Language`) pair next to the language's label on the tree.


## Usage

TODO: See https://github.com/clld/grambank/commit/4101243597c3c95d21786fe8bdcf8cf060da609b for a minimal example.

To make `clld-phylogeny-plugin` functionality available to a `clld` app, it must be included in the app's configuration - typically in `<app>:main`:
```python
    config.include('clld_phylogeny_plugin')
```

This will add a *Resource* `Phylogeny` with corresponding routes
- `/phylogenys` - the index page listing all available phylogenies
- `/phylogenys/<ID>` - a phylogeny's details page, by default rendering the associated tree.


### Plotting parameters on trees

To synchronize plotting of markers for parameter values on maps and trees, the `Tree.get_marker` method may need to
be adjusted. This can be done by registering a derived `Tree` class as `ITree` utility:
```python
class MyTree(clld_phylogeny_plugin.tree.Tree):
    def get_marker(self, valueset):
        # compute marker shape and color from valueset
        return shape, color

....
    config.registry.registerUtility(MyTree, ITree)
```
