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 this library either in whole or in part in your analysis, or use any code derived from it, please cite it as:
Sukumaran, J. and Mark T. Holder. 2010. DendroPy: A Python library for phylogenetic computing. Bioinformatics 26: 1569-1571.
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”.
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 Oct 27, 2023, from http://dendropy.org/.
Copyright, License and Warranty¶
The DendroPy project, including all source code, documentation, images, and other supporting files and media, either as provided online or otherwise distributed, is (unless otherwise explicitly noted):
Copyright 2009-2023, Jeet Sukumaran and Mark T. Holder. All rights reserved.
The DendroPy project source code and associated data files are licensed for redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
The names of its contributors may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JEET SUKUMARAN OR MARK T. HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
All DendroPy documentation, (non-logo) images and other media, as provided online or otherwise distributed, can be used in accordance with the Attribution-NonCommercial-ShareAlike 4.0 International License , which allows anyone to copy, modify and redistribute modifications of all or part of the DendroPy documentation as long as:
The license is included with all copies or redistributions.
the DendroPy documentation is attributed as the originating document.
You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
You may not use the material for commercial purposes.
If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
The DendroPy logo can be used and reproduced freely only to identify, advertise, or otherwise denote association or usage of the DendroPy library.
The test data files (available at
dendropy/test/data) have all been (a) sourced from public domain data, (b) obtained as part of example data bundled with other applications, and typically having been used in published analyses (c) generated using analysis programs from public domain data.In the case of (a), the data is from GenBank, and thus in public domain. Where possible, we have maintained citation information for the original authors/work that generated the data.
In the case of (b), the original data is also available from the public domain. Where possible, we have maintained citation information for the original authors/work that generated the data.
In the case of (c), no program we have used places any restriction on their output. We maintain the generated text (“File generated by DnaSp … etc”) to track provenance.
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.
