improve rule docs

.github/workflows/Documenter.yml

@@ -0,0 +1,18 @@
+name: Documenter
+on:
+  push:
+    branches: [master]
+    tags: [v*]
+  pull_request:
+    branches: [master]
+jobs:
+  Documenter:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/julia-buildpkg@latest
+      - uses: julia-actions/julia-docdeploy@latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/TagBot.yml

@@ -1,11 +1,15 @@
 name: TagBot
 on:
-  schedule:
-    - cron: 0 * * * *
+  issue_comment:
+    types:
+      - created
+  workflow_dispatch:
 jobs:
   TagBot:
+    if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
     runs-on: ubuntu-latest
     steps:
       - uses: JuliaRegistries/TagBot@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/ci.yml

@@ -34,20 +34,3 @@ jobs:
         with:
           file: lcov.info
           fail_ci_if_error: true
-  docs:
-    name: Documentation
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
-        with:
-          version: '1.5'
-      - run: |
-          julia --project=docs -e '
-            using Pkg
-            Pkg.develop(PackageSpec(path=pwd()))
-            Pkg.instantiate()'
-      - run: julia --project=docs docs/make.jl
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

docs/src/example.jmd

@@ -18,6 +18,7 @@ NetCDF and GeoTiff files, respectively.
 ```{julia; results="hidden"}
 # using Pkg
 # Pkg.add(PackageSpec(url="https://github.com/rafaqz/GeoData.jl", rev="master"))
+
 using GeoData, DimensionalData, Dispersal, Dates, NCDatasets, ArchGDAL, Plots
 using DimensionalData: rebuild, Forward, Reverse
 basedir = joinpath(dirname(Base.pathof(Dispersal)), "../docs")
@@ -59,9 +60,8 @@ And select just the bounding box for Australia, and set the dimension order to L
 ```{julia; results="hidden"}
 growthrates = NCDarray(growthratesfilepath)
 # Set the length of the timestep. TODO: get this automatically from NetCDF units in GeoData.jl
-ti = dims(growthrates, Ti)
 mode_ = Sampled(DimensionalData.order(ti), Regular(timestep), Intervals(Start()))
-growthrates = setdims(growthrates, rebuild(ti; mode=mode_));
+growthrates = set(growthrates, Ti=mode_);
 ```
 
 Plot the growth layer:

docs/src/index.md

@@ -16,8 +16,6 @@ in the surrounding cells.
 
 ```@docs
 InwardsDispersal
-InwardsBinaryDispersal
-InwardsPopulationDispersal
 ```
 
 ## Partial Neighborhood Rules
@@ -28,8 +26,6 @@ are harder to optimise and will generally have worse performance.
 
 ```@docs
 OutwardsDispersal
-OutwardsBinaryDispersal
-OutwardsPopulationDispersal
 ```
 
 ## Dispersal kernels 
@@ -58,20 +54,15 @@ AreaToArea
 ## Cell rules
 Rules that simply transform the state of a single cell, ignoring the rest of the grid.
 
-
 ### Growth rules
 
 ```@docs
 GrowthRule
 ExponentialGrowth
 LogisticGrowth
-GrowthMapRule
-ExponentialGrowthMap
-LogisticGrowthMap
-MaskGrowthMap
+ThresholdGrowth
 ```
 
-
 ### Allee effects
 
 ```@docs
@@ -98,38 +89,3 @@ populate
 downsample
 downsample!
 ```
-
-# Aux data retrieval
-
-```@docs
-auxval
-AuxCopy
-```
-
-## Optimisation
-
-Dispersal.jl provides optimisation tools for optimising the parameters of
-arbitrary `Ruleset`s, given target data. [`Objective`](@ref) can be extended to
-add specific objection functions to transform simulation outputs.
-
-```@docs
-Parametriser
-Objective
-SimpleObjective
-RegionObjective
-RegionOutput
-ColorRegionFit
-targets
-predictions
-```
-
-### Simulation replicates
-
-Methods for running replicate simulations can be specified.
-
-```julia
-Replicates
-DistributedReplicates
-SingleCoreReplicates
-ThreadedReplicates
-```

src/Dispersal.jl

@@ -32,7 +32,7 @@ export AlleeExtinction, JumpDispersal
 
 export HumanDispersal, BatchGroups, HeirarchicalGroups
 
-export ThresholdGrowth, ExponentialGrowth, LogisticGrowth
+export ExponentialGrowth, LogisticGrowth, ThresholdGrowth
 
 # Documentation templates
 @template TYPES =
@@ -44,7 +44,6 @@ export ThresholdGrowth, ExponentialGrowth, LogisticGrowth
 const DG = DynamicGrids
 
 include("downsampling.jl")
-include("utils.jl") 
 include("kernel/common.jl")
 include("kernel/inwards.jl")
 include("kernel/outwards.jl")

src/allee.jl

@@ -1,15 +1,17 @@
 """ 
     AlleeExtinction(minfounders)
-    AlleeExtinction(; minfounders=5.0)
+    AlleeExtinction{R}(; minfounders=5.0)
     AlleeExtinction{R,W}(minfounders)
 
 Causes extinction in a cell when a population is below the 
 minimum number of individuals required to maintain it. 
 
-Pass grid name `Symbol`s to `R` and `W` type parameters to use specific grids.
+- `minfounders`: minimum founding individuals required to to start an ongoing population.
+  Must be a type that can be compared to the grid values using `isless`.
+
+Pass grid `Symbol`s to `R` or both `R` and `W` type parameters to use to specific grids.
 """
 struct AlleeExtinction{R,W,MF} <: CellRule{R,W}
-    "Minimum founding individuals required to to start an ongoing population"
     minfounders::MF 
 end
 AlleeExtinction{R,W}(; minfounders=Param(5.0, bounds=(1.0, 200.0))) where {R,W} = 

src/growth.jl

@@ -4,30 +4,34 @@ const INTRINSICRATE_PARAM = Param(0.1,      bounds=(0.0, 10.0))
 const THRESHOLD_PARAM     = Param(0.5;      bounds=(0.0, 1.0))
 
 """
-Extends CellRule for rules of growth dynamics
-
-For best performance these should be chained with other
-CellRule or following an NeighborhoodRule.
+Abstract supertype of `CellRule` for growth dynamics rules.
 """
 abstract type GrowthRule{R,W} <: CellRule{R,W} end
 
 """
+    ExponentialGrowth(; rate, timestep)
+    ExponentialGrowth{R}(; rate, timestep)
+    ExponentialGrowth{R,W}(; rate, timestep)
+
 Exponential growth based on a growth rate data, using exact solution.
+
+# Keyword Arguments
+
+- `rate`: Growth rate. May be a `Number`, an [`Aux`](@ref) array or another [`Grid`](@ref).
+- `timestep`: Time step for the growth rate, in a type compatible with the simulation `tspan`.
+
+Pass grid `Symbol`s to `R` or both `R` and `W` type parameters to use to specific grids.
 """
 struct ExponentialGrowth{R,W,GR,TS,S} <: GrowthRule{R,W}
-    "Key for aux data or single rate"
     rate::GR
-    "Precalculated time interpolation index for aux data"
     timestep::TS
-    "The fractional number of rule timesteps in the current simulation timestep"
     nsteps::S
 end
 function ExponentialGrowth{R,W}(; 
     rate=INTRINSICRATE_PARAM, 
-    timestep=nothing, 
-    nsteps=1.0
+    timestep, 
 ) where {R,W}
-    ExponentialGrowth{R,W}(rate, timestep, nsteps)
+    ExponentialGrowth{R,W}(rate, timestep, nothing)
 end
 
 precalcrule(rule::ExponentialGrowth, data) = precalc_timestep(rule, data)
@@ -39,26 +43,34 @@ precalcrule(rule::ExponentialGrowth, data) = precalc_timestep(rule, data)
 end
 
 """
+    LogisticGrowth(; rate, carrycap, timestep)
+    LogisticGrowth{R}(; rate, carrycap, timestep)
+    LogisticGrowth{R,W}(; rate, carrycap, timestep)
+
 Logistic growth based on a growth rate layer, using exact solution.
 
 Saturation only applies with positive growth
+
+# Keyword Arguments
+
+- `rate`: Growth rate. May be a `Number`, an [`Aux`](@ref) array or another [`Grid`](@ref).
+- `carrycap`: Carrying capacity. May be a `Number`, an [`Aux`](@ref) array or another [`Grid`](@ref).
+- `timestep`: Time step for the growth rate, in a type compatible with the simulation `tspan`.
+
+Pass grid `Symbol`s to `R` or both `R` and `W` type parameters to use to specific grids.
 """
 struct LogisticGrowth{R,W,GR,CC,TS,S} <: GrowthRule{R,W}
-    "Key for aux data or single rate"
     rate::GR
-    "Carrying capacity for each cell"
     carrycap::CC
-    "Timestep used in the formulation"
     timestep::TS
-    "The fractional number of rule timesteps in the current simulation timestep"
     nsteps::S
 end
 function LogisticGrowth{R,W}(;
     rate=INTRINSICRATE_PARAM, 
     carrycap=CARRYCAP_PARAM, 
-    timestep=nothing, nsteps=1.0,
+    timestep, 
 ) where {R,W}
-    LogisticGrowth{R,W}(rate, carrycap, timestep, nsteps)
+    LogisticGrowth{R,W}(rate, carrycap, timestep, nothing)
 end
 
 precalcrule(rule::LogisticGrowth, data) = precalc_timestep(rule, data)
@@ -77,12 +89,22 @@ precalcrule(rule::LogisticGrowth, data) = precalc_timestep(rule, data)
 end
 
 """
+    ThresholdGrowth(; rate, threshold)
+    ThresholdGrowth{G}(; rate, threshold)
+    ThresholdGrowth{R,W}(; rate, threshold)
+
 Simple threshold mask. Values below a certain threshold are replaced with zero.
+
+# Keyword Arguments
+
+- `rate`: Growth rate. May be a `Number`, an [`Aux`](@ref) array or another [`Grid`](@ref).
+- `threshold`: Minimum viability threshold below which population falls to zero. 
+  May be a `Number`, an [`Aux`](@ref) array or another [`Grid`](@ref).
+
+Pass grid `Symbol`s to `R` or both `R` and `W` type parameters to use to specific grids.
 """
 struct ThresholdGrowth{R,W,GR,Th} <: GrowthRule{R,W}
-    "Key for aux data or single rate"
     rate::GR
-    "Minimum viability threshold."
     threshold::Th
 end
 function ThresholdGrowth{R,W}(; 
@@ -97,3 +119,9 @@ end
     threshold = get(data, rule.threshold, I...)
     intrinsicrate >= threshold ? population : zero(population)
 end
+
+precalc_timestep(rule, data) = precalc_timestep(rule.timestep, rule, data)
+precalc_timestep(ruletimestep::DatePeriod, rule, data) =
+    @set rule.nsteps = currenttimestep(data) / Millisecond(ruletimestep)
+precalc_timestep(ruletimestep, rule, data) =
+    @set rule.nsteps = timestep(data) / ruletimestep

src/human.jl

@@ -38,9 +38,6 @@ isless(x, y::CellInterval) = isless(x, y.cumprop)
 
 
 """
-    HumanDispersal{R,W}(mode, human_pop, cellsize, scale, aggregator, human_exponent,
-                        dist_exponent, dispersalperpop, max_dispersers, nshortlisted,
-                        dest_shortlists, proportion_covered, human_buffer, distances)
     HumanDispersal{R,W}(; mode=BatchGroups(),
                           human_pop,
                           cellsize=1.0,
@@ -63,32 +60,34 @@ will downsample the grid to improve precalulation time and runtime performance.
 scale value is good for use in a live interface.
 
 ## Keyword Arguments
+
+- `mode`: Dispersal mode: Defaults to `BatchGroups()`, otherwise `HeirarchicalGroups()`.
+- `human_pop`: An array match the grid size containing human population data.
+- `cellsize`: The size of the cell width, assuming they are square
+- `scale`: Downscaling factor to reduce memory use and improve performance, defaults to 4 which means a 1:16 ratio.
+- `aggregator`: a function that aggregates scaled-down cells, defualting to `mean`.
+- `human_exponent`: human population exponent.
+- `dist_exponent`: distance exponent.
+- `dispersalperpop`: scales the number of dispersing individuals by human activity.
+- `max_dispersers`: maximum number of dispersers in a dispersal events
+- `nshortlisted`: length of the dispersal destination shortlist for each cell. 
+  Longer lists are more accurate in the tail of the distribution, but are slower to access.
+
+Pass grid `Symbol`s to `R` or both `R` and `W` type parameters to use to specific grids.
 """
 struct HumanDispersal{R,W,M,HP,CS,S,AG,HE,DE,DP,MD,SL,PC,B,D} <: SetCellRule{R,W}
-    "Dispersal mode"
     mode::M
-    "An array match the grid size containing human population data."
     human_pop::HP
-    "The size of the cell width, assuming they are square"
     cellsize::CS
     scale::S
-    "A function that aggregates scaled down cells"
     aggregator::AG
-    "Human population exponent"
     human_exponent::HE
-    "Distance exponent"
     dist_exponent::DE
-    "Scales the number of dispersing individuals by human activity (ie population^human_exponent)"
     dispersalperpop::DP
-    "Maximum number of dispersers in a dispersal events"
     max_dispersers::MD
-    "Length of dest shortlist"
     nshortlisted::SL
-    "Array of destination vectors for each cell. Automatically calculated"
     dest_shortlists::PC
-    "Buffer array used in precalculation"
     human_buffer::B
-    "Buffer array used in precalculation"
     distances::D
     # This constructor is run for every parameter change
     function HumanDispersal{R,W,M,HP,CS,S,AG,HE,DE,DP,MD,SL,PC,B,D}(