v0.17.0: splintering and migration of specialized functionalities to …

…new packages (#218) * some new features, e.g. traversal routines, getting node heights, check for time-consistency * internal field names modified * many function names were modified: older exported names are deprecated * new packages: SNaQ.jl, PhyloTraits, PhyLiNC. * function to search for most parsimony network left in (not exported), but not working (was limited to level-1 networks) * nj: swap in-place instead of taking views (which became slow under julia v1.11) --------- Co-authored-by: Josh Justison, Jingcheng Xu, Claudia Solis-Lemus, Paul Bastide
JuliaPhylo · Nov 20, 2024 · 752f516 · 752f516 · cecileane · Nov 20, 2024
1 parent be61ecb
commit 752f516
Show file tree

Hide file tree

Showing 163 changed files with 7,309 additions and 33,224 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -8,6 +8,7 @@ on:
     branches:
       - master
     tags: ['*']
+  workflow_dispatch:
 
 concurrency:
   # Skip intermediate builds: always.
@@ -40,7 +41,7 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
           files: lcov.info
           token: ${{ secrets.CODECOV_TOKEN }}
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -6,6 +6,7 @@ on:
       - master
     tags: '*'
   pull_request:
+  workflow_dispatch:
 
 jobs:
   Documenter:

diff --git a/CITATION.bib b/CITATION.bib
@@ -9,30 +9,7 @@ @article{2017SolislemusBastideAne_PhyloNetworks
   pages = {3292-3298},
   doi = {10.1093/molbev/msx235},
 }
-
-% paper on the SNaQ method
-@article{2016SolislemusAne_SNaQ,
-  author = {Sol{\'\i}s-Lemus, Claudia and An{\'e}, C{\'e}cile},
-  title = {Inferring Phylogenetic Networks with Maximum Pseudolikelihood under Incomplete Lineage Sorting},
-  journal = {PLOS Genetics},
-  year = {2016},
-  volume = {12},
-  number = {3},
-  pages = {1-21},
-  doi = {10.1371/journal.pgen.1005896},
-}
-% paper on phylogenetic comparative methods for continuous traits on networks
-@article{2018Bastide_continuoustraitevolution,
-  author = {Bastide, Paul and Sol{\'\i}s-Lemus, Claudia and Kriebel, Ricardo and William Sparks, K and An{\'e}, C{\'e}cile},
-  title = {Phylogenetic Comparative Methods on Phylogenetic Networks with Reticulations},
-  journal = {Systematic Biology},
-  year = {2018},
-  volume = {67},
-  number = {5},
-  pages = {800-820},
-  doi = {10.1093/sysbio/syy033},
-}
-% paper on phylogenetic comparative methods for discrete traits on networks
+% paper describing network calibration, based on genetic distances estimated from gene trees
 @article{2020Karimi_baobab_discretetraitevolution,
   author = {Karimi, Nisa and Grover, Corrinne E and Gallagher, Joseph P and Wendel, Jonathan F and An{\'e}, C{\'e}cile and Baum, David A},
   title = {Reticulate Evolution Helps Explain Apparent Homoplasy in Floral Biology and Pollination in Baobabs (\textit{{Adansonia}}; {Bombacoideae}; {Malvaceae})},
@@ -43,12 +20,14 @@ @article{2020Karimi_baobab_discretetraitevolution
   pages = {462-478},
   doi = {10.1093/sysbio/syz073},
 }
-% paper on continuous traits with intraspecific variation
-@article{2022Teo_intraspeciesvariation,
-  author = {Teo, Benjamin and Rose, Jeffrey P. and Bastide, Paul and An{\'e}, C{\'e}cile},
-  title = {Accounting for intraspecific variation in continuous trait evolution on a reticulate phylogeny},
-  journal = {bioRxiv},
-  year = {2022},
-  doi = {10.1101/2022.05.12.490814},
-  publisher = {Cold Spring Harbor Laboratory},
+% dissertation describing semidirected NNI (nearest neighbor interchange)
+% to modify a semidirected network: in Chapter 4
+@phdthesis{2020AllenSavietta-Ane,
+  author  = {Allen-Savietta, Cora},
+  title   = {Estimating Phylogenetic Networks from Concatenated Sequence Alignments},
+  school  = {The University of Wisconsin - Madison},
+  year    = 2020,
+  note = {Ph.D. dissertation, advised by Cécile Ané, ProQuest Dissertations & Theses 28263540},
+  url = {https://www.proquest.com/docview/2476856270/},
+  pages = 165,
 }
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,25 +4,29 @@ The following guidelines are designed for contributors of `PhyloNetworks`.
 
 ## Reporting Issues and Questions
 
-For reporting a bug, a failed function or requesting a new feature, you can simply open an issue in [the issue tracker](https://github.com/juliaphylo/PhyloNetworks.jl/issues).
-First, seach through existing issues (open or closed) that might have the answer to your question.
+For reporting a bug, a failed function or requesting a new feature,
+please open an issue in [the issue tracker](https://github.com/juliaphylo/PhyloNetworks.jl/issues).
+First, search through existing issues (open or closed) that might have the answer to your question.
 If you are reporting a bug, please also include a minimal code example or all relevant information for us to replicate the issue.
 
 For general questions, make sure to check out the [google user group](https://groups.google.com/g/phylonetworks-users). If you cannot find answers to your question, please post a new question. We do our best to reply in a timely fashion, but we are undermanned so we appreciate your patience.
 
 ## Contributing Code
 
-To make contributions to `PhyloNetworks`, you need to set up your [GitHub](https://github.com/) account (if you do not have one) and request your change(s) or contribution(s) via a pull request against the `master` branch of `PhyloNetworks` from a non-master branch in your fork.
+To make contributions to `PhyloNetworks`, you need to set up a [GitHub](https://github.com/) account (if you do not have one) and request your change(s) or contribution(s) via a pull request against the `master` branch of `PhyloNetworks` from a non-master branch in your fork.
 Using a non-master branch on your end will give developers push access to your
 branch to make edits to it (in case we want to work collaboratively on the new code).
 
 Please use the following steps:
 
 1. Fork the `PhyloNetworks` repository to your GitHub account
 2. Clone your fork locally with `git clone`
-3. Create a new branch with a name that describes your contribution. For example, if your contribution is fixing a bug in `readTopology`, your new branch can be named `fix-bug-readTopology`. You can create it and switch with:
+3. Create a new branch with a name that describes your contribution.
+   For example, if your contribution is fixing a bug in `readnewick`,
+   your new branch can be named `fix-bug-readnewick`.
+   You can create it and switch with:
    ```
-   git checkout -b fix-bug-readTopology
+   git checkout -b fix-bug-readnewick
    ```
 4. Make your changes on this new branch.
    Write a [docstring](https://docs.julialang.org/en/v1/manual/documentation/)
@@ -32,7 +36,7 @@ Please use the following steps:
 5. Push your changes to your fork
 6. [Submit a pull request](https://github.com/juliaphylo/PhyloNetworks.jl/pulls) against the `master` branch in `PhyloNetworks`. Make sure that your code passes all the automatic tests and that it is not in conflict with the current status of `master`
 
-Please make sure to follow the Julia package guidelines and conventions on your code. `PhyloNetworks` was created before these conventions were catalyzed, but we are attempting to follow them going forward. 
+Please make sure to follow the Julia package guidelines and conventions on your code. `PhyloNetworks` was created before these conventions were catalyzed, but we are attempting to follow them going forward.
 
 To learn more about the Julia conventions, check out the following links:
 

diff --git a/LICENSE.md b/LICENSE.md
@@ -1,22 +1,22 @@
-The PhyloNetworks.jl package is licensed under the MIT "Expat" License:
-
-> Copyright (c) 2014-2018: Claudia Solis-Lemus and Cecile Ane.
->
-> Permission is hereby granted, free of charge, to any person obtaining a copy
-> of this software and associated documentation files (the "Software"), to deal
-> in the Software without restriction, including without limitation the rights
-> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-> copies of the Software, and to permit persons to whom the Software is
-> furnished to do so, subject to the following conditions:
->
-> The above copyright notice and this permission notice shall be included in all
-> copies or substantial portions of the Software.
->
-> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-> SOFTWARE.
->
+The PhyloNetworks.jl package is licensed under the MIT "Expat" License:
+
+> Copyright (c) 2014-2018: Claudia Solis-Lemus and Cecile Ane.
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.
+>
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "PhyloNetworks"
 uuid = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
 license = "MIT"
-version = "0.16.4"
+version = "0.17.0"
 
 [deps]
 BioSequences = "7e6ae17a-c86d-528c-b3b9-7f778a29fe59"
@@ -15,16 +15,12 @@ Distributed = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 FASTX = "c2308a5c-f048-11e8-3e8a-31650f418d12"
 Functors = "d9f16b24-f501-4c13-a1f2-28368ffc5196"
-GLM = "38e38edf-8417-5370-95a0-9cbb8c7f171a"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
-StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
-StatsFuns = "4c63d2b9-4356-54db-8cca-17b64c39e42c"
-StatsModels = "3eaba693-59b7-5ba5-a881-562e759f1c8d"
 
 [compat]
 BioSequences = "2.0, 3"
@@ -35,17 +31,14 @@ DataFrames = "1.3"
 DataStructures = "0.9, 0.10, 0.11, 0.12, 0.13, 0.14, 0.15, 0.16, 0.17, 0.18"
 Distributions = "0.15, 0.16, 0.17, 0.18, 0.19, 0.20, 0.21, 0.22, 0.23, 0.24, 0.25"
 FASTX = "1.1, 2"
-Functors = "0.2, 0.3, 0.4"
-GLM = "1.1, 1.2, 1.3, 1.4"
+Functors = "0.2, 0.3, 0.4, 0.5"
 NLopt = "0.5.1, 0.6, 1"
-StaticArrays = "0.8.3, 0.9, 0.10, 0.11, 0.12, 1.0"
 StatsBase = "0.26, 0.27, 0.28, 0.29, 0.30, 0.31, 0.32, 0.33, 0.34"
-StatsFuns = "0.7, 0.8, 0.9, 1"
-StatsModels = "0.6, 0.7"
-julia = "1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7"
+julia = "1.5, 1.6, 1.7"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 
 [targets]
-test = ["Test"]
+test = ["Test", "StableRNGs"]
diff --git a/README.md b/README.md
@@ -1,5 +1,3 @@
-# PhyloNetworks: analysis for phylogenetic networks <img src="docs/src/logo_text.png" align=right>
-
 [![doc stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliaphylo.github.io/PhyloNetworks.jl/stable)
 [![doc dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliaphylo.github.io/PhyloNetworks.jl/dev)
 [![Build status](https://github.com/juliaphylo/PhyloNetworks.jl/workflows/CI/badge.svg?branch=master)](https://github.com/juliaphylo/PhyloNetworks.jl/actions/workflows/ci.yml)
@@ -8,88 +6,69 @@
 [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
 [![PkgEval](https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/P/PhyloNetworks.svg)](https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/report.html)
 
+<div align="right">
+
+  ![logo dark](docs/src/logo_text_darkmode.png#gh-dark-mode-only)
+  ![logo light](docs/src/logo_text.png#gh-light-mode-only)
+
+</div>
+
 ## Overview
 
-PhyloNetworks is a [Julia](http://julialang.org) package with utilities to:
-- read / write phylogenetic trees and networks,
-  in (extended) Newick format.
-  Networks are considered explicit: nodes represent ancestral species.
-  They can be rooted or unrooted.
+PhyloNetworks is a [Julia](http://julialang.org) package with utilities to
+to handle phylogenetic trees and networks.
+It serves as a core package that other packages can depend on, such as
+[PhyloPlots](https://github.com/JuliaPhylo/PhyloPlots.jl)
+to visualize phylogenies,
+[SNaQ](https://github.com/JuliaPhylo/PhyloPlots.jl)
+to infer phylogenies from genetic data,
+[PhyloTraits](https://github.com/JuliaPhylo/PhyloTraits.jl)
+to analyze the evolution of traits along phylogenies.
+
+Phylogenetic networks represent the evolutionary relationships between a set
+of organisms, e.g. populations, species, languages, cultures etc.
+They are also called *admixture graphs* when their leaves are populations
+of the same or closely related species.
+They are *explicit* graph representations, in which nodes represent
+ancestral populations / species, and edge lengths represent evolutionary time.
+
+Utilities in this core package include:
+- read / write phylogenies in (extended) Newick format
 - manipulate networks: re-root, prune taxa, remove hybrid edges,
+  transform a network with a semidirected nearest-neighbor interchange (sNNI),
   extract the major tree from a network, extract displayed networks / trees
-- compare networks / trees with dissimilarity measures
-  (Robinson-Foulds distance on trees)
-- summarize samples of bootstrap networks (or trees)
-  with edge and node support
-- estimate species networks from multilocus data: SNaQ
-- phylogenetic comparative methods for continuous trait evolution
-  on species networks / trees
-- plot networks (and trees), via the companion package
-  [PhyloPlots](https://github.com/juliaphylo/PhyloPlots.jl)
+- compare networks with dissimilarity measures
+  (e.g. the Robinson-Foulds distance on trees)
+- summarize samples of networks with support for local features
+  (edges and clades of hybrid origin or sister to a hybrid clade)
+- fit edges lengths from average pairwise distances between leaves,
+  using least-squares
+- network traversal routines
 
 To get help, check
 
 - the [latest documentation](https://juliaphylo.github.io/PhyloNetworks.jl/dev)
-- the [wiki](https://github.com/juliaphylo/PhyloNetworks.jl/wiki) for a step-by-step tutorial
-  with background on networks (last revised 2022)
+- the [wiki](https://github.com/juliaphylo/PhyloNetworks.jl/wiki) for a
+  step-by-step tutorial with background on networks (last revised 2022)
 - [tutorial](https://cecileane.github.io/networkPCM-workshop/) for
   comparative methods, including network calibration (2023 workshop)
 - the [google group](https://groups.google.com/forum/#!forum/phylonetworks-users)
   for common questions. Join the group to post/email your questions,
   or to receive information on new versions, bugs fixed, etc.
 
-If you use the package, please cite ([bibtex format here](CITATION.bib))
+If you use the package, please cite ([bibtex format here](CITATION.bib)).
+For the PhyloNetworks package in particular, please cite:
 
 - Claudia Sol&iacute;s-Lemus, Paul Bastide and C&eacute;cile An&eacute; (2017).
   PhyloNetworks: a package for phylogenetic networks.
   [Molecular Biology and Evolution](https://academic.oup.com/mbe/article/doi/10.1093/molbev/msx235/4103410/PhyloNetworks-a-package-for-phylogenetic-networks?guestAccessKey=230afceb-df28-4160-832d-aa7c73f86369)
   34(12):3292–3298.
   [doi:10.1093/molbev/msx235](https://doi.org/10.1093/molbev/msx235)
 
-## Maximum pseudolikelihood estimation of species network: SNaQ <img src="docs/src/snaq.png" align=right title="SNaQ logo" width=262.5 height=111>
-<!-- ![SNaQ logo](http://pages.stat.wisc.edu/~claudia/Images/snaq.png)
-original size: 525px × 222px-->
-
-SNaQ implements the statistical inference method in Sol&iacute;s-Lemus and An&eacute;
-[(2016)](http://journals.plos.org/plosgenetics/article?id=10.1371/journal.pgen.1005896).
-The procedure involves a
-numerical optimization of branch lengths and inheritance probabilities
-and a heuristic search in the space of phylogenetic
-networks.
-
-If you use SNaQ, please cite
-
-- Claudia Sol&iacute;s-Lemus and C&eacute;cile An&eacute; (2016).
-  Inferring Phylogenetic Networks with Maximum Pseudolikelihood under Incomplete Lineage Sorting.
-  [PLoS Genet](http://journals.plos.org/plosgenetics/article?id=10.1371/journal.pgen.1005896)
-  12(3):e1005896.
-  [doi:10.1371/journal.pgen.1005896](https://doi.org/10.1371/journal.pgen.1005896)
-
-## Phylogenetic comparative methods for trait evolution
-
-For continuous traits, study based on the Brownian motion process,
-with or without transgressive evolution after reticulations:
-
-- Bastide, Solís-Lemus, Kriebel, Sparks, Ané (2018).
-  Phylogenetic Comparative Methods for Phylogenetic Networks with Reticulations.
-  Systematic Biology, 67(5):800–820.
-  [doi:10.1093/sysbio/syy033](https://doi.org/10.1093/sysbio/syy033).
-  SI on [dryad](http://dx.doi.org/10.5061/dryad.nt2g6)
-  including a tutorial for trait evolution
-  and a tutorial for network calibration.
-
-Continuous traits, accounting for within-species variation:
-
-- Benjamin Teo, Jeffrey P. Rose, Paul Bastide & Cécile Ané (2022).
-  Accounting for intraspecific variation in continuous trait evolution
-  on a reticulate phylogeny.
-  [bioRxiv](https://doi.org/10.1101/2022.05.12.490814)
-
-For a discrete trait (influence of gene flow on the trait,
-ancestral state reconstruction, rates):
-
-- Karimi, Grover, Gallagher, Wendel, Ané & Baum (2020). Reticulate evolution
-  helps explain apparent homoplasy in floral biology and pollination in baobabs
-  (*Adansonia*; Bombacoideae; Malvaceae).
-  Systematic Biology,
-  69(3):462-478. doi: [10.1093/sysbio/syz073](https://academic.oup.com/sysbio/advance-article/doi/10.1093/sysbio/syz073/5613901?guestAccessKey=a32e7dd3-27fd-4a13-b171-7ff5d6da0e01).
+> [!NOTE]
+> Version 0.17 of PhyloNetworks is a major change from version v0.16.4. Many
+> functionalities were moved to other packages (e.g. SNaQ.jl and PhyloTraits.jl),
+> the names of many methods were changed, and various internal functions
+> were improved with breaking changes (e.g. traversal routines).
+> PhyloNetworks v0.17 should serve as a better "core", used by other packages
+> with more specialized functionalities.