% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/STARS.R
\name{STARS}
\alias{STARS}
\title{Spatial-temporal autoregressive model}
\usage{
STARS(
  x,
  M,
  curve = c("gompertz", "makeham", "oppermann", "thiele", "wittsteinbumsted", "perks",
    "weibull", "vandermaen", "beard", "heligmanpollard", "rogersplanck", "siler",
    "martinelle", "thatcher", "gompertz2", "makeham2", "oppermann2", "thiele2",
    "wittsteinbumsted2", "perks2", "weibull2", "vandermaen2", "beard2",
    "heligmanpollard2", "rogersplanck2", "siler2", "martinelle2", "thatcher2"),
  h = 10
)
}
\arguments{
\item{x}{vector of ages.}

\item{M}{matrix of mortality rates (rows as years and columns as ages).}

\item{curve}{name of mortality curve for smoothing forecasted mortality rates (including gompertz, makeham, oppermann, thiele, wittsteinbumsted, perks, weibull, vandermaen, beard, heligmanpollard, rogersplanck, siler, martinelle, thatcher, gompertz2, makeham2, oppermann2, thiele2, wittsteinbumsted2, perks2, weibull2, vandermaen2, beard2, heligmanpollard2, rogersplanck2, siler2, martinelle2, thatcher2, where first 14 curves' parameters are unconstrained and last 14 curves' parameters are generally restricted to be positive).}

\item{h}{forecast horizon (default = 10).}
}
\value{
An object of class STARS with associated S3 methods coef, forecast, plot, residuals, and simulate (nsim for setting number of simulations; seed for initialising random number generator).
}
\description{
Fits and forecasts mortality rates using spatial-temporal autoregressive model.
}
\details{
The spatial-temporal autoregressive (STAR) model is specified as

\eqn{ln(M_t) = \mu + R ln(M_{t-1}) + E_t},

where \eqn{\mu} contains intercept parameters and \eqn{R} is banded matrix with non-zero entries in main diagonal and two subdiagonals below that.

The model is estimated by constrained regression and is forecasted via its autoregressive nature. Constraints in \eqn{R} include: all non-zero entries are between zero and one and sum of each row is one. It can be applied to whole age range.
}
\examples{
x <- 60:89
a <- c(-4.8499,-4.7676,-4.6719,-4.5722,-4.4847,-4.3841,-4.2813,-4.1863,-4.0861,-3.9962,
-3.8885,-3.7896,-3.6853,-3.5737,-3.4728,-3.3718,-3.2586,-3.1474,-3.0371,-2.9206,
-2.7998,-2.6845,-2.5653,-2.4581,-2.3367,-2.2159,-2.1017,-1.9941,-1.8821, -1.7697)
b <- c(0.0283,0.0321,0.0335,0.0336,0.0341,0.0358,0.0368,0.0403,0.0392,0.0395,
0.0396,0.0399,0.0397,0.0386,0.039,0.0375,0.0367,0.0368,0.035,0.0354,
0.0336,0.0323,0.0313,0.0295,0.0282,0.0265,0.024,0.0226,0.0219,0.0183)
k <- c(12.11,10.69,11.18,9.64,9.35,8.21,6.89,5.74,4.56,3.6,
3.27,2.04,1.11,-0.44,-1.05,-1.03,-1.84,-2.9,-4.03,-4.12,
-5.18,-5.64,-6,-6.51,-6.91,-6.9,-8.32,-8.53,-9.69,-9.31)
set.seed(123)
M <- exp(outer(k,b)+matrix(a,nrow=30,ncol=30,byrow=TRUE)+rnorm(900,0,0.035))
fit <- STARS(x=x,M=M,curve="makeham",h=30)
coef(fit)
forecast::forecast(fit)
plot(fit)
residuals(fit)

}
\references{
Li, H. and Lu, Y. (2017). Coherent forecasting of mortality rates: A sparse vector-autoregression approach. ASTIN Bulletin, 47(2), 563-600.
}
