ArchaeoPhases 1.5 Released
700 Words | Approximately 4 Minutes Read | Last Modified on December 14, 2020
Anne Philippe released ArchaeoPhases 1.5 on CRAN. This release fixes two minor
bugs and adds new read, plot, and statistical functions. It represents the first
step in a re-design that aims to aid replication and distribution of analytic
results.
New read functions read_bcal(), read_oxcal(), and read_chronomodel() are
intended to replace the general purpose function, ImportCSV(). The new
functions are built on the function read_csv(), which is fast and able to read
remote files, as well as local files. The new functions return S3 objects that
can identify the file that produced them. This facility might be useful in
situations where an analysis is based on a remote file that isn’t under the
analyst’s control, or when files are shared electronically and potentially
subject to corruption.
The following code block illustrates this capability. The second line reads a
remote OxCal file and assigns it to the variable oxc. The third line checks
if the original file used to create the oxc object has changed since the
object was created. If the original file still exists and is unchanged, then
the function returns TRUE. If the original file cannot be found, or has
changed, then the function returns FALSE.
library(ArchaeoPhases)
oxc <- read_oxcal("http://tsdye.online/AP/ox.csv", quiet = "yes")
## TRUE, if ox.csv has not changed on the server
original_file(oxc)
The new plot functions, multi_dates_plot(), tempo_activity_plot(),
tempo_plot(), marginal_plot(), multi_marginal_plot(), and
occurrence_plot() are functional replacements for the originals with camelCase
names, e.g., TempoPlot() -> tempo_plot(). They return S3 objects with plot() and reproduce() methods that inherit from data frame and can be passed to statistical functions.
The following code block illustrates the plot() and reproduce()
capabilities. The first line draws a plot of the first marginal posterior in
oxc and returns an S3 object, which is assigned to oxc.mar. The second line
draws the same plot, and also returns an S3 object. Note that the S3 objects
returned by marginal_plot() and plot() differ because the calls that created
them differ. Nevertheless, the data returned by the two calls is identical, as
expected. The call, reproduce(oxc.mar) checks that the original file is
accessible and has not changed, then recreates the plot. If successful, the
object it returns is identical with the object it reproduces.
oxc.mar <- marginal_plot(oxc)
oxc.mar.plot <- plot(oxc.mar)
## FALSE, calls differ
identical(oxc.mar, oxc.mar.plot)
## TRUE, data identical
identical(oxc.mar$x, oxc.mar.plot$x)
oxc.mar.rep <- reproduce(oxc.mar)
## TRUE
identical(oxc.mar.rep, oxc.mar)
The following code block illustrates that the objects returned by the read_*() functions behave like data frames. The new function, multi_marginal_statistics, expects a data frame as its first argument.
oxc.stats <- multi_marginal_statistics(oxc)
oxc.stats$statistics
The ability to reproduce an ArchaeoPhases analysis might find several uses. If
you are at all like me, then you work on a project for a while, move on to
something else, then pick up the project again when time and impulse coincide.
In this use case, objects produced during an earlier session and saved to disk
can be read into the new R session where they can be reproduced, or not,
depending on whether or not the Bayesian calibration software was run with
changes to the underlying chronological model, overwriting the original MCMC
file.
Similarly, in the case of a collaboration, one might wish to distribute an MCMC file and the R code required to make an informative plot. An email message with the MCMC file and the saved ArchaeoPhases object attached is a reasonable way this might be accomplished. In this situation, the recipient can point the reproduce() function to the local MCMC file and verify that the analysis carried out by the sender can actually be reproduced.
If you intend to make use of this functionality, please be aware that the S3
objects produced by ArchaeoPhases can be manipulated to include malicious code.
The best defense is, as usual, to choose trustworthy collaborators and not try
to reproduce objects from unknown sources. In any event, a simple way to check
for malicious code is to inspect the call attribute of the object, as shown in the following source code block.
oxc.mar$call
Enjoy ArchaeoPhases 1.5!