summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSuraj Yerramilli2016-02-17 11:29:05 +0530
committerSuraj Yerramilli2016-02-17 11:29:05 +0530
commit9a5d12a60d6c0e6dd415e97116a4aaf91c80dd0a (patch)
tree98fcd2a786e3c6d1ad9f0e4a280dcff0c6f84b56
parent92c3caebef9ae7bb361d6811589d3fd6e5c0430a (diff)
downloadSysID-R-code-9a5d12a60d6c0e6dd415e97116a4aaf91c80dd0a.tar.gz
SysID-R-code-9a5d12a60d6c0e6dd415e97116a4aaf91c80dd0a.tar.bz2
SysID-R-code-9a5d12a60d6c0e6dd415e97116a4aaf91c80dd0a.zip
adding documentation for iv routine
-rw-r--r--R/iv.R52
-rw-r--r--man/iv.Rd64
2 files changed, 116 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]
diff --git a/man/iv.Rd b/man/iv.Rd
new file mode 100644
index 0000000..54d44d2
--- /dev/null
+++ b/man/iv.Rd
@@ -0,0 +1,64 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/iv.R
+\name{iv}
+\alias{iv}
+\title{ARX model estimation using instrumental variable method}
+\usage{
+iv(z, order = c(0, 1, 0), x = NULL)
+}
+\arguments{
+\item{z}{an idframe object containing the data}
+
+\item{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}
+
+\item{x}{instrument variable matrix. x must be of the same size as the output
+data. (Default: \code{NULL})}
+}
+\value{
+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}
+}
+\description{
+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
+}
+\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.
+}
+\examples{
+data(arxsim)
+mod_iv <- iv(z,c(2,1,1))
+
+}
+\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
+}
+\seealso{
+arx
+}
+