Merge pull request #76 from r-hyperspec/feature-38/rename-functions

Feature 38/rename functions (40)

DESCRIPTION

@@ -124,6 +124,8 @@ Collate:
     'DEPRECATED-read.txt.long.R'
     'DEPRECATED-read.txt.wide.R'
     'DEPRECATED-scan.R'
+    'identify_spc.R'
+    'DEPRECATED-spc.identify.R'
     'DEPRECATED-spc_bin.R'
     'spc_fit_poly.R'
     'DEPRECATED-spc_fit_poly.R'
@@ -174,7 +176,6 @@ Collate:
     'paracetamol.R'
     'laser.R'
     'hyperspec-package.R'
-    'identify_spc.R'
     'labels.R'
     'plot_map.R'
     'levelplot.R'

NEWS.md

@@ -46,6 +46,7 @@
      `spc.bin()`             | `spc_bin()`                      |  cbeleites/hyperSpec#208, cbeleites/hyperSpec#301
      `spc.fit.poly()`        | `spc_fit_poly()`                 |  cbeleites/hyperSpec#208, cbeleites/hyperSpec#301
      `spc.fit.poly.below()`  | `spc_fit_poly_below()`           |  cbeleites/hyperSpec#208, cbeleites/hyperSpec#301
+     `spc.identify()`        | `identify_spc()`                 |  #40
      `spc.loess()`           | `spc_loess()`                    |  cbeleites/hyperSpec#208, cbeleites/hyperSpec#301
      `spc.NA.approx()`       | `spc_na_approx()`                |  cbeleites/hyperSpec#208, cbeleites/hyperSpec#301
      `spc.rubberband()`      | `spc_rubberband()`               |  cbeleites/hyperSpec#208, cbeleites/hyperSpec#301

R/DEPRECATED-spc.identify.R

@@ -0,0 +1,35 @@
+#' @name DEPRECATED-spc.identify
+#' @concept deprecated
+#'
+#' @title (DEPRECATED)
+#'        Identifying spectra and spectral data points
+#'
+#' @description
+#' These \pkg{hyperSpec} functions are **deprecated** and not maintained any
+#' more. You should not use these.
+#' Currently they are present due to back-compatibility reasons and will be
+#' removed in the next release of the package.
+#' Please, use the suggested alternative functions instead:
+#'
+#' - [hyperSpec::identify_spc()]
+#'
+#'
+#' @param ... arguments to [hyperSpec::identify_spc()].
+#'
+#' @include identify_spc.R
+#' @export
+spc.identify <- function(...) {
+  hySpc_deprecated("identify_spc")
+  identify_spc(...)
+}
+
+
+# Unit tests -----------------------------------------------------------------
+
+hySpc.testthat::test(spc.identify) <- function() {
+  context("Deprecated functions")
+
+  test_that("spc.identify() is deprecated", {
+    expect_error(expect_warning(spc.identify(), "deprecated"))
+  })
+}

R/calculate_stacked_offsets.R

@@ -108,7 +108,7 @@
 #'
 #' \item{wavelengths}{the wavelengths of the plotted spectral data points}
 #'
-#' This can be used together with [spc.identify()].
+#' This can be used together with [identify_spc()].
 #'
 #' @author C. Beleites
 #'
@@ -559,7 +559,7 @@ plotspc <- function(object,
     }
   }
 
-  ## return some values that are needed by spc.identify
+  ## return some values that are needed by identify_spc
   invisible(list(
     x = rep(unlist(x), each = nrow(spc)),
     y = spc,

R/hy_options.R

@@ -19,7 +19,7 @@
 #' Currently, the following options are defined:
 #' \tabular{llll}{
 #' **Name**          \tab **Default Value (range)**      \tab **Description**                               \tab **Used by**\cr
-#' debuglevel           \tab 0 (1L 2L 3L)                      \tab amount of debugging information produced         \tab [spc.identify()] [map.identify()]\cr
+#' debuglevel           \tab 0 (1L 2L 3L)                      \tab amount of debugging information produced         \tab [identify_spc()] [map.identify()]\cr
 #'                      \tab                                   \tab                                                  \tab various file import functions\cr
 #'                      \tab                                   \tab                                                  \tab [spc_fit_poly_below()]\cr
 #' gc                   \tab FALSE                             \tab triggers frequent calling of gc ()               \tab [read.ENVI()], `new ("hyperSpec")`\cr

R/identify_spc.R

@@ -2,12 +2,12 @@
 
 #' Identifying spectra and spectral data points
 #'
-#' Function [spc.identify()] allows to identify the spectrum and the wavelength
+#' Function [identify_spc()] allows identifing the spectrum and the wavelength
 #' of a point in a plot produced by [plotspc()].
 #'
 #' @rdname identify_spc
 #'
-#' @aliases spc.identify
+#' @aliases identify_spc
 #'          spc.label.default
 #'          spc.label.wlonly
 #'          spc.point.default
@@ -16,7 +16,7 @@
 #'          spc.point.sqr
 #'
 #' @details
-#' Function [spc.identify()] first finds the spectrum with a point closest
+#' Function [identify_spc()] first finds the spectrum with a point closest
 #' to the clicked  position (see [locator()][graphics::locator()]).
 #' The distance to the clicked  point is evaluated relative to the size
 #' of the tolerance window.
@@ -61,7 +61,7 @@
 #' be switched of by `warn = FALSE`. In that case, the click will produce
 #' a row of `NA`s in the resulting data.frame.
 #'
-#' [spc.identify()] uses option `debuglevel` to determine whether debugging
+#' [identify_spc()] uses option `debuglevel` to determine whether debugging
 #' output  should be produced.
 #' - `debuglevel == 2` will plot the tolerance window for every clicked point,
 #' - `debuglevel == 1` will plot the tolerance window only if no data point was
@@ -99,7 +99,7 @@
 #' @param delta `spc.point.sqr` fits the parabola in the window wlclick
 #'   \eqn{\pm}{+-} delta points.
 #'
-#' @return [spc.identify()] returnsa `data.frame` with columns:
+#' @return [identify_spc()] returnsa `data.frame` with columns:
 #'  \item{ispc}{spectra indices of the identified points, i.e. the rows of the
 #'               `hyperSpec` object that was  plotted.
 #'
@@ -129,31 +129,31 @@
 #' ispc <- sample(nrow(laser), 10)
 #' ispc
 #'
-#' identified <- spc.identify(plotspc(laser[ispc]))
+#' identified <- identify_spc(plotspc(laser[ispc]))
 #'
 #' ## convert to the "real" spectra indices
 #' ispc[identified$ispc]
 #' identified$wl
 #' identified$spc
 #'
 #' ## allow the labels to be plotted into the plot margin
-#' spc.identify(plotspc(laser[ispc]), ispc = ispc, xpd = NA)
+#' identify_spc(plotspc(laser[ispc]), ispc = ispc, xpd = NA)
 #'
-#' spc.identify(plotspc(paracetamol,
+#' identify_spc(plotspc(paracetamol,
 #'   xoffset = 1100,
 #'   wl.range = c(600 ~ 1700, 2900 ~ 3150)
 #' ),
 #' formatter = spc.label.wlonly
 #' )
 #'
 #' ## looking for minima
-#' spc.identify(
+#' identify_spc(
 #'   plot(-paracetamol, wl.reverse = TRUE),
 #'   point.fn = spc.point.min, adj = c(1, 0.5)
 #' )
 #'
 #' }}
-spc.identify <- function(x, y = NULL,
+identify_spc <- function(x, y = NULL,
                          wavelengths = NULL,
                          ispc = NULL,
                          tol.wl = diff(range(x)) / 200,
@@ -166,7 +166,7 @@ spc.identify <- function(x, y = NULL,
                          srt = 90, # for the label text
                          warn = TRUE) {
   if (!interactive()) {
-    stop("spc.identify works only on interactive graphics devices.")
+    stop("identify_spc works only on interactive graphics devices.")
   }
 
   if (is.list(x)) {

R/map_identify.R

@@ -6,7 +6,7 @@
 #' @concept plotting
 #' @concept plotting tools
 #'
-#' @seealso  [`hyperSpec options()`][hyperSpec::options] [spc.identify()]
+#' @seealso  [`hyperSpec options()`][hyperSpec::options] [identify_spc()]
 #' [map.sel.poly()]
 #' @param tol tolerance for `map.identify` as fraction of the viewport
 #'   (i.e. in "npc" [unit][grid::unit]s)

R/plot_map.R

@@ -40,7 +40,7 @@
 #' the same order as the points were clicked. Also, multiple clicks on the same point are returned
 #' as multiple entries with the same index.
 #'
-#' `map.identify` uses option `debuglevel` similar to [spc.identify()]:
+#' `map.identify` uses option `debuglevel` similar to [identify_spc()]:
 #' `debuglevel == 1` will plot the tolerance window if no data point was inside (and
 #' additionally labels the point) while `debuglevel == 2` will always plot the tolerance
 #' window.

vignettes/hyperSpec.Rmd

@@ -1826,7 +1826,7 @@ See the [plotting](#list-of-vignettes) vignette.
 
 name  | default value (range)  | description | used by
 ----- | :---:                  |-------------| -----
-`debuglevel`           | `0`{.r} (`1L`{.r}, `2L`{.r}) | Amount of debugging information produced | `spc.identify()`{.r}, `map.identify()`{.r}, `spc_rubberband()`{.r},<br> various file import functions.
+`debuglevel`           | `0`{.r} (`1L`{.r}, `2L`{.r}) | Amount of debugging information produced | `identify_spc()`{.r}, `map.identify()`{.r}, `spc_rubberband()`{.r},<br> various file import functions.
 `gc`                   | `FALSE`{.r} | Triggers frequent calling of `gc()`{.r} | `read.ENVI()`{.r}, <br>\newline`new("hyperSpec")`{.r}
 `tolerance`            | `sqrt(.Machine$.double.eps)`{.r} | Tolerance for numerical comparisons   | File import functions (removing empty spectra), `normalize01()`{.r}
 `wl.tolerance`         | `sqrt(.Machine$.double.eps)`{.r} | Tolerance for comparisons of the wavelength axis | `rbind()`{.r}, `rbind2()`{.r}, `bind("r", ...)`{.r}, `all.equal()`{.r}, `collapse()`{.r}

vignettes/plotting.Rmd

@@ -1385,19 +1385,19 @@ if (require(rgl)) {
 
 # Interactive Graphics {#interactive-plots}
 
-Package **hyperSpec** offers basic interaction, `spc.identify()`{.r} for spectra plots, and `map.identify()`{.r} and `map.sel.poly()`{.r} for maps.
+Package **hyperSpec** offers basic interaction, `identify_spc()`{.r} for spectra plots, and `map.identify()`{.r} and `map.sel.poly()`{.r} for maps.
 The first two identify points in spectra plots and map plots, respectively.
 Function `map.sel.poly()`{.r} selects the part of a `hyperSpec`{.r} object that lies inside the user defined polygon.
 
 
-## `spc.identify()`{.r} Finding Out Wavelength, Intensity and Spectrum {#sec:spc.identify}
+## `identify_spc()`{.r} Finding Out Wavelength, Intensity and Spectrum {#sec:identify_spc}
 
-Function `spc.identify()`{.r} allows to measure points in graphics produced by `plotspc()`{.r}.
+Function `identify_spc()`{.r} allows to measure points in graphics produced by `plotspc()`{.r}.
 It works correctly with reversed and cut wavelength axes.
 
 
 ```{r eval=FALSE}
-spc.identify(plotspc(paracetamol, wl.range = c(600 ~ 1800, 2800 ~ 3200), xoffset = 800))
+identify_spc(plotspc(paracetamol, wl.range = c(600 ~ 1800, 2800 ~ 3200), xoffset = 800))
 ```
 
 The result is a data.frame with the indices of the spectra, the wavelength, and its intensity.