# commonnexus
[](https://github.com/dlce-eva/commonnexus/actions?query=workflow%3Atests)
[](https://commonnexus.readthedocs.io/en/latest/?badge=latest)
[](https://pypi.org/project/commonnexus)
This package provides functionality to read and write the NEXUS file format as specified in
> Maddison, Swofford, and Maddison (1997). "NEXUS: An extensible file format for systematic information". Systematic Biology. 46 (4): 590–621. [doi:10.1093/sysbio/46.4.590](https://doi.org/10.1093/sysbio/46.4.590)
Rather than trying to rip out relevant portions of a NEXUS file as quickly as possible, the implementation
in `commonnexus` tries to do "the right thing" according to the specification, i.e. parse a file token by
token. Thus, we sacrifice speed for correctness and the ability to support weird edge cases like
> Comments do not break tokens. Thus, `AssuMP[comment]TiONS` is processed as `ASSUMPTIONS`.
## Install
Install `commonnexus` from [PyPI](https://pypi.org/project/commonnexus):
```shell
pip install commonnexus
```
## Overview
`commonnexus` provides a [Python API](#python-api) as well as a [shell command](#command-line-usage)
to manipulate (the data in) NEXUS files.
In particular, it allows reading NEXUS
```python
>>> from commonnexus import Nexus
>>> nex = Nexus.from_file('docs/characters.nex')
>>> nex.CHARACTERS.get_matrix()['t1'].values()
odict_values(['1', '0', '0', '1', '0', '1', '0', '0', '0', '0'])
```
and writing NEXUS
```python
>>> from commonnexus import Nexus
>>> from commonnexus.blocks import Data
>>> nex = Nexus.from_file('docs/characters.nex')
>>> print(Nexus.from_blocks(Data.from_data(nex.CHARACTERS.get_matrix())))
#NEXUS
BEGIN DATA;
DIMENSIONS NCHAR=10;
FORMAT DATATYPE=STANDARD MISSING=? GAP=- SYMBOLS="01";
MATRIX
t1 1001010000
t2 0101000100
t3 0011101010
t4 0001100001
t5 0001100001
;
END;
```
## Command line usage
Installing the `commonnexus` package will also install a command line interface `commonnexus`, which provides several
sub-commands to manipulate NEXUS files.
Run `commonnexus -h` to get an overview of available sub-commands or find detailed documentation
with examples [on ReadTheDocs](https://commonnexus.readthedocs.io/en/latest/cli.html).
## Python API
The Python API tries to convert NEXUS constructs to appropriate Python objects, e.g.
- NEXUS content is a `list` of `Command` objects,
- missing states in a CHARACTERS MATRIX are conveyed as `None` values, etc.
This allows for dealing with NEXUS data in a way that is abstracted from the NEXUS formatting
conventions
For a detailed documentation of the Python API, refer to the
[docs on ReadTheDocs](https://commonnexus.readthedocs.io/en/latest/index.html).
## See also
- https://doi.org/10.1093/sysbio/46.4.590
- https://github.com/dlce-eva/python-nexus
- http://wiki.christophchamp.com/index.php?title=NEXUS_file_format
Raw data
{
"_id": null,
"home_page": "https://github.com/dlce-eva/commonnexus",
"name": "commonnexus",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "phylogenetics nexus newick paup splitstree",
"author": "Robert Forkel",
"author_email": "robert_forkel@eva.mpg.de",
"download_url": "https://files.pythonhosted.org/packages/34/5e/b7fafce548ea433cc3abb0ae61787111d4678a8f3a7f1a12d0c1fed909b7/commonnexus-1.9.2.tar.gz",
"platform": "any",
"description": "# commonnexus\n\n[](https://github.com/dlce-eva/commonnexus/actions?query=workflow%3Atests)\n[](https://commonnexus.readthedocs.io/en/latest/?badge=latest)\n[](https://pypi.org/project/commonnexus)\n\nThis package provides functionality to read and write the NEXUS file format as specified in\n\n> Maddison, Swofford, and Maddison (1997). \"NEXUS: An extensible file format for systematic information\". Systematic Biology. 46 (4): 590\u2013621. [doi:10.1093/sysbio/46.4.590](https://doi.org/10.1093/sysbio/46.4.590)\n\nRather than trying to rip out relevant portions of a NEXUS file as quickly as possible, the implementation\nin `commonnexus` tries to do \"the right thing\" according to the specification, i.e. parse a file token by\ntoken. Thus, we sacrifice speed for correctness and the ability to support weird edge cases like\n\n> Comments do not break tokens. Thus, `AssuMP[comment]TiONS` is processed as `ASSUMPTIONS`.\n\n\n## Install\n\nInstall `commonnexus` from [PyPI](https://pypi.org/project/commonnexus):\n```shell\npip install commonnexus\n```\n\n\n## Overview\n\n`commonnexus` provides a [Python API](#python-api) as well as a [shell command](#command-line-usage)\nto manipulate (the data in) NEXUS files.\n\nIn particular, it allows reading NEXUS\n\n```python\n>>> from commonnexus import Nexus\n>>> nex = Nexus.from_file('docs/characters.nex')\n>>> nex.CHARACTERS.get_matrix()['t1'].values()\nodict_values(['1', '0', '0', '1', '0', '1', '0', '0', '0', '0'])\n```\n\nand writing NEXUS\n\n```python\n>>> from commonnexus import Nexus\n>>> from commonnexus.blocks import Data\n>>> nex = Nexus.from_file('docs/characters.nex')\n>>> print(Nexus.from_blocks(Data.from_data(nex.CHARACTERS.get_matrix())))\n#NEXUS\nBEGIN DATA;\nDIMENSIONS NCHAR=10;\nFORMAT DATATYPE=STANDARD MISSING=? GAP=- SYMBOLS=\"01\";\nMATRIX \nt1 1001010000\nt2 0101000100\nt3 0011101010\nt4 0001100001\nt5 0001100001\n;\nEND;\n```\n\n\n## Command line usage\n\nInstalling the `commonnexus` package will also install a command line interface `commonnexus`, which provides several\nsub-commands to manipulate NEXUS files.\n\nRun `commonnexus -h` to get an overview of available sub-commands or find detailed documentation\nwith examples [on ReadTheDocs](https://commonnexus.readthedocs.io/en/latest/cli.html).\n\n\n## Python API\n\nThe Python API tries to convert NEXUS constructs to appropriate Python objects, e.g.\n- NEXUS content is a `list` of `Command` objects,\n- missing states in a CHARACTERS MATRIX are conveyed as `None` values, etc.\n\nThis allows for dealing with NEXUS data in a way that is abstracted from the NEXUS formatting\nconventions\n\nFor a detailed documentation of the Python API, refer to the\n[docs on ReadTheDocs](https://commonnexus.readthedocs.io/en/latest/index.html).\n\n\n## See also\n\n- https://doi.org/10.1093/sysbio/46.4.590\n- https://github.com/dlce-eva/python-nexus\n- http://wiki.christophchamp.com/index.php?title=NEXUS_file_format\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A nexus (phylogenetics) file reader and writer (.nex, .trees)",
"version": "1.9.2",
"project_urls": {
"Bug Tracker": "https://github.com/dlce-eva/commonnexus/issues",
"Homepage": "https://github.com/dlce-eva/commonnexus"
},
"split_keywords": [
"phylogenetics",
"nexus",
"newick",
"paup",
"splitstree"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e0fa341a27987018b6431d3ce06c617ac024990e48f1e6e62035effc28e226b7",
"md5": "6b1923b9afc477e746e126d41afa6e17",
"sha256": "24d0607f560097c007cd3eb90d97a26eb00fcd2b01dd09eec1d0f32cc40c4a86"
},
"downloads": -1,
"filename": "commonnexus-1.9.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "6b1923b9afc477e746e126d41afa6e17",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 81354,
"upload_time": "2023-11-26T12:00:52",
"upload_time_iso_8601": "2023-11-26T12:00:52.365841Z",
"url": "https://files.pythonhosted.org/packages/e0/fa/341a27987018b6431d3ce06c617ac024990e48f1e6e62035effc28e226b7/commonnexus-1.9.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "345eb7fafce548ea433cc3abb0ae61787111d4678a8f3a7f1a12d0c1fed909b7",
"md5": "9dcb4484c23ef0866089ee322e0ab8c0",
"sha256": "292da1cf4aeb0ab474a274235313f9dc64d8f489d7953163c5f6570f302583f3"
},
"downloads": -1,
"filename": "commonnexus-1.9.2.tar.gz",
"has_sig": false,
"md5_digest": "9dcb4484c23ef0866089ee322e0ab8c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 85959,
"upload_time": "2023-11-26T12:00:56",
"upload_time_iso_8601": "2023-11-26T12:00:56.350088Z",
"url": "https://files.pythonhosted.org/packages/34/5e/b7fafce548ea433cc3abb0ae61787111d4678a8f3a7f1a12d0c1fed909b7/commonnexus-1.9.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-26 12:00:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dlce-eva",
"github_project": "commonnexus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "commonnexus"
}
JSON
