v1.0.0: transfer of functionalities for trait evolution from PhyloNetworks v0.16, with breaking changes and improvements

.github/workflows/CI.yml

@@ -23,7 +23,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.2'
+          - '1'
         os:
           - ubuntu-latest
           - macOS-latest
@@ -40,7 +40,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 }}
@@ -54,6 +54,8 @@ jobs:
       statuses: write
     steps:
       - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+      - run: echo "LD_LIBRARY_PATH=$(R RHOME)/lib:$LD_LIBRARY_PATH" >> $GITHUB_ENV
       - uses: julia-actions/setup-julia@v2
         with:
           version: '1'
@@ -74,5 +76,5 @@ jobs:
         run: |
           using Documenter: DocMeta, doctest
           using PhyloTraits
-          DocMeta.setdocmeta!(PhyloTraits, :DocTestSetup, :(using PhyloTraits); recursive=true)
+          DocMeta.setdocmeta!(PhyloTraits, :DocTestSetup, :(using PhyloTraits; using PhyloNetworks); recursive=true)
           doctest(PhyloTraits)

CITATION.bib

@@ -30,11 +30,13 @@ @article{2020Karimi_baobab_discretetraitevolution
   doi = {10.1093/sysbio/syz073},
 }
 % paper on continuous traits with intraspecific variation
-@article{2022Teo_intraspeciesvariation,
+@article{2023Teo_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},
+  journal = {Bulletin of the Society of Systematic Biologists},
+  year = {2023},
+  volume = {2},
+  number = {3},
+  pages = {1-29},
+  doi = {10.18061/bssb.v2i3.8977},
 }

Project.toml

@@ -1,7 +1,43 @@
 name = "PhyloTraits"
 uuid = "bce24f4f-6725-4ba4-a77f-2b043c8e33c5"
 authors = ["Cecile Ane <[email protected]>", "Paul Bastide <[email protected]>", "and contributors"]
-version = "0.1.0-DEV"
+version = "1.0.0"
+
+[deps]
+BioSequences = "7e6ae17a-c86d-528c-b3b9-7f778a29fe59"
+BioSymbols = "3c28c6f8-a34d-59c4-9654-267d177fcfa9"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+FASTX = "c2308a5c-f048-11e8-3e8a-31650f418d12"
+GLM = "38e38edf-8417-5370-95a0-9cbb8c7f171a"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
+PhyloNetworks = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+StatsAPI = "82ae8749-77ed-4fe6-ae5f-f523153014b0"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+StatsFuns = "4c63d2b9-4356-54db-8cca-17b64c39e42c"
+StatsModels = "3eaba693-59b7-5ba5-a881-562e759f1c8d"
 
 [compat]
+BioSequences = "2, 3"
+BioSymbols = "4, 5"
+DataFrames = "1.3"
+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"
+GLM = "1.1"
+LinearAlgebra = "1"
+NLopt = "0.5.1, 0.6, 1"
+PhyloNetworks = "1"
+Printf = "1"
+Random = "1"
+StaticArrays = "0.8.3, 0.9, 0.10, 0.11, 0.12, 1"
+Statistics = "1"
+StatsAPI = "1.5"
+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.2"

README.md

@@ -1,4 +1,4 @@
-# PhyloTraits
+# PhyloTraits: trait evolution along phylogenies
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaPhylo.github.io/PhyloTraits.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaPhylo.github.io/PhyloTraits.jl/dev/)
@@ -13,11 +13,39 @@
 a phylogeny, including phylogenetic networks. It depends on utilities from
 [PhyloNetworks](https://github.com/JuliaPhylo/PhyloNetworks.jl).
 
+## Citing
+
+See [`CITATION.bib`](CITATION.bib) for the relevant reference(s).
+Below is a short list.
+
+For continuous traits, analyses 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é (2023).
+  Accounting for intraspecific variation in continuous trait evolution
+  on a reticulate phylogeny.
+  Bulletin of the Society of Systematic Biologists, 2(3):1-29.
+  doi: [10.18061/bssb.v2i3.8977](https://doi.org/10.18061/bssb.v2i3.8977)
+
+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]
 > Much of this package was formerly part of PhyloNetworks v0.16.4 (and prior).
 > PhyloNetworks v0.17 will be stripped of functions for trait evolution.
-
-## Citing
-
-See [`CITATION.bib`](CITATION.bib) for the relevant reference(s).

docs/Project.toml

@@ -1,3 +1,16 @@
 [deps]
+BioSequences = "7e6ae17a-c86d-528c-b3b9-7f778a29fe59"
+BioSymbols = "3c28c6f8-a34d-59c4-9654-267d177fcfa9"
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+GLM = "38e38edf-8417-5370-95a0-9cbb8c7f171a"
+PhyloNetworks = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
+PhyloPlots = "c0d5b6db-e3fc-52bc-a87d-1d050989ed3b"
 PhyloTraits = "bce24f4f-6725-4ba4-a77f-2b043c8e33c5"
+RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
+StatsAPI = "82ae8749-77ed-4fe6-ae5f-f523153014b0"
+StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
+StatsModels = "3eaba693-59b7-5ba5-a881-562e759f1c8d"

docs/make.jl

@@ -1,23 +1,50 @@
 using PhyloTraits
 using Documenter
 
-DocMeta.setdocmeta!(PhyloTraits, :DocTestSetup, :(using PhyloTraits); recursive=true)
+# Interlink with PhyloNetworks
+using DocumenterInterLinks
+links = InterLinks(
+    "PhyloNetworks" => "https://juliaphylo.github.io/PhyloNetworks.jl/stable/objects.inv"
+)
+
+# NOTE: default loading of PhyloNetworks in all docstring examples
+DocMeta.setdocmeta!(
+    PhyloTraits,
+    :DocTestSetup,
+    :(using PhyloNetworks; using PhyloTraits);
+    recursive=true)
 
 makedocs(;
     modules=[PhyloTraits],
     authors="Cecile Ane <[email protected]>, Paul Bastide <[email protected]>, and contributors",
     sitename="PhyloTraits.jl",
     format=Documenter.HTML(;
+        prettyurls = get(ENV, "CI", nothing) == "true", # easier local build
+        size_threshold = 600 * 2^10,
+        size_threshold_warn = 500 * 2^10, # 600 KiB
         canonical="https://JuliaPhylo.github.io/PhyloTraits.jl",
         edit_link="main",
         assets=String[],
     ),
     pages=[
         "Home" => "index.md",
+        "Manual" => [
+            "Continuous trait analysis" => "man/phyloregression.md",
+            "Continuous trait simulation" => "man/simulate_continuous.md",
+            "Discrete trait analysis" => "man/fitDiscrete.md",
+            "DNA evolutionary models" => "man/fitdiscreteDNA.md",
+            "Discrete trait simulation" => "man/simulate_discrete.md",
+        ],
+        "Library" => [
+            "public" => "lib/public.md",
+            "internals" => "lib/internal.md",
+        ]
     ],
+    plugins=[links],
 )
 
 deploydocs(;
     repo="github.com/JuliaPhylo/PhyloTraits.jl",
     devbranch="main",
+    push_preview = true,
 )

docs/readme.md

@@ -0,0 +1,150 @@
+# notes to maintain documentation
+
+- built with [Documenter](https://documenter.juliadocs.org/stable/).
+- deployed [here](https://juliaphylo.github.io/PhyloTraits.jl/)
+  using GitHub and files committed to the `gh-pages` branch:
+  go to `dev/`, or manually type the url to preview the docs from a pull request:
+  [https://juliaphylo.github.io/PhyloTraits.jl/previews/PR#/] with `#` replaced
+  by the pull request number.
+
+## quick start: create a local version of the website
+
+generally: to see deprecation warnings, add the option `--depwarn=yes`.
+go into the `docs/` folder, load the project environment, then run `make.jl`:
+
+```shell
+cd docs
+julia --project -e 'using Pkg; Pkg.instantiate(); Pkg.develop(PackageSpec(path=dirname(pwd())))'
+julia --project --color=yes make.jl
+```
+
+or interactively in `docs/`, if needing to have finer control of loaded dependencies:
+
+```shell
+pkg> activate .
+pkg> status # just to check
+pkg> status --manifest
+pkg> instantiate # after deleting Manifest.toml
+# do what you need to do to update dependencies / dev packages
+julia> include("make.jl")
+```
+
+or, after project & manifest setup, from the main repo instead of `docs/`:
+```shell
+julia --project=docs/ --color=yes docs/make.jl
+```
+
+it will:
+- test the `jldoctest` blocks of examples in the docstrings
+- create or update a `build/` directory with html files.
+
+To see the result, just open `docs/build/index.html` in a browser and follow the links.
+
+## how it works: overview
+
+- The `docs` job (named "Documentation") of `.github/workflows/CI.yml`
+  * installs R, installs Julia
+  * runs Julia commands that asks to start the doc project, which will trigger
+    the installation of dependencies listed in `docs/Project.toml`,
+  * then run `doctest(PhyloTraits)`, which will call `./docs/make.jl`.
+- the julia script `docs/make.jl` includes these steps:
+  1. run `makedocs()` to create the documentation website.
+     also runs all `jldoctest` blocks in the source files, to check that
+     the output in the blocks matches the actual output.
+     This steps also translate the "Documenter md" documentation files
+     into html files.
+  2. run `deploydocs(...)` also from Documenter:
+     to push the files on github, gh-pages branch.
+
+for now, docstrings are automatically used to build an entry for
+- each internal thing that has a docstring (e.g. not exported in `src/PhyloTraits.jl`)
+- each public thing.
+
+## The "Documenter md" format
+
+The documentation pages are all written in this format. It is a regular md, but
+with extra blocks of codes (as `@example` and `@setup`) that contain Julia
+commands. These lines will be executed during the `makedoc()` process. See the
+`Documenter` [doc](https://juliadocs.github.io/Documenter.jl/stable/man/syntax/)
+for more details on the syntax. For instance, @example blocks with the same "name"
+are run in the same session. Otherwise, an @example blocks with no name
+is run in its own anonymous Module.
+
+## documentation figures & plots
+
+Some of these blocks may contain plots, which are going to be drawn during the
+process, requiring the use of `PhyloPlots` along with `RCall`. Hence,
+before the doc is built, `.github/workflows/ci.yml` installs `R` on the server,
+sets up the julia environment with dependencies like `PhyloPlots` before
+starting the build in itself.
+
+### directory to save figures
+
+We chose to group all the output plots in the directory `assets/figures`.
+Hence, the typical setup in a documentation page containing plots is:
+
+    ```@setup name
+    using PhyloPlots, RCall
+    mkpath("../assets/figures")
+    figname(x) = joinpath("..", "assets", "figures", x) # hide
+    ```
+
+The `mkpath` command is there to ensure that the target directory does indeed
+exist. In theory, it only needs to be called once (by the first documentation
+page being built). However, as this order might be subject to change over time,
+it could be safer to include it on every such page.
+
+### figure format
+
+After trial and error and discussions, we chose to use only the *SVG* format
+for plots. This format should ensure that when a plot is drawn again,
+identical, in a new build, then Git will recognize that it has not changed, and
+hence not save a new version of it. This should ensure that the repository does
+not grow unreasonably at each build of the doc, i.e. after each push to
+master. The typical commands to save and display a plot should hence be:
+
+    ```@example name
+    R"svg"(figname("my_useful_name.svg"), width=4, height=4) # hide
+    plot(net);
+    R"dev.off()" # hide
+    nothing # hide
+    ```
+    ![my_useful_name](../assets/figures/my_useful_name.svg)
+
+**Warning**: this is not like an interactive session. If the same file name
+is re-used by some other documentation page for some other plot, only the
+final version of the plot will be committed by git, with possible unintended
+consequences. Make sure to use different file names for plots that are supposed
+to look different (across the whole site).
+
+## references
+
+big difference:
+
+    [blabla](@ref)
+    [`blabla`](@ref)
+
+The first version will look for a *section* header "blabla", to link to that section.
+The secon version will look for a *function* named "blabla",
+to link to the documentation for that function.
+
+### external references
+
+References to functions from external packages are handled with
+[`DocumenterInterLinks.jl`](https://juliadocs.org/DocumenterInterLinks.jl/stable/).
+To set up external references, `make.jl` needs to be modified to include
+the package for referencing. For example, to make references to functions in
+`PhyloNetworks`, `make.jl` has these additional lines of code:
+
+```julia
+# Interlink with PhyloNetworks
+using DocumenterInterLinks
+links = InterLinks(
+    "PhyloNetworks" => "https://juliaphylo.github.io/PhyloNetworks.jl/stable/objects.inv"
+)
+```
+
+The `links` object is then used in the `plugins` argument of `makedocs()` ran
+at the end of `make.jl`.
+Now `@ref` can be used to reference things in `PhyloNetworks`!
+We can also use `@extref` to specify that a reference is an external one.