README/paper.md

Author: scollinselliott

README.Rmd

@@ -19,7 +19,7 @@ knitr::opts_chunk$set(
 <!-- badges: start -->
 <!-- badges: end -->
 
-The `R` package `eratosthenes` aims to provide a general, flexible toolkit for archaeological chronology-building by incorporating, computationally, all relevant sources of information on uncertain archaeological or historical dates. Archaeological dates are subject to relational conditions (via seriation or stratigraphic relationships) and absolute constraints (such as radiocarbon dates, datable artifacts, or other known historical events, as _termini post_ or _ante quos_), which prompt the use of a joint conditional probability density to convey those relationships. The date of any one event can then be marginalized from that full, joint conditional distribution.
+The `R` package `eratosthenes` aims to provide a general, flexible toolkit for archaeological chronology-building by incorporating, computationally, all relevant sources of information on uncertain archaeological or historical dates. Archaeological dates are subject to relational conditions (via seriation or stratigraphic relationships) and absolute constraints (such as radiocarbon dates, datable artifacts, or other known historical events, as _termini post_ or _ante quos_), which prompt the use of a joint conditional probability density to convey those relationships. The date of any one event can then be marginalized from that full, joint conditional distribution. `Rcpp` is used for faster sampling [@eddelbuettel_extending_2018].
 
 While software exists for calibrating and conditioning radiocarbon dates upon relative constraints, such as `OxCal` [@bronk_ramsey_bayesian_2009] and `BCal` [@buck_bcal_1999], as well as R packages `oxcAAR` [@hinz_oxcaar_2021], `Bchron` [@haslett_simple_2008], and `rcarbon` [@crema_spatio-temporal_2017], along with software for general chronological modeling like `Chronomodel` [@lanos_hierarchical_2017] and `ChronoLog` [@levy_chronological_2021], formal methods for dating artifacts and artifact types are lacking. One of the major goals of  `eratosthenes` is to advance the synchronism of chronologies and the crafting of large-scale chronological models that rely heavily upon artifact typologies. The package therefore facilitates the marginalization of dates of a type's production, use, and deposition. The method of sampling employed in `eratosthenes` involves a two-step process of Gibbs sampling, using consistent batch means (CBM) and Monte Carlo standard errors (MCSE) to determine convergence [@jones_fixed-width_2006; @flegal_markov_2008]. Finaly, `eratosthenes` provides tools for analyzing the impact of events on each other with the conditional structure stipulated by the investigator, by implementing a jackknife-style estimator of squared displacement (how much the date of one event shifts when another is omitted). Ancillary functions include checking for discrepancies in sequences of events and constraining optimal seriations to known sequences. 
 

README.md

@@ -15,7 +15,8 @@ absolute constraints (such as radiocarbon dates, datable artifacts, or
 other known historical events, as *termini post* or *ante quos*), which
 prompt the use of a joint conditional probability density to convey
 those relationships. The date of any one event can then be marginalized
-from that full, joint conditional distribution.
+from that full, joint conditional distribution. `Rcpp` is used for
+faster sampling (Eddelbuettel and Balamuta 2018).
 
 While software exists for calibrating and conditioning radiocarbon dates
 upon relative constraints, such as `OxCal` (Bronk Ramsey 2009) and
@@ -556,6 +557,14 @@ Archaeological Science* 87: 1–9.
 
 </div>
 
+<div id="ref-eddelbuettel_extending_2018" class="csl-entry">
+
+Eddelbuettel, D., and J. J. Balamuta. 2018. “Extending R with C++: A
+Brief Introduction to Rcpp.” *The American Statistician* 72: 28–36.
+<https://doi.org/10.1080/00031305.2017.1375990>.
+
+</div>
+
 <div id="ref-flegal_markov_2008" class="csl-entry">
 
 Flegal, J. M., M. Haran, and G. L. Jones. 2008. “Markov Chain Monte

inst/REFERENCES.bib

@@ -298,4 +298,15 @@ @book{lancel_byrsa_1982
 	publisher = {École française de Rome},
 	author = {Lancel, S. and Morel, J.-P. and Thuillier, J.-P.},
 	year = {1982},
+}
+
+
+@article{eddelbuettel_extending_2018,
+	title = {Extending {R} with {C}++: {A} {Brief} {Introduction} to {Rcpp}},
+	volume = {72},
+	doi = {10.1080/00031305.2017.1375990},
+	journal = {The American Statistician},
+	author = {Eddelbuettel, D. and Balamuta, J.J.},
+	year = {2018},
+	pages = {28--36},
 }

paper/paper.md

@@ -19,9 +19,9 @@ bibliography: ../inst/REFERENCES.bib
 
 # Summary
 
-Archaeological chronology-building centers on two types of dates, absolute and relative. Absolute dates are associated with a calendrical date (even approximate), and relative refer to events only known via relationships to others (before/after). Relative events are then associated to absolute via contextual or logical associations. E.g, a _terminus post quem_ (_t.p.q._) of a datable coin found in a soil deposit ensures the deposit came after the production of the coin. Applying probabilistic methods to chronology has traditionally centered on radiocarbon dating, but the broader goal of extending formal methods to all aspects of chronology necessitate a way to address artifact typologies. Artifacts largely persist in being dated by qualitative judgment (e.g, "around the start of the 4th century BCE"). Moreover, typologies are in a constant state of revision and adjustment, such that the dates of types may differ according to authority. The reasons why a type is dated the way it is (i.e., which sites, deposits, and comparisons inform its date) can also become opaque, such that investigators inherently resist chronological revisions in order to assess its bibliography (on this conservatism, see @rotroff_four_2005[20]). This situation presents a challenge for any researcher applying statistical methods to archaeological chronologies with artifacts, as one must make _ad hoc_ and often awkward decisions about dates of types, resulting in what @lavan_checklist_2021[15] called "abonimable dates."
+Archaeological chronology-building centers on two types of dates, absolute and relative. Absolute dates are associated with a calendrical date (even approximate), and relative refer to events only known via relationships to others (before/after). Relative events are then associated to absolute via contextual or logical associations. E.g, a _terminus post quem_ (_t.p.q._) of a datable coin found in a soil deposit ensures the deposit came after the production of the coin. Applying probabilistic methods to chronology has traditionally centered on radiocarbon dating, but the broader goal of extending formal methods to all aspects of chronology necessitate a way to address artifact typologies. Artifacts largely persist in being dated by qualitative judgment (e.g, "around the start of the 4th century BCE"). Moreover, typologies are in a constant state of revision and adjustment, such that the dates of types may differ according to authority. The reasons why a type is dated the way it is (i.e., which sites, deposits, and comparisons inform its date) can also become opaque, such that investigators inherently resist chronological revisions in order to assess its bibliography (on this conservatism, see @rotroff_four_2005[20]). This situation presents a challenge for any researcher applying statistical methods to datable artifacts, as one must make _ad hoc_ and often awkward decisions, resulting in what @lavan_checklist_2021[15] has called "abonimable dates."
 
-The `R` package `eratosthenes` (named after Eratosthenes of Cyrene, author of the _Chronographiai_) provides functions for chronology-building, above all to bring artifact dating within the scope of formal mathematical estimation. Hence, an investigator can obtain separate probability density functions (p.d.f.) for the production, use, and deposition of an artifact type, in addition to marginal p.d.f.s for all relative sequential events (howsover determined) and absolute constraints (howsoever defined). It uses Gibbs sampling, by now a conventional Markov Chain Monte Carlo method in archaeological chronology [@geman_stochastic_1984; @buck_bayesian_1996]. Here, `eratosthenes` performs a two-step Gibbs routine, the first a preliminiary sampler to select a starting date, and a second main sampler that uses consistent batch means (CBM) as a stopping rule, given that convergence in distribution is assured [@jones_fixed-width_2006; @flegal_markov_2008]. Full reporting on the Monte Carlo standard errors (MCSE) is provided, giving an error in +/- years for each marginal density. Finally, `eratosthenes` provides functions for assessing the level of dependence of events upon each other within the joint conditional. Changes in dates brought about by any alteration in the structure of a chronology can therefore be readily evaluted. In sum, `eratosthenes` allows for expedient revision of chronologies, transparency in the definition of the full joint conditional, and statistics on the certainty of estimates via MCSE.
+The `R` package `eratosthenes` (named after Eratosthenes of Cyrene, author of the _Chronographiai_) provides functions for chronology-building, above all to bring artifact dating within the scope of formal mathematical estimation. Hence, an investigator can obtain separate probability density functions (p.d.f.) for the production, use, and deposition of an artifact type, in addition to marginal p.d.f.s for all relative sequential events (howsover determined) and absolute constraints (howsoever defined). It uses Gibbs sampling, by now a conventional Markov Chain Monte Carlo method in archaeological chronology [@geman_stochastic_1984; @buck_bayesian_1996]. Using `Rcpp`, [@eddelbuettel_extending_2018], `eratosthenes` performs a two-step Gibbs routine, the first a preliminiary sampler to select a starting date, and a second main sampler that uses consistent batch means (CBM) as a stopping rule, given that convergence in distribution is assured [@jones_fixed-width_2006; @flegal_markov_2008]. Full reporting on the Monte Carlo standard errors (MCSE) is provided, giving an error in +/- years for each marginal density. Finally, `eratosthenes` provides functions for assessing the level of dependence of events upon each other within the joint conditional. Changes in dates brought about by any alteration in the structure of a chronology can therefore be readily evaluted. In sum, `eratosthenes` allows for expedient revision of chronologies, transparency in the definition of the full joint conditional, and statistics on the certainty of estimates via MCSE. 
 
 # Statement of Need