Merge pull request #28 from BioJulia/docfixup

Constructor consistency/documentation fix

.github/workflows/test-lts.yml

@@ -0,0 +1,34 @@
+name: julia-1.0
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: ['1.0']
+        julia-arch: [x64]
+        os: [ubuntu-latest, macOS-latest]
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.julia-version }}
+          arch: ${{ matrix.julia-arch }}
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+        with:
+          depwarn: no

.github/workflows/test-nightly.yml

@@ -0,0 +1,34 @@
+name: julia-nightly
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        julia-version: ['nightly']
+        julia-arch: [x64]
+        os: [ubuntu-latest, macOS-latest]
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.julia-version }}
+          arch: ${{ matrix.julia-arch }}
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+        with:
+          depwarn: no

.github/workflows/ci-stable.yml → .github/workflows/test-stable.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: julia-1.6
 
 on: [push, pull_request]
 
@@ -8,7 +8,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        julia-version: ['1.0', '1']
+        julia-version: ['1.6']
         julia-arch: [x64]
         os: [ubuntu-latest, macOS-latest]
 

Project.toml

@@ -1,7 +1,7 @@
 name = "SubstitutionModels"
 uuid = "8365b1bb-bd83-58ee-a267-f2965fc81c73"
 authors = ["Justin Angevaare <[email protected]>"]
-version = "0.4.2"
+version = "0.5.0"
 
 [deps]
 BioSymbols = "3c28c6f8-a34d-59c4-9654-267d177fcfa9"
@@ -11,7 +11,7 @@ StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 [compat]
 BioSymbols = "3, 4, 5"
 StaticArrays = "0.12, 1"
-julia = "1"
+julia = "1.0, 1"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

README.md

@@ -10,7 +10,9 @@
 
 **Development status:**
 
-[![CI-stable](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/ci-stable.yml/badge.svg)](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/ci-stable.yml)
+[![test-lts](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/test-lts.yml/badge.svg)](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/test-lts.yml)
+[![test-stable](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/test-stable.yml/badge.svg)](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/test-stable.yml)
+[![test-nightly](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/test-nightly.yml/badge.svg)](https://github.com/BioJulia/SubstitutionModels.jl/actions/workflows/test-nightly.yml)
 [![codecov.io](http://codecov.io/github/BioJulia/SubstitutionModels.jl/coverage.svg?branch=master)](http://codecov.io/github/BioJulia/SubstitutionModels.jl?branch=master)
 [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://BioJulia.github.io/SubstitutionModels.jl/latest)
 
@@ -30,8 +32,8 @@ The current release version can be installed
 from the Julia REPL:
 
 ```julia
-julia> using Pkg
-julia> add("SubstitutionModels")
+using Pkg
+Pkg.add("SubstitutionModels")
 ```
 
 ## Contributing and Questions

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/Project.toml

@@ -1,5 +1,2 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-
-[compat]
-Documenter = "~0.22"

docs/make.jl

@@ -1,9 +1,10 @@
-using Documenter, SubstitutionModels
+using Documenter
+using SubstitutionModels
 
 makedocs(
-    modules = [SubstitutionModels],
+    sitename = "SubstitutionModels",
     format = Documenter.HTML(),
-    sitename = "SubstitutionModels.jl",
+    modules = [SubstitutionModels],
     pages = [
         "Home" => "index.md",
         "Manual" => [
@@ -17,5 +18,6 @@ makedocs(
 )
 
 deploydocs(
-    repo = "github.com/BioJulia/SubstitutionModels.jl.git"
+    repo = "github.com/BioJulia/SubstitutionModels.jl.git",
+    push_preview = true
 )

docs/src/man/modeltypes.md

@@ -1,3 +1,7 @@
+```@setup sm
+using SubstitutionModels
+```
+
 # Nucleic Acid Substitution Models
 
 ## Included Substitution Models
@@ -16,90 +20,56 @@ For the convenience of the user, several construction methods exist for each sub
 
 ### Method 1
 The most basic construction method detects whether the absolute or relative rate form of a substitution model is being referenced based on the number of parameters, and constructs it:
-```jldoctest
+```@repl sm
 K80(1e-2)
-
-# output
-Kimura 1980 model (relative rate form)
-κ = 0.01
 ```
 
 Substitution model construction involves a number of checks for parameter validity, though these may be optionally bypassed:
 
-```jldoctest
-K80(-1e-2, false)
-
-# output
-Kimura 1980 model (relative rate form)
-κ = -0.01
+```@repl sm
+K80(-1e-2, safe=false)
 ```
 
 The exact model type may be specific as well, to avoid the software detection of absolute or relative rate specification. The specific forms are the parent models' name followed by `abs` for absolute or `rel` for relative rate form.
 
-```jldoctest
+```@repl sm
 K80rel<:K80, K80abs<:K80
-
-# output
-(true, true)
 ```
 
-```jldoctest
+```@repl sm
 K80abs(1e-2, 1.5e-2)
-
-# output
-Kimura 1980 model (absolute rate form)
-α = 0.01, β = 0.015
 ```
 
 For models requiring specification of base frequencies, those can be provided in the same manner as the other model parameters:
 
-```jldoctest
+```@repl sm
 fieldnames(F81abs)
-
-# output
-(:β, :πA, :πC, :πG, :πT)
 ```
 
-```jldoctest
+```@repl sm
 F81abs(1e-2, 0.2475, 0.2425, 0.2575, 0.2525)
-
-# output
-Felsenstein 1981 model (absolute rate form)
-β = 0.01, π = [0.2475, 0.2425, 0.2575, 0.2525]
 ```
 
 ### Method 2
 It may be familar or convenient for some SubstitutionModels.jl users to construct substitution model objects using a parameter vector of some kind.
 This is also a supported construction method. When specifying a model with an equal base frequency, a single parameter vector is required for construction.
 For models that support different base frequencies, a parameter vector and a base frequency vector are both required.
 
-```jldoctest
+```@repl sm
 F81abs([1e-2], [0.2475, 0.2425, 0.2575, 0.2525])
-
-# output
-Felsenstein 1981 model (absolute rate form)
-β = 0.01, π = [0.2475, 0.2425, 0.2575, 0.2525]
 ```
 
 The unsafe construction method is still available, as is auto-detection of absolute or relative rate types of substitution models.
 
-```jldoctest
-K80([1e-2, 1.5e-2], true)
-
-# output
-Kimura 1980 model (absolute rate form)
-α = 0.01, β = 0.015
+```@repl sm
+K80([1e-2, 1.5e-2], safe = true)
 ```
 
 ### Method 3
 Lastly, `convert` methods are also provided for each substitution model type:
 
-```jldoctest
-convert(K80, [1e-2, 1.5e-2], true)
-
-# output
-Kimura 1980 model (absolute rate form)
-α = 0.01, β = 0.015
+```@repl sm
+convert(K80, [1e-2, 1.5e-2])
 ```
 
 ## User defined substitution models

src/core.jl

@@ -22,15 +22,15 @@ const Pmatrix = SMatrix{4, 4, Float64}
 
 
 function Base.convert(::Type{T}, θ::F...; safe::Bool=true) where {T <: NASM, F <: Float64}
-  return T(θ..., safe)
+  return T(θ..., safe=safe)
 end
 
 
 function Base.convert(::Type{T}, θ_vec::A; safe::Bool=true) where {T <: NASM, A <: AbstractArray}
-  return T(θ_vec, safe)
+  return T(θ_vec, safe=safe)
 end
 
 
 function Base.convert(::Type{T}, θ_vec::A, π_vec::A; safe::Bool=true) where {T <: NASM, A <: AbstractArray}
-  return T(θ_vec, π_vec, safe)
+  return T(θ_vec, π_vec, safe=safe)
 end

src/nucleic_acid/f81/absolute.jl

@@ -5,7 +5,7 @@ struct F81abs <: F81
   πG::Float64
   πT::Float64
   function F81abs(β::Float64,
-                  πA::Float64, πC::Float64, πG::Float64, πT::Float64,
+                  πA::Float64, πC::Float64, πG::Float64, πT::Float64;
                   safe::Bool=true)
     if safe
       if β <= 0.

src/nucleic_acid/f81/outer_constructors.jl

@@ -1,35 +1,35 @@
-F81(πA::F, πC::F, πG::F, πT::F,
+F81(πA::F, πC::F, πG::F, πT::F;
     safe::Bool=true) where F <: Float64 =
 F81rel(πA, πC, πG, πT)
 
 
 F81(β::F,
-    πA::F, πC::F, πG::F, πT::F,
+    πA::F, πC::F, πG::F, πT::F;
     safe::Bool=true) where F <: Float64 =
-F81abs(β, πA, πC, πG, πT, safe)
+F81abs(β, πA, πC, πG, πT, safe=safe)
 
 
 function F81(θ_vec::A,
-             π_vec::A,
+             π_vec::A;
              safe::Bool=true) where A <: AbstractArray
   if safe && length(π_vec) != 4
     error("Incorrect base frequency vector length")
   end
   if length(θ_vec) == 0
     return F81rel(π_vec[DNA_A], π_vec[DNA_C], π_vec[DNA_G], π_vec[DNA_T],
-                  safe)
+                  safe=safe)
   elseif length(θ_vec) == 1
     return F81abs(θ_vec[1],
                   π_vec[DNA_A], π_vec[DNA_C], π_vec[DNA_G], π_vec[DNA_T],
-                  safe)
+                  safe = safe)
   else
     error("Parameter vector length incompatiable with absolute or relative rate form of substitution model")
   end
 end
 
 
 function F81rel(θ_vec::A,
-                π_vec::A,
+                π_vec::A;
                 safe::Bool=true) where A <: AbstractArray
   if safe
     if length(θ_vec) != 0
@@ -38,13 +38,13 @@ function F81rel(θ_vec::A,
       error("Incorrect base frequency vector length")
     end
   end
-  return F81rel(π_vec[DNA_A], π_vec[DNA_C], π_vec[DNA_G], π_vec[DNA_T], safe)
+  return F81rel(π_vec[DNA_A], π_vec[DNA_C], π_vec[DNA_G], π_vec[DNA_T], safe=safe)
 end
 
 
 
 function F81abs(θ_vec::A,
-                π_vec::A,
+                π_vec::A;
                 safe::Bool=true) where A <: AbstractArray
   if safe
     if length(θ_vec) != 1
@@ -53,5 +53,5 @@ function F81abs(θ_vec::A,
       error("Incorrect base frequency vector length")
     end
   end
-  return F81abs(θ_vec[1], π_vec[DNA_A], π_vec[DNA_C], π_vec[DNA_G], π_vec[DNA_T], safe)
+  return F81abs(θ_vec[1], π_vec[DNA_A], π_vec[DNA_C], π_vec[DNA_G], π_vec[DNA_T], safe=safe)
 end

src/nucleic_acid/f81/relative.jl

@@ -3,7 +3,7 @@ struct F81rel <: F81
   πC::Float64
   πG::Float64
   πT::Float64
-  function F81rel(πA::Float64, πC::Float64, πG::Float64, πT::Float64,
+  function F81rel(πA::Float64, πC::Float64, πG::Float64, πT::Float64;
                   safe::Bool=true)
     if safe
       if sum([πA,πC,πG,πT]) != 1.0

src/nucleic_acid/f84/absolute.jl

@@ -6,7 +6,7 @@ struct F84abs <: F84
   πG::Float64
   πT::Float64
   function F84abs(κ::Float64, β::Float64,
-                  πA::Float64, πC::Float64, πG::Float64, πT::Float64,
+                  πA::Float64, πC::Float64, πG::Float64, πT::Float64;
                   safe::Bool=true)
     if safe
       if κ <= 0.