---
title: "Event Date Model"
author: "N. Frerebeau"
date: "`r Sys.Date()`"
output:
  markdown::html_format:
    options:
      toc: true
      number_sections: true
header-includes:
   - \usepackage{amsmath}
   - \usepackage{amssymb}
vignette: >
  %\VignetteIndexEntry{Event Date Model}
  %\VignetteEngine{knitr::knitr}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE, echo=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = NULL
)
```

```{r packages}
## Install extra packages (if needed):
# install.packages("folio") # datasets

# Load packages
library(kairos)
```

## Definition

Event and accumulation dates are density estimates of the occupation and duration of an archaeological site (Bellanger, Husi and Tomassone 2006; Bellanger, Tomassone and Husi 2008; Bellanger and Husi 2012).

The event date is an estimation of the *terminus post-quem* of an archaeological assemblage. The accumulation date represents the "chronological profile" of the assemblage. According to Bellanger and Husi (2012), accumulation date can be interpreted "at best [...] as a formation process reflecting the duration or succession of events on the scale of archaeological time, and at worst, as imprecise dating due to contamination of the context by residual or intrusive material." In other words, accumulation dates estimate occurrence of archaeological events and rhythms of the long term.

### Event Date

Event dates are estimated by fitting a Gaussian multiple linear regression model on the factors resulting from a correspondence analysis - somewhat similar to the idea introduced by Poblome and Groenen (2003). This model results from the known dates of a selection of reliable contexts and allows to predict the event dates of the remaining assemblages.

First, a correspondence analysis (CA) is carried out to summarize the information in the count matrix $X$. The correspondence analysis of $X$ provides the coordinates of the $m$ rows along the $q$ factorial components, denoted $f_{ik} ~\forall i \in \left[ 1,m \right], k \in \left[ 1,q \right]$.

Then, assuming that $n$ assemblages are reliably dated by another source, a Gaussian multiple linear regression model is fitted on the factorial components for the $n$ dated assemblages:

$$
t^E_i = \beta_{0} + \sum_{k = 1}^{q} \beta_{k} f_{ik} + \epsilon_i ~\forall i \in [1,n]
$$
where $t^E_i$ is the known date point estimate of the $i$th assemblage, $\beta_k$ are the regression coefficients and $\epsilon_i$ are normally, identically and independently distributed random variables, $\epsilon_i \sim \mathcal{N}(0,\sigma^2)$.

These $n$ equations are stacked together and written in matrix notation as

$$
t^E = F \beta + \epsilon
$$

where $\epsilon \sim \mathcal{N}_{n}(0,\sigma^2 I_{n})$, $\beta = \left[ \beta_0 \cdots \beta_q \right]' \in \mathbb{R}^{q+1}$ and

$$
F = 
\begin{bmatrix}
1 & f_{11} & \cdots & f_{1q} \\
1 & f_{21} & \cdots & f_{2q} \\
\vdots & \vdots & \ddots & \vdots \\
1 & f_{n1} & \cdots & f_{nq}
\end{bmatrix}
$$

Assuming that $F'F$ is nonsingular, the ordinary least squares estimator of the unknown parameter vector $\beta$ is:

$$
\widehat{\beta} = \left( F'F \right)^{-1} F' t^E
$$

Finally, for a given vector of CA coordinates $f_i$, the predicted event date of an assemblage $t^E_i$ is:

$$
\widehat{t^E_i} = f_i \hat{\beta}
$$

The endpoints of the $100(1 − \alpha)$% associated prediction confidence interval are given as:

$$
\widehat{t^E_i} \pm t_{\alpha/2,n-q-1} \sqrt{\widehat{V}}
$$

where $\widehat{V_i}$ is an estimator of the variance of the prediction error:
<!-- https://stats.stackexchange.com/questions/147242/how-to-calculate-the-prediction-interval-for-an-ols-multiple-regression -->
$$
\widehat{V_i} = \widehat{\sigma}^2 \left( f_i^T \left( F'F \right)^{-1} f_i + 1 \right)
$$

were $\widehat{\sigma} = \frac{\sum_{i=1}^{n} \left( t_i - \widehat{t^E_i} \right)^2}{n - q - 1}$.

The probability density of an event date $t^E_i$ can be described as a normal distribution:

$$
t^E_i \sim \mathcal{N}(\widehat{t^E_i},\widehat{V_i})
$$

### Accumulation Date
As row (assemblages) and columns (types) CA coordinates are linked together through the so-called transition formulae, event dates for each type $t^E_j$ can be predicted following the same procedure as above.

Then, the accumulation date $t^A_i$ is defined as the weighted mean of the event date of the ceramic types found in a given assemblage. The weights are the conditional frequencies of the respective types in the assemblage (akin to the MCD).

The accumulation date is estimated as:
$$ 
\widehat{t^A_i} = \sum_{j = 1}^{p} \widehat{t^E_j} \times \frac{x_{ij}}{x_{i \cdot}}
$$

The probability density of an accumulation date $t^A_i$ can be described as a Gaussian mixture: 

$$
t^A_i \sim \frac{x_{ij}}{x_{i \cdot}} \mathcal{N}(\widehat{t^E_j},\widehat{V_j}^2)
$$

Interestingly, the integral of the accumulation date offers an estimates of the cumulative occurrence of archaeological events, which is close enough to the definition of the *tempo plot* introduced by Dye (2016).

## Limitation

Event and accumulation dates estimation relies on the same conditions and assumptions as the matrix seriation problem. Dunnell (1970) summarizes these conditions and assumptions as follows.

The homogeneity conditions state that all the groups included in a seriation must:

* Be of comparable duration.
* Belong to the same cultural tradition.
* Come from the same local area.

The mathematical assumptions state that the distribution of any historical or temporal class:

* Is continuous through time.
* Exhibits the form of a unimodal curve.

Theses assumptions create a distributional model and ordering is accomplished by arranging the matrix so that the class distributions approximate the required pattern. The resulting order is inferred to be chronological.

Predicted dates have to be interpreted with care: these dates are highly dependent on the range of the known dates and the fit of the regression.

## Usage

This package provides an implementation of the chronological modeling method developed by Bellanger and Husi (2012). This method is slightly modified here and allows the construction of different probability density curves of archaeological assemblage dates (*event*, *activity* and *tempo*).

```{r event-model}
## Bellanger et al. did not publish the data supporting their demonstration: 
## no replication of their results is possible. 
## Here is an example using the Zuni dataset from Peeples and Schachner 2012
data("zuni", package = "folio")

## Assume that some assemblages are reliably dated (this is NOT a real example)
## The names of the vector entries must match the names of the assemblages
zuni_dates <- c(
  LZ0569 = 1097, LZ0279 = 1119, CS16 = 1328, LZ0066 = 1111,
  LZ0852 = 1216, LZ1209 = 1251, CS144 = 1262, LZ0563 = 1206,
  LZ0329 = 1076, LZ0005Q = 859, LZ0322 = 1109, LZ0067 = 863,
  LZ0578 = 1180, LZ0227 = 1104, LZ0610 = 1074
)

## Model the event and accumulation date for each assemblage
model <- event(zuni, dates = zuni_dates, rank = 10)

## Extract model coefficients
## (convert results to Gregorian years)
coef(model, calendar = CE())

## Extract residual standard deviation
## (convert results to Gregorian years)
sigma(model, calendar = CE())

## Extract model residuals
## (convert results to Gregorian years)
resid(model, calendar = CE())

## Extract model fitted values
## (convert results to Gregorian years)
fitted(model, calendar = CE())
```

```{r event-predict}
## Estimate event dates
eve <- predict_event(model, margin = 1, level = 0.95)
head(eve)

## Estimate accumulation dates (median)
acc <- predict_accumulation(model, level = 0.95)
head(acc)
```

```{r event-plot, fig.width=7, fig.height=7}
## Activity plot
plot(model, type = "activity", event = TRUE, select = 1:6)
plot(model, type = "activity", event = TRUE, select = "LZ1105")

## Tempo plot
plot(model, type = "tempo", select = "LZ1105")
```

Resampling methods can be used to check the stability of the resulting model. If `jackknife()` is used, one type/fabric is removed at a time and all statistics are recalculated. In this way, one can assess whether certain type/fabric has a substantial influence on the date estimate. If `bootstrap()` is used, a large number of new bootstrap assemblages is created, with the same sample size, by resampling the original assemblage with replacement. Then, examination of the bootstrap statistics makes it possible to pinpoint assemblages that require further investigation.

```{r event-refine, warning=FALSE}
## Check model variability
## Jackknife fabrics
jack <- jackknife(model)
head(jack)

## Bootstrap of assemblages
boot <- bootstrap(model, n = 30)
head(boot)
```

## References

Bellanger, L., Husi, P. & Tomassone,  R. (2006). Une approche statistique pour la datation de contextes archéologiques. *Revue de statistique appliquée*, 54(2), 65-81. URL: <https://www.numdam.org/item/RSA_2006__54_2_65_0/>.

Bellanger, L. & Husi, P. (2012). Statistical Tool for Dating and Interpreting Archaeological Contexts Using Pottery. *Journal of Archaeological Science*, 39(4), 777-790. DOI: [10.1016/j.jas.2011.06.031](https://doi.org/10.1016/j.jas.2011.06.031).

Bellanger, L. & Tomassone, R. & Husi, P. (2008). A Statistical Approach for Dating Archaeological Contexts. *Journal of Data Science*, 6, 135-154.

Dunnell, R. C. (1970). Seriation Method and Its Evaluation. *American Antiquity*, 35(3), 305-319. DOI: [10.2307/278341](https://doi.org/10.2307/278341).

Dye, T. S. (2016). Long-Term Rhythms in the Development of Hawaiian Social Stratification. *Journal of Archaeological Science*, 71, 1-9. DOI: [10.1016/j.jas.2016.05.006](https://doi.org/10.1016/j.jas.2016.05.006).

Poblome, J. & Groenen, P. J. F. (2003). Constrained Correspondence Analysis for Seriation of Sagalassos Tablewares. In M. Doerr & A. Sarris (Eds.), *The Digital Heritage of Archaeology* Athens: Hellenic Ministry of Culture.
