simulator can take user-defined random number generator

.github/workflows/CI.yml

@@ -3,7 +3,7 @@ on:
   push:
     branches:
       - main
-    tags: '*'
+    tags: ['*']
   pull_request:
 concurrency:
   # Skip intermediate builds: always.
@@ -36,27 +36,7 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v2
+      - uses: codecov/codecov-action@v4
         with:
+          token: ${{ secrets.CODECOV_TOKEN }}
           files: lcov.info
-  docs:
-    name: Documentation
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: r-lib/actions/setup-r@v2
-      - run: echo "LD_LIBRARY_PATH=$(R RHOME)/lib" >> $GITHUB_ENV
-      - uses: julia-actions/setup-julia@v1
-        with:
-          version: '1'
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-docdeploy@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
-      - run: |
-          julia --project=docs -e '
-            using Documenter: DocMeta, doctest
-            using PhyloCoalSimulations
-            DocMeta.setdocmeta!(PhyloCoalSimulations, :DocTestSetup, :(using PhyloCoalSimulations); recursive=true)
-            doctest(PhyloCoalSimulations)'

.github/workflows/doccleanup.yml

@@ -1,28 +1,34 @@
-name: Doc Preview Cleanup
+# remove PR previews once they're merged
+name: doc preview cleanup
 
 on:
   pull_request:
     types: [closed]
 
+# ensure that only one "doc preview cleanup" workflow is force-pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
 jobs:
   doc-preview-cleanup:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
-      - name: Checkout gh-pages branch
-        uses: actions/checkout@v2
+      - name: checkout gh-pages branch
+        uses: actions/checkout@v4
         with:
           ref: gh-pages
-
-      - name: Delete preview and history
+      - name: delete preview and history + push changes
         run: |
-            git config user.name "Documenter.jl"
-            git config user.email "[email protected]"
-            git rm -rf "previews/PR$PRNUM"
-            git commit -m "delete preview"
-            git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
         env:
-            PRNUM: ${{ github.event.number }}
-
-      - name: Push changes
-        run: |
-            git push --force origin gh-pages-new:gh-pages
+          preview_dir: previews/PR${{ github.event.number }}

.github/workflows/documentation.yml

@@ -0,0 +1,30 @@
+name: Documenter
+
+on:
+  push:
+    branches:
+      - main
+    tags: '*'
+  pull_request:
+
+jobs:
+  Documenter:
+    name: documentation
+    permissions:
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: r-lib/actions/setup-r@v2
+      - run: echo "LD_LIBRARY_PATH=$(R RHOME)/lib" >> $GITHUB_ENV
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v1
+      - uses: julia-actions/julia-buildpkg@latest
+      - uses: julia-actions/julia-docdeploy@latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

CITATION.bib

@@ -5,7 +5,9 @@ @article{2023fogg_phylocoalsimulations
         models, including a new extension for the inheritance of gene flow},
   journal = {Systematic Biology},
   year = {2023},
-  volume = {in press},
+  volume = {72},
+  number = {5},
+  pages = {1171-1179},
   doi = {10.1093/sysbio/syad030},
 }
 % older bioRxiv preprint

Project.toml

@@ -2,11 +2,12 @@ name = "PhyloCoalSimulations"
 uuid = "53f7b83a-06b5-4910-9a21-1896bf762ade"
 authors = ["Cecile Ane <[email protected]>",
            "John Fogg <[email protected]>"]
-version = "0.1.2"
+version = "0.1.3"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 PhyloNetworks = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 
 [compat]
 Distributions = "0.25"

README.md

@@ -1,6 +1,16 @@
 # PhyloCoalSimulations
 
-[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://cecileane.github.io/PhyloCoalSimulations.jl/stable)
-[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://cecileane.github.io/PhyloCoalSimulations.jl/dev)
+[![stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://cecileane.github.io/PhyloCoalSimulations.jl/stable)
+[![dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://cecileane.github.io/PhyloCoalSimulations.jl/dev)
 [![Build Status](https://github.com/cecileane/PhyloCoalSimulations.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/cecileane/PhyloCoalSimulations.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/cecileane/PhyloCoalSimulations.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/cecileane/PhyloCoalSimulations.jl)
+[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
+[![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/PhyloCoalSimulations.svg)](https://JuliaCI.github.io/NanosoldierReports/pkgeval_badges/report.html)
+
+
+PhyloCoalSimulations is a [Julia](http://julialang.org/) package to
+simulate phylogenies under the coalescent.
+It implements the network multi-species coalescent model with
+possible inheritance correlation:
+please see [CITATION](CITATION.bib) and documentation (links above).

docs/Project.toml

@@ -2,12 +2,12 @@
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433"
 PhyloCoalSimulations = "53f7b83a-06b5-4910-9a21-1896bf762ade"
 PhyloNetworks = "33ad39ac-ed31-50eb-9b15-43d0656eaa72"
 PhyloPlots = "c0d5b6db-e3fc-52bc-a87d-1d050989ed3b"
 RCall = "6f49c342-dc21-5d91-9882-a32aef131414"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 
 [compat]
-Documenter = "~0.27"
+Documenter = "1"
 PhyloPlots = "1"

docs/make.jl

@@ -6,11 +6,10 @@ DocMeta.setdocmeta!(PhyloCoalSimulations, :DocTestSetup, :(using PhyloCoalSimula
 makedocs(;
     modules=[PhyloCoalSimulations],
     authors="Cecile Ane <[email protected]> and contributors",
-    repo="https://github.com/cecileane/PhyloCoalSimulations.jl/blob/{commit}{path}#{line}",
     sitename="PhyloCoalSimulations.jl",
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://cecileane.github.io/PhyloCoalSimulations.jl",
+        canonical="https://cecileane.github.io/PhyloCoalSimulations.jl/stable/",
         assets=String[],
     ),
     pages=[

docs/readme.md

@@ -5,13 +5,14 @@
   (go to `dev/` or `stable/`)
   using github and files committed to the `gh-pages` branch.
 
-The workflow is controlled by `.github/workflows/CI.yml`, which launches
-`docs/make.jl`. To meet the dependency on R (via PhyloPlots) CI.yml installs R.
+The workflow is controlled by `.github/workflows/documentation.yml`,
+which launches `docs/make.jl`.
+To meet the dependency on R (via PhyloPlots) documentation.yml installs R.
 
 ## what to update
 
 - Documenter version in `docs/Project.toml`
-- update Julia version in `.github/workflows/CI.yml` under `docs:`.
+- update Julia version in `.github/workflows/documentation.yml`
 
 ## to build the documentation locally
 

docs/src/index.md

@@ -14,15 +14,18 @@ References:
 please see [bibtex entries here](https://github.com/cecileane/PhyloCoalSimulations.jl/blob/main/CITATION.bib).
 
 - for this package and the network coalescent model with inheritance correlation:\
-  [Fogg, Allman & Ané (2023)](https://doi.org/10.1093/sysbio/syad030)
+  Fogg, Allman & Ané (2023).
   PhyloCoalSimulations: A simulator for network multispecies coalescent models,
   including a new extension for the inheritance of gene flow.
+  [Systematic Biology](https://academic.oup.com/sysbio/advance-article/doi/10.1093/sysbio/syad030/7187011?guestAccessKey=616778e9-ea09-4e4e-9853-229499b5f068),
+  72(5):1171–1179.
+  [doi:10.1093/sysbio/syad030](https://doi.org/10.1093/sysbio/syad030).
 
 - for [PhyloNetworks](https://github.com/crsl4/PhyloNetworks.jl),
   which this package depends on:\
   Solís-Lemus, Bastide & Ané (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)
+  [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)
 

docs/src/man/converting_coal2generation_units.md

@@ -1,8 +1,8 @@
 ```@setup converting
-using PhyloNetworks, PhyloPlots, PhyloCoalSimulations
+using PhyloNetworks, PhyloPlots, PhyloCoalSimulations, StableRNGs
 figpath = joinpath("..", "assets", "figures"); mkpath(figpath)
 figname(x) = joinpath(figpath, x)
-net = readTopology("((C:0.9,(B:0.2)#H1:0.7::0.6)I1:0.6,(#H1:0.6::0.4,A:1.0)I2:0.5)I3;");
+net = readTopology("((C:0.9,(B:0.2)#H1:0.7::0.6)i1:0.6,(#H1:0.6::0.4,A:1.0)i2:0.5)i3;");
 ```
 
 # converting between units
@@ -23,8 +23,8 @@ including the root edge.
 Here is an example using the same network and simulated gene tree as earlier.
 ```@repl converting
 writeTopology(net)
-using Random; Random.seed!(261); # as in mapping block
-tree = simulatecoalescent(net,1,1; nodemapping=true)[1];
+rng = StableRNG(7); # as in mapping section
+tree = simulatecoalescent(rng, net,1,1; nodemapping=true)[1];
 writeTopology(tree, round=true)
 ```
 ![example 1, same as in mapping section](../assets/figures/genetree_example1.svg)
@@ -68,16 +68,17 @@ then the coalescence rate on that edge is determined by the harmonic mean
 
 Let's assume we have a network with number of generations as edge lengths:
 ```@repl converting
-net_gen = readTopology("((C:900,(B:200)#H1:700::0.6)I1:600,(#H1:600::0.4,A:1000)I2:500)I3;");
+net_gen = readTopology("((C:900,(B:200)#H1:700::0.6)i1:600,(#H1:600::0.4,A:1000)i2:500)i3;");
 ```
 and that we have a dictionary listing the (harmonic mean) population
 size along each edge of the species network, and also along the root edge
 above the network. Below, we simulate a population size for each population,
 from a uniform distribution between 1,000 and 1,500.
 
 ```@repl converting
+using Distributions
 # uniform distribution between 1000 and 1500, that we can draw from later
-Ne_distribution() = round(Int, 1000 + 500*Random.rand());
+Ne_distribution() = rand(rng, DiscreteUniform(1000, 1500));
 Ne = Dict(e.number => Ne_distribution() for e in net_gen.edge);
 rootedgenumber = PhyloCoalSimulations.get_rootedgenumber(net_gen)
 push!(Ne, rootedgenumber => Ne_distribution()); # Nₑ above the root
@@ -116,6 +117,6 @@ writeMultiTopology(genetree_gen, stdout) # 3 gene trees, lengths in #generations
 
 !!! warning
     When Nₑ is given as an extra input to `simulatecoalescent`,
-    edge lengths in the network are assumed to be in # of generations.
+    edge lengths in the network are assumed to be in number of generations.
     If Nₑ is *not* given as input, then edge lengths are assumed to be
     in coalescent units.

docs/src/man/mapping_genetree_to_network.md

@@ -1,5 +1,5 @@
 ```@setup mapping
-using PhyloNetworks, PhyloPlots, PhyloCoalSimulations, RCall, DataFrames
+using PhyloNetworks, PhyloPlots, PhyloCoalSimulations, RCall, DataFrames, StableRNGs
 figpath = joinpath("..", "assets", "figures"); mkpath(figpath)
 figname(x) = joinpath(figpath, x)
 ```
@@ -19,11 +19,11 @@ can later map nodes in the gene tree.
 
 ```@repl mapping
 net = readTopology("((C:0.9,(B:0.2)#H1:0.7::0.6):0.6,(#H1:0.6,A:1):0.5);");
-PhyloNetworks.nameinternalnodes!(net, "I"); # "I" is a prefix to name internal nodes
+PhyloNetworks.nameinternalnodes!(net, "i"); # "i" is a prefix to name internal nodes
 writeTopology(net)
 ```
 
-Notice the extra node names in the species phylogeny: I1, I2, and I3 at the root.
+Notice the extra node names in the species phylogeny: i1, i2, and i3 at the root.
 
 Next, we use the option `nodemapping=true` when simulating gene trees,
 to ask for extra degree-2 nodes in gene trees. These nodes are created each time
@@ -32,18 +32,18 @@ each time that a gene tree lineage crosses a speciation node or a hybridization
 We'll simulate a single tree here each time.
 
 ```@repl mapping
-using Random; Random.seed!(261); # to replicate randomness
-tree_regular = simulatecoalescent(net,1,1)[1];
+using StableRNGs; rng = StableRNG(7); # to replicate randomness, but default RNG is better
+tree_regular = simulatecoalescent(rng, net,1,1)[1];
 writeTopology(tree_regular, round=true) # regular nodes only
-Random.seed!(261); # to replicate the same coalescent simulation
-tree = simulatecoalescent(net,1,1; nodemapping=true)[1];
+rng = StableRNG(7); # to replicate the same coalescent simulation
+tree = simulatecoalescent(rng, net,1,1; nodemapping=true)[1];
 writeTopology(tree, round=true) # extra degree-2 nodes for mapping
 ```
 
 Notice that regular nodes in the gene tree (nodes that we get without the
 `nodemapping` option) don't have names. With the `nodemapping` option, there are
 many new nodes, all of degree-2, named after internal nodes in the network
-(I1, I2, I3). These extra degree-2 nodes and their names are sufficient to map
+(i1, i2, i3). These extra degree-2 nodes and their names are sufficient to map
 the gene tree into the species network.
 
 The network is shown on the left below, with edges annotated by their numbers.
@@ -73,8 +73,8 @@ For example, the horizontal line tracing B's ancestry back in time maps into the
 network like this:
 - from B, go back along edge 2
 - meet hybrid node H1, was inherited from the minor hybrid edge 5,
-- from speciation node I2, trace back along edge 7,
-- meet the network's root node I3, trace back along the network's root edge 8
+- from speciation node i2, trace back along edge 7,
+- meet the network's root node i3, trace back along the network's root edge 8
   before coalescing with the ancestor of the other lineages (which have already
   coalesced by then).