---
title: "Using package ArchaeoPhases to process the raw MCMC output from chronological modelling software."
author: "Anne Philippe and Marie-Anne Vibet"
date: "`r Sys.Date()`"
output:
  html_document:
    fig_caption: false
    toc: true
    toc_float:
      collapsed: false
      smooth_scroll: false
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{3.ArchaeoPhases: Analysis of groups of dates}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

3. ArchaeoPhases : Analysis of groups of dates
===============

```{r, echo = FALSE, message = FALSE}
hasData <- requireNamespace("ArchaeoPhases.dataset", quietly = TRUE)
if (!hasData) {
    knitr::opts_chunk$set(eval = FALSE)
    msg <- paste("Note: Examples in this vignette require that the",
    "`ArchaeoPhases.dataset` package be installed. The system",
    "currently running this vignette does not have that package",
    "installed, so code examples will not be evaluated.")
    msg <- paste(strwrap(msg), collapse="\n")
    message(msg)
}
knitr::opts_chunk$set(comment = "")
options(width = 120, max.print = 5)
library(ArchaeoPhases)
library(ArchaeoPhases.dataset)

```

## Groups of dates
A group of dates is defined by the date of the minimum and the date of the maximum of the group. In this part, we will use the data containing these values for each group of dates.

### Time Range Interval
We can estimate the time range of a group of dates as the shortest interval that contains all the dates of the group at a given confidence level (see Philippe and Vibet 2017 for more details).
The following code gives the endpoints of the time range of all groups of dates of Ksar Akil data and recall the given confidence level.
```{r,fig.align='center',fig.width=6,fig.height=5}
data("KAPhasesChronoModel")
MultiPhaseTimeRange(KAPhasesChronoModel, c(8,6,4,2), level = 0.95)
```
The time range interval of the group of dates is a way to summarise the estimation of its minimum, the estimation of its maximum and their uncertainties at the same time.

### Graphical representation
The function **PhasePlot()** may be used to draw a plot of the characteristics of several groups of dates on a same graph : the marginal posterior density of the minimum and the maximum of each group and its time range at a desired level.
```{r,fig.align='center',fig.width=6,fig.height=5}
data("KAPhasesChronoModel")
MultiPhasePlot(KAPhasesChronoModel, c(8,6,4,2), level = 0.95)
```

## Succession of groups
We may also be interested in a succession of phases. This is actually the case of the succession of IUP, Ahmarian, UP and EPI that are in stratigraphic order. Hence, we can estimate the transition interval and, if it exists, the gap between these successive phases.

### Transistions between successive groups
The transition interval between two successive phases is the shortest interval that covers the end of the oldest group of dates and the start of the youngest group of dates. The start and the end are estimated by the minimum and the maximum of the dates included in the group of dates. It gives an idea of the transition period between two successive group of dates. From a computational point of view this is equivalent to the time range calculated between the end of the oldest group of dates and the start of the youngest group of dates.
See Philippe and Vibet 2017 for more statistical details.
```{r,fig.align='center',fig.width=6,fig.height=5}
data("KAPhasesChronoModel")
MultiPhasesTransition(KAPhasesChronoModel, c(8,6,4,2), level = 0.95)
```
For this function, the order of the groups of dates is important. The vector of positions of the minimums should start with the minimum of the oldest phase and end with the one of the youngest phase. For data extracted from ChronoModel or using the function CreateMinMaxGroup(), the vector of positions of the phases’ maximums is deduced from the vector of the minimum. For other data, this vector should be specified.

### Gap between successive groups
Successive phases may also be separated in time. Indeed there may exist a gap between them. This testing procedure check whether a gap exists between two successive groups of dates with fixed probability. If a gap exists, it is an interval that covers the end of one group of dates and the start of the successive one with fixed posterior probability. See Philippe and Vibet 2017 for more statistical details.
```{r,fig.align='center',fig.width=6,fig.height=5}
data("KAPhasesChronoModel")
MultiPhasesGap(KAPhasesChronoModel, c(8,6,4,2), level = 0.95)
```
At a confidence level of 95%, there is no gap between the succession of phases IUP, Ahmarian and UP, but there exists one of 203 years between phase UP and phase EPI.

### Graphical representation
Now, let's summarise these pieces of information in a plot. The following lines generate the plot of the succession of phases from Ksar Akil.
```{r,fig.align='center',fig.width=6,fig.height=5}
data("KAPhasesChronoModel")
MultiSuccessionPlot(KAPhasesChronoModel, c(8,6,4,2), level = 0.95)
```
The characteristics of phase IUP are drawn in red, those of phase Ahmarian are in green, those of phase UP are in light blue and those of phase EPI are in purple.
As there is only one event in the phases EPI and IUP, the minimum and the maximum of these phases have the same values at each iteration. Hence, we can only see one curve for each of these phases.
Time range are displayed by segments above the curves. Two-coloured segments correspond to transition interval or to the gap range between successive phases associated to a level confidence of 95%.
As there are no gaps at 95% between phases IUP and Ahmarian, and Ahmarian and UP, a cross is drawn instead.

## References

For a description of the statiscal aspects of the functions implemented in ArchaeoPhases version 1.0 :
Anne Philippe, Marie-Anne Vibet. (2017). Analysis of Archaeological Phases using the CRAN Package 'ArchaeoPhases'. HAL, hal-01347895, version 3.

For a use of the tempo plot defined by Dye :
Dye, T.S. (2016). Long-term rhythms in the development of Hawaiian social stratification. Journal of Archaeological Science, 71, 1--9

For more details on the diagnostic of Markov chain :
Robert and Casella (2009). Introducing Monte Carlo Methods with R. Springer Science & Business Media.

For more details on the Ksar Akil site :
Bosch, M. et al. (2015) New chronology for Ksar Akil (Lebanon) supports Levantine route of modern human dispersal into Europe. Proceedings of the National Academy of Sciences, 112, 7683--6.
