Name | hstrat JSON |
Version |
1.11.7
JSON |
| download |
home_page | None |
Summary | hstrat enables phylogenetic inference on distributed digital evolution populations |
upload_time | 2024-03-21 22:28:53 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.8 |
license | MIT license |
keywords |
hstrat
|
VCS |
|
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
![hstrat wordmark](docs/assets/hstrat-wordmark.png)
[
![PyPi](https://img.shields.io/pypi/v/hstrat.svg)
](https://pypi.python.org/pypi/hstrat)
[
![codecov](https://codecov.io/gh/mmore500/hstrat/branch/master/graph/badge.svg?token=JwMfFOpBBD)
](https://codecov.io/gh/mmore500/hstrat)
[
![Codacy Badge](https://app.codacy.com/project/badge/Grade/9ab14d415aa9458d97b4cf760b95f874)
](https://www.codacy.com/gh/mmore500/hstrat/dashboard)
[
![CI](https://github.com/mmore500/hstrat/actions/workflows/ci.yaml/badge.svg)
](https://github.com/mmore500/hstrat/actions)
[
![Read The Docs](https://readthedocs.org/projects/hstrat/badge/?version=latest)
](https://hstrat.readthedocs.io/en/latest/?badge=latest)
[
![GitHub stars](https://img.shields.io/github/stars/mmore500/hstrat.svg?style=round-square&logo=github&label=Stars&logoColor=white)](https://github.com/mmore500/hstrat)
[
![Zenodo](https://zenodo.org/badge/464531144.svg)
](https://zenodo.org/badge/latestdoi/464531144)
[![JOSS](https://joss.theoj.org/papers/10.21105/joss.04866/status.svg)](https://doi.org/10.21105/joss.04866)
_hstrat_ enables phylogenetic inference on distributed digital evolution populations
- Free software: MIT license
- Documentation: <https://hstrat.readthedocs.io>
- Repository: <https://github.com/mmore500/hstrat>
## Install
`python3 -m pip install hstrat`
## Features
_hstrat_ serves to enable **robust, efficient extraction of evolutionary history** from evolutionary simulations where centralized, direct phylogenetic tracking is not feasible.
Namely, in large-scale, **decentralized parallel/distributed evolutionary simulations**, where agents' evolutionary lineages migrate among many cooperating processors over the course of simulation.
_hstrat_ can
- accurately estimate **time since MRCA** among two or several digital agents, even for uneven branch lengths
- **reconstruct phylogenetic trees** for entire populations of evolving digital agents
- **serialize genome annotations** to/from text and binary formats
- provide **low-footprint** genome annotations (e.g., reasonably as low as **64 bits** each)
- be directly configured to satisfy **memory use limits** and/or **inference accuracy requirements**
_hstrat operates just as well in single-processor simulation, but direct phylogenetic tracking using a tool like [phylotrackpy](https://github.com/emilydolson/phylotrackpy/) should usually be preferred in such cases due to its capability for perfect record-keeping given centralized global simulation observability._
## Example Usage
This code briefly demonstrates,
1. initialization of a population of `HereditaryStratigraphicColumn` of objects,
2. generation-to-generation transmission of `HereditaryStratigraphicColumn` objects with simple synchronous turnover, and then
3. reconstruction of phylogenetic history from the final population of `HereditaryStratigraphicColumn` objects.
```python3
from random import choice as rchoice
import alifedata_phyloinformatics_convert as apc
from hstrat import hstrat; print(f"{hstrat.__version__=}") # when last ran?
from hstrat._auxiliary_lib import seed_random; seed_random(1) # reproducibility
# initialize a small population of hstrat instrumentation
# (in full simulations, each column would be attached to an individual genome)
population = [hstrat.HereditaryStratigraphicColumn() for __ in range(5)]
# evolve population for 40 generations under drift
for _generation in range(40):
population = [rchoice(population).CloneDescendant() for __ in population]
# reconstruct estimate of phylogenetic history
alifestd_df = hstrat.build_tree(population, version_pin=hstrat.__version__)
tree_ascii = apc.RosettaTree(alifestd_df).as_dendropy.as_ascii_plot(width=20)
print(tree_ascii)
```
```
hstrat.__version__='1.8.8'
/--- 1
/---+
/--+ \--- 3
| |
/---+ \------- 2
| |
+--+ \---------- 0
|
\-------------- 4
```
In [actual usage](https://hstrat.readthedocs.io/en/latest/demo-ping.html), each _hstrat_ column would be bundled with underlying genetic material of interest in the simulation --- entire genomes or, in systems with sexual recombination, individual genes.
The _hstrat_ columns are designed to operate as a neutral genetic annotation, enhancing observability of the simulation but not affecting its outcome.
## How it Works
In order to enable phylogenetic inference over fully-distributed evolutionary simulation, hereditary stratigraphy adopts a paradigm akin to phylogenetic work in natural history/biology.
In these fields, phylogenetic history is inferred through comparisons among genetic material of extant organisms, with --- in broad terms --- phylogenetic relatedness established through the extent of genetic similarity between organisms.
Phylogenetic tracking through _hstrat_, similarly, is achieved through analysis of similarity/dissimilarity among genetic material sampled over populations of interest.
Rather than random mutation as with natural genetic material, however, genetic material used by _hstrat_ is structured through _hereditary stratigraphy_.
This methodology, described fully in our documentation, provides strong guarantees on phylogenetic inferential power, minimizes memory footprint, and allows efficient reconstruction procedures.
See [here](https://hstrat.readthedocs.io/en/latest/mechanism.html) for more detail on underlying hereditary stratigraphy methodology.
## Getting Started
Refer to our documentation for a [quickstart guide](https://hstrat.readthedocs.io/en/latest/quickstart.html) and an [annotated end-to-end usage example](https://hstrat.readthedocs.io/en/latest/demo-ping.html).
The `examples/` folder provides extensive usage examples, including
- incorporation of hstrat annotations into a custom genome class,
- automatic stratum retention policy parameterization,
- pairwise and population-level phylogenetic inference, and
- phylogenetic tree reconstruction.
Interested users can find an explanation of how hereditary stratigraphy methodology implemented by _hstrat_ works "under the hood," information on project-specific _hstrat_ configuration, and full API listing for the _hstrat_ package in [the documentation](https://hstrat.readthedocs.io/).
## Citing
If _hstrat_ software or hereditary stratigraphy methodology contributes to a scholarly work, please cite it according to references provided [here](https://hstrat.readthedocs.io/en/latest/citing.html).
We would love to list your project using _hstrat_ in our documentation, see more [here](https://hstrat.readthedocs.io/en/latest/projects.html).
## Credits
This package was created with Cookiecutter and the `audreyr/cookiecutter-pypackage` project template.
## hcat
![hcat](docs/assets/hcat-banner.png)
Raw data
{
"_id": null,
"home_page": null,
"name": "hstrat",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "hstrat",
"author": null,
"author_email": "Matthew Andres Moreno <m.more500@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/24/28/2a152a3753ec9a3059d3a654b702815ffbc8c0c89fca502132b2074fd1e8/hstrat-1.11.7.tar.gz",
"platform": null,
"description": "![hstrat wordmark](docs/assets/hstrat-wordmark.png)\n\n[\n![PyPi](https://img.shields.io/pypi/v/hstrat.svg)\n](https://pypi.python.org/pypi/hstrat)\n[\n![codecov](https://codecov.io/gh/mmore500/hstrat/branch/master/graph/badge.svg?token=JwMfFOpBBD)\n](https://codecov.io/gh/mmore500/hstrat)\n[\n![Codacy Badge](https://app.codacy.com/project/badge/Grade/9ab14d415aa9458d97b4cf760b95f874)\n](https://www.codacy.com/gh/mmore500/hstrat/dashboard)\n[\n![CI](https://github.com/mmore500/hstrat/actions/workflows/ci.yaml/badge.svg)\n](https://github.com/mmore500/hstrat/actions)\n[\n![Read The Docs](https://readthedocs.org/projects/hstrat/badge/?version=latest)\n](https://hstrat.readthedocs.io/en/latest/?badge=latest)\n[\n![GitHub stars](https://img.shields.io/github/stars/mmore500/hstrat.svg?style=round-square&logo=github&label=Stars&logoColor=white)](https://github.com/mmore500/hstrat)\n[\n![Zenodo](https://zenodo.org/badge/464531144.svg)\n](https://zenodo.org/badge/latestdoi/464531144)\n[![JOSS](https://joss.theoj.org/papers/10.21105/joss.04866/status.svg)](https://doi.org/10.21105/joss.04866)\n\n_hstrat_ enables phylogenetic inference on distributed digital evolution populations\n\n- Free software: MIT license\n- Documentation: <https://hstrat.readthedocs.io>\n- Repository: <https://github.com/mmore500/hstrat>\n\n## Install\n\n`python3 -m pip install hstrat`\n\n## Features\n\n_hstrat_ serves to enable **robust, efficient extraction of evolutionary history** from evolutionary simulations where centralized, direct phylogenetic tracking is not feasible.\nNamely, in large-scale, **decentralized parallel/distributed evolutionary simulations**, where agents' evolutionary lineages migrate among many cooperating processors over the course of simulation.\n\n_hstrat_ can\n\n- accurately estimate **time since MRCA** among two or several digital agents, even for uneven branch lengths\n- **reconstruct phylogenetic trees** for entire populations of evolving digital agents\n- **serialize genome annotations** to/from text and binary formats\n- provide **low-footprint** genome annotations (e.g., reasonably as low as **64 bits** each)\n- be directly configured to satisfy **memory use limits** and/or **inference accuracy requirements**\n\n_hstrat operates just as well in single-processor simulation, but direct phylogenetic tracking using a tool like [phylotrackpy](https://github.com/emilydolson/phylotrackpy/) should usually be preferred in such cases due to its capability for perfect record-keeping given centralized global simulation observability._\n\n## Example Usage\n\nThis code briefly demonstrates,\n\n1. initialization of a population of `HereditaryStratigraphicColumn` of objects,\n2. generation-to-generation transmission of `HereditaryStratigraphicColumn` objects with simple synchronous turnover, and then\n3. reconstruction of phylogenetic history from the final population of `HereditaryStratigraphicColumn` objects.\n\n```python3\nfrom random import choice as rchoice\nimport alifedata_phyloinformatics_convert as apc\nfrom hstrat import hstrat; print(f\"{hstrat.__version__=}\") # when last ran?\nfrom hstrat._auxiliary_lib import seed_random; seed_random(1) # reproducibility\n\n# initialize a small population of hstrat instrumentation\n# (in full simulations, each column would be attached to an individual genome)\npopulation = [hstrat.HereditaryStratigraphicColumn() for __ in range(5)]\n\n# evolve population for 40 generations under drift\nfor _generation in range(40):\n population = [rchoice(population).CloneDescendant() for __ in population]\n\n# reconstruct estimate of phylogenetic history\nalifestd_df = hstrat.build_tree(population, version_pin=hstrat.__version__)\ntree_ascii = apc.RosettaTree(alifestd_df).as_dendropy.as_ascii_plot(width=20)\nprint(tree_ascii)\n```\n\n```\nhstrat.__version__='1.8.8'\n /--- 1\n /---+\n /--+ \\--- 3\n | |\n /---+ \\------- 2\n | |\n+--+ \\---------- 0\n |\n \\-------------- 4\n```\n\nIn [actual usage](https://hstrat.readthedocs.io/en/latest/demo-ping.html), each _hstrat_ column would be bundled with underlying genetic material of interest in the simulation --- entire genomes or, in systems with sexual recombination, individual genes.\nThe _hstrat_ columns are designed to operate as a neutral genetic annotation, enhancing observability of the simulation but not affecting its outcome.\n\n## How it Works\n\nIn order to enable phylogenetic inference over fully-distributed evolutionary simulation, hereditary stratigraphy adopts a paradigm akin to phylogenetic work in natural history/biology.\nIn these fields, phylogenetic history is inferred through comparisons among genetic material of extant organisms, with --- in broad terms --- phylogenetic relatedness established through the extent of genetic similarity between organisms.\nPhylogenetic tracking through _hstrat_, similarly, is achieved through analysis of similarity/dissimilarity among genetic material sampled over populations of interest.\n\nRather than random mutation as with natural genetic material, however, genetic material used by _hstrat_ is structured through _hereditary stratigraphy_.\nThis methodology, described fully in our documentation, provides strong guarantees on phylogenetic inferential power, minimizes memory footprint, and allows efficient reconstruction procedures.\n\nSee [here](https://hstrat.readthedocs.io/en/latest/mechanism.html) for more detail on underlying hereditary stratigraphy methodology.\n\n## Getting Started\n\nRefer to our documentation for a [quickstart guide](https://hstrat.readthedocs.io/en/latest/quickstart.html) and an [annotated end-to-end usage example](https://hstrat.readthedocs.io/en/latest/demo-ping.html).\n\nThe `examples/` folder provides extensive usage examples, including\n\n- incorporation of hstrat annotations into a custom genome class,\n- automatic stratum retention policy parameterization,\n- pairwise and population-level phylogenetic inference, and\n- phylogenetic tree reconstruction.\n\nInterested users can find an explanation of how hereditary stratigraphy methodology implemented by _hstrat_ works \"under the hood,\" information on project-specific _hstrat_ configuration, and full API listing for the _hstrat_ package in [the documentation](https://hstrat.readthedocs.io/).\n\n## Citing\n\nIf _hstrat_ software or hereditary stratigraphy methodology contributes to a scholarly work, please cite it according to references provided [here](https://hstrat.readthedocs.io/en/latest/citing.html).\nWe would love to list your project using _hstrat_ in our documentation, see more [here](https://hstrat.readthedocs.io/en/latest/projects.html).\n\n## Credits\n\nThis package was created with Cookiecutter and the `audreyr/cookiecutter-pypackage` project template.\n\n## hcat\n\n![hcat](docs/assets/hcat-banner.png)\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "hstrat enables phylogenetic inference on distributed digital evolution populations",
"version": "1.11.7",
"project_urls": {
"documentation": "https://hstrat.readthedocs.io",
"homepage": "https://github.com/mmore500/hstrat",
"repository": "https://github.com/mmore500/hstrat"
},
"split_keywords": [
"hstrat"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "16f765ee1108ad2a613775b8e2c599b9fa2f028a569f596dc731bd68d034866b",
"md5": "4114ef74637b78f57cd20e1dfb99d83a",
"sha256": "d21d4d57df5ef93ef272eca8ce8ca5f98a6f407ee0d4e4130160cce072ee8b6a"
},
"downloads": -1,
"filename": "hstrat-1.11.7-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "4114ef74637b78f57cd20e1dfb99d83a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 561418,
"upload_time": "2024-03-21T22:28:50",
"upload_time_iso_8601": "2024-03-21T22:28:50.639210Z",
"url": "https://files.pythonhosted.org/packages/16/f7/65ee1108ad2a613775b8e2c599b9fa2f028a569f596dc731bd68d034866b/hstrat-1.11.7-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "24282a152a3753ec9a3059d3a654b702815ffbc8c0c89fca502132b2074fd1e8",
"md5": "d06a308cb82ea6f42f17b0dd1ff9f93c",
"sha256": "cf1a575d13e6338df44cd7074b92cdf3874561b6c0a68387027d06a28f604bb1"
},
"downloads": -1,
"filename": "hstrat-1.11.7.tar.gz",
"has_sig": false,
"md5_digest": "d06a308cb82ea6f42f17b0dd1ff9f93c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6144147,
"upload_time": "2024-03-21T22:28:53",
"upload_time_iso_8601": "2024-03-21T22:28:53.109802Z",
"url": "https://files.pythonhosted.org/packages/24/28/2a152a3753ec9a3059d3a654b702815ffbc8c0c89fca502132b2074fd1e8/hstrat-1.11.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-21 22:28:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mmore500",
"github_project": "hstrat",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "hstrat"
}