doc: clrify inputs #69

R/spliceCorrection.R

@@ -1,40 +1,53 @@
-#' @title Splice correction of a spectral matrix acquired with an ASD spectrometer
+#' @title Splice correction of a spectral matrix
 #' @description
-#' Corrects steps in an input spectral matrix by linear interpolation of the
-#' values of the edges of the middle sensor
+#' Corrects discontinuities (splices) in a spectral matrix by performing linear 
+#' interpolation at the boundaries between different detectors in the spectrometer.
+#' This method is commonly used for near-infrared (NIR) spectra where splicing 
+#' artifacts occur due to the transition between multiple detectors in the 
+#' spectrometer.
 #'
 #' @usage
-#'
 #' spliceCorrection(X, wav, splice = c(1000, 1830), interpol.bands = 10)
 #'
-#' @param X a numeric matrix or vector to transform (optionally a data frame that can
-#' be coerced to a numerical matrix).
-#' @param wav a numeric vector with band positions.
-#' @param splice a numeric vector of length 1 or 2 with the positions of the
-#' splice(s). Default:
-#' \code{c(1000, 1830)} (as for the ASD FieldSpec Pro spectrometer of Malvern
-#' Panalytical). See details.
-#' @param interpol.bands the number of interpolation bands.
+#' @param X A numeric matrix of spectra or a vector representing a single 
+#' spectrum to be corrected (optionally a data frame that can be coerced to a 
+#' numeric matrix).
+#' @param wav A numeric vector representing the band positions (e.g. wavelengths)
+#' corresponding to the spectral data.
+#' @param splice A numeric vector of length 1 or 2 specifying the band 
+#' (e.g. wavelength) positions where splicing occurs.
+#' The default values \code{c(1000, 1830)} refer to typical splice positions for 
+#' NIR spectrometers like the ASD FieldSpec Pro.
+#' For other spectrometers, different splice positions may be applicable (see 
+#' Details).
+#' @param interpol.bands The number of bands around the splice positions to use 
+#' for linear interpolation. Default is 10 bands.
+#' 
 #' @details
-#' This function uses by default the positions for the ASD FieldSpec Pro
-#' spectroradiometer (Malvern Panalytical) which usually exhibit
-#' steps at the splice of the three built-in detectors,
-#' positioned at 1000 nm (end of VNIR detector) and 1830 nm (end of SWIR1 detector).
-#' The data corresponding to the spectral region after the first step is used as
-#' reference for correcting the first region and the laste region (if 2 steps
-#' are supplied).
-#' Other typical examples of splice artifacts caused by concatenating data
-#' captured by different detectors inside the spectrometer:
+#' This function addresses splicing artifacts caused by transitioning between 
+#' different detectors, often seen in NIR spectrometers.
+#' Splicing occurs when data from multiple detectors are combined, potentially 
+#' introducing steps or discontinuities in the spectral data. 
+#' This correction method uses linear interpolation across a specified number 
+#' of bands around the splice points to smooth transitions and eliminate these 
+#' artifacts.
+#'
+#' The default splice positions are set for the ASD FieldSpec Pro spectrometer, 
+#' which has detectors at 1000 nm and 1830 nm. 
+#' For other NIR instruments, common splice positions include:
 #' \itemize{
-#'  \item{XDS (FOSS): 1100 nm}
-#'  \item{ProxiMate (BUCHI Labortechnik): 900 nm}
+#'   \item{XDS (FOSS): 1100 nm}
+#'   \item{ProxiMate (BUCHI Labortechnik): 900 nm}
 #' }
 #'
-#'
-#' @return a matrix with the splice corrected data.
-#' @author Antoine Stevens and \href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez}
+#' @return A matrix containing the spectra with corrected splices, ensuring 
+#' smoother transitions across detectors.
+#' @author
+#' Antoine Stevens and 
+#' \href{https://orcid.org/0000-0002-5369-5120}{Leonardo Ramirez-Lopez}
 #' @export
 
+
 spliceCorrection <- function(X, wav, splice = c(1000, 1830), interpol.bands = 10) {
   extrapfun <- function(x, y, xout) {
     fit <- lm(y ~ x)