Export find_peaks()

Revise its documentation adding examples.

DESCRIPTION

@@ -2,7 +2,7 @@ Package: ggpmisc
 Type: Package
 Title: Miscellaneous Extensions to 'ggplot2'
 Version: 0.5.4-1.9001
-Date: 2023-11-05
+Date: 2023-11-12
 Authors@R:
     c(
     person("Pedro J.", "Aphalo", email = "[email protected]", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-3385-972X")),

NAMESPACE

@@ -25,6 +25,7 @@ export(StatQuantBand)
 export(StatQuantEq)
 export(StatQuantLine)
 export(StatValleys)
+export(find_peaks)
 export(keep_augment)
 export(keep_glance)
 export(keep_tidy)

NEWS.md

@@ -8,6 +8,7 @@ editor_options:
 
 -   Fix decoding of `orientation` from formula to allow function calls on the
 rhs of formulas, e.g., `I(y - 10) ~ x` or `I(x - 10) ~ y`.
+-   Export function `find_peaks()` which was previously internal. 
 -   Move transcriptomics example data objects to package 'ggpp'.
 -   Fix scrambled table in the vignette (reported by _markbneal_).
 

R/stat-peaks.R

@@ -1,6 +1,6 @@
 #' Find local maxima or global maximum (peaks)
 #'
-#' This method finds peaks (local maxima) in a spectrum, using a user selectable
+#' This method finds peaks (local maxima) in a vector, using a user selectable
 #' span and size threshold relative to the tallest peak (global maximum).
 #'
 #' @param x numeric vector
@@ -9,34 +9,55 @@
 #' @param span a peak is defined as an element in a sequence which is greater
 #'   than all other elements within a window of width span centered at that
 #'   element. The default value is 3, meaning that a peak is bigger than both of
-#'   its neighbors. Default: 3.
+#'   its neighbors. \code{span = NULL} extends the span to the whole length of
+#'   \code{x}.
 #' @param strict logical flag: if TRUE, an element must be strictly greater than
 #'   all other values in its window to be considered a peak. Default: TRUE.
 #' @param na.rm logical indicating whether \code{NA} values should be stripped
 #'   before searching for peaks.
 #'
-#' @return A vector of logical values. Values that are TRUE
-#'   correspond to local peaks in the data.
+#' @return A vector of logical values. Values that are TRUE correspond to local
+#'   peaks in vector \code{x} and can be used to extract the rows corresponding
+#'   to peaks from a data frame.
 #'
 #' @details This function is a wrapper built on function
 #'   \code{\link[splus2R]{peaks}} from \pkg{splus2R} and handles non-finite
 #'   (including NA) values differently than \code{peaks}, instead of giving an
-#'   error they are replaced with the smallest finite value in \code{x}.
-#'   \code{span = NULL} is treated as a special case and returns \code{max(x)}.
+#'   error when \code{na.rm = FALSE} they are replaced with the smallest finite
+#'   value in \code{x}. \code{span = NULL} is treated as a special case and
+#'   returns \code{max(x)}.
 #'
-#' @note The default for parameter \code{strict} is \code{TRUE} in functions
-#'   \code{peaks()} and \code{find_peaks()}, while the default is \code{FALSE}
-#'   in \code{stat_peaks()} and in \code{stat_valleys()}.
+#' @note The default for parameter \code{strict} is \code{FALSE} in functions
+#'   \code{peaks()} and \code{find_peaks()}, as in \code{stat_peaks()} and in
+#'   \code{stat_valleys()}, while the default in \code{\link[splus2R]{peaks}}
+#'   is \code{strict = TRUE}.
 #'
 #' @seealso \code{\link[splus2R]{peaks}}
 #'
-#' @keywords internal
+#' @export
+#'
+#' @examples
+#' # lynx is a time.series object
+#' lynx_num.df <-
+#'   try_tibble(lynx,
+#'              col.names = c("year", "lynx"),
+#'              as.numeric = TRUE) # years -> as numeric
+#'
+#' which(find_peaks(lynx_num.df$lynx, span = 31))
+#' lynx_num.df[find_peaks(lynx_num.df$lynx, span = 31), ]
+#'
+#' lynx_datetime.df <-
+#'    try_tibble(lynx,
+#'               col.names = c("year", "lynx")) # years -> POSIXct
+#'
+#' which(find_peaks(lynx_datetime.df$lynx, span = 31))
+#' lynx_datetime.df[find_peaks(lynx_num.df$lynx, span = 31), ]
 #'
 find_peaks <-
   function(x,
            ignore_threshold = 0,
            span = 3,
-           strict = TRUE,
+           strict = FALSE,
            na.rm = FALSE) {
     # find peaks
     if(is.null(span)) {

build-binary-from-source.sh

@@ -1,3 +1,3 @@
 cd ..
-R CMD INSTALL --build ggpmisc_0.5.2.tar.gz
+R CMD INSTALL --build ggpmisc_0.5.4-1.9001.tar.gz
 cd ./ggpmisc