% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/packagefiles.R
\name{estimateETAS}
\alias{estimateETAS}
\title{Draws samples from the posterior distribution of the ETAS model}
\usage{
estimateETAS(
  ts,
  ms,
  M0,
  maxTime = NULL,
  xs = NULL,
  ys = NULL,
  area = NULL,
  sims = 5000,
  burnin = 1000,
  initval = NA,
  sigma2_prior_shape = 3,
  sigma2x_prior_rate = NULL,
  sigma2y_prior_rate = NULL,
  handle_ties = c("error", "jitter"),
  c_lower = NULL
)
}
\arguments{
\item{ts}{Vector containing the earthquake times}

\item{ms}{Vector containing the earthquake magnitudes}

\item{M0}{Magnitude of completeness.}

\item{maxTime}{Length of the time window [0,maxTime] the catalog was observed over. If not specified, will be taken as the time of the last earthquake.}

\item{xs}{(For the spatio-temporal ETAS model only), a vector containing the x coordinates of the earthquakes}

\item{ys}{(For the spatio-temporal ETAS model only), a vector containing the y coordinates of the earthquakes}

\item{area}{(For the spatio-temporal ETAS model only), a single number containing the area of the rectangular spatial region containing the earthquakes. For example if the earthquakes are defined on [28,35]x[-119,-128] then the area would be 7x9 = 63. If this is not specified then it will be calculated based on the distance between the furthest apart earthquakes in the catalog.}

\item{sims}{Number of posterior samples to draw}

\item{burnin}{Number of burnin samples. If (eg) sims=5000 and burnin=2000 then 7000 samples will be drawn with the first 2000 discarded}

\item{initval}{Initial value at which to start the estimation. If specified, should be a vector, with elements (mu, K, alpha, c, p) for the temporal model and  (mu, K, alpha, c, p, sigma2x,sigma2y) for the spatio-temporal model. If unspecified, the sampler will be initialized at the maximum likelihood estimate of the model parameters}

\item{sigma2_prior_shape}{Shape parameter for the inverse-gamma prior on Gaussian spatial variances, using a shape/rate convention. Must be greater than 2.}

\item{sigma2x_prior_rate}{Rate parameter for the inverse-gamma prior on \eqn{\sigma^2_x}. If \code{NULL}, a scale-aware default equal to \eqn{2 * (0.1 * diff(range(xs)))^2} is used.}

\item{sigma2y_prior_rate}{Rate parameter for the inverse-gamma prior on \eqn{\sigma^2_y}. If \code{NULL}, a scale-aware default equal to \eqn{2 * (0.1 * diff(range(ys)))^2} is used.}

\item{handle_ties}{How to handle duplicate event times. The default \code{"error"} stops because continuous-time ETAS requires strictly increasing event times. \code{"jitter"} applies a deterministic, order-preserving jitter before fitting. This is a preprocessing convention, not part of the ETAS model.}

\item{c_lower}{Lower bound for the Omori \eqn{c} parameter. If \code{NULL}, a data-scale default equal to one tenth of the smallest positive event-time gap after tie handling is used.}
}
\value{
A data frame containing the posterior samples. Each row is a single sample, and the columns correspond to (mu, K, alpha, c, p) for the temporal model and  (mu, K, alpha, c, p,sigma2x,sigma2y) for the spatio-temporal model
}
\description{
This function implements the latent variable MCMC scheme from (Ross 2019) which draws samples from the Bayesian posterior distribution of the Epidemic Type Aftershock Sequence (ETAS)  model. Either the temporal ETAS or the spatio-temporal (with a bivariate Gaussian trigger kernel) can be sampled.
\deqn{}
The ETAS model is widely used to quantify the degree of seismic activity in a geographical region, and to forecast the occurrence of future mainshocks and aftershocks (Ross 2019). The temporal ETAS model is a point process where the probability of an earthquake occurring at time \eqn{t} depends on the previous seismicity \eqn{H_t}{Ht}, and is defined by the conditional intensity function:
\deqn{ \lambda(t|H_t) = \mu + \sum_{t[i] < t}  \kappa(m[i]|K,\alpha) h(t-t[i]|c,p)}{ \lambda(t|Ht) = \mu + \sum \kappa(m[i]|K,\alpha) h(t[i]|c,p)s(x-x[i],y-y[i],}
where
\deqn{\kappa(m_i|K,\alpha) = Ke^{\alpha \left( m_i-M_0 \right)}}{\kappa(m[i]|K,\alpha) = K * exp(\alpha(m[i]-M0))}
and
\deqn{ h(t_i|c,p) = \frac{(p-1)c^{p-1}}{(t-t_i+c)^p}}{ h(t[i]|c,p) = (p-1) * c^(p-1) * (t-t[i]+c)^(-p)}
and s() is a spatial triggering kernel. The public spatio-temporal fitting routines currently use a Gaussian spatial triggering kernel with a homogeneous spatial background over the supplied area and no spatial edge correction. s() can also be omitted to fit the temporal ETAS model without a spatial component.
The summation is over all previous earthquakes that occurred in the region, with the i'th such earthquake occurring at time \eqn{ t_i}{t[i]} at spatial location (\eqn{ x_i}{x[i]},,\eqn{ y_i}{y[i]}) aand having magnitude \eqn{ m_i}{m[i]}. The quantity \eqn{M_0}{M0} denotes the magnitude of completeness of the catalog, so that \eqn{m_i \geq  M_0}{m[i] \ge M0} for all i. The temporal ETAS model has 5 parameters: \eqn{\mu} controls the background rate of seismicity, \eqn{ K} and \eqn{ \alpha} determine the productivity (average number of aftershocks) of an earthquake with magnitude \eqn{m}, and \eqn{c} and \eqn{ p}  are the parameters of the Modified Omori Law (which has here been normalized to integrate to 1) and represent the speed at which the aftershock rate decays over time. Each earthquake is assumed to have a magnitude which is an independent draw from the Gutenberg-Richter law \eqn{ p(m_i) = \beta e^{\beta(m_i-M_0)}}{ p(m) = \beta * exp(\beta(m-M0)}.
}
\details{
In the spatio-temporal version of the model, s() is the multivariate Gaussian with diagonal covariance parameters \eqn{\sigma^2_x} and \eqn{\sigma^2_y}. The spatial background is homogeneous over the supplied area and no spatial edge correction is implemented.

The inverse-gamma priors for \eqn{\sigma^2_x} and \eqn{\sigma^2_y} use a shape/rate convention. If the spatial prior rates are not supplied, the defaults are scale-aware: \eqn{2 * (0.1 * diff(range(xs)))^2} for \eqn{\sigma^2_x} and \eqn{2 * (0.1 * diff(range(ys)))^2} for \eqn{\sigma^2_y}. Degenerate coordinate ranges require explicit prior rates.

The likelihood assumes strictly increasing event times. By default duplicate times are rejected. With \code{handle_ties = "jitter"}, tied event times are separated deterministically by a small amount before fitting. The Omori \eqn{c} parameter is constrained to be greater than \code{c_lower}; this prevents finite-resolution catalogues with exact or near ties from driving \eqn{c} to zero.
}
\examples{
\donttest{
#temporal model
ts <- c(1, 2, 3, 5, 8)
ms <- c(3.0, 3.1, 3.3, 3.2, 3.0)
samples <- estimateETAS(ts, ms, M0=3, maxTime=10, sims=20, burnin=5,
    initval=c(0.1, 0.1, 0.5, 0.2, 1.5))
apply(samples, 2, median) #point estimate

#spatio-temporal model
xs <- c(1, 2, 3, 4, 5)
ys <- c(1, 1.5, 2, 1.5, 1)
samples <- estimateETAS(ts, ms, M0=3, maxTime=10, xs=xs, ys=ys,
    area=25, sims=20, burnin=5,
    initval=c(0.1, 0.1, 0.5, 0.2, 1.5, 1, 1))
apply(samples, 2, median) #point estimate
}

}
\references{
Gordon J. Ross - Bayesian Estimation of the ETAS Model for Earthquake Occurrences (2019)
}
\author{
Gordon J Ross
}
