Functions that included mixed case are now all lower-case

Author: kmartinet

.github/CONTRIBUTING.md

@@ -31,7 +31,7 @@ See tidyverse's guide on [how to create a great issue](https://code-review.tidyv
 
 *   Please do not restyle code that has nothing to do with your PR.
 
-*   New code should follow the tidyverse [style guide](https://style.tidyverse.org), with one exception: please use camelCase for new function names, or create an alias so that both snake_case and camelCase work for the function call.
+*   New code should follow the tidyverse [style guide](https://style.tidyverse.org).
 
 *  We use [roxygen2](https://cran.r-project.org/package=roxygen2), with [Markdown syntax](https://cran.r-project.org/web/packages/roxygen2/vignettes/rd-formatting.html), for documentation.  
 

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.4.1
+Version: 0.5.0
 URL: https://github.com/kmartinet/ssarp, https://kmartinet.github.io/ssarp/
 BugReports: https://github.com/kmartinet/ssarp/issues
 Imports: 

NAMESPACE

@@ -4,9 +4,14 @@ S3method(plot,SAR)
 S3method(print,SAR)
 export(create_SAR)
 export(create_SpAR)
+export(create_sar)
+export(create_spar)
 export(estimate_BAMM)
 export(estimate_DR)
 export(estimate_MS)
+export(estimate_bamm)
+export(estimate_dr)
+export(estimate_ms)
 export(find_areas)
 export(find_land)
 export(find_pam_areas)

NEWS.md

@@ -1,3 +1,10 @@
+ssarp 0.5.0 (2025-09-16)
+=========================
+
+### NEW FEATURES
+
+  * The default versions of `create_SAR()`, `create_SpAR()`, `estimate_BAMM()`, `estimate_DR()`, and `estimate_MS()` are now all-lowercase (`create_sar()`, `create_spar()`, `estimate_bamm()`, `estimate_dr()`, and `estimate_ms()`). The original spellings have been added as aliases to the functions (both spellings may be used).
+
 ssarp 0.4.1 (2025-09-11)
 =========================
 

R/create_SAR.R

@@ -5,7 +5,7 @@
 #' of species)
 #'
 #' If the user would prefer to create their own plot of the
-#' `ssarp::create_SAR()` output, the `aggDF` element of the returned list
+#' `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.
 #' @param occurrences The dataframe output by `ssarp::find_areas()` (or if
@@ -35,7 +35,7 @@
 #' land <- find_land(occurrences = dat)
 #' areas <- find_areas(occs = land)
 #'
-#' seg <- create_SAR(occurrences = areas,
+#' seg <- create_sar(occurrences = areas,
 #'                   npsi = 1,
 #'                   visualize = FALSE)
 #' plot(seg)
@@ -44,7 +44,7 @@
 #' points <- seg$aggDF
 #' @export
 
-create_SAR <- function(occurrences, npsi = 1, visualize = FALSE) {
+create_sar <- function(occurrences, npsi = 1, visualize = FALSE) {
   # Checkmate input validation
   checkmate::assertDataFrame(occurrences)
   checkmate::assertNumeric(npsi)
@@ -225,3 +225,8 @@ create_SAR <- function(occurrences, npsi = 1, visualize = FALSE) {
     return(result)
   }
 }
+
+# Create alias for create_sar
+#' @rdname create_sar
+#' @export
+create_SAR <- create_sar

R/create_SpAR.R

@@ -5,15 +5,15 @@
 #' log(speciation rate)
 #'
 #' If the user would prefer to create their own plot of the
-#' `ssarp::create_SpAR()` output, the `aggDF` element of the returned list
+#' `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
+#' 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
@@ -44,11 +44,11 @@
 #'                                    "Patton_Anolis_trimmed.tree",
 #'                                    package = "ssarp"))
 #'
-#' occ_speciation <- estimate_MS(tree = tree,
+#' 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)
@@ -57,7 +57,7 @@
 #' points <- seg$aggDF
 #' @export
 
-create_SpAR <- function(occurrences, npsi = 1, visualize = FALSE) {
+create_spar <- function(occurrences, npsi = 1, visualize = FALSE) {
   # Checkmate input validation
   checkmate::assertDataFrame(occurrences)
   checkmate::assertNumeric(npsi)
@@ -247,3 +247,8 @@ create_SpAR <- function(occurrences, npsi = 1, visualize = FALSE) {
     return(result)
   }
 }
+
+# Create alias for create_spar
+#' @rdname create_spar
+#' @export
+create_SpAR <- create_spar

R/estimate_BAMM.R

@@ -47,12 +47,12 @@
 #'
 #' edata <- BAMMtools::getEventData(phy = tree, eventdata = event_data)
 #'
-#' occ_speciation <- estimate_BAMM(label_type = "epithet",
+#' occ_speciation <- estimate_bamm(label_type = "epithet",
 #'                                  occurrences = areas ,
 #'                                  edata = edata)
 #' @export
 
-estimate_BAMM <- function(label_type = "binomial", occurrences, edata) {
+estimate_bamm <- function(label_type = "binomial", occurrences, edata) {
   # Checkmate input validation
   checkmate::assertString(label_type)
   checkmate::assertDataFrame(occurrences)
@@ -111,3 +111,8 @@ estimate_BAMM <- function(label_type = "binomial", occurrences, edata) {
 
   return(occurrences)
 }
+
+# Create alias for estimate_bamm
+#' @rdname estimate_bamm
+#' @export
+estimate_BAMM <- estimate_bamm

R/estimate_DR.R

@@ -59,13 +59,13 @@
 #'                                    "Patton_Anolis_trimmed.tree",
 #'                                    package = "ssarp"))
 #'
-#' occ_speciation <- estimate_DR(tree = tree,
+#' occ_speciation <- estimate_dr(tree = tree,
 #'                               label_type = "epithet",
 #'                               occurrences = areas)
 #'
 #' @export
 
-estimate_DR <- function(tree, label_type = "binomial", occurrences) {
+estimate_dr <- function(tree, label_type = "binomial", occurrences) {
   # Checkmate input validation
   checkmate::assertString(label_type)
   checkmate::assertDataFrame(occurrences)
@@ -136,3 +136,8 @@ estimate_DR <- function(tree, label_type = "binomial", occurrences) {
 
   return(sp_occ)
 }
+
+# Create alias for estimate_dr
+#' @rdname estimate_dr
+#' @export
+estimate_DR <- estimate_dr

R/estimate_MS.R

@@ -36,13 +36,13 @@
 #'                                    "Patton_Anolis_trimmed.tree",
 #'                                    package = "ssarp"))
 #'
-#' occ_speciation <- estimate_MS(tree = tree,
+#' occ_speciation <- estimate_ms(tree = tree,
 #'                               label_type = "epithet",
 #'                               occurrences = areas)
 #'
 #' @export
 
-estimate_MS <- function(tree, label_type = "binomial", occurrences) {
+estimate_ms <- function(tree, label_type = "binomial", occurrences) {
   # Checkmate input validation
   checkmate::assertString(label_type)
   checkmate::assertDataFrame(occurrences)
@@ -160,3 +160,7 @@ estimate_MS <- function(tree, label_type = "binomial", occurrences) {
   return(final_df)
 }
 
+# Create alias for estimate_ms
+#' @rdname estimate_ms
+#' @export
+estimate_MS <- estimate_ms

README.Rmd

@@ -176,11 +176,11 @@ The "area_dat" dataframe includes records with GPS points that are associated wi
 
 #### Step 4: Create the species-area relationship
 
-Finally, we will generate the SAR using the `ssarp::create_SAR()` function. The `ssarp::create_SAR()` function creates multiple regression objects with breakpoints up to the user-specified “npsi” parameter. For example, if “npsi” is two, `ssarp::create_SAR()` will generate regression objects with zero (linear regression), one, and two breakpoints. The function will then return the regression object with the lowest AIC score. The “npsi” parameter will be set to one in this example. Note that if linear regression (zero breakpoints) is better-supported than segmented regression with one breakpoint, the linear regression will be returned instead.
+Finally, we will generate the SAR using the `ssarp::create_sar()` function. The `ssarp::create_sar()` function creates multiple regression objects with breakpoints up to the user-specified “npsi” parameter. For example, if “npsi” is two, `ssarp::create_sar()` will generate regression objects with zero (linear regression), one, and two breakpoints. The function will then return the regression object with the lowest AIC score. The “npsi” parameter will be set to one in this example. Note that if linear regression (zero breakpoints) is better-supported than segmented regression with one breakpoint, the linear regression will be returned instead.
 
 ```{r}
 
-create_SAR(occurrences = area_dat, npsi = 1, visualize = TRUE)
+create_sar(occurrences = area_dat, npsi = 1, visualize = TRUE)
 
 ```
 This is the species-area relationship (SAR) for Anolis including island-based occurrences within a polygon around Caribbean islands from the first 10,000 records for the genus in GBIF! The best-fit model was a segmented regression with one breakpoint. The R console will also output statistical information about the model.
@@ -194,15 +194,15 @@ Species-area relationships (SARs) and speciation-area relationships (SpARs) are
 1. Use `rgbif` to gather occurrence records, or input your own dataframe of occurrence records.
 2. Use `find_land()` with the dataframe obtained in Step 1 to figure out the names of landmasses using the occurrence record GPS points and the [*maps* R package](https://cran.r-project.org/web/packages/maps/index.html).  Setting the `fillgaps` parameter to `TRUE` will enable the use of [Photon API](https://photon.komoot.io/) to fill in any missing landmass names left by the *maps* R package.
 3. Use `find_areas()` with the dataframe obtained in Step 2 to match the landmass names to a dataset that includes names of most islands on the planet and their areas. If the user would like to use a custom island area dataset instead of the built-in one, the `area_custom` parameter can be set to the name of the custom island area dataframe. If you'd like to only include occurrence records from islands, you can remove continental records by using `remove_continents()` with the dataframe returned by `find_areas()`
-4. Use `create_SAR()` with the dataframe obtained in Step 3 to create a species-area relationship plot that reports information important to the associated regression. The `npsi` parameter indicates the maximum number of breakpoints the user would like to compare for model selection. The returned model and plot correspond with the best-fit model.
+4. Use `create_sar()` with the dataframe obtained in Step 3 to create a species-area relationship plot that reports information important to the associated regression. The `npsi` parameter indicates the maximum number of breakpoints the user would like to compare for model selection. The returned model and plot correspond with the best-fit model.
 
 ### Workflow summary for using data from GBIF and a user-provided phylogenetic tree to create a speciation-area relationship plot
 
 1. Use `rgbif` to gather occurrence records, or input your own dataframe of occurrence records.
 2. Use `find_land()` with the dataframe obtained in Step 1 to figure out the names of landmasses using the occurrence record GPS points and the [*maps* R package](https://cran.r-project.org/web/packages/maps/index.html).  Setting the `fillgaps` parameter to `TRUE` will enable the use of [Photon API](https://photon.komoot.io/) to fill in any missing landmass names left by the *maps* R package.
 3. Use `find_areas()` with the dataframe obtained in Step 2 to match the landmass names to a dataset that includes names of most islands on the planet and their areas. If the user would like to use a custom island area dataset instead of the built-in one, the `area_custom` parameter can be set to the name of the custom island area dataframe. If you'd like to only include occurrence records from islands, you can remove continental records by using `remove_continents()` with the dataframe returned by `find_areas()`
-4. Use either `estimate_DR()` or `estimate_MS()` with your own phylogenetic tree that corresponds with the taxa signified in previous steps, a classifier that describes your tip labels (whether the tip labels are simply species epithets or full scientific names), and the dataframe obtained in Step 3 to add tip speciation rates using the DR statistic (Jetz et al. 2012) or the lambda calculation for crown groups from Magallόn and Sanderson (2001) respectively to the occurrence dataframe. The user may also choose to estimate tip speciation rates from a BAMM analysis (Rabosky 2014) by using `estimate_BAMM()` with a classifier that describes your tip labels (whether the tip labels are simply species epithets or full scientific names), the occurrence record dataframe obtained in Step 3, and a `bammdata` object generated by reading the event data file from a BAMM analysis with the *BAMMtools* package (Rabosky et al. 2014).
-5. Use `create_SpAR(occ, npsi)` with the dataframe obtained in Step 4 to create a speciation-area relationship plot that reports information important to the associated regression. The `npsi` parameter indicates the maximum number of breakpoints the user would like to compare for model selection. The returned model and plot correspond with the best-fit model.
+4. Use either `estimate_dr()` or `estimate_ms()` with your own phylogenetic tree that corresponds with the taxa signified in previous steps, a classifier that describes your tip labels (whether the tip labels are simply species epithets or full scientific names), and the dataframe obtained in Step 3 to add tip speciation rates using the DR statistic (Jetz et al. 2012) or the lambda calculation for crown groups from Magallόn and Sanderson (2001) respectively to the occurrence dataframe. The user may also choose to estimate tip speciation rates from a BAMM analysis (Rabosky 2014) by using `estimate_bamm()` with a classifier that describes your tip labels (whether the tip labels are simply species epithets or full scientific names), the occurrence record dataframe obtained in Step 3, and a `bammdata` object generated by reading the event data file from a BAMM analysis with the *BAMMtools* package (Rabosky et al. 2014).
+5. Use `create_spar(occ, npsi)` with the dataframe obtained in Step 4 to create a speciation-area relationship plot that reports information important to the associated regression. The `npsi` parameter indicates the maximum number of breakpoints the user would like to compare for model selection. The returned model and plot correspond with the best-fit model.
 
 ### Some helpful notes about well-known text (WKT) representation of geometry
 When using `rgbif::occ_search` to gather occurrence records from GBIF, the user can specify a well-known text (WKT) representation of geometry to restrict the geographic location of the returned occurrence records. The `rgbif::occ_search` function requires a counter-clockwise winding order for WKT. I find it helpful to think about WKT polygons in this way: imagine a square around your geographic area of interest and pick one of the corners as a starting point. The order of points in WKT format should follow counter-clockwise from the corner you picked first, and the final entry in the WKT string needs to be the same as the first entry. Additionally, while GPS points are typically represented in "latitude, longitude" format, WKT expects them in "longitude latitude" format with commas separating the points rather than individual longitude and latitude values. WKT polygons can have more specified points than included in this simple square example, and even include polygons nested within others or polygons with holes in the middle.