1 files changed, 52 insertions, 0 deletions
diff --git a/R/iv.R b/R/iv.R
index bf89390..ec74ebc 100644
--- a/R/iv.R
+++ b/R/iv.R
@@ -1,3 +1,55 @@
+#' ARX model estimation using instrumental variable method
+#' 
+#' Estimates an ARX model of the specified order from input-output data using
+#' the instrument variable method. If arbitrary instruments are not supplied 
+#' by the user, the instruments are generated using the arx routine
+#' 
+#' @param z an idframe object containing the data
+#' @param order Specification of the orders: the three integer components 
+#' (na,nb,nk) are the order of polynolnomial A, (order of polynomial B + 1) 
+#' and the input-output delay
+#' @param x instrument variable matrix. x must be of the same size as the output 
+#' data. (Default: \code{NULL})
+#' 
+#' @details
+#' SISO ARX models are of the form 
+#' \deqn{
+#'    y[k] + a_1 y[k-1] + \ldots + a_{na} y[k-na] = b_{nk} u[k-nk] + 
+#'    \ldots + b_{nk+nb} u[k-nk-nb] + e[k] 
+#' }
+#' The function estimates the coefficients using linear least squares (with
+#' regularization).
+#' \cr
+#' The data is expected to have no offsets or trends. They can be removed 
+#' using the \code{\link{detrend}} function. 
+#' 
+#' @return
+#' An object of class \code{estpoly} containing the following elements:
+#'  \item{sys}{an \code{idpoly} object containing the 
+#'    fitted ARX coefficients}
+#'  \item{fitted.values}{the predicted response}
+#'  \item{residuals}{the residuals}
+#'  \item{input}{the input data used}
+#'  \item{call}{the matched call}
+#'  \item{stats}{A list containing the following fields: \cr
+#'      \code{vcov} - the covariance matrix of the fitted coefficients \cr
+#'      \code{sigma} - the standard deviation of the innovations\cr
+#'      \code{df} - the residual degrees of freedom}
+#' 
+#' 
+#' @references
+#' Arun K. Tangirala (2015), \emph{Principles of System Identification: 
+#' Theory and Practice}, CRC Press, Boca Raton. Sections 21.7.1, 21.7.2
+#' 
+#' Lennart Ljung (1999), \emph{System Identification: Theory for the User}, 
+#' 2nd Edition, Prentice Hall, New York. Section 7.6
+#' 
+#' @examples
+#' data(arxsim)
+#' mod_iv <- iv(z,c(2,1,1))
+#' 
+#' @seealso arx
+#' 
 #' @export
 iv <- function(z,order=c(0,1,0),x=NULL){
   y <- outputData(z); u <- inputData(z); N <- dim(y)[1]