Type:	Package
Title:	Post-Processing of Markov Chain Monte Carlo Simulations for Chronological Modelling
Version:	2.0
Maintainer:	Anne Philippe <anne.philippe@univ-nantes.fr>
Description:	Statistical analysis of archaeological dates and groups of dates. This package allows to post-process Markov Chain Monte Carlo (MCMC) simulations from 'ChronoModel' https://chronomodel.com/, 'Oxcal' https://c14.arch.ox.ac.uk/oxcal.html or 'BCal' https://bcal.shef.ac.uk/. It provides functions for the study of rhythms of the long term from the posterior distribution of a series of dates (tempo and activity plot). It also allows the estimation and visualization of time ranges from the posterior distribution of groups of dates (e.g. duration, transition and hiatus between successive phases) as described in Philippe and Vibet (2020) <doi:10.18637/jss.v093.c01>.
License:	GPL (≥ 3)
URL:	https://ArchaeoStat.github.io/ArchaeoPhases/, https://github.com/ArchaeoStat/ArchaeoPhases
BugReports:	https://github.com/ArchaeoStat/ArchaeoPhases/issues
Depends:	R (≥ 3.5)
Imports:	arkhe (≥ 1.6.0), aion (≥ 1.0.2), graphics, grDevices, methods, stats, tools, utils
Suggests:	ArchaeoData, coda, knitr, rmarkdown, rsvg, svglite, tinysnapshot, tinytest
VignetteBuilder:	knitr
Additional_repositories:	https://archaeostat.r-universe.dev
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.1
Collate:	'reexport.R' 'AllClasses.R' 'AllGenerics.R' 'ArchaeoPhases-defunct.R' 'ArchaeoPhases-deprecated.R' 'ArchaeoPhases-internal.R' 'ArchaeoPhases-package.R' 'activity.R' 'allen-mcmc.R' 'allen-relations.R' 'bind.R' 'boundaries.R' 'coerce.R' 'data.R' 'depth.R' 'duration.R' 'elapse.R' 'events.R' 'hiatus.R' 'interpolate.R' 'interval.R' 'mutators.R' 'occurrence.R' 'phases.R' 'plot.R' 'read.R' 'sensitivity.R' 'show.R' 'sort.R' 'subset.R' 'summary.R' 'tempo.R' 'test.R' 'transition.R' 'validate.R' 'zzz.R'
NeedsCompilation:	no
Packaged:	2024-06-15 16:36:43 UTC; annephilippe
Author:	Anne Philippe [aut, cre], Marie-Anne Vibet [aut], Thomas S. Dye [ctb], Nicolas Frerebeau [aut]
Repository:	CRAN
Date/Publication:	2024-06-16 15:00:02 UTC

ArchaeoPhases: Post-Processing of Markov Chain Monte Carlo Simulations for Chronological Modelling

Description

Statistical analysis of archaeological dates and groups of dates. This package allows to post-process Markov Chain Monte Carlo (MCMC) simulations from 'ChronoModel' https://chronomodel.com/, 'Oxcal' https://c14.arch.ox.ac.uk/oxcal.html or 'BCal' https://bcal.shef.ac.uk/. It provides functions for the study of rhythms of the long term from the posterior distribution of a series of dates (tempo and activity plot). It also allows the estimation and visualization of time ranges from the posterior distribution of groups of dates (e.g. duration, transition and hiatus between successive phases) as described in Philippe and Vibet (2020) doi:10.18637/jss.v093.c01.

Details

Package options

ArchaeoPhases uses the following options() to configure behaviour:

• ArchaeoPhases.calendar: a TimeScale object (default calendar for printing).

• ArchaeoPhases.grid: a numeric value specifying the number of equally spaced points at which densities are to be estimated (defaults to 512). Should be a power of 2.

• ArchaeoPhases.precision: an integer indicating the number of decimal places (defaults to 0).

• ArchaeoPhases.progress: a logical scalar specifying if progress bars should be displayed (defaults to interactive()).

Author(s)

Full list of authors and contributors (alphabetic order)

Package maintainer

Anne Philippe
anne.philippe@univ-nantes.fr

Laboratoire de Mathématiques Jean Leray (UMR 6629)
2, rue de la Houssinière
BP 92208
F-44322 Nantes Cedex 3
France

See Also

Useful links:

• https://ArchaeoStat.github.io/ArchaeoPhases/

• https://github.com/ArchaeoStat/ArchaeoPhases

• Report bugs at https://github.com/ArchaeoStat/ArchaeoPhases/issues

Activity

Description

An S4 class to store the result of an activity plot.

Slots

hash

A character string giving the 32-byte MD5 hash of the original data file.

Coerce

In the code snippets below, x is an ActivityEvents object.

as.data.frame(x)

Coerces to a data.frame.

Note

This class inherits from TimeSeries.

Author(s)

N. Frerebeau

See Also

Other classes: AgeDepthModel-class, CumulativeEvents-class, DurationsMCMC-class, EventsMCMC-class, MCMC-class, OccurrenceEvents-class, PhasesMCMC-class, TimeRange-class

Age-Depth Model

Description

An S4 class to represents an age-depth model.

Slots

depth

A numeric vector giving the depth of the samples.

model

A list of local polynomial regressions (see stats::loess()).

hash

A character string giving the 32-byte MD5 hash of the original data file.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, CumulativeEvents-class, DurationsMCMC-class, EventsMCMC-class, MCMC-class, OccurrenceEvents-class, PhasesMCMC-class, TimeRange-class

Defunct Functions in ArchaeoPhases

Description

These functions are defunct and have been replaced in ArchaeoPhases 2.0.

Usage

AgeDepth(...)

CreateMinMaxGroup(...)

CredibleInterval(...)

credible_interval(...)

DatesHiatus(...)

dates_hiatus(...)

estimate_range(...)

MarginalPlot(...)

marginal_plot(...)

MarginalProba(...)

MarginalStatistics(...)

marginal_statistics(...)

multi_marginal_statistics(...)

MultiCredibleInterval(...)

multi_credible_interval(...)

MultiDatesPlot(...)

multi_dates_plot(...)

MultiHPD(...)

multi_hpd(...)

MultiMarginalPlot(...)

multi_marginal_plot(...)

MultiPhasePlot(...)

MultiPhaseTimeRange(...)

MultiPhasesGap(...)

MultiPhasesTransition(...)

MultiSuccessionPlot(...)

OccurrencePlot(...)

occurrence_plot(...)

PhaseDurationPlot(...)

PhasePlot(...)

PhaseStatistics(...)

PhaseTimeRange(...)

PhasesGap(...)

phases_gap(...)

PhasesTransition(...)

SuccessionPlot(...)

TempoActivityPlot(...)

tempo_activity_plot(...)

TempoPlot(...)

tempo_plot(...)

undated_sample(...)

Arguments

Details

See the changelog for details: news(Version >= "2.0", package = "ArchaeoPhases").

Deprecated Functions in ArchaeoPhases

Description

These functions still work but will be removed (defunct) in the next version.

Cumulative Events

Description

An S4 class to store the result of a tempo plot.

Slots

lower

A numeric vector giving the lower boundaries of the credibility interval.

upper

A numeric vector giving the upper boundaries of the credibility interval.

level

A length-one numeric vector giving the confidence level.

gauss

A logical scalar indicating if the Gaussian approximation of the credible interval was used.

counts

A logical scalar.

events

An integer scalar giving the number of events included in the tempo plot.

hash

A character string giving the 32-byte MD5 hash of the original data file.

Coerce

In the code snippets below, x is a CumulativeEvents object.

as.data.frame(x)

Coerces to a data.frame.

Note

This class inherits from TimeSeries.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, AgeDepthModel-class, DurationsMCMC-class, EventsMCMC-class, MCMC-class, OccurrenceEvents-class, PhasesMCMC-class, TimeRange-class

MCMC Duration

Description

S4 classes to represent the output of a MCMC algorithm.

Note

This class inherits from MCMC.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, AgeDepthModel-class, CumulativeEvents-class, EventsMCMC-class, MCMC-class, OccurrenceEvents-class, PhasesMCMC-class, TimeRange-class

MCMC Events

Description

S4 classes to represent a collection of events.

Note

This class inherits from MCMC.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, AgeDepthModel-class, CumulativeEvents-class, DurationsMCMC-class, MCMC-class, OccurrenceEvents-class, PhasesMCMC-class, TimeRange-class

MCMC

Description

An S4 class to represent the output of a MCMC algorithm.

Slots

labels

A character vector specifying the name of the events.

depth

A numeric vector giving the sample depth.

hash

A character string giving the 32-byte MD5 hash of the original data file.

Subset

In the code snippets below, x is a MCMC object.

x[[i]]

Extracts a single event (one chain) selected by subscript i. i is a length-one numeric or character vector.

Note

This class inherits from matrix.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, AgeDepthModel-class, CumulativeEvents-class, DurationsMCMC-class, EventsMCMC-class, OccurrenceEvents-class, PhasesMCMC-class, TimeRange-class

Occurrence

Description

An S4 class to store the result of an occurrence plot.

Slots

events

An integer vector giving the occurrence.

start

A numeric vector giving the lower boundaries of the credibility interval.

end

A numeric vector giving the upper boundaries of the credibility interval.

level

A length-one numeric vector giving the confidence level.

hash

A character string giving the 32-byte MD5 hash of the original data file.

Coerce

In the code snippets below, x is an OccurrenceEvents object.

as.data.frame(x)

Coerces to a data.frame.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, AgeDepthModel-class, CumulativeEvents-class, DurationsMCMC-class, EventsMCMC-class, MCMC-class, PhasesMCMC-class, TimeRange-class

MCMC Phases

Description

S4 classes to represent a collection of phases.

Details

A phase object is ann x m x 2 array, with n being the number of iterations, m being the number of phases and with the 2 columns of the third dimension containing the boundaries of the phases.

Slots

labels

A character vector specifying the name of the phases.

hash

A character string giving the 32-byte MD5 hash of the original data file.

Subset

In the code snippets below, x is a PhasesMCMC object.

x[[i]]

Extracts a single phase (two chains) selected by subscript i. i is a length-one numeric or character vector.

Note

This class inherits from array.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, AgeDepthModel-class, CumulativeEvents-class, DurationsMCMC-class, EventsMCMC-class, MCMC-class, OccurrenceEvents-class, TimeRange-class

Cumulative Events

Description

An S4 class to represent time ranges.

Slots

start,end

A numeric matrix giving the lower and upper boundaries.

labels

A character vector specifying the name of the events/phases.

hash

A character string giving the 32-byte MD5 hash of the original data file.

Coerce

In the code snippets below, x is a CumulativeEvents object.

as.data.frame(x)

Coerces to a data.frame.

Author(s)

N. Frerebeau

See Also

Other classes: ActivityEvents-class, AgeDepthModel-class, CumulativeEvents-class, DurationsMCMC-class, EventsMCMC-class, MCMC-class, OccurrenceEvents-class, PhasesMCMC-class

Activity Plot

Description

Plots the first derivative of the tempo plot Bayesian estimate.

Usage

activity(object, ...)

## S4 method for signature 'EventsMCMC'
activity(
  object,
  from = min(object),
  to = max(object),
  grid = getOption("ArchaeoPhases.grid")
)

## S4 method for signature 'CumulativeEvents'
activity(object)

## S4 method for signature 'ActivityEvents,missing'
plot(
  x,
  calendar = getOption("ArchaeoPhases.calendar"),
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

Value

• activity() returns an ActivityEvents object.

• plot() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

References

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.

See Also

Other event tools: elapse(), occurrence(), tempo()

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Tempo plot
tmp <- tempo(eve)
plot(tmp)
plot(tmp, interval = "credible", panel.first = grid())
plot(tmp, interval = "gauss", panel.first = grid())

## Activity plot
act <- activity(tmp)
plot(act, panel.first = grid())

Analyze Composite Allen Relations

Description

Visualize composite Allen relations with a Nokel lattice.

Usage

allen_analyze(x, y, ...)

Arguments

Value

allen_analyze() is called it for its side-effects: it results in a graphic being displayed.

Author(s)

T. S. Dye

See Also

Other Allen's intervals: allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Examples

allen_analyze("mDFo", "MdfO", main = "Composite reticulation relation")

Complement of an Allen Relation

Description

Complement of an Allen Relation

Usage

allen_complement(x, ...)

## S4 method for signature 'character'
allen_complement(x)

## S4 method for signature 'matrix'
allen_complement(x)

Arguments

Value

A character vector or matrix (same as x).

Author(s)

T. S. Dye, N. Frerebeau

References

Allen, J. F. (1983). Maintaining Knowledge about Temporal Intervals. Communications of the ACM, 26(11): 832-843. doi:10.1145/182.358434.

See Also

Other Allen's intervals: allen_analyze(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Examples

## Data from Husi 2022
loire <- data.frame(
  lower = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  upper = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
            1400, 1500, 1300, 1375, 1500, 1325, 1425)
)

## Basic relations
allen_relation(loire$lower, loire$upper)

## Complement
(comp <- allen_complement("F")) # "pmoDseSdfOMP"

## Converse
(conv <- allen_converse(comp)) # "pmoFDseSdOMP"

## Composition
allen_composition("oFD", "oFDseS") # "pmoFD"

## Intersection
allen_intersect("pFsSf", "pmoFD") # "pF"

# Union
allen_union("pFsSf", "pmoFD") # "pmoFDsSf"

Composition of Allen Relations

Description

Composition of Allen Relations

Usage

allen_composition(x, y, ...)

## S4 method for signature 'character,character'
allen_composition(x, y)

Arguments

Value

A character vector.

Author(s)

T. S. Dye, N. Frerebeau

References

Allen, J. F. (1983). Maintaining Knowledge about Temporal Intervals. Communications of the ACM, 26(11): 832-843. doi:10.1145/182.358434.

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Examples

## Data from Husi 2022
loire <- data.frame(
  lower = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  upper = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
            1400, 1500, 1300, 1375, 1500, 1325, 1425)
)

## Basic relations
allen_relation(loire$lower, loire$upper)

## Complement
(comp <- allen_complement("F")) # "pmoDseSdfOMP"

## Converse
(conv <- allen_converse(comp)) # "pmoFDseSdOMP"

## Composition
allen_composition("oFD", "oFDseS") # "pmoFD"

## Intersection
allen_intersect("pFsSf", "pmoFD") # "pF"

# Union
allen_union("pFsSf", "pmoFD") # "pmoFDsSf"

Converse of an Allen Relation

Description

Converse of an Allen Relation

Usage

allen_converse(x, ...)

## S4 method for signature 'character'
allen_converse(x)

## S4 method for signature 'matrix'
allen_converse(x)

Arguments

Value

A character vector or matrix (same as x).

Author(s)

T. S. Dye, N. Frerebeau

References

Allen, J. F. (1983). Maintaining Knowledge about Temporal Intervals. Communications of the ACM, 26(11): 832-843. doi:10.1145/182.358434.

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Examples

## Data from Husi 2022
loire <- data.frame(
  lower = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  upper = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
            1400, 1500, 1300, 1375, 1500, 1325, 1425)
)

## Basic relations
allen_relation(loire$lower, loire$upper)

## Complement
(comp <- allen_complement("F")) # "pmoDseSdfOMP"

## Converse
(conv <- allen_converse(comp)) # "pmoFDseSdOMP"

## Composition
allen_composition("oFD", "oFDseS") # "pmoFD"

## Intersection
allen_intersect("pFsSf", "pmoFD") # "pF"

# Union
allen_union("pFsSf", "pmoFD") # "pmoFDsSf"

Illustrate Basic and Composite Allen Relations

Description

Illustrate Basic and Composite Allen Relations

Usage

allen_illustrate(relations = "basic", ...)

Arguments

Details

Illustrate basic and composite Allen relations for several chronological model domains with a Nokel lattice. Chronological model domains include stratigraphy and branching, transformative, and reticulate processes of artifact change.

The illustrative graphics include:

basic

the 13 basic Allen relations (default);

concurrent

concurrent relations;

distinct

relations with distinct endpoints;

stratigraphic

basic relations established by an observation of superposition;

branching

basic branching relations;

transformation

basic relations of transformation;

reticulation

basic relations of reticulation;

sequence

composite relations in a stratigraphic sequence;

branch

composite relations of branching;

transform

composite relations of transformation; or

reticulate

composite relations of reticulation.

Value

allen_illustrate() is called it for its side-effects: it results in a graphic being displayed.

Author(s)

T. S. Dye

References

Harris, E. C. (1997). Principles of Archaeological Stratigraphy. Second edition. London: Academic Press.

Lyman, R. L. and O'Brien, M. J. (2017). "Sedation and Cladistics: The Difference between Anagenetic and Cladogenetic Evolution". In Mapping Our Ancestors: Phylogenetic Approaches in Anthropology and Prehistory, edited by Lipo, C. P., O'Brien, M. J., Couard, M., and Shennan, S. J. New York: Routledge. doi:10.4324/9780203786376.

Viola, T. (2020). Peirce on the Uses of History. De Gruyter. doi:10.1515/9783110651560. See chapter 3, "Historicity as Process", especially p. 83-88.

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Examples

## Plot the basic Allen relations
allen_illustrate()

Intersection of Allen Relations

Description

Intersection of Allen Relations

Usage

allen_intersect(x, y, ...)

## S4 method for signature 'character,character'
allen_intersect(x, y)

Arguments

Value

A character vector.

Author(s)

T. S. Dye, N. Frerebeau

References

Allen, J. F. (1983). Maintaining Knowledge about Temporal Intervals. Communications of the ACM, 26(11): 832-843. doi:10.1145/182.358434.

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Examples

## Data from Husi 2022
loire <- data.frame(
  lower = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  upper = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
            1400, 1500, 1300, 1375, 1500, 1325, 1425)
)

## Basic relations
allen_relation(loire$lower, loire$upper)

## Complement
(comp <- allen_complement("F")) # "pmoDseSdfOMP"

## Converse
(conv <- allen_converse(comp)) # "pmoFDseSdOMP"

## Composition
allen_composition("oFD", "oFDseS") # "pmoFD"

## Intersection
allen_intersect("pFsSf", "pmoFD") # "pF"

# Union
allen_union("pFsSf", "pmoFD") # "pmoFDsSf"

Joint Concurrence of Two or More Observed Intervals

Description

Estimates the age of an undated context based on the known depositional history of associated artifacts.

Usage

allen_joint_concurrency(x, groups, ...)

## S4 method for signature 'EventsMCMC,list'
allen_joint_concurrency(x, groups, ...)

Arguments

Value

A PhasesMCMC object.

Author(s)

T. S. Dye

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Observe the Relation Between two Phases

Description

Plots an empirical Nökel lattice.

Usage

allen_observe(x, groups, ...)

## S4 method for signature 'PhasesMCMC,missing'
allen_observe(x, converse = TRUE, ...)

## S4 method for signature 'EventsMCMC,list'
allen_observe(x, groups, converse = TRUE, ...)

Arguments

Value

allen_observe() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

T. S. Dye, N. Frerebeau

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe_frequency(), allen_relation(), allen_relation_code(), allen_union()

Examples

if (requireNamespace("ArchaeoData", quietly = TRUE)) {
  ## Load the Anglo Saxon burials dataset
  path <- system.file("oxcal/burials.csv", package = "ArchaeoData")
  burials <- read.table(path, header = TRUE, sep = ",", dec = ".",
                        check.names = FALSE)

  ## Coerce to event
  burials <- as_events(burials, calendar = CE())

  ## Dates associated with bead BE3 Amber
  be3_amber <- c(
    "UB-4836 (WG27)", "UB-5208 (ApD107)", "UB-4965 (ApD117)",
    "UB-4735 (Ber022)", "UB-4739 (Ber134/1)", "UB-4728 (MH064)",
    "UB-4729 (MH068)", "UB-4732 (MH094)", "UB-4733 (MH095)",
    "UB-4734 (MH105c)", "UB-4984 (Lec018)", "UB-4709 (EH014)",
    "UB-4707 (EH079)", "UB-4708 (EH083)", "UB-6033 (WHes113)",
    "UB-4706 (WHes118)", "UB-4705 (WHes123)", "UB-6040 (CasD053)",
    "UB-6037 (CasD134)", "UB-6472 (BuD222)", "UB-6473 (BuD250)",
    "UB-6476 (BuD339)", "UB-4963 (SPTip208)", "UB-4890 (MelSG075)",
    "UB-4887 (MelSG082)", "UB-4888 (MelSG089)", "MaDE1 & E2",
    "UB-4552 (MaDE3)", "UB-4975 (AstCli12)", "UB-4835 (ApD134)",
    "SUERC-39108 ERLK G322", "SUERC-39109 ERL G362", "SUERC-39112 ERL G405",
    "SUERC-51560 ERL G038", "SUERC-39091 (ERL G003)", "SUERC-39092 (ERL G005)",
    "SUERC-39113 (ERL G417)", "SUERC-51549 (ERL G195)", "SUERC-51552 (ERL G107)",
    "SUERC-51550 (ERL G254)"
  )

  ## Dates associated with bead BE1 Dghnt
  be1_dghnt <- c(
    "UB-4503 (Lec148)", "UB-4506 (Lec172/2)", "UB-6038 (CasD183)",
    "UB-4512 (EH091)", "UB-4501 (Lec014)", "UB-4507 (Lec187)",
    "UB-4502 (Lec138)", "UB-4042 (But1674)", "SUERC-39100 (ERL G266)"
  )

  ## Construct a list of lists
  chains <- list(
    list("BE3-Amber" = be3_amber, "BE1-Dghnt" = be1_dghnt),
    list("BE1-Dghnt" = be1_dghnt, "BE3-Amber" = be3_amber)
  )

  ## Plot
  allen_observe(x = burials, groups = chains)

  ## Observe 2x2 frequency matrix of the relation of trunk to branch
  allen_observe_frequency(burials, groups = chains, set = "oFD")
}

Observed Frequency of an Allen Set

Description

Creates a matrix of observed frequencies of a given Allen set among two or more groups of chains from the MCMC output of a Bayesian calibration.

Usage

allen_observe_frequency(x, groups, ...)

## S4 method for signature 'PhasesMCMC,missing'
allen_observe_frequency(x, set)

## S4 method for signature 'EventsMCMC,list'
allen_observe_frequency(x, groups, ...)

Arguments

Value

A square matrix of observed frequencies.

Author(s)

T. S. Dye, N. Frerebeau

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_relation(), allen_relation_code(), allen_union()

Examples

if (requireNamespace("ArchaeoData", quietly = TRUE)) {
  ## Load the Anglo Saxon burials dataset
  path <- system.file("oxcal/burials.csv", package = "ArchaeoData")
  burials <- read.table(path, header = TRUE, sep = ",", dec = ".",
                        check.names = FALSE)

  ## Coerce to event
  burials <- as_events(burials, calendar = CE())

  ## Dates associated with bead BE3 Amber
  be3_amber <- c(
    "UB-4836 (WG27)", "UB-5208 (ApD107)", "UB-4965 (ApD117)",
    "UB-4735 (Ber022)", "UB-4739 (Ber134/1)", "UB-4728 (MH064)",
    "UB-4729 (MH068)", "UB-4732 (MH094)", "UB-4733 (MH095)",
    "UB-4734 (MH105c)", "UB-4984 (Lec018)", "UB-4709 (EH014)",
    "UB-4707 (EH079)", "UB-4708 (EH083)", "UB-6033 (WHes113)",
    "UB-4706 (WHes118)", "UB-4705 (WHes123)", "UB-6040 (CasD053)",
    "UB-6037 (CasD134)", "UB-6472 (BuD222)", "UB-6473 (BuD250)",
    "UB-6476 (BuD339)", "UB-4963 (SPTip208)", "UB-4890 (MelSG075)",
    "UB-4887 (MelSG082)", "UB-4888 (MelSG089)", "MaDE1 & E2",
    "UB-4552 (MaDE3)", "UB-4975 (AstCli12)", "UB-4835 (ApD134)",
    "SUERC-39108 ERLK G322", "SUERC-39109 ERL G362", "SUERC-39112 ERL G405",
    "SUERC-51560 ERL G038", "SUERC-39091 (ERL G003)", "SUERC-39092 (ERL G005)",
    "SUERC-39113 (ERL G417)", "SUERC-51549 (ERL G195)", "SUERC-51552 (ERL G107)",
    "SUERC-51550 (ERL G254)"
  )

  ## Dates associated with bead BE1 Dghnt
  be1_dghnt <- c(
    "UB-4503 (Lec148)", "UB-4506 (Lec172/2)", "UB-6038 (CasD183)",
    "UB-4512 (EH091)", "UB-4501 (Lec014)", "UB-4507 (Lec187)",
    "UB-4502 (Lec138)", "UB-4042 (But1674)", "SUERC-39100 (ERL G266)"
  )

  ## Construct a list of lists
  chains <- list(
    list("BE3-Amber" = be3_amber, "BE1-Dghnt" = be1_dghnt),
    list("BE1-Dghnt" = be1_dghnt, "BE3-Amber" = be3_amber)
  )

  ## Plot
  allen_observe(x = burials, groups = chains)

  ## Observe 2x2 frequency matrix of the relation of trunk to branch
  allen_observe_frequency(burials, groups = chains, set = "oFD")
}

Allen Relation Between Definite Intervals

Description

Allen Relation Between Definite Intervals

Usage

allen_relation(x, y, ...)

## S4 method for signature 'numeric,numeric'
allen_relation(x, y)

## S4 method for signature 'ANY,missing'
allen_relation(x)

Arguments

Details

Value

A character matrix specifying the Allen relations.

Author(s)

T. S. Dye, N. Frerebeau

References

Allen, J. F. (1983). Maintaining Knowledge about Temporal Intervals. Communications of the ACM, 26(11): 832-843. doi:10.1145/182.358434.

Alspaugh, T. (2019). Allen's Interval Algebra. URL: https://thomasalspaugh.org/pub/fnd/allen.html.

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation_code(), allen_union()

Examples

## Data from Husi 2022
loire <- data.frame(
  lower = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  upper = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
            1400, 1500, 1300, 1375, 1500, 1325, 1425)
)

## Basic relations
allen_relation(loire$lower, loire$upper)

## Complement
(comp <- allen_complement("F")) # "pmoDseSdfOMP"

## Converse
(conv <- allen_converse(comp)) # "pmoFDseSdOMP"

## Composition
allen_composition("oFD", "oFDseS") # "pmoFD"

## Intersection
allen_intersect("pFsSf", "pmoFD") # "pF"

# Union
allen_union("pFsSf", "pmoFD") # "pmoFDsSf"

The Basic Allen Relation Set

Description

The Basic Allen Relation Set

Usage

allen_relation_code(...)

allen_relation_string(...)

allen_relation_concurrent(...)

allen_relation_distinct(...)

Arguments

Value

• allen_relation_code() returns a character vector of one-letter codes for the thirteen basic Allen relations.

• allen_relation_string() returns a character vector of string descriptors of the Allen basic relations.

• allen_relation_concurrent() returns a character vector of nine one-letter codes for the Allen concurrent relations.

• allen_relation_distinct() returns the six value Allen relation set for intervals with distinct endpoints.

Note

The codes were proposed by Thomas Alspaugh.

Author(s)

T. S. Dye

References

Allen, J. F. (1983). Maintaining Knowledge about Temporal Intervals. Communications of the ACM, 26(11): 832-843. doi:10.1145/182.358434.

Alspaugh, T. (2019). Allen's Interval Algebra. URL: https://thomasalspaugh.org/pub/fnd/allen.html.

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_union()

Union of Allen Relations

Description

Union of Allen Relations

Usage

allen_union(x, y, ...)

## S4 method for signature 'character,character'
allen_union(x, y)

Arguments

Value

A character vector.

Author(s)

T. S. Dye, N. Frerebeau

References

Allen, J. F. (1983). Maintaining Knowledge about Temporal Intervals. Communications of the ACM, 26(11): 832-843. doi:10.1145/182.358434.

See Also

Other Allen's intervals: allen_analyze(), allen_complement(), allen_composition(), allen_converse(), allen_illustrate(), allen_intersect(), allen_joint_concurrency(), allen_observe(), allen_observe_frequency(), allen_relation(), allen_relation_code()

Examples

## Data from Husi 2022
loire <- data.frame(
  lower = c(625, 700, 1200, 1225, 1250, 500, 1000, 1200,
            1325, 1375, 1200, 1300, 1375, 1275, 1325),
  upper = c(750, 825, 1250, 1275, 1325, 700, 1300, 1325,
            1400, 1500, 1300, 1375, 1500, 1325, 1425)
)

## Basic relations
allen_relation(loire$lower, loire$upper)

## Complement
(comp <- allen_complement("F")) # "pmoDseSdfOMP"

## Converse
(conv <- allen_converse(comp)) # "pmoFDseSdOMP"

## Composition
allen_composition("oFD", "oFDseS") # "pmoFD"

## Intersection
allen_intersect("pFsSf", "pmoFD") # "pF"

# Union
allen_union("pFsSf", "pmoFD") # "pmoFDsSf"

Coerce to Coda

Description

Extracts parallel chains from an MCMC object to create an mcmc.list object for use with coda diagnostic tools.

Usage

as_coda(from, ...)

## S4 method for signature 'MCMC'
as_coda(from, chains = 1)

Arguments

Value

An coda::mcmc.list object.

Author(s)

A. Philippe, M.-A. Vibet

See Also

coda::mcmc(), coda::mcmc.list()

Other read methods: as_events(), as_phases(), check, read_bcal(), read_chronomodel, read_oxcal()

Examples

if (requireNamespace("coda", quietly = TRUE)) {
  ## Load coda
  library(coda)

  ## Coerce to MCMC
  eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)

  ## Coerce to coda
  mc <- as_coda(eve[, 1:2], chains = 3)
  plot(mc)

  ## Autocorrelation
  autocorr.plot(mc)

  ## Gelman-Rubin diagnostic
  ## The multivariate criterion can not be evaluated when a phase
  ## contains only one date. This induces colinearity problems.
  gelman.diag(mc)
  gelman.plot(mc)
}

Coerce to Events

Description

Coerce to Events

Usage

as_events(from, ...)

## S4 method for signature 'matrix'
as_events(from, calendar, iteration = NULL)

## S4 method for signature 'data.frame'
as_events(from, calendar, iteration = NULL)

Arguments

Value

An EventsMCMC object.

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

See Also

Other read methods: as_coda(), as_phases(), check, read_bcal(), read_chronomodel, read_oxcal()

Examples

## Coerce to events
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)

## Plot first event
plot(eve[, 1], interval = "hdr")

## Colorfull plot
plot(eve, col.density = c("#4477AA", "#EE6677", "#228833", "#CCBB44"))

## Plot events
plot(eve, calendar = CE(), interval = "credible", level = 0.68)
plot(eve, calendar = BP(), interval = "hdr", level = 0.68)

## Plot only 95% credible interval
plot(eve, density = FALSE, interval = "credible", lwd = 3, tcl = 0)

Coerce to Phases

Description

Coerce to Phases

Usage

as_phases(from, ...)

## S4 method for signature 'matrix'
as_phases(
  from,
  calendar = NULL,
  start = seq(from = 1, to = ncol(from), by = 2),
  stop = start + 1,
  names = NULL,
  iteration = NULL
)

## S4 method for signature 'data.frame'
as_phases(
  from,
  calendar,
  start = seq(from = 1, to = ncol(from), by = 2),
  stop = start + 1,
  names = NULL,
  iteration = NULL
)

Arguments

Value

A PhasesMCMC object.

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

See Also

Other read methods: as_coda(), as_events(), check, read_bcal(), read_chronomodel, read_oxcal()

Examples

## Coerce to phases
(pha <- as_phases(mcmc_phases, start = c(1, 3), calendar = CE(), iteration = 1))
summary(pha, calendar = CE())

## Plot phases
plot(pha)
plot(pha, succession = "hiatus")
plot(pha, succession = "transition")

## Compute phases from events
(eve <- as_events(mcmc_events, calendar = CE(), iteration = 1))

## Compute min-max range for all chains
pha1 <- phases(eve)
summary(pha1, calendar = CE())

## Compute min-max range by group
pha2 <- phases(eve, groups = list(phase_1 = c(1, 3), phase_2 = c(2, 4)))
summary(pha2, calendar = CE())


zz <- pha@.Data
head(zz)

head(zz[, 1, ])

head(pha)

Combine two MCMC Objects

Description

Combine two MCMC Objects

Usage

## S4 method for signature 'MCMC,MCMC'
cbind2(x, y)

Arguments

Value

An MCMC object.

Author(s)

N. Frerebeau

See Also

Other mutators: data.frame, names(), sort(), sort.list(), subset()

Examples

## Events
(eve <- as_events(mcmc_events, calendar = CE(), iteration = 1))

eve[1:1000, ] # Select the first 1000 iterations
eve[, 1:2]    # Select the first 2 events

cbind2(eve[, 1:2], eve[, 3:4]) # Combine two MCMC objects
sort(eve, decreasing = TRUE)   # Sort events in descending order

## Phases
(pha <- as_phases(mcmc_phases, start = c(1, 3), calendar = CE(), iteration = 1))

pha[1:1000, , ]          # Select the first 1000 iterations
pha[, 1, , drop = FALSE] # Select the first phase

Phase Time Range

Description

Computes the shortest interval that satisfies P(PhaseMin < IntervalInf < IntervalSup < PhaseMax | M) = level for each phase.

Usage

boundaries(x, y, ...)

## S4 method for signature 'numeric,numeric'
boundaries(x, y, level = 0.95)

## S4 method for signature 'PhasesMCMC,missing'
boundaries(x, level = 0.95)

Arguments

Value

The endpoints of the shortest time range (at a given level).

Methods (by class)

• boundaries(x = numeric, y = numeric): Returns a length-two numeric vector (terminal times).

• boundaries(x = PhasesMCMC, y = missing): Returns a TimeRange object.

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

See Also

Other time ranges: hiatus(), transition()

Examples

## Coerce to events
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Compute min-max range by group
pha <- phases(eve, groups = list(A = c(1, 3), B = c(2, 4)))

## Compute phase ranges
bou <- boundaries(pha)
as.data.frame(bou)

## Compute phase transition
tra <- transition(pha)
as.data.frame(tra)

## Compute phase hiatus
hia <- hiatus(pha)
as.data.frame(hia)

Age-Depth Modeling

Description

Computes the age-depth curve from the output of the MCMC algorithm and the known depth of each dated samples.

Usage

bury(object, depth, ...)

## S4 method for signature 'EventsMCMC,numeric'
bury(object, depth)

## S4 method for signature 'AgeDepthModel'
predict(object, newdata)

## S4 method for signature 'AgeDepthModel,missing'
plot(
  x,
  level = 0.95,
  calendar = getOption("ArchaeoPhases.calendar"),
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

Details

We assume it exists a function f relating the age and the depth age = f(depth). We estimate the function using local regression (also called local polynomial regression): f = loess(age ~ depth). This estimated function f depends on the unknown dates. However, from the posterior distribution of the age/date sequence, we can evaluate the posterior distribution of the age function for each desired depth.

Value

• bury() returns an AgeDepthModel object.

• predict() returns an EventsMCMC object.

• plot() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

A. Philippe

References

Jha, D. K., Sanyal, P. & Philippe, A. (2020). Multi-Proxy Evidence of Late Quaternary Climate and Vegetational History of North-Central India: Implication for the Paleolithic to Neolithic Phases. Quaternary Science Reviews, 229: 106121. doi:10.1016/j.quascirev.2019.106121.

Ghosh, S., Sanyal, P., Roy, S., Bhushan, R., Sati, S. P., Philippe, A. & Juyal, N. (2020). Early Holocene Indian Summer Monsoon and Its Impact on Vegetation in the Central Himalaya: Insight from dD and d13C Values of Leaf Wax Lipid. The Holocene, 30(7): 1063-1074. doi:10.1177/0959683620908639.

See Also

Other age-depth modeling tools: interpolate()

Examples

## Coerce to MCMC
eve <- matrix(rnorm(6000, (1:6)^2), ncol = 6, byrow = TRUE)
eve <- as_events(eve, calendar = CE())

## Compute an age-depth curve
age <- bury(eve, depth = 1:6)
plot(age)

## Predict new values
new <- predict(age, newdata = 1.5:5.5)
summary(new)

plot(eve)
plot(new)

Check for an Original MCMC File

Description

Checks whether or not a file is identical to the one used to create an object.

Usage

is_original(object, ...)

## S4 method for signature 'MCMC'
is_original(object, file, download = FALSE)

## S4 method for signature 'PhasesMCMC'
is_original(object, file, download = FALSE)

## S4 method for signature 'CumulativeEvents'
is_original(object, file, download = FALSE)

## S4 method for signature 'ActivityEvents'
is_original(object, file, download = FALSE)

## S4 method for signature 'OccurrenceEvents'
is_original(object, file, download = FALSE)

Arguments

Value

A logical: TRUE if the files match, FALSE otherwise.

Author(s)

T. S. Dye, N. Frerebeau

See Also

digest::digest()

Other read methods: as_coda(), as_events(), as_phases(), read_bcal(), read_chronomodel, read_oxcal()

Examples

## Not run: 
## Import OxCal Output
path_output <- system.file("oxcal/ksarakil/MCMC_Sample.csv", package = "ArchaeoData")
url_output <- paste0("https://raw.githubusercontent.com/ArchaeoStat/ArchaeoData/master/",
                     "inst/oxcal/ksarakil/MCMC_Sample.csv")

oxcal <- read_oxcal(path_output)

## Check md5 sum
is_original(oxcal, path_output) # Same as local file? TRUE
is_original(oxcal, url_output, download = FALSE) # Same as remote file? FALSE
is_original(oxcal, url_output, download = TRUE) # Same as remote file? TRUE

## End(Not run)

Coerce to a Data Frame

Description

Coerce to a Data Frame

Usage

## S4 method for signature 'CumulativeEvents'
as.data.frame(x, ..., calendar = getOption("ArchaeoPhases.calendar"))

## S4 method for signature 'ActivityEvents'
as.data.frame(x, ..., calendar = getOption("ArchaeoPhases.calendar"))

## S4 method for signature 'OccurrenceEvents'
as.data.frame(x, ..., calendar = getOption("ArchaeoPhases.calendar"))

## S4 method for signature 'TimeRange'
as.data.frame(x, ..., calendar = getOption("ArchaeoPhases.calendar"))

Arguments

Value

A data.frame with an extra time column giving the (decimal) years at which the time series was sampled.

Author(s)

N. Frerebeau

See Also

Other mutators: bind, names(), sort(), sort.list(), subset()

Phase Duration

Description

Phase Duration

Usage

duration(x, y, ...)

## S4 method for signature 'numeric,numeric'
duration(x, y)

## S4 method for signature 'PhasesMCMC,missing'
duration(x)

Arguments

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

See Also

Other phase tools: phases()

Examples

## Coerce to phases
pha <- as_phases(mcmc_phases, start = c(1, 3), calendar = CE(), iteration = 1)

## Compute phase duration
dur <- duration(pha)
summary(dur)

Elapsed Time Scale

Description

Elapsed Time Scale

Usage

elapse(object, ...)

## S4 method for signature 'MCMC'
elapse(object, origin = 1)

Arguments

Value

Returns an object of the same class as object with an elapsed

An object of the same sort as object with a new time scale.

Note

There is no year 0 in BCE/CE scale.

Author(s)

N. Frerebeau

See Also

Other event tools: activity(), occurrence(), tempo()

Examples

## Coerce to events
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)

## Elapsed origin
eve_elapse <- elapse(eve, origin = 4)
plot(eve_elapse)

Hiatus Between Two Dates

Description

Tests for the existence of a hiatus between two parameters.

Usage

hiatus(x, y, ...)

## S4 method for signature 'numeric,numeric'
hiatus(x, y, level = 0.95)

## S4 method for signature 'EventsMCMC,missing'
hiatus(x, level = 0.95)

## S4 method for signature 'PhasesMCMC,missing'
hiatus(x, level = 0.95)

Arguments

Details

Finds if a gap exists between two dates and returns the longest interval that satisfies P(x < HiatusInf < HiatusSup < y | M) = level

The hiatus between two successive phases is the longest interval that satisfies P(Phase1Max < IntervalInf < IntervalSup < Phase2Min | M) = level (this assumes that the phases are in temporal order constraint).

Value

The endpoints of the hiatus between successive events/phases (at a given level).

Methods (by class)

• hiatus(x = numeric, y = numeric): Returns a length-three numeric vector (terminal times and hiatus duration, if any).

• hiatus(x = EventsMCMC, y = missing): Returns a TimeRange object.

• hiatus(x = PhasesMCMC, y = missing): Returns a TimeRange object.

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

See Also

Other time ranges: boundaries(), transition()

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Test for anteriority
older(eve)

## Test for hiatus
hia <- hiatus(eve)
as.data.frame(hia)

Interpolate Between Two Dates

Description

Interpolate Between Two Dates

Usage

interpolate(x, y, ...)

## S4 method for signature 'numeric,numeric'
interpolate(x, y)

## S4 method for signature 'EventsMCMC,missing'
interpolate(x, e1 = 1, e2 = 2)

Arguments

Details

For a given output of MCMC algorithm, this function interpolates between to events x and y (assuming x < y).

Author(s)

N. Frerebeau

See Also

Other age-depth modeling tools: bury()

Examples

## Coerce to events
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Interpolate between two events
inter <- interpolate(eve, e1 = 2, e2 = 3)
plot(inter, level = 0.95, interval = "credible")

Bayesian Credible Interval

Description

Computes the shortest credible interval of the output of the MCMC algorithm for a single parameter.

Usage

interval_credible(x, ...)

## S4 method for signature 'MCMC'
interval_credible(
  x,
  level = 0.95,
  calendar = getOption("ArchaeoPhases.calendar")
)

Arguments

Details

A (100 \times level) % credible interval is an interval that keeps N \times (1 - level) elements of the sample outside the interval.

The (100 \times level) % credible interval is the shortest of all those intervals.

For instance, the 95% credible interval is the central portion of the posterior distribution that contains 95% of the values.

Value

Returns a list of numeric matrix.

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

See Also

arkhe::interval_credible()

Other statistics: interval_hdr(), sensitivity(), summary()

Examples

## Coerce to events
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Rata die
interval_credible(eve, level = 0.95) # Credible interval
interval_hdr(eve, level = 0.68) # HPD interval

## BP
interval_credible(eve, level = 0.95, calendar = BP()) # Credible interval
interval_hdr(eve, level = 0.95, calendar = BP()) # HPD interval

Bayesian HPD Regions

Description

Bayesian HPD Regions

Usage

interval_hdr(x, y, ...)

## S4 method for signature 'MCMC,missing'
interval_hdr(
  x,
  level = 0.95,
  calendar = getOption("ArchaeoPhases.calendar"),
  ...
)

Arguments

Value

Returns a list of numeric matrix.

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

References

Hyndman, R. J. (1996). Computing and graphing highest density regions. American Statistician, 50: 120-126. doi:10.2307/2684423.

See Also

stats::density(), arkhe::interval_hdr()

Other statistics: interval_credible(), sensitivity(), summary()

Examples

## Coerce to events
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Rata die
interval_credible(eve, level = 0.95) # Credible interval
interval_hdr(eve, level = 0.68) # HPD interval

## BP
interval_credible(eve, level = 0.95, calendar = BP()) # Credible interval
interval_hdr(eve, level = 0.95, calendar = BP()) # HPD interval

Events

Description

A data set containing information on the ages of four dated events.

Usage

mcmc_events

Format

A data.frame with 30,000 rows and 5 variables:

iter

Iteration of the MCMC algorithm.

E1

Information on event 1.

E2

Information on event 2.

E3

Information on event 3.

E4

Information on event 4.

See Also

Other datasets: mcmc_phases

Phases

Description

A data set containing information on the start and end dates of two phases.

Usage

mcmc_phases

Format

A data.frame with 30,000 rows and 5 variables:

iter

Iteration of the MCMC algorithm.

P2_alpha

Start date of Phase 2.

P2_beta

End date of Phase 2.

P1_alpha

Start date of Phase 1.

P1_beta

End date of Phase 1.

See Also

Other datasets: mcmc_events

The Names of an Object

Description

Get or set the names of an object.

Usage

## S4 method for signature 'MCMC'
names(x)

## S4 replacement method for signature 'MCMC'
names(x) <- value

## S4 method for signature 'PhasesMCMC'
names(x)

## S4 replacement method for signature 'PhasesMCMC'
names(x) <- value

Arguments

Value

An object of the same sort as x with the new names assigned.

Author(s)

N. Frerebeau

See Also

Other mutators: bind, data.frame, sort(), sort.list(), subset()

Occurrence Plot

Description

A statistical graphic designed for the archaeological study of when events of a specified kind occurred.

Usage

occurrence(object, ...)

## S4 method for signature 'EventsMCMC'
occurrence(object, level = 0.95)

## S4 method for signature 'OccurrenceEvents,missing'
plot(
  x,
  calendar = getOption("ArchaeoPhases.calendar"),
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

Arguments

Details

If we have k events, then we can estimate the calendar date t corresponding to the smallest date such that the number of events observed before t is equal to k.

The occurrence() estimates these occurrences and gives the credible interval or the highest posterior density (HPD) region for a given level of confidence.

Value

• occurrence() returns an OccurrenceEvents object.

• plot() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

An OccurrenceEvents object.

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

See Also

Other event tools: activity(), elapse(), tempo()

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Occurrence plot
occ <- occurrence(eve)
plot(occ, panel.first = graphics::grid())

Bayesian Test for Anteriority/Posteriority

Description

A Bayesian test for checking the following assumption: "event x is older than event y".

Usage

older(x, y, ...)

## S4 method for signature 'numeric,numeric'
older(x, y)

## S4 method for signature 'EventsMCMC,missing'
older(x, y)

Arguments

Details

For a given output of MCMC algorithm, this function estimates the posterior probability of the event x < y by the relative frequency of the event "the value of event x is less than the value of event y" in the simulated Markov chain.

Methods (by class)

• older(x = numeric, y = numeric): Returns a length-one numeric vector (the posterior probability of the assumption: "event x is older than event y").

• older(x = EventsMCMC, y = missing): Returns a numeric matrix of posterior probabilities.

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Test for anteriority
older(eve)

## Test for hiatus
hia <- hiatus(eve)
as.data.frame(hia)

Compute Phases

Description

Constructs the minimum and maximum for a group of events (phase).

Usage

phases(x, groups, ...)

## S4 method for signature 'EventsMCMC,missing'
phases(x)

## S4 method for signature 'EventsMCMC,list'
phases(x, groups)

Arguments

Value

A PhasesMCMC object.

Note

The default value of start or end corresponds to a CSV file exported from ChronoModel.

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

See Also

Other phase tools: duration()

Examples

## Coerce to phases
(pha <- as_phases(mcmc_phases, start = c(1, 3), calendar = CE(), iteration = 1))
summary(pha, calendar = CE())

## Plot phases
plot(pha)
plot(pha, succession = "hiatus")
plot(pha, succession = "transition")

## Compute phases from events
(eve <- as_events(mcmc_events, calendar = CE(), iteration = 1))

## Compute min-max range for all chains
pha1 <- phases(eve)
summary(pha1, calendar = CE())

## Compute min-max range by group
pha2 <- phases(eve, groups = list(phase_1 = c(1, 3), phase_2 = c(2, 4)))
summary(pha2, calendar = CE())


zz <- pha@.Data
head(zz)

head(zz[, 1, ])

head(pha)

Plot Events

Description

Plots credible intervals or HPD regions of a series of events.

Usage

## S4 method for signature 'MCMC,missing'
plot(
  x,
  calendar = getOption("ArchaeoPhases.calendar"),
  density = TRUE,
  interval = NULL,
  level = 0.95,
  sort = TRUE,
  decreasing = TRUE,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = FALSE,
  panel.first = NULL,
  panel.last = NULL,
  col.density = "grey",
  col.interval = "#77AADD",
  ...
)

Arguments

Value

plot() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

See Also

stats::density()

Other plot methods: plot_phases

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)

## Summary
summary(eve, calendar = CE())
summary(eve, calendar = BP())

## Plot events
plot(eve, calendar = CE(), interval = "credible", level = 0.68)
plot(eve, calendar = BP(), interval = "hdr", level = 0.68)
plot(eve[, 1], interval = "hdr")

## Compute phases
pha <- phases(eve, groups = list(B = c(2, 4), A = c(1, 3)))

## Summary
summary(pha, calendar = CE())
summary(pha, calendar = BP())

## Plot phases
plot(pha, calendar = BP())
plot(pha, succession = "hiatus")
plot(pha, succession = "transition")

Plot Phases

Description

Plots the characteristics of a group of events (phase).

Usage

## S4 method for signature 'PhasesMCMC,missing'
plot(
  x,
  calendar = getOption("ArchaeoPhases.calendar"),
  density = TRUE,
  range = TRUE,
  succession = NULL,
  level = 0.95,
  sort = TRUE,
  decreasing = TRUE,
  legend = TRUE,
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = FALSE,
  panel.first = NULL,
  panel.last = NULL,
  col.density = "grey",
  col.range = "black",
  col.succession = c("#77AADD", "#EE8866"),
  ...
)

Arguments

Value

plot() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

See Also

stats::density()

Other plot methods: plot_events

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)

## Summary
summary(eve, calendar = CE())
summary(eve, calendar = BP())

## Plot events
plot(eve, calendar = CE(), interval = "credible", level = 0.68)
plot(eve, calendar = BP(), interval = "hdr", level = 0.68)
plot(eve[, 1], interval = "hdr")

## Compute phases
pha <- phases(eve, groups = list(B = c(2, 4), A = c(1, 3)))

## Summary
summary(pha, calendar = CE())
summary(pha, calendar = BP())

## Plot phases
plot(pha, calendar = BP())
plot(pha, succession = "hiatus")
plot(pha, succession = "transition")

Read BCal Output

Description

Reads MCMC output.

Usage

read_bcal(file, ...)

## S4 method for signature 'character'
read_bcal(file, bin_width = 1, calendar = BP())

Arguments

Value

An EventsMCMC object.

Author(s)

T. S. Dye, N. Frerebeau

References

Buck C. E., Christen J. A. & James G. N. (1999). BCal: an on-line Bayesian radiocarbon calibration tool. Internet Archaeology, 7. doi:10.11141/ia.7.1.

See Also

utils::read.table()

Other read methods: as_coda(), as_events(), as_phases(), check, read_chronomodel, read_oxcal()

Examples

if (requireNamespace("ArchaeoData", quietly = TRUE)) {
  ## Import BCal Output
  path_output <- system.file("bcal/fishpond.csv", package = "ArchaeoData")
  (bcal <- read_bcal(path_output))
}

Read ChronoModel Output

Description

Reads MCMC output.

Usage

read_chronomodel_events(file, ...)

read_chronomodel_phases(file, ...)

## S4 method for signature 'character'
read_chronomodel_events(file, calendar = CE(), sep = ",", dec = ".")

## S4 method for signature 'character'
read_chronomodel_phases(file, calendar = CE(), sep = ",", dec = ".")

Arguments

Value

An EventsMCMC or a PhasesMCMC object.

Author(s)

T. S. Dye, N. Frerebeau

References

Lanos, Ph., Philippe, A. & Dufresne, Ph. (2015). Chronomodel: Chronological Modeling of Archaeological Data using Bayesian Statistics. URL: https://chronomodel.com/.

See Also

utils::read.table()

Other read methods: as_coda(), as_events(), as_phases(), check, read_bcal(), read_oxcal()

Examples

if (requireNamespace("ArchaeoData", quietly = TRUE)) {
  ## Import ChronoModel Output
  path <- "chronomodel/ksarakil"

  ## Events
  path_events <- system.file(path, "Chain_all_Events.csv", package = "ArchaeoData")
  (chrono_events <- read_chronomodel_events(path_events))

  ## Phases
  path_phases <- system.file(path, "Chain_all_Phases.csv", package = "ArchaeoData")
  (chrono_phases <- read_chronomodel_phases(path_phases))
}

Read OxCal Output

Description

Reads MCMC output.

Usage

read_oxcal(file, ...)

## S4 method for signature 'character'
read_oxcal(file, calendar = CE())

Arguments

Value

An EventsMCMC object.

Author(s)

T. S. Dye, N. Frerebeau

References

Bronk Ramsey, C. (2009). Bayesian Analysis of Radiocarbon Dates. Radiocarbon, 51(1), 337-360. doi:10.1017/S0033822200033865.

See Also

utils::read.table()

Other read methods: as_coda(), as_events(), as_phases(), check, read_bcal(), read_chronomodel

Examples

if (requireNamespace("ArchaeoData", quietly = TRUE)) {
  ## Import OxCal Output
  path <- "oxcal/ksarakil/"

  path_output <- system.file(path, "MCMC_Sample.csv", package = "ArchaeoData")
  (oxcal <- read_oxcal(path_output))
}

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

aion

AD, BC, BCE, BP, CE, b2k, calendar, start, start, time, year_axis

Sensitivity

Description

Calculates the ranges of summary statistics from the output of two or more runs of the MCMC algorithm.

Usage

sensitivity(...)

## S4 method for signature 'EventsMCMC'
sensitivity(..., positions = NULL, level = 0.95)

Arguments

Details

This function is useful for estimating the sensitivity of calibration results to different model parameters.

Value

A data.frame.

Author(s)

T. S. Dye, N. Frerebeau

See Also

summary()

Other statistics: interval_credible(), interval_hdr(), summary()

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)

## Returns 0's
sensitivity(eve, eve)

Sort an MCMC Object

Description

Sort (or order) an object into ascending or descending temporal order.

Usage

## S4 method for signature 'MCMC'
sort(x, decreasing = FALSE)

## S4 method for signature 'PhasesMCMC'
sort(x, decreasing = FALSE)

Arguments

Value

An object of the same sort as x.

Author(s)

N. Frerebeau

See Also

Other mutators: bind, data.frame, names(), sort.list(), subset()

Examples

## Events
(eve <- as_events(mcmc_events, calendar = CE(), iteration = 1))

eve[1:1000, ] # Select the first 1000 iterations
eve[, 1:2]    # Select the first 2 events

cbind2(eve[, 1:2], eve[, 3:4]) # Combine two MCMC objects
sort(eve, decreasing = TRUE)   # Sort events in descending order

## Phases
(pha <- as_phases(mcmc_phases, start = c(1, 3), calendar = CE(), iteration = 1))

pha[1:1000, , ]          # Select the first 1000 iterations
pha[, 1, , drop = FALSE] # Select the first phase

Ordering Permutation of an MCMC Object

Description

Returns a permutation which rearranges an object into ascending or descending temporal order.

Usage

## S4 method for signature 'MCMC'
sort.list(x, decreasing = FALSE)

## S4 method for signature 'PhasesMCMC'
sort.list(x, decreasing = FALSE)

Arguments

Value

An integer vector.

Author(s)

N. Frerebeau

See Also

Other mutators: bind, data.frame, names(), sort(), subset()

Examples

## Events
(eve <- as_events(mcmc_events, calendar = CE(), iteration = 1))

eve[1:1000, ] # Select the first 1000 iterations
eve[, 1:2]    # Select the first 2 events

cbind2(eve[, 1:2], eve[, 3:4]) # Combine two MCMC objects
sort(eve, decreasing = TRUE)   # Sort events in descending order

## Phases
(pha <- as_phases(mcmc_phases, start = c(1, 3), calendar = CE(), iteration = 1))

pha[1:1000, , ]          # Select the first 1000 iterations
pha[, 1, , drop = FALSE] # Select the first phase

Extract or Replace Parts of an Object

Description

Operators acting on objects to extract or replace parts.

Usage

## S4 method for signature 'MCMC'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'PhasesMCMC'
x[i, j, k, drop = FALSE]

Arguments

Value

A subsetted object.

Author(s)

N. Frerebeau

See Also

Other mutators: bind, data.frame, names(), sort(), sort.list()

Examples

## Events
(eve <- as_events(mcmc_events, calendar = CE(), iteration = 1))

eve[1:1000, ] # Select the first 1000 iterations
eve[, 1:2]    # Select the first 2 events

cbind2(eve[, 1:2], eve[, 3:4]) # Combine two MCMC objects
sort(eve, decreasing = TRUE)   # Sort events in descending order

## Phases
(pha <- as_phases(mcmc_phases, start = c(1, 3), calendar = CE(), iteration = 1))

pha[1:1000, , ]          # Select the first 1000 iterations
pha[, 1, , drop = FALSE] # Select the first phase

Marginal Summary Statistics for Multiple MCMC Chains

Description

Calculates summary statistics of the output of the MCMC algorithm for multiple parameters. Results are given in calendar years (BC/AD).

Usage

## S4 method for signature 'MCMC'
summary(object, level = 0.95, calendar = getOption("ArchaeoPhases.calendar"))

## S4 method for signature 'PhasesMCMC'
summary(object, level = 0.95, calendar = getOption("ArchaeoPhases.calendar"))

Arguments

Value

A data.frame where the rows correspond to the chains of interest and columns to the following statistics:

mean

The mean of the MCMC chain.

sd

The standard deviation of the MCMC chain.

min

Minimum value of the MCMC chain.

q1

First quantile of the MCMC chain.

median

Median of the MCMC chain.

q3

Third quantile of the MCMC chain.

max

Maximum value of the MCMC chain.

lower

Lower boundary of the credible interval of the MCMC chain at level.

upper

Upper boundary of the credible interval of the MCMC chain at level.

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

See Also

Other statistics: interval_credible(), interval_hdr(), sensitivity()

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)

## Summary
summary(eve, calendar = CE())
summary(eve, calendar = BP())

## Plot events
plot(eve, calendar = CE(), interval = "credible", level = 0.68)
plot(eve, calendar = BP(), interval = "hdr", level = 0.68)
plot(eve[, 1], interval = "hdr")

## Compute phases
pha <- phases(eve, groups = list(B = c(2, 4), A = c(1, 3)))

## Summary
summary(pha, calendar = CE())
summary(pha, calendar = BP())

## Plot phases
plot(pha, calendar = BP())
plot(pha, succession = "hiatus")
plot(pha, succession = "transition")

Tempo Plot

Description

A statistical graphic designed for the archaeological study of rhythms of the long term that embodies a theory of archaeological evidence for the occurrence of events.

Usage

tempo(object, ...)

## S4 method for signature 'CumulativeEvents,missing'
plot(
  x,
  calendar = getOption("ArchaeoPhases.calendar"),
  interval = c("credible", "gauss"),
  col.tempo = "#004488",
  col.interval = "grey",
  main = NULL,
  sub = NULL,
  ann = graphics::par("ann"),
  axes = TRUE,
  frame.plot = axes,
  panel.first = NULL,
  panel.last = NULL,
  ...
)

## S4 method for signature 'EventsMCMC'
tempo(
  object,
  level = 0.95,
  count = FALSE,
  credible = TRUE,
  gauss = TRUE,
  from = min(object),
  to = max(object),
  grid = getOption("ArchaeoPhases.grid")
)

Arguments

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.

Value

• tempo() returns an CumulativeEvents object.

• plot() is called it for its side-effects: it results in a graphic being displayed (invisibly returns x).

Author(s)

A. Philippe, M.-A. Vibet, T. S. Dye, N. Frerebeau

References

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.

See Also

Other event tools: activity(), elapse(), occurrence()

Examples

## Coerce to MCMC
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Tempo plot
tmp <- tempo(eve)
plot(tmp)
plot(tmp, interval = "credible", panel.first = grid())
plot(tmp, interval = "gauss", panel.first = grid())

## Activity plot
act <- activity(tmp)
plot(act, panel.first = grid())

Transition Range Between Successive Phases

Description

Estimates the transition endpoints between two phases.

Usage

transition(x, y, ...)

## S4 method for signature 'numeric,numeric'
transition(x, y, level = 0.95)

## S4 method for signature 'PhasesMCMC,missing'
transition(x, level = 0.95)

Arguments

Details

The transition is the shortest interval that satisfies P(IntervalInf < Phase1Max < Phase2Min < IntervalSup | M) = level.

This assumes that the phases are in temporal order constraint.

Value

The endpoints of the transition interval for each pair of successive phases (at a given level).

Methods (by class)

• transition(x = numeric, y = numeric): Returns a length-two numeric vector (terminal times of the transition interval).

• transition(x = PhasesMCMC, y = missing): Returns a TimeRange object.

Author(s)

A. Philippe, M.-A. Vibet, N. Frerebeau

See Also

Other time ranges: boundaries(), hiatus()

Examples

## Coerce to events
eve <- as_events(mcmc_events, calendar = CE(), iteration = 1)
eve <- eve[1:10000, ]

## Compute min-max range by group
pha <- phases(eve, groups = list(A = c(1, 3), B = c(2, 4)))

## Compute phase ranges
bou <- boundaries(pha)
as.data.frame(bou)

## Compute phase transition
tra <- transition(pha)
as.data.frame(tra)

## Compute phase hiatus
hia <- hiatus(pha)
as.data.frame(hia)