---
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{2.ArchaeoPhases : Analysis of a series of dates}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

2. ArchaeoPhases : Analysis of a series 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)

```


## Analysis of a series of dates

### Tempo Plot
The tempo plot has been introduced by Thomas S. Dye (Dye, T.S. (2016) Long-term rhythms in the development of Hawaiian social stratification. Journal of Archaeological Science, 71, 1--9). See Philippe and Vibet 2017 for more statistical details.

The tempo plot is one way to measure change over time: it estimates the cumulative occurrence of archaeological events in a Bayesian calibration.
The tempo plot yields a graphic where the slope of the plot directly reflects the pace of change: a period of rapid change yields a steep slope and a period of slow change yields a gentle slope. When there is no change, the plot is horizontal. When change is instantaneous, the plot is vertical.

The code is the following (Warning : be patient. The execution time depends on the number of dates included.)
```{r,fig.align='center',fig.width=6,fig.height=5}
data("KADatesChronoModel")
tempo_plot(KADatesChronoModel, c(2:10), level = 0.95)
```
From these graphs, we can see that the highest part of the sampled activity is dated between -45 000 to -35 000 but two dates are younger, at about -32 000 and -28 000.

### Tempo Activity Plot
The activity plot displays the derivative of the Bayes estimate of the Tempo plot.
It is an other way to see changes over time.

The code is the following (Warning : be patient. The execution time depends on the number of dates included.)
```{r,fig.align='center',fig.width=6,fig.height=5}
tempo_activity_plot(KADatesChronoModel, c(2:10))
```

### Occurrence Plot
The Occurrence plot calculates the calendar date t corresponding to the smallest date such that the number of events observed before t is equal to k, for k =[(1, 16)].
The Occurrence plot draws the credible intervals or the highest posterior density (HPD) region of those dates associated to a desired level of confidence.
```{r,fig.align='center',fig.width=6,fig.height=5}
data("KADatesChronoModel")
OccurrencePlot(KADatesChronoModel, c(2:17), level = 0.95, newWindow= FALSE)
```

## 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.
