Update readme and create pkgdown site

.Rbuildignore

@@ -3,3 +3,6 @@
 ^doc$
 ^Meta$
 ^\.github$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

.github/workflows/pkgdown.yaml

@@ -0,0 +1,50 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+name: pkgdown
+
+permissions: read-all
+
+jobs:
+  pkgdown:
+    runs-on: ubuntu-latest
+    # Only restrict concurrency for non-PR jobs
+    concurrency:
+      group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: r-lib/actions/setup-pandoc@v2
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          extra-packages: any::pkgdown, local::.
+          needs: website
+
+      - name: Build site
+        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+        shell: Rscript {0}
+
+      - name: Deploy to GitHub pages 🚀
+        if: github.event_name != 'pull_request'
+        uses: JamesIves/github-pages-deploy-action@v4.5.0
+        with:
+          clean: false
+          branch: gh-pages
+          folder: docs

.gitignore

@@ -5,3 +5,4 @@
 inst/doc
 /doc/
 /Meta/
+docs

DESCRIPTION

@@ -21,3 +21,4 @@ Imports:
     terra,
     sf
 Config/testthat/edition: 3
+URL: https://biologicalrecordscentre.github.io/STRIDER/

R/SimulationObjectClass.R

@@ -13,7 +13,24 @@ setClass("SimulationObject",
          )
 )
 
-# Create a constructor for the SimulationObject class
+#' Create a SimulationObject
+#'
+#' A constructor for the `SimulationObject` class, which initializes the object with the specified background and optional state components.
+#'
+#' @param background A `SpatRaster` object representing the background raster data.
+#' @param state_env Optional. A `SpatRaster` object representing the environmental state. Default is `NULL`.
+#' @param state_target_suitability Optional. A `SpatRaster` object representing the target suitability state. Default is `NULL`.
+#' @param state_target_realised Optional. A `SpatRaster` object representing the realised target state. Default is `NULL`.
+#' @param effort Optional. A data frame or spatial object representing the sampling effort. Default is `NULL`.
+#' @param detect Optional. A data frame or spatial object representing the detection events. Default is `NULL`.
+#' @param report Optional. A data frame or spatial object representing the reporting events. Default is `NULL`.
+#' @return An object of class `SimulationObject`.
+#' @examples
+#' \dontrun{
+#' background <- terra::rast(matrix(0, 500, 500))
+#' sim_obj <- SimulationObject(background)
+#' }
+#' @export
 SimulationObject <- function(background, state_env = NULL, state_target_suitability = NULL, state_target_realised= NULL, effort = NULL, detect = NULL, report = NULL) {
   tmp <- new("SimulationObject",
       background = background,
@@ -39,6 +56,19 @@ SimulationObject <- function(background, state_env = NULL, state_target_suitabil
   )
 }
 
+#' Plot a SimulationObject
+#'
+#' This method plots the different components of a `SimulationObject`, including the environmental state, target suitability, realised target state, effort, detection events, and reporting events.
+#'
+#' @param x A `SimulationObject` to be plotted.
+#' @return Plots the various components of the `SimulationObject` to the current graphics device.
+#' @examples
+#' \dontrun{
+#' background <- terra::rast(matrix(0, 500, 500))
+#' sim_obj <- SimulationObject(background)
+#' plot(sim_obj)
+#' }
+#' @export
 setMethod("plot", "SimulationObject", function(x) {
   x <- read_sim_obj_rasters(x)
 

R/basic_functions.R

@@ -181,6 +181,7 @@ state_target_realise_threshold <- function(simulation_object,threshold){
 #' @param n_sample_units The number of sample units per visit. Default is 1.
 #' @param replace A logical value indicating whether sampling with replacement is allowed. Default is FALSE.
 #' @param prob_raster A SpatRaster providing the probability of sampling each cell. Default is NULL.
+#' @param ... Any other arguments to function
 #'
 #' @return An sf object containing the sampling effort points.
 #' @examples

R/util.R

@@ -1,27 +1,39 @@
-#' If the spatraster slots are character filepaths then load in the rasters using terra::rast()
+#' If the spatraster slots are character filepaths then load in the rasters using terra::rast(), alternatively, if the spatraster slots are of class PackedSpatRaster then unwrap the rasters. Internal function.
 #' @param sim_obj a SimulationObject
 #' @noRd
 read_sim_obj_rasters <- function(sim_obj){
-
   #load background
   if(is.character(sim_obj@background)){
     sim_obj@background <- terra::rast(sim_obj@background)
   }
+  if(class(sim_obj@background)[1] == "PackedSpatRaster"){
+    sim_obj@background <- terra::unwrap(sim_obj@background)
+  }
+
 
   #load state env
   if(is.character(sim_obj@state_env)){
     sim_obj@state_env <- terra::rast(sim_obj@state_env)
   }
+  if(class(sim_obj@state_env)[1] == "PackedSpatRaster"){
+    sim_obj@state_env <- terra::unwrap(sim_obj@state_env)
+  }
 
   #load state_target_suitability
   if(is.character(sim_obj@state_target_suitability)){
     sim_obj@state_target_suitability <- terra::rast(sim_obj@state_target_suitability)
   }
+  if(class(sim_obj@state_target_suitability)[1] == "PackedSpatRaster"){
+    sim_obj@state_target_suitability <- terra::unwrap(sim_obj@state_target_suitability)
+  }
 
   #load state_target_realised
   if(is.character(sim_obj@state_target_realised)){
     sim_obj@state_target_realised <- terra::rast(sim_obj@state_target_realised)
   }
+  if(class(sim_obj@state_target_realised)[1] == "PackedSpatRaster"){
+    sim_obj@state_target_realised <- terra::unwrap(sim_obj@state_target_realised)
+  }
 
   #return the object
   sim_obj
@@ -38,7 +50,20 @@ write_raster_return_filename <- function(x, filename,overwrite=T, ...){
 }
 
 
-
+#' Generate a Hash for a SimulationObject
+#'
+#' This function generates a hash for a `SimulationObject` by extracting and hashing its components. Useful for tracking changes when using {targets} pipelines.
+#'
+#' @param sim_obj A `SimulationObject` for which to generate the hash.
+#' @return A hash string representing the `SimulationObject`.
+#' @examples
+#' \dontrun{
+#' background <- terra::rast(matrix(0, 500, 500))
+#' sim_obj <- SimulationObject(background)
+#' hash <- hash_sim_obj(sim_obj)
+#' print(hash)
+#' }
+#' @noRd
 hash_sim_obj <- function(sim_obj){
   sim_obj <- read_sim_obj_rasters(sim_obj)
   sim_obj@hash <- NULL

README.Rmd

@@ -5,7 +5,7 @@ output:
 ---
 
 ```{r setup, include=FALSE,echo=F}
-knitr::opts_chunk$set(echo = TRUE)
+knitr::opts_chunk$set(echo = TRUE,fig.path = "man/figures/")
 library(STRIDER)
 library(terra)
 library(sf)
@@ -27,7 +27,7 @@ STRIDER is an R package for facilitating the simulation of virtual species and t
  * Identification/Detection: what happens when a sampler encounters the target (is the species detected? is the species correctly identified?)
  * Reporting: how is the interaction reported? (is the species recorded? Are absences recorded? At what spatial resolution is it reported at?)
 
-![](diagrams/overview.drawio.svg)
+![](man/figures/overview.drawio.svg)
 
 ## Overview
 
@@ -131,10 +131,7 @@ Here we define the state of the target or targets. We define two versions of thi
 ```{r realisation_diagram, echo=F}
 sim_obj <- sim_state_target_suitability(sim_obj,fun = "uniform")
 sim_obj <- sim_state_target_realise(sim_obj,fun = "binomial")
-par(mfrow=c(1,2))
-plot(sim_obj@state_target_suitability,main = "@state_target_suitability")
-plot(sim_obj@state_target_realised,main = "@state_target_realised")
-par(mfrow=c(1,1))
+plot(sim_obj)
 ```
 
 Both of these representations of state are represented in the simulation object as SpatRaster with layers for each target. Again, if you want the target to change over time then create a list of rasters where each list item represents the target state at each time step, but this will need some wrangling.
@@ -175,7 +172,7 @@ Here's a very basic example where we generate effort comprising of two samplers,
 
 ```{r sampling data}
 # Simulate the sampling effort
-sim_obj <- sim_effort(sim_obj,fun = "uniform", n_samplers=2, n_visits = 1, n_sample_units = 2)
+sim_obj <- sim_effort(sim_obj,fun = "basic", n_samplers=2, n_visits = 1, n_sample_units = 2)
 sim_obj@effort
 ```
 
@@ -254,20 +251,13 @@ sim_obj <- sim_state_target_suitability(sim_obj,fun = "uniform", value = 0.5)
 sim_obj <- sim_state_target_realise(sim_obj,fun = "binomial")
 
 # Simulate the sampling effort
-sim_obj <- sim_effort(sim_obj,fun = "uniform", n_visits = 100, replace = FALSE)
+sim_obj <- sim_effort(sim_obj,fun = "basic", n_visits = 100, replace = FALSE)
 
 # Simulate the detection
 sim_obj <- sim_detect(sim_obj,fun = "equal", prob = 0.5)
 
 # Simulate the reporting
 sim_obj <- sim_report(sim_obj,fun = "equal", prob = 0.8, platform = "iRecord")
 
-plot(sim_obj@state_target_realised) # State of the target
-plot(sim_obj@effort$geometry, add = TRUE,pch=16) # Effort
-plot(sim_obj@detect$geometry[sim_obj@detect$detected == FALSE], col = "red", pch = 4, add = TRUE) # Highlight the non-detections
-plot(sim_obj@report$geometry[sim_obj@report$reported], col = "yellow", add = TRUE) # Highlight reported records as yellow
-
-#add a legend
-legend(1, 5, legend=c("Sampled", "Not detected","Reported"),
-       col=c("black","red", "yellow"), pch=c(16,4,1), cex=0.8,bg='grey')
+plot(sim_obj) 
 ```

README.md

@@ -23,7 +23,7 @@ organisms or similar. The simulation is split into a series processes:
 - Reporting: how is the interaction reported? (is the species recorded?
   Are absences recorded? At what spatial resolution is it reported at?)
 
-![](diagrams/overview.drawio.svg)
+![](man/figures/overview.drawio.svg)
 
 ## Overview
 
@@ -186,8 +186,18 @@ sim_obj
     ## Slot "report":
     ## NULL
     ## 
+    ## Slot "metadata":
+    ## $state_env
+    ## $state_env$fun
+    ## [1] "uniform"
+    ## 
+    ## $state_env$value
+    ## [1] 20
+    ## 
+    ## 
+    ## 
     ## Slot "hash":
-    ## [1] "02770d7a1351d2b3c355c14ad2ebe33a"
+    ## [1] "253f8b7c8478a288ccd2b954fa3f1196"
 
 ### Simulating the environmental state
 
@@ -230,7 +240,7 @@ occurrence (slot `@state_target`), and a realised absolute value (slot
 representing species occupancy or a positive integer representing
 abundance. Here’s an example:
 
-![](README_files/figure-gfm/realisation_diagram-1.png)<!-- -->
+![](man/figures/realisation_diagram-1.png)<!-- -->![](man/figures/realisation_diagram-2.png)<!-- -->![](man/figures/realisation_diagram-3.png)<!-- -->
 
 Both of these representations of state are represented in the simulation
 object as SpatRaster with layers for each target. Again, if you want the
@@ -297,20 +307,25 @@ target present).
 
 ``` r
 # Simulate the sampling effort
-sim_obj <- sim_effort(sim_obj,fun = "uniform", n_samplers=2, n_visits = 1, n_sample_units = 2)
+sim_obj <- sim_effort(sim_obj,fun = "basic", n_samplers=2, n_visits = 1, n_sample_units = 2)
 sim_obj@effort
 ```
 
-    ## Simple feature collection with 4 features and 7 fields
+    ## Simple feature collection with 4 features and 10 fields
     ## Geometry type: POINT
     ## Dimension:     XY
-    ## Bounding box:  xmin: 11.5 ymin: 29.5 xmax: 14.5 ymax: 29.5
+    ## Bounding box:  xmin: 11.5 ymin: 5.5 xmax: 27.5 ymax: 13.5
     ## CRS:           NA
-    ##   sampler visit unit cell_id          geometry env suit_target_1 real_target_1
-    ## 1       1     1    1      15 POINT (14.5 29.5)  20           0.5             1
-    ## 2       1     1    2      15 POINT (14.5 29.5)  20           0.5             1
-    ## 3       2     1    1      12 POINT (11.5 29.5)  20           0.5             1
-    ## 4       2     1    2      12 POINT (11.5 29.5)  20           0.5             1
+    ##   sampler visit unit cell_id          geometry ID env suit_ID suit_target_1
+    ## 1       1     1    1     492 POINT (11.5 13.5)  1  20       1           0.5
+    ## 2       1     1    2     492 POINT (11.5 13.5)  2  20       2           0.5
+    ## 3       2     1    1     748  POINT (27.5 5.5)  3  20       3           0.5
+    ## 4       2     1    2     748  POINT (27.5 5.5)  4  20       4           0.5
+    ##   real_ID real_target_1
+    ## 1       1             1
+    ## 2       2             1
+    ## 3       3             0
+    ## 4       4             0
 
 The function for simulating effort start is `sim_effort`
 
@@ -413,22 +428,15 @@ sim_obj <- sim_state_target_suitability(sim_obj,fun = "uniform", value = 0.5)
 sim_obj <- sim_state_target_realise(sim_obj,fun = "binomial")
 
 # Simulate the sampling effort
-sim_obj <- sim_effort(sim_obj,fun = "uniform", n_visits = 100, replace = FALSE)
+sim_obj <- sim_effort(sim_obj,fun = "basic", n_visits = 100, replace = FALSE)
 
 # Simulate the detection
 sim_obj <- sim_detect(sim_obj,fun = "equal", prob = 0.5)
 
 # Simulate the reporting
 sim_obj <- sim_report(sim_obj,fun = "equal", prob = 0.8, platform = "iRecord")
 
-plot(sim_obj@state_target_realised) # State of the target
-plot(sim_obj@effort$geometry, add = TRUE,pch=16) # Effort
-plot(sim_obj@detect$geometry[sim_obj@detect$detected == FALSE], col = "red", pch = 4, add = TRUE) # Highlight the non-detections
-plot(sim_obj@report$geometry[sim_obj@report$reported], col = "yellow", add = TRUE) # Highlight reported records as yellow
-
-#add a legend
-legend(1, 5, legend=c("Sampled", "Not detected","Reported"),
-       col=c("black","red", "yellow"), pch=c(16,4,1), cex=0.8,bg='grey')
+plot(sim_obj) 
 ```
 
-![](README_files/figure-gfm/example-1.png)<!-- -->
+![](man/figures/example-1.png)<!-- -->![](man/figures/example-2.png)<!-- -->![](man/figures/example-3.png)<!-- -->![](man/figures/example-4.png)<!-- -->![](man/figures/example-5.png)<!-- -->![](man/figures/example-6.png)<!-- -->

_pkgdown.yml

@@ -0,0 +1,4 @@
+url: https://biologicalrecordscentre.github.io/STRIDER/
+template:
+  bootstrap: 5
+

vignettes/example_minimal.Rmd

@@ -207,12 +207,12 @@ mod_pa <- fit_mod(data_pa)
 mod_pa_predictions <- predict(sim_obj@state_env,mod_pa,type = "response")
 ```
 
-## Many simulations
+## A simulation workflow
 
 In this section, we will run multiple simulations to investigate the impact of different sampling methods on model performance. We will use predefined objects and a new function to adjust sampling weight rasters. By chaining together various steps of the simulation pipeline, we can systematically alter the factors of interest, such as sampling bias strength and the number of samplers, to study their effects on the results.
 
 ### Predefined Objects
-We start with the predefined objects: background, env, and suitabiity_function. These objects were defined in the earlier sections of this vignette.
+We start with the predefined objects: background, env, and suitability_function. These objects were defined in the earlier sections of this vignette.
 
 ```{r previous objects}
 #use pre-defined objects
@@ -312,9 +312,9 @@ single_run_time <- system.time(run_simulation(1,1,500))["elapsed"]
 # define parameters data frame
 simulation_parameters <- 
   expand.grid(
-    rep = 1:5,
-    sampling_bias_strength = c(0,0.25,0.5,0.75,1),
-    n_samplers=seq(from = 50,to= 400, by = 50),
+    rep = 1:3,
+    sampling_bias_strength = c(0,0.5,1),
+    n_samplers=seq(from = 50,to= 350, by = 100),
     stringsAsFactors = F
   )