Merge pull request #11 from r-spatialecology/main

📝 Update DOCS for CRAN

DESCRIPTION

@@ -1,16 +1,19 @@
 Type: Package
 Package: onpoint
 Title: Helper Functions for Point Pattern Analysis
-Version: 1.0
+Version: 1.0.1
 Authors@R: 
   person("Maximillian H.K.", "Hesselbarth", 
   email = "[email protected]",
   role = c("aut", "cre"), 
   comment = c(ORCID = "0000-0003-1125-9918"))
 Maintainer: Maximillian H.K. Hesselbarth <[email protected]>
 Description: 
-  Growing collection of small helper functions for point pattern analysis. Most functions
-  are designed to work with the 'spatstat' package.
+  Growing collection of helper functions for point pattern analysis. Most functions
+  are designed to work with the 'spatstat' (<http://spatstat.org>) package. The focus of 
+  most functions are either null models or summary functions for spatial point patterns. 
+  For a detailed description of all null models and summary functions, see 
+  Wiegand and Moloney (2014, ISBN:9781420082548).
 URL: https://r-spatialecology.github.io/onpoint/
 BugReports: https://github.com/r-spatialecology/onpoint/issues
 License: GPL (>= 3)

NAMESPACE

@@ -1,7 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(plot,env_summarised)
-S3method(print,env_summarised)
+S3method(plot,env_summarized)
+S3method(print,env_summarized)
 export(balance_points)
 export(calc_area)
 export(center_l_function)
@@ -12,4 +12,4 @@ export(rlabel_local)
 export(simulate_antecedent_conditions)
 export(simulate_heterogenous_pattern)
 export(split_at)
-export(summarise_envelope)
+export(summarize_envelope)

NEWS.md

@@ -1,3 +1,7 @@
+# onpoint 1.0.1
+* Improve documentation for CRAN submission
+* Renamed `summarise_envelope` to `summarize_envelope`
+
 # onpoint 1.0
 * Use GPL3 license
 * Adapt to new `spatstat` structure

R/balance_points.R

@@ -8,7 +8,7 @@
 #'
 #' @details
 #' The function balances out the number of points in the input pattern to either
-#' the provided number of points as integer or the same number of points if a ppp
+#' the provided number of points as integer or the same number of points if a \code{ppp}
 #' object is provided.
 #'
 #' @return ppp
@@ -20,7 +20,6 @@
 #'
 #' balance_points(pattern = input, n = 110)
 #' balance_points(pattern = input, n = input_b)
-
 #'
 #' @aliases balance_points
 #' @rdname balance_points
@@ -29,32 +28,32 @@
 balance_points <- function(pattern, n, verbose = TRUE) {
 
   # check if n is valid
-  if(!spatstat.geom::is.ppp(n)) {
+  if (!spatstat.geom::is.ppp(n)) {
     if (n %% 1 != 0) {
     stop("n must be either integer or ppp.", call. = FALSE)
     }
   }
 
   # if n is pattern - get number of points
-  if(spatstat.geom::is.ppp(n)) {
+  if (spatstat.geom::is.ppp(n)) {
     n <- n$n
   }
 
-  if(verbose) {
+  if (verbose) {
 
     difference_rel <- abs((pattern$n - n)) / pattern$n
 
     message("> Relative difference between pattern and n: ", round(difference_rel, 2))
 
-    if(difference_rel > 0.33) {
+    if (difference_rel > 0.33) {
       warning("Differences between pattern and n more than 0.33.", call. = FALSE)
     }
   }
 
   abs((pattern$n - n))
 
   # remove points because more points in simulated
-  if(pattern$n > n) {
+  if (pattern$n > n) {
 
     # difference between patterns
     difference <- pattern$n - n
@@ -67,7 +66,7 @@ balance_points <- function(pattern, n, verbose = TRUE) {
   }
 
   # add points because less points in simulated
-  else if(pattern$n < n) {
+  else if (pattern$n < n) {
 
     # difference between patterns
     difference <- n - pattern$n

R/calc_area.R

@@ -1,35 +1,42 @@
-#' calc_area
-#'
-#' @description Calculate area of polygon
-#'
-#' @param x matrix
-#'
-#' @details
-#' Calculate area of polygon
-#'
-#' @aliases calc_area
-#' @rdname calc_area
-#'
-#' @keywords internal
-#'
-#' @export
-calc_area <- function(x){
-
-  # check if polygon is closed
-  if (x[1, 1] != x[nrow(x), 1] || x[1, 2] != x[nrow(x), 2]) {
-    # close the polygon
-    x <- rbind(x, x[1, ])
-  }
-
-  # get number of rows
-  nrow_x <- nrow(x)
-
-  # get coordinates
-  x_coord <- x[ ,1]
-  y_coord <- x[, 2]
-
-  area <- abs(sum((x_coord[2:nrow_x] - x_coord[1:nrow_x - 1]) *
-                (y_coord[2:nrow_x] + y_coord[1:nrow_x - 1])) / 2)
-
-  return(area)
-}
+#' calc_area
+#'
+#' @description Calculate area of polygon
+#'
+#' @param x matrix with x,y coordinates.
+#'
+#' @details
+#' Calculate area of polygon in input units. If the polygon is not closed, the first
+#' coordinate is used as last coordinate to close it.
+#'
+#' @return numeric
+#'
+#' @examples
+#' dat <- matrix(data = c(0, 0, 0, 10, 10, 10, 10, 0), ncol = 2, byrow = TRUE)
+#' calc_area(x = dat)
+#'
+#' @aliases calc_area
+#' @rdname calc_area
+#'
+#' @keywords internal
+#'
+#' @export
+calc_area <- function(x){
+
+  # check if polygon is closed
+  if (x[1, 1] != x[nrow(x), 1] || x[1, 2] != x[nrow(x), 2]) {
+    # close the polygon
+    x <- rbind(x, x[1, ])
+  }
+
+  # get number of rows
+  nrow_x <- nrow(x)
+
+  # get coordinates
+  x_coord <- x[ ,1]
+  y_coord <- x[, 2]
+
+  area <- abs(sum((x_coord[2:nrow_x] - x_coord[1:nrow_x - 1]) *
+                (y_coord[2:nrow_x] + y_coord[1:nrow_x - 1])) / 2)
+
+  return(area)
+}

R/center_l_function.R

@@ -9,6 +9,10 @@
 #' Centers Besag's L-function to zero by calculating L(r) -r. Centering the L-function
 #' allows an easier interpretation and plotting of the results (Haase 1995).
 #'
+#' Returns an 'Function value object' of the \code{spatstat} package.
+#'
+#' @return fv.object
+#'
 #' @seealso
 #' \code{\link{Lest}}
 #'
@@ -20,24 +24,29 @@
 #' center_l_function(lest)
 #'
 #' @references
-#' Besag, J. E. 1977. Discussion on Dr. Ripley's paper. - J. R. Stat. Soc. Ser. B 39: 193-195.
+#' Besag, J.E., 1977. Discussion on Dr. Ripley’s paper. Journal of the Royal
+#' Statistical Society. Series B (Methodological) 39, 193–195.
+#' https://doi.org/10.1111/j.2517-6161.1977.tb01616.x
 #'
-#' Ripley, B. D. 1977. Modelling spatial patterns. - J. R. Stat. Soc. Ser. B 39: 172-192.
+#' Ripley, B.D., 1977. Modelling spatial patterns. Journal of the Royal Statistical
+#' Society. Series B (Methodological) 39, 172–192.
+#' https://doi.org/10.1111/j.2517-6161.1977.tb01615.x
 #'
-#' Haase, P. 1995. Spatial pattern analysis in ecology based on Ripley's K-function:
-#' Introduction and methods of edge correction. - J. Veg. Sci. 6: 575-582.
+#' Haase, P., 1995. Spatial pattern analysis in ecology based on Ripley’s K-function:
+#' Introduction and methods of edge correction. Journal of Vegetation Science 6, 575–582.
+#' https://doi.org/10.2307/3236356
 #'
 #' @aliases center_l_function
 #' @rdname center_l_function
 
 #' @export
 center_l_function <- function(x, ...) {
 
-  if(!spatstat.geom::is.ppp(x) && !spatstat.geom::is.fv(x)) {
+  if (!spatstat.geom::is.ppp(x) && !spatstat.geom::is.fv(x)) {
     stop("Please provide either ppp or fv object.")
   }
 
-  if(spatstat.geom::is.ppp(x)) {
+  if (spatstat.geom::is.ppp(x)) {
     x <- spatstat.core::Lest(x, ...)
   }
 

R/estimate_o_ring.R

@@ -6,14 +6,19 @@
 #' @param ... Arguments passed to \code{spatstat.core::pcf.ppp()}
 #'
 #' @details
-#' Estimates the O-ring function proposed by Wiegand and Moloney (2004). The O-ring statistic
-#' is defined as:
+#' Estimates the O-ring function proposed by Wiegand and Moloney (2004). The
+#' O-ring statistic is defined as:
 #'
 #' \deqn{O(r) = \lambda * g(r)}
 #'
-#' Generally speaking, O(r) scales the pair correlation g(r) function with help of the intensity \eqn{\lambda}.
-#' One advantage of the O-ring statistic is that it can be interpreted as a neighborhood density because it is
-#' a probability density function (Wiegand & Moloney 2004).
+#' Generally speaking, O(r) scales the pair correlation g(r) function with help
+#' of the intensity \eqn{\lambda}. One advantage of the O-ring statistic is that
+#' it can be interpreted as a neighborhood density because it is a probability density
+#' function (Wiegand & Moloney 2004, 2014).
+#'
+#' Returns an 'Function value object' of the \code{spatstat} package.
+#'
+#' @return fv.object
 #'
 #' @seealso
 #' \code{\link{density.ppp}} \cr
@@ -24,17 +29,19 @@
 #' estimate_o_ring(input_pattern)
 #'
 #' @references
-#' Wiegand, T. and Moloney, K. A. 2014. Handbook of spatial point-pattern analysis in ecology. - Chapman and Hall/CRC Press.
+#' Wiegand, T., Moloney, K.A., 2014. Handbook of spatial point-pattern analysis
+#' in ecology. Chapman and Hall/CRC Press, Boca Raton.
 #'
-#' Wiegand, T. and Moloney, K. A. 2004. Rings, circles, and null models for point pattern analysis in ecology. - Oikos 104: 209-229.
+#' Wiegand, T., Moloney, K.A., 2004. Rings, circles, and null models for point pattern
+#' analysis in ecology. Oikos 104, 209–229. https://doi.org/10.1111/j.0030-1299.2004.12497.x
 #'
 #' @aliases estimate_o_ring
 #' @rdname estimate_o_ring
 
 #' @export
 estimate_o_ring <- function(x, ...) {
 
-  if(!spatstat.geom::is.ppp(x)) {
+  if (!spatstat.geom::is.ppp(x)) {
     stop("Please provide ppp.")
   }
 

R/estimate_pcf_fast.R

@@ -8,7 +8,10 @@
 #' @details
 #' The functions estimates the pair correlation functions based on an estimation
 #' of Ripley's K-function. This makes it computationally faster than estimating the
-#' pair correlation function directly. It is a wrapper around `Kest` and `pcf.fv`.
+#' pair correlation function directly.
+#'
+#' It is a wrapper around \code{Kest} and \code{pcf.fv} and returns a 'Function value
+#' object' of the \code{spatstat} package.
 #'
 #' @seealso
 #' \code{\link{Kest}} \cr
@@ -25,9 +28,11 @@
 #' @rdname estimate_pcf_fast
 #'
 #' @references
-#' Ripley, B. D. 1977. Modelling spatial patterns. - J. R. Stat. Soc. Ser. B 39: 172-192.
+#' Ripley, B.D., 1977. Modelling spatial patterns. Journal of the Royal Statistical
+#' Society. Series B (Methodological) 39, 172–192. https://doi.org/10.1111/j.2517-6161.1977.tb01615.x
 #'
-#' Stoyan, D. and Stoyan, H. 1994. Fractals, random shapes and point fields. - John Wiley & Sons.
+#' Stoyan, D., Stoyan, H., 1994. Fractals, random shapes and point fields.
+#' John Wiley & Sons, Chichester.
 
 #' @export
 estimate_pcf_fast <- function(pattern, ...){

R/onpoint-package.R

@@ -9,18 +9,5 @@
 "_PACKAGE"
 
 # Global variables
-globalVariables(c("hi",
-                  "high",
-                  "lo",
-                  "low",
-                  "marks",
-                  "obs",
-                  "observed",
-                  "r",
-                  "theo",
-                  "theoretical",
-                  "type",
-                  "is",
-                  "x",
-                  "y"))
-
+globalVariables(c(
+  "hi", "high", "is", "lo", "low", "marks", "obs", "observed", "r", "theo", "theoretical", "type", "y"))

R/plot.env_summarised.R → R/plot.env_summarized.R

@@ -1,19 +1,23 @@
-#' plot.env_summarised
+#' plot.env_summarized
 #'
-#' @description Plotting method for env_summarised object
+#' @description Plotting method for \code{env_summarized} object
 #'
 #' @param x Random patterns.
-#' @param col Colours for areas above and below envelope.
+#' @param col Colors for areas above and below envelope.
 #' @param x_lab,y_lab Labels of x- and y-axis.
 #' @param base_size Base size of plot
 #' @param label If TRUE the ratios of the area above and below are added to the plot.
 #' @param ... To be generic for plotting function.
 #'
 #' @details
-#' Ploting method for summarised envelope created with \code{\link{summarise_envelope}}.
+#' Plotting method for summarized envelope created with \code{\link{summarize_envelope}}.
+#'
+#' Returns a \code{ggplot} object.
+#'
+#' @return ggplot
 #'
 #' @seealso
-#' \code{\link{summarise_envelope}}
+#' \code{\link{summarize_envelope}}
 #'
 #' @examples
 #' set.seed(42)
@@ -22,18 +26,18 @@
 #' cluster_env <- spatstat.core::envelope(input_pattern, fun = "pcf", nsim = 39,
 #' funargs = list(divisor = "d", correction = "Ripley", stoyan = 0.25))
 #'
-#' x <- summarise_envelope(cluster_env)
+#' x <- summarize_envelope(cluster_env)
 #' plot(x)
 #'
-#' @aliases plot.env_summarised
-#' @rdname plot.env_summarised
+#' @aliases plot.env_summarized
+#' @rdname plot.env_summarized
 
 #' @export
-plot.env_summarised <- function(x, col = c("#97CBDE", "#E1B0B5"),
+plot.env_summarized <- function(x, col = c("#97CBDE", "#E1B0B5"),
                                 x_lab = NULL, y_lab = NULL, base_size = 10,
                                 label = TRUE, ...) {
 
-  # check if colour for polygons is correct
+  # check if color for polygons is correct
   if (length(col) != 2) {
     warning("Please provide two colours for the polygons. Setting to default.",
             call. = FALSE)