R/RcppExports.R

In piotrek-orlowski/ukfRcpp: R and C++ Unscented Kalman Filter

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' @title Cholesky rank-1 update (downdate)
#' @name cholupdate
#' @description Let RMat be the lower triangular Cholesky factor of PMat. This function calculates the lower-triangular Cholesky factor of P1 = P + nu^(0.5) * xVec \%*\% t(xVec). For downdate take nu < 0.
#' @param RMat square matrix, cholesky decomposition (lower) of matrix A
#' @param xVec numeric vector such that \code{length(xVec) = dim(RMat)[j]}, \code{j=1,2}
#' @param nu real, positive for update, negative for downdate. Mind the square root in description.
#' @details This follows the definition in van der Merwe PhD Thesis ``Sigma-Point Kalma Filters for Probabilistic Inference in Dynamic State-Space Models''
#' @export
cholupdate <- function(RMat, xVec, nu) {
    .Call('_ukfRcpp_cholupdate', PACKAGE = 'ukfRcpp', RMat, xVec, nu)
}

#' @title UKF: sigma points and weights
#' @name ukfPtsWts
#' @description Functions for generating sigma-points from original state and a Cholesky decomposition of the state variance-covariance matrix, and for generating weights for calculating mean and covariance via the Unscented Transformation.
#' @param xMat Original state matrix: each column is a value of state variables. If \code{ncol(xMat)==1}, the matrix is simply expanded with \code{+/- gam * PMatChol[,k]}. If \code{xMat} has more than one column, it's rewritten and an expansion of the first column is concatenated on the right.
#' @param gam Numeric. \code{gamma} parameter for Unscented Transformations.
#' @param PMatChol Cholesky decomposition (preferably lower) of the variance-covariance matrix of \code{xMat[,1]}. If past states are propagated, then the top-left block of \code{PMatChol} contains the decomposition and other entries are \code{0}.
#' @param L Dimension of state expansion. Should be equal to the number of non-zero entries on \code{diag(PMatChol)}
#' @return Matrix of size \code{nrow(xMat) x (ncol(xMat) + 2*L)}.
#' @export
generateSigmaPoints <- function(xMat, gam, PMatChol, L) {
    .Call('_ukfRcpp_generateSigmaPoints', PACKAGE = 'ukfRcpp', xMat, gam, PMatChol, L)
}

#' @rdname ukfPtsWts
#' @param alpha Numeric in \code{[0,1]}: size of step in the Scaled Uncented Transformation.
#' @param beta Numeric. Corrections in weights for calculating higher moments. Set to \code{0} unless you know what you're doing.
#' @return Matrix of size \code{(2*L+1) x 2}. First column contains weights for the calculation of the non-linearly transformed mean; second column -- for the variance-covariance matrix.
#' @export
generateSigmaWeights <- function(L, alpha, beta) {
    .Call('_ukfRcpp_generateSigmaWeights', PACKAGE = 'ukfRcpp', L, alpha, beta)
}

#' @title Filtering application example
#' @name filtTests
#' @description These functions are provided as (1) a simple testing ground for the filter, (2) as a demo of how to write the Transition and Observation handler functions.
#' @param Nlength Integer. Length of generated sample for filtering.
#' @return List with true and estimated states, and the state covariance matrices.
#' @details The states follow an AR(1) model with correlated errors. All paramters are hard-coded in this example but can be passed in despective \code{Rcpp::List} objects. The observation equations are signed powers of the states, observed with additional correlated error. \code{testUKFclass} runs the standard-form filter. \code{testSqrtUKFclass} runs the square-root form (better numerical stability).
#' @export
testUKFclass <- function(Nlength) {
    .Call('_ukfRcpp_testUKFclass', PACKAGE = 'ukfRcpp', Nlength)
}

#' @rdname filtTests
#' @export
testSqrtUKFclass <- function(Nlength) {
    .Call('_ukfRcpp_testSqrtUKFclass', PACKAGE = 'ukfRcpp', Nlength)
}

#' @name unscentedKalmanFilter
#' @title Unscented Kalman Filter
#' @description This function accepts pointers to compiled c++ evaluator 
#'   functions for the observation equations and the transition equations, plus
#'   data and parameters, and evaluates the UKF.
#' @param dataMat matrix containing observed data, by-column
#' @param initState initial state vector values
#' @param initProcCov initial variance-covariance matrix of the state vector
#' @param modelParams \code{list} of model parameter objects, compatible with 
#'   your \code{predictState} and \code{evaluateState} functions, and with the 
#'   specification of the \code{ukfClass}
#' @param predict_Xptr \code{XPtr} to \code{predictState} function which 
#'   handles your one-step head prediction of the state variable, given current
#'   values.
#' @param evaluate_XPtr \code{XPtr} to \code{evaluateState} function which 
#'   calculates the values of the measurement equation given values of the 
#'   state.
#' @param control_XPtr \code{XPtr} to \code{stateController} function which 
#'   handles pathological state cases after the filtering step (e.g. when using
#'   a Gaussian filter on strictly positive variables, which turn negative 
#'   after the filtering step, it is useful to set them to a small value)
#' @return \code{List} with the following fields: \code{estimState} \code{(T+1)
#'   x N} matrix of filtered states, with the initial state vector in the first
#'   row; \code{stateCovCube} 3-dimensional array of posterior state 
#'   variance-covariance matrices, \code{N x N x T}; \code{logL} vector of 
#'   Gaussian likelihood values, see e.g. "Time Series Analysis" by J.D. 
#'   Hamilton, \code{predMat} \code{T x M} matrix of predictions of 
#'   observations at time \code{t} given observations at time \code{t-1}, 
#'   \code{fitMat} \code{T x M} matrix of observation equations evaluated at
#'   filtered state values.
#' @export
NULL

unscentedKalmanFilter <- function(dataMat, initState, initProcCov, modelParams, predict_XPtr, evaluate_XPtr, control_XPtr) {
    .Call('_ukfRcpp_unscentedKalmanFilter', PACKAGE = 'ukfRcpp', dataMat, initState, initProcCov, modelParams, predict_XPtr, evaluate_XPtr, control_XPtr)
}

#' @name ukfMeanCov
#' @title Unscented Kalman Filter: Means and Covariances
#' @description Functions for calculating means and covariances of non-linear transformations of random variables with the use of the Scaled Unscented Transformation.
#' @param xSigma Numeric matrix. Output from \code{\link{generateSigmaPoints}}: expanded state values.
#' @param ySigma as above
#' @param unscWts Numeric vector. Weights for mean calculation. First column from output of \code{\link{generateSigmaWeights}}.
#' @param unscWtsMean as above
#' @param unscWtsCov Numeric vector. Weights for covariance calculation. Second column from output of \code{\link{generateSigmaWeights}}.
#' @return Mean vector or (variance-)covariance matrix.
#' @export
#' @useDynLib ukfRcpp
unscentedMean <- function(xSigma, unscWts) {
    .Call('_ukfRcpp_unscentedMean', PACKAGE = 'ukfRcpp', xSigma, unscWts)
}

#' @rdname ukfMeanCov
#' @export
unscentedCov <- function(xSigma, unscWtsMean, unscWtsCov) {
    .Call('_ukfRcpp_unscentedCov', PACKAGE = 'ukfRcpp', xSigma, unscWtsMean, unscWtsCov)
}

#' @rdname ukfMeanCov
#' @export
unscentedCrossCov <- function(xSigma, ySigma, unscWtsMean, unscWtsCov) {
    .Call('_ukfRcpp_unscentedCrossCov', PACKAGE = 'ukfRcpp', xSigma, ySigma, unscWtsMean, unscWtsCov)
}