Documentation edits, update NEWS

Author: kmartinet

DESCRIPTION

@@ -4,7 +4,7 @@ Title: ssarp (Species-/Speciation-Area Relationship Projector)
 Description: Create Species- and Speciation-Area Relationships for any taxa.
 Authors@R: person("Kristen", "Martinet", email = "kmartinet@outlook.com", role = c("aut", "cre"))
 Maintainer: Kristen Martinet <kmartinet@outlook.com>
-Version: 0.3.0
+Version: 0.4.0
 URL: https://github.com/kmartinet/ssarp, https://kmartinet.github.io/ssarp/
 BugReports: https://github.com/kmartinet/ssarp/issues
 Imports: 

NEWS.md

@@ -1,3 +1,34 @@
+ssarp 0.4.0 (2025-07-19)
+=========================
+
+### NEW FEATURES
+
+  * Package name is now `ssarp` instead of `SSARP`
+  * Added the `ssarp::get_richness()` function, which creates a standard species richness dataframe
+  * The `ssarp::get_data()` and `ssarp::get_key()` functions have been replaced by [a helpful vignette describing how to access occurrence records](https://kmartinet.github.io/ssarp/articles/Get_Data.html) using `rgbif`.
+  * Messages across the package can be silenced using `options(ssarp.silent = TRUE)` now
+  * A new example file for testing `ssarp::estimate_BAMM` has been added (`inst/extdata/event_data_Patton_Anolis.txt`)
+  
+### DOCUMENTATION FIXES
+
+  * All examples run instead of remaining in a `\dontrun` block
+  * More information about using the metadata from plots created with `ssarp::create_SAR()` and `ssarp::create_SpAR()` has been added to their documentation
+  * More information about the speciation rate estimation methods in `ssarp` have been added to the `ssarp::create_SpAR()` documentation
+  
+  
+### OTHER FIXES
+  
+  * New `testthat` test cases to ensure that calculations are done correctly across the package
+  * Column names have been standardized across the package
+  * Plot printing is now off by default in `ssarp::create_SAR()` and `ssarp::create_SpAR()`
+  
+### DEPRECATED FUNCTIONS
+  
+  * `get_data()`
+  * `get_key()`
+  * `quick_create_SAR()`
+
+
 SSARP 0.3.0 (2025-07-04)
 =========================
 

R/create_SAR.R

@@ -3,8 +3,8 @@
 #' Use segmented regression to create a species-area relationship (SAR) plot.
 #' The X axis represents log(island area) and the Y axis represents log(number
 #' of species)
-#' 
-#' If the user would prefer to create their own plot of the 
+#'
+#' If the user would prefer to create their own plot of the
 #' `ssarp::create_SAR()` output, the `aggDF` element of the returned list
 #' includes the raw points from the plot created here. They can be accessed
 #' as demonstrated in the Examples section.
@@ -13,15 +13,15 @@
 #' specificEpithet, areas)
 #' @param npsi The maximum number of breakpoints to estimate for model
 #' selection.  Default: 1
-#' @param visualize (boolean) Whether the plot should be displayed when the 
+#' @param visualize (boolean) Whether the plot should be displayed when the
 #' function is called. Default: FALSE
 #' @return A list of 4 including: the summary output, the regression
 #' object, the aggregated dataframe used to create the plot, and the AIC scores
 #' used in model selection
 #' @examples
 #' # The GBIF key for the Anolis genus is 8782549
 #' # Read in example dataset filtered from:
-#' #  dat <- rgbif::occ_search(taxonKey = 8782549, 
+#' #  dat <- rgbif::occ_search(taxonKey = 8782549,
 #' #                           hasCoordinate = TRUE,
 #' #                           limit = 10000)
 #' dat <- read.csv(system.file("extdata",
@@ -104,7 +104,7 @@ create_SAR <- function(occurrences, npsi = 1, visualize = FALSE) {
   # If the min_score is index 1, then the best-fit model is linear
   if (min_score == 1) {
     # Plot linear regression (if the user wants)
-    if(visualize){
+    if (visualize) {
       plot(
         dat,
         xlim = c(x_min, (x_max + 0.5)),
@@ -143,7 +143,7 @@ create_SAR <- function(occurrences, npsi = 1, visualize = FALSE) {
     )
 
     # Plot the breakpoint regression line (if user wants)
-    if(visualize){
+    if (visualize) {
       plot(
         seg,
         rug = FALSE,
@@ -186,7 +186,7 @@ create_SAR <- function(occurrences, npsi = 1, visualize = FALSE) {
 
     # Plot defaults to multiple outputs when npsi > 1, so my npsi = 1 plot
     #  doesn't apply
-    if(visualize){
+    if (visualize) {
       plot(seg)
     }
 

R/create_SpAR.R

@@ -3,34 +3,37 @@
 #' Use segmented regression to create a speciation-area relationship plot. The
 #' X axis represents log(island area) and the Y axis represents
 #' log(speciation rate)
-#' 
-#' If the user would prefer to create their own plot of the 
+#'
+#' If the user would prefer to create their own plot of the
 #' `ssarp::create_SpAR()` output, the `aggDF` element of the returned list
 #' includes the raw points from the plot created here. They can be accessed
 #' as demonstrated in the Examples section.
+#'
+#' More information about the three methods for estimating speciation rate
+#' included in `ssarp` can be found in [ssarp's SpAR vignette](https://kmartinet.github.io/ssarp/articles/Create_SpAR.html).
 #' @param occurrences The dataframe output by one of ssarp's speciation
 #' methods (`ssarp::estimate_BAMM()`, `ssarp::estimate_DR()`,
 #' `ssarp::estimate_MS()`), or if using a custom dataframe, ensure that it
 #' has the following columns: areas, rate
 #' @param npsi The maximum number of breakpoints to estimate for model
 #' selection.  Default: 1
-#' @param visualize (boolean) Whether the plot should be displayed when the 
+#' @param visualize (boolean) Whether the plot should be displayed when the
 #' function is called. Default: FALSE
 #' @return A list of 4 including: the summary output, the regression
 #' object, the aggregated dataframe used to create the plot, and the AIC scores
 #' used in model selection
 #' @examples
 #' # The GBIF key for the Anolis genus is 8782549
 #' # Read in example dataset filtered from:
-#' #  dat <- rgbif::occ_search(taxonKey = 8782549, 
+#' #  dat <- rgbif::occ_search(taxonKey = 8782549,
 #' #                           hasCoordinate = TRUE,
 #' #                           limit = 10000)
 #' dat <- read.csv(system.file("extdata",
 #'                             "ssarp_Example_Dat.csv",
 #'                             package = "ssarp"))
 #' land <- find_land(occurrences = dat)
 #' areas <- find_areas(occs = land)
-#' 
+#'
 #' # Read tree from Patton et al. (2021), trimmed to Caribbean species
 #' tree <- ape::read.tree(system.file("extdata",
 #'                                    "Patton_Anolis_trimmed.tree",
@@ -39,8 +42,8 @@
 #' occ_speciation <- estimate_MS(tree = tree,
 #'                               label_type = "epithet",
 #'                               occurrences = areas)
-#' 
-#' seg <- create_SpAR(occurrences = occ_speciation, 
+#'
+#' seg <- create_SpAR(occurrences = occ_speciation,
 #'                    npsi = 1,
 #'                    visualize = FALSE)
 #' plot(seg)
@@ -122,7 +125,7 @@ create_SpAR <- function(occurrences, npsi = 1, visualize = FALSE) {
 
   # If the min_score is index 1, then the best-fit model is linear
   if (min_score == 1) {
-    if(visualize){
+    if (visualize) {
       plot(
         dat,
         xlim = c(x_min, (x_max + 0.5)),
@@ -161,7 +164,7 @@ create_SpAR <- function(occurrences, npsi = 1, visualize = FALSE) {
     )
 
     # Plot the breakpoint regression line
-    if(visualize){
+    if (visualize) {
       plot(
         seg,
         rug = FALSE,
@@ -204,7 +207,7 @@ create_SpAR <- function(occurrences, npsi = 1, visualize = FALSE) {
 
     # Plot defaults to multiple outputs when npsi > 1, so my npsi = 1 plot
     #  doesn't apply
-    if(visualize){
+    if (visualize) {
       plot(seg)
     }
 

R/estimate_BAMM.R

@@ -26,7 +26,7 @@
 #' @examples
 #' # The GBIF key for the Anolis genus is 8782549
 #' # Read in example dataset filtered from:
-#' #  dat <- rgbif::occ_search(taxonKey = 8782549, 
+#' #  dat <- rgbif::occ_search(taxonKey = 8782549,
 #' #                           hasCoordinate = TRUE,
 #' #                           limit = 10000)
 #' dat <- read.csv(system.file("extdata",
@@ -44,7 +44,7 @@
 #' event_data <- system.file("extdata",
 #'                           "event_data_Patton_Anolis.txt",
 #'                            package = "ssarp")
-#'                            
+#'
 #' edata <- BAMMtools::getEventData(phy = tree, eventdata = event_data)
 #'
 #' occ_speciation <- estimate_BAMM(label_type = "epithet",

R/estimate_DR.R

@@ -45,7 +45,7 @@
 #' @examples
 #' # The GBIF key for the Anolis genus is 8782549
 #' # Read in example dataset filtered from:
-#' #  dat <- rgbif::occ_search(taxonKey = 8782549, 
+#' #  dat <- rgbif::occ_search(taxonKey = 8782549,
 #' #                           hasCoordinate = TRUE,
 #' #                           limit = 10000)
 #' dat <- read.csv(system.file("extdata",
@@ -80,7 +80,7 @@ estimate_DR <- function(tree, label_type = "binomial", occurrences) {
   #  estimate_DR documentation)
   rootnode <- length(tree$tip.label) + 1
   speciation_rates <- numeric(length(tree$tip.label))
-  for (i in seq_len(length(speciation_rates))) {
+  for (i in seq_along(speciation_rates)) {
     node <- i
     index <- 1
     qx <- 0

R/estimate_MS.R

@@ -22,7 +22,7 @@
 #' @examples
 #' # The GBIF key for the Anolis genus is 8782549
 #' # Read in example dataset filtered from:
-#' #  dat <- rgbif::occ_search(taxonKey = 8782549, 
+#' #  dat <- rgbif::occ_search(taxonKey = 8782549,
 #' #                           hasCoordinate = TRUE,
 #' #                           limit = 10000)
 #' dat <- read.csv(system.file("extdata",