R/unimonotone.R

In monotone: Performs Monotone Regression

#' Unimodal Monotone Regression Function
#'
#' \code{unimonotone} performs unimodal monotone regression.
#' The function follows the up-and-down-blocks implementation (Kruskal, 1964)
#' of the pool-adjacent-violators algorithm (Ayer, Brunk, Ewing, Reid, and Silverman, 1955)
#' for both isotonic and antitonic regression,
#' and the prefix isotonic regression approach (Stout, 2008)
#' with additional lookaheads and progressive error sum-of-squares computation.
#'
#' @param x a real-valued vector.
#' @param w a real-valued vector with positive weights (default a vector with ones).
#'
#' @details Error checking on \code{x} or \code{w} is not present.
#'
#' @return Returns a real-valued vector with values of \code{x} in umbrella order.
#'
#' @references Bril G, Dykstra R, Pillers C, Robertson T (1984).
#'   Algorithm AS 206: isotonic regression in two independent variables.
#'   Journal of the Royal Statistical Society. Series C (Applied Statistics), 33(3), 352-357. 
#'   URL https://www.jstor.org/stable/pdf/2347723.pdf.
#' 
#'   Busing, F.M.T.A. (2022). 
#'   Monotone Regression: A Simple and Fast O(n) PAVA Implementation. 
#'   \emph{Journal of Statistical Software, Code Snippets, 102 (1)}, pp. 1-25. 
#'   (<doi:10.18637/jss.v102.c01>)
#'
#'   Stout, Q.F. (2008).
#'   Unimodal Regression via Prefix Isotonic Regression.
#'   \emph{Computational Statistics and Data Analysis}, 53, pp. 289-297.
#'   URL https://doi:10.1016/j.csda.2008.08.005
#'
#'   Turner, T.R. and Wollan, P.C. (1997).
#'   Locating a maximum using isotonic regression.
#'   \emph{Computational statistics and data analysis}, 25(3), pp. 305-320.
#'   URL https://doi.org/10.1016/S0167-9473(97)00009-1
#'   
#'   Turner, T.R. (2019).
#'   Iso: Functions to Perform Isotonic Regression.
#'   R package version 0.0-18.
#'   URL https://cran.r-project.org/package=Iso
#'   
#' @examples
#' y <- c( 0.0,61.9,183.3,173.7,250.6,238.1,292.6,293.8,268.0,285.9,258.8,
#' 297.4,217.3,226.4,170.1,74.2,59.8,4.1,6.1 )
#' x <- unimonotone( y )
#' print( x )
#'
#' @export
#'
#' @useDynLib monotone unimonotone
unimonotone <- function( x, w = rep( 1, length( x ) ) ) {
  n <- length( x )
  return( .C( "unimonotoneC", as.integer( n ), x = as.double( x ), as.double( w ), PACKAGE= "monotone" )$x )
}