prob.phases.relat: R function to calculate the Posterior Probability for...

View source: R/prob_phases_relat.R

prob.phases.relatR Documentation

R function to calculate the Posterior Probability for different chronological relations between two Bayesian radiocarbon phases

Description

The function allows to calculate the posterior probability for different chronological relations between two phases defined via Bayesian radiocarbon modeling. For the results to make sense, the phases have to be defined as independent if one wishes to assess what is the posterior probability for different relative chronological relations between them.

Usage

prob.phases.relat(
  data = NULL,
  sAoldersB = NULL,
  sAoldereB = NULL,
  eAoldersB = NULL,
  eAoldereB = NULL,
  sBoldersA = NULL,
  sBoldereA = NULL,
  eBoldersA = NULL,
  eBoldereA = NULL,
  sort = FALSE
)

Arguments

data

Matrix containing the posterior probability of the chronological relation between the Starting and Ending boundaries of two independent phases, as returned by the OxCal's 'Order' query (see Details).

sAoldersB

Probability of startA being older than startB.

sAoldereB

Probability of startA being older than endB.

eAoldersB

Probability of endA being older than startB.

eAoldereB

Probability of endA being older than endB.

sBoldersA

Probability of startB being older than startA.

sBoldereA

Probability of startB being older than endA.

eBoldersA

Probability of endB being older than startA.

eBoldereA

Probability of endB being older than endA.

sort

logical which takes TRUE or FALSE (default) if the user does or does not want the returned posterior probabilities sorted in descending order.

Details

The rationale for this approach is made clear in an article by Buck et al 1992 (https://doi.org/10.1016/0305-4403(92)90025-X), and it runs as follows: "if we do not make any assumption about the relationship between the phases, can we test how likely they are to be in any given order"?

Data can be fed into the function in two ways:

-the function takes as input the table provided by the 'OxCal' program as result of the 'Order' query.
Once the table as been saved from 'OxCal' in .csv format, you have to feed it in R. A .csv file can be imported into R using (for instance): mydata <- read.table(file.choose(), header=TRUE, sep=",", dec=".", as.is=T);

be sure to insert the phases' parameters (i.e., the starting and ending boundaries of the two phases) in the OxCal's Order query in the following order: StartA, EndA, StartB, EndB; that is, first the start and end of your first phase, then the start and end of the second one; you can give any name to your phases, as long as the order is like the one described.

-alternatively, 8 relevant parameters (which can be read off from the Oxcal's Order query output) can be manually fed into the function (see the Arguments section above).

Given two phases A and B, the function allows to calculate the posterior probability for:

-A being within B
-B being within A
-A starting earlier but overlapping with B
-B starting earlier but overlapping with A
-A being entirely before B
-B being entirely before A
-sA being within B
-eA being within B
-sB being within A
-eB being within A
where 's' and 'e' refer to the starting and ending boundaries of a phase.

The function will return a table and a dot plot.

Thanks are due to Dr. Andrew Millard (Durham University) for the help provided in working out the operations on probabilities.

Examples

#load a toy dataset
data(phases)

 #calculate the Posterior Probability for the chronological relation between two phases,
 # stores the results in the 'res' object, and produce a dot chart.
res <- prob.phases.relat(phases)

# same as above, but manually feeding relevant parameters
res <- prob.phases.relat(data=NULL, sAoldersB=0.613, sAoldereB=1, eAoldersB=0.0010,
eAoldereB=0.666, sBoldersA= 0.386, sBoldereA=0.999, eBoldersA=0.000039, eBoldereA=0.3334)


GmAMisc documentation built on March 18, 2022, 6:32 p.m.