DendroPy Phylogenetic Computing Library¶
DendroPy is a Python library for phylogenetic computing. It provides classes and functions for the simulation, processing, and manipulation of phylogenetic trees and character matrices, and supports the reading and writing of phylogenetic data in a range of formats, such as NEXUS, NEWICK, NeXML, Phylip, FASTA, etc. Application scripts for performing some useful phylogenetic operations, such as data conversion and tree posterior distribution summarization, are also distributed and installed as part of the libary. DendroPy can thus function as a stand-alone library for phylogenetics, a component of more complex multi-library phyloinformatic pipelines, or as a scripting “glue” that assembles and drives such pipelines.
Prerequisites¶
DendroPy is a pure-Python library with no dependencies, and runs under any version of Python 3 and Python 2.7. If you want to run DendroPy under Python version of less than 2.7, you should download the DendroPy legacy release.
Changed in version 4.0.0: Python 2.4, 2.5, and 2.6 support removed. Python 3.x support added.
Installing¶
You can install directly from the main GitHub repository using:
$ python3 -m pip install git+https://github.com/jeetsukumaran/DendroPy.git
$ python3 -m pip install git+git://github.com/jeetsukumaran/DendroPy.git
Alternatively, if you want to install from a particular branch, e.g., the latest development branch, development-main:
$ python3 -m pip install git+https://github.com/jeetsukumaran/DendroPy.git@development-main
$ python3 -m pip install git+git://github.com/jeetsukumaran/DendroPy.git@development-main
DendroPy is also fully easy-installable and can be installed using pip:
$ python3 -m pip install -U dendropy
If you do not have pip installed, you should definitely install it ! Other ways of obtaining and installing DendroPy (e.g., by downloading the DendroPy source code archive, or by cloning the DendroPy Git repository), are discussed in detail in the “Downloading and Installing DendroPy” section.
If you are using the conda package manager, DendroPy can be installed to your conda environment via pip. From within an Anaconda terminal, or a Jupyter Notebook, type:
$ import pip
$ pip.main(['install', 'dendropy'])
DendroPy will now be available in your conda-managed environment.
More information on downloading and installing DendroPy can be found in our setup instructions.
Documentation¶
Downloading and Installing DendroPy
The many ways to get DendroPy up and running on your system.
A detailed primer on how to use the DendroPy library, with lots of annotated practical examples and code walk-throughs.
DendroPy Library API Reference
The technical details of the modules, classes and methods of the DendroPy library. Almost all of this information is also readily available from the Python interpreter by invoking
help()on an object or name.How to use SumTrees, an application script bundled with DendroPy that faciliates the summarization of non-parameteric bootstrap or Bayesian posterior probability support for splits or clades on phylogenetic trees.
DendroPy 4 is improved in many ways over DendroPy 3. However, some of the changes are significant enough to break code written for DendroPy 3. This reference provides an overview of these changes, as well as notes on how to fix, handle or otherwise work-around issues that might result from trying to run code written for DendroPy 3 under DendroPy 4.
This reference provides how-to’s for tasks like linting, testing, and releasing DendroPy. Great place to start for new contributors.
A summary of major changes (new features, bug fixes, bug creations, etc.) of each release of DendroPy.
Announcements relating to DendroPy.
Feature Requests¶
We are constantly expanding and improving the DendroPy library. And we are constantly looking for ideas on how to expand and improve DendroPy. If you have an idea that you would like to see implemented in DendroPy, or a need/requirement for some sort of functionality that DendroPy does not provide or does not provide easily, or, for that matter, a suggestion/idea for how something DendroPy already does that can be done better, please let us know by posting it as an issue on the DendroPy Issues page. We take these very seriously, and look forward to ideas/suggestions/requests/critiques such as these, not only because they improve the library for the entire community of users, but also because they sometimes provide for interesting side-projects for us.
Bug Reports and Other Issues¶
Everyone has issues. And sometimes, not pointing them out is enabling rather than helping. So, if you encounter or think you have encountered a problem in the way DendroPy works, please report it on the DendroPy Issues page. The DendroPy library has a really large suite of tests, but it is also a really, really, really, really large and complex library, and there are many nooks and crannies in which can scurry many crooks and nannies, so you will be doing us and the community a really generous favor by reporting bugs and problems. Even if you are not sure if you are actually dealing with a bug, please do not hesitate to report it as an issue: false positives are better than false negatives in this context.
Having said that, please do take the trouble to write-up a decent bug report. It really is quite frustrating to receive vague and lackadaisical “reports” that are little more than stream-of-consciousness responses to stimuli from the monitor that were almost accidentally blurted into the keyboard (e.g., “doesn’t work”). At the very least, you should provide:
A brief explication of what occurred, describing the operation that you were trying to do, and the result (or non-result) that you observed that led you to think there is an error.
The environment in which this error occurred. This includes, at the very least, the operating system, as well as things such as the python version, DendroPy version, the installation locations of DendroPy and the Python libraries, etc. Apart from the operating system, you can retrieve all this information by running the following command:
$ python -m dendropyThe version of SumTrees that ships with DendroPy 4 onwards includes a special flag, “
--describe” (i.e., you would type “sumtrees.py --describe”), that also provides this information. Including the details of either of these commands in their entirety along with the operating system is not only useful, but essential.We have gone to great lengths to write sensible and meaningful error messages, and that chunk of text that usually appears on the screen on error (i.e., the “stack trace”) is packed with useful information, and should be included in its entirety should it appear.
We need to be able to reproduce the error on our side to be able to fix. Thus, providing a self-contained and minimum example of the error is crucial. This might involve a little bit of work on your side, to extract the essential bits of code from their context and to ensure that it can run, at least, up to the point where it does not due to the error. The “steps to reproduce” section of a bug report is so important and useful that anyone who makes sure to include a good one into their bug report would be perfectly justified in expecting that strawberry cheesecake and a orange mocha frappuccino get delivered to their doorstep the moment the report is posted.
Help, Discussion, and Comments¶
The DendroPy Users discussion group is available for general discussion on the usage of the DendroPy library. If you want more information on how to use a particular feature or carry out specific task or want to make some general comments on the DendroPy library, you should post a message to the DendroPy Users discussion group. I follow and respond to messages on this group fairly regularly, so you should get a response within 24 hours.
Of course, we accept all bug reports, bad or good, and I guess we would prefer to have a bad bug report than no report at all, so if all the above seem enough of a hassle to discourage you from posting an issue at all, feel free to go ahead and write it up any way you see fit.
Code of Conduct¶
We are dedicated to fostering a supportive and inclusive atmosphere for everyone involved in our project.
We oversee DendroPy according to a Code of Conduct from the Contributor Covenant project. This document describes expectations for project participants and provides mechanisms to address misconduct. Please take a moment to familiarize yourself with it here.
Citation¶
If you use version 5 of this library either in whole or in part in your research, or use any code derived from it, please cite it as:
Moreno, M. A., Holder, M. T., & Sukumaran, J. (2024). DendroPy 5: a mature Python library for phylogenetic computing. Journal of Open Source Software, 9(101), 6943, https://doi.org/10.21105/joss.06943
For BibTex users:
@misc{dendropy5,
doi = {10.21105/joss.06943},
url = {https://doi.org/10.21105/joss.06943},
year = {2024},
publisher = {The Open Journal},
volume = {9},
number = {101},
pages = {6943},
author = {Matthew Andres Moreno and Mark T. Holder and Jeet Sukumaran},
title = {DendroPy 5: a mature Python library for phylogenetic computing},
journal = {Journal of Open Source Software}
}
Note that, in the interests of scientific reproducibility, in addition to noting the primary citation for DendroPy as given above in the reference section, you should note in the text of your publications (e.g., in the “Methods” section, or, at the very least, in the “Supplemental Materials” section) the specific version of DendroPy that you used (e.g., “DendroPy version 4.0.0, revision 78e6a63”). You can get useful information about your DendroPy installation by typing “python -m dendropy”.
Earlier DendroPy versions can be cited as:
Sukumaran, J. and M. T. Holder. 2010. DendroPy: a Python library for phylogenetic computing. Bioinformatics 26: 1569-1571. https://doi.org/10.1093/bioinformatics/btq228
If you use or reference any part of this documentation, you can cite it as:
Sukumaran, J. and Mark T. Holder. The DendroPy Phylogenetic Computing Library Documentation. Retrieved Sep 23, 2024, from https://jeetsukumaran.github.io/DendroPy/.
Consider also leaving a star on GitHub!
Copyright, License, and Warranty¶
Acknowledgments¶
Portions of DendroPy were developed under CIPRES, a multi-site collaboration funded by the NSF Information Technology Research (ITR) program grant entitled “BUILDING THE TREE OF LIFE: A National Resource for Phyloinformatics and Computational Phylogenetics” and NSF ATOL grant 0732920 to Mark Holder.
