diff --git a/R/bounded_niche.R b/R/bounded_niche.R index 1832bcf..e32c9ad 100644 --- a/R/bounded_niche.R +++ b/R/bounded_niche.R @@ -11,7 +11,7 @@ bounded_niche = function(g_min, g_max){ #' @returns a function describing the niche for usage with `apply_niche`. The function returns 1 if the taxon is within its niche (the gradient is between `g_min` and `g_max`), and 0 otherwise #' #' @description - #' Defines a simple niche model where the defined is given by a lower limit (`g_min`) and an upper limie (`g_max`) of a gradient the taxon can tolerate + #' Defines a simple niche model where the niche defined is given by a lower limit (`g_min`) and an upper limie (`g_max`) of a gradient the taxon can tolerate #' #' @examples #' \dontrun{ diff --git a/R/snd_niche.R b/R/snd_niche.R index 0b65c54..f230ea8 100644 --- a/R/snd_niche.R +++ b/R/snd_niche.R @@ -7,7 +7,7 @@ snd_niche = function(opt, tol, prob_modifier = 1, cutoff_val = NULL){ #' @param opt optimum value, gradient value where collection probability is highest #' @param tol tolerance to changes in gradient. For large values, collection probability drops off slower away from `opt` #' @param prob_modifier collection probability modifier, collection probability at `opt`. - #' @param cutoff_val NULL of a number. If a number, all collection probabilities at gradient values below `cutoff_value` are set to 0. This can for example be used to model exclusively marine species when the gradient is water depth (see examples). + #' @param cutoff_val NULL or a number. If a number, all collection probabilities at gradient values below `cutoff_value` are set to 0. This can for example be used to model exclusively marine species when the gradient is water depth (see examples). #' #' @returns a function for usage with `apply_niche`. #' @@ -30,7 +30,7 @@ snd_niche = function(opt, tol, prob_modifier = 1, cutoff_val = NULL){ #' #' @seealso [apply_niche()] for usage of the returned function, [bounded_niche()] for another niche model #' @description - #' Defines niche model based in the "Probability of collection" model by Holland and Patzkowsky (2002). + #' Defines niche model based in the "Probability of collection" model by Holland and Patzkowsky (1999). #' The collection probability follows the shape of a bell curve across a gradient, where `opt` determines the peak (mean) of the bell curve, and `tol` the standard deviation. "snd" stands for "scaled normal distribution", as the collection probability has the shape of the probability density of the normal distribution. #' @references * Holland, Steven M. and Patzkowsky, Mark E. 1999. "Models for simulating the fossil record." Geology. https://doi.org/10.1130/0091-7613(1999)027%3C0491:MFSTFR%3E2.3.CO;2 diff --git a/man/bounded_niche.Rd b/man/bounded_niche.Rd index 6ff4581..70ef73b 100644 --- a/man/bounded_niche.Rd +++ b/man/bounded_niche.Rd @@ -15,7 +15,7 @@ bounded_niche(g_min, g_max) a function describing the niche for usage with \code{apply_niche}. The function returns 1 if the taxon is within its niche (the gradient is between \code{g_min} and \code{g_max}), and 0 otherwise } \description{ -Defines a simple niche model where the defined is given by a lower limit (\code{g_min}) and an upper limie (\code{g_max}) of a gradient the taxon can tolerate +Defines a simple niche model where the niche defined is given by a lower limit (\code{g_min}) and an upper limie (\code{g_max}) of a gradient the taxon can tolerate } \examples{ \dontrun{ diff --git a/man/snd_niche.Rd b/man/snd_niche.Rd index 038d915..0114277 100644 --- a/man/snd_niche.Rd +++ b/man/snd_niche.Rd @@ -13,13 +13,13 @@ snd_niche(opt, tol, prob_modifier = 1, cutoff_val = NULL) \item{prob_modifier}{collection probability modifier, collection probability at \code{opt}.} -\item{cutoff_val}{NULL of a number. If a number, all collection probabilities at gradient values below \code{cutoff_value} are set to 0. This can for example be used to model exclusively marine species when the gradient is water depth (see examples).} +\item{cutoff_val}{NULL or a number. If a number, all collection probabilities at gradient values below \code{cutoff_value} are set to 0. This can for example be used to model exclusively marine species when the gradient is water depth (see examples).} } \value{ a function for usage with \code{apply_niche}. } \description{ -Defines niche model based in the "Probability of collection" model by Holland and Patzkowsky (2002). +Defines niche model based in the "Probability of collection" model by Holland and Patzkowsky (1999). The collection probability follows the shape of a bell curve across a gradient, where \code{opt} determines the peak (mean) of the bell curve, and \code{tol} the standard deviation. "snd" stands for "scaled normal distribution", as the collection probability has the shape of the probability density of the normal distribution. } \examples{ diff --git a/vignettes/StratPal.Rmd b/vignettes/StratPal.Rmd index 61e6227..7edfd1d 100644 --- a/vignettes/StratPal.Rmd +++ b/vignettes/StratPal.Rmd @@ -145,7 +145,7 @@ The `StratPal` package comes with some example data for age-depth models stored ### Defining age-depth models -Let's start with defining an age-depth model. This can be done with `tp_to_adm` (tie points to age-depth model): +Let's start with defining the age-depth model 2 km from shore in scenario A. This can be done with `tp_to_adm` (tie points to age-depth model): ```{r} t = scenarioA$t_myr # extract time tie points diff --git a/vignettes/event_data.Rmd b/vignettes/event_data.Rmd index a182a94..d826159 100644 --- a/vignettes/event_data.Rmd +++ b/vignettes/event_data.Rmd @@ -244,14 +244,14 @@ plot(t, gc(t), main = "Water depth 2 km offshore") ``` -Next, we define the niche. This is done using a function that takes water depth (our gradient) as input, and returns numbers between 0 and 1. A 1 corresponds to the taxon's environmental optimum, and a 0 reflects that it is completely outside of its niche. Values between 0 and 1 are are interpreted as observation or collection probabilities. They determine the probability to actually observe a specimen that is present at a given time at the specified gradient. +Next, we define the niche. This is done using a function that takes water depth (our gradient) as input, and returns numbers between 0 and 1. A 1 corresponds to the taxon's environmental optimum, and a 0 reflects that it is completely outside of its niche. Values between 0 and 1 are are interpreted as observation or collection probabilities. If a specimen is present at a given time, the collection probability is the probability to observe it at the specified gradient. -For our example, we use the helper function `snd_niche` (snd standing for scaled normal distribution) to define a niche. The collection probability in this model follows the shape of a bell curve with a peak at the environmental optimum, and a width specified by the `tol` parameter. This is identical to the *probability of collection* model by [Holland and Patzkowsky (1999)](#References). See the "advanced functionality" vignette for details how to construct other niche definitions, or `?bounded_niche` for another template niche model. +For our example, we use the helper function `snd_niche` (*snd* standing for "scaled normal distribution") to define a niche. The collection probability in this model follows the shape of a bell curve with a peak at the environmental optimum, and a width specified by the `tol` parameter. This is identical to the *probability of collection* model by [Holland and Patzkowsky (1999)](#References). See the "advanced functionality" vignette for details how to construct other niche definitions, or `?bounded_niche` for another template niche model. ```{r} my_niche = snd_niche(opt = 10, # preferred water depth tol = 5, # tolerance to water depth fluctuations - cutoff_val = 0) # cut off negative values - the taxon does not survive on land + cutoff_val = 0) # cut off negative values - the taxon does not survive on land x = seq(-2, 30, by = 0.1) plot(x, my_niche(x), type = "l", @@ -266,7 +266,7 @@ With the niche and the change in gradient defined, we can use `apply_niche` for ```{r} p3(rate = 300, from = min_time(adm_2km), to = max_time(adm_2km)) |> # model occurrences of taxon based on a constant rate - apply_niche(niche_def = my_niche, gc = gc) |> # apply the niche preference of the taxon as defined above + apply_niche(niche_def = my_niche, gc = gc) |> # apply the niche model hist(xlab = "Time [Myr]", main = "Fossil abundance", ylab = "# Fossils", @@ -279,7 +279,7 @@ With the basic niche modeling done, we can incorporate it into our modeling pipe ```{r} p3(rate = 300, from = min_time(adm_2km), to = max_time(adm_2km)) |> # model occurrences based on constant rate - apply_niche(niche_def = my_niche, gc = gc) |> # apply niche preference + apply_niche(niche_def = my_niche, gc = gc) |> # apply niche model time_to_strat(adm_2km, destructive = TRUE) |> # transform into strat. domain, destroy fossils that coincide with hiatuses hist(xlab = "Stratigraphic height [m]", # plot results main = "Fossil abundance 2 km from shore",