joeroe/stratigraphr

R package for archaeological stratigraphy and chronological sequences

stratigraphr

stratigraphr is a tidy framework for working with archaeological stratigraphy and chronology in R. It includes tools for reading, analysing, and visualising stratigraphies (Harris matrices) and sequences as directed graphs; helper functions for using radiocarbon dates in a tidy data analysis; and an R interface to OxCal's Chronological Query Language (CQL).

Installation

You can install the development version of stratigraphr from GitHub:

# install.packages("devtools")
devtools::install_github("joeroe/stratigraphr")

Please note that this package is in an early stage of development. It is functional, but many features are missing and future versions are likely to contain breaking changes.

Usage

• Graph-bases stratigraphic analysis: see vignette("stratigraph").
• Tidy analysis of radiocarbon dates: see vignette("tidy_radiocarbon").
• Chronological query language: see vignette("cql").

stratigraphr's Issues

Trim dependencies

Do we really need?

Imports:

• rdpack, yes
• checkmate?
• cli, no, remove with #14
• dplyr, maybe? https://www.tidyverse.org/blog/2023/04/performant-packages/
• glue, no, remove with #14
• igraph, yes
• magrittr, no, replace with native pipe
• purrr, yes
• rcarbon, no, remove with #14
• readr, maybe? https://www.tidyverse.org/blog/2023/04/performant-packages/
• relations, yes
• rlang, yes
• sets, yes
• stringr?
• tibble, maybe not after #15
• tidygraph, yes
• tidyr, surely not?
• utils, yes

Suggests:

• bchron, no, remove with #14
• covr, yes
• fs, no
• ggplot2, maybe not after #14
• ggraph, yes
• knitr, yes
• oxcaar, yes
• readxl, surely not?
• rmarkdown, yes
• testthat, yes

Missing dependencies when building pkgdown

I had to add a line to https://github.com/joeroe/stratigraphr/blob/master/.github/workflows/pkgdown.yaml to get the pkgdown documentation to build automatically on commit:

remotes::install_github(c("yihui/tinytex", "yihui/knitr", "r-lib/withr"))

I think this is because CRAN is missing macOS binaries for the latest versions of these packages. Presumably this will be sorted out soon, so this line should be removed when it's no longer needed.

read_lst() throws an error on Windows

From https://github.com/joeroe/stratigraphr/runs/1209018776?check_suite_focus=true, the example for read_lst() throws an error on Windows:

  Error in .f(.x[[i]], ...) : 
    Assertion on 'attr' failed: Must comply to pattern '.*:.*'.
  Calls: read_lst ... <Anonymous> -> map -> .f -> <Anonymous> -> makeAssertion -> mstop
  Execution halted

I imagine this is a newline/character encoding issue since there are no problems on Linux or macOS.

Support constructing stratigraphs from tidy data frames

I.e.,

data.frame(
    unit = c("A", "B", "C", "C"),
    above = c(NA, "A", "A", "B")
)

Should have the same result as

tibble(
    unit = c("A", "B", "C"),
    above = list(NA, "A", c("A", "B"))
)

does now.

Don't know how common this format will be in the wild, but it's much easier for quickly constructing graphs in R itself.

Should be configurable, but also probably the default if label is not unique?

strat_is_valid() should detect the source of a cycle

igraph has a feedback_arc_set function that can help isolate the source of a cycle. IIRC, the package implements a fast approximate algorithm (which is helpful) and a slower exact algorithm (which is what most users will probably enjoy).

Detect whether a stratigraph obeys the law of stratigraphic succession, and fix it if it doesn't

Harris' law of stratigraphical succession is satisfied by transitive reduction of the DAG. The intermediate tabular format might want to serve up information to the transitive reduction function with as little fuss as possible. Transitive reduction is another feature igraph apparently lacks: igraph/igraph/issues/932

Originally posted by @tsdye in #2 (comment)

Input and output formats

We should be able to read and write data to/from these formats:

• Complex tables like @tsdye / hm: http://www.tsdye.online/harris-matrix/data-tables/
• Complex tables like ArkMatrix: https://gitlab.com/arklab/ArkMatrix/blob/master/docs/format_csv.md
• INTCHRON JSON files: https://doi.org/10.1017/RDC.2019.21
• Generic tables of relations (i.e. "above", "below", "equal", as on a typical context sheet)
• BASP/ArchEd/Stratify .LST files: http://archaeologic.al/wiki/Harris_Matrix#LST

We probably won't be handle these formats:

• .HM files from ArchEd – are in binary format, and the only software that could write/read them doesn't appear to be functional any more (see http://archaeologic.al/wiki/Harris_Matrix#ArchEd)
• CRMarchaeo/CIDOC CRM ontologies: http://cidoc-crm.org/crmarchaeo/sites/default/files/CRMarchaeo_v1.3.pdf – extremely complicated so indefinitely postponed pending evidence that anyone actually uses it.

Remove deprecated c14_* and cal_* functions

Moved to and superseded by https://github.com/joeroe/c14 and set to be deprecated 0.3.1. Should be safe to remove them in a couple of versions.

read_lst() doesn't work with Stratify files

Using harris2graph's example Stratify .lst file:

library(stratigraphr)
tmpfile <- fs::file_temp()
download.file("https://raw.githubusercontent.com/lparchaeology/harris2graph/master/stratify.lst", tmpfile)
#> trying URL 'https://raw.githubusercontent.com/lparchaeology/harris2graph/master/stratify.lst'
#> Content type 'text/plain; charset=utf-8' length 1537 bytes
#> ==================================================
#> downloaded 1537 bytes
#> 
read_lst(tmpfile)
#> New names:
#> * below -> below...1
#> * below -> below...4
#> New names:
#> * Unit_class -> Unit_class...1
#> * Unit_class -> Unit_class...4
#> New names:
#> * TST -> TST...1
#> * TST -> TST...4
#> New names:
#> * Unit_class -> Unit_class...1
#> * Unit_class -> Unit_class...4
#> New names:
#> * below -> below...1
#> * below -> below...4
#> Error in if (value == "") { : missing value where TRUE/FALSE needed

This is because, predictably, Stratify doesn't follow the assumption that LST files always use 5 lines per stratum. We will need a more flexible way of initially splitting the file by stratum in read_lst().

Vignettes

• cql
• stratigraph
• tidy_radiocarbon

Unimplemented CQL commands

• cql_age()
• cql_axis()
• cql_c_combine()
• cql_c_simulate()
• cql_correl_matrix()
• cql_correlation()
• cql_covar_matrix()
• cql_curve()
• cql_delta_r()
• cql_difference()
• cql_end()
• cql_exp()
• cql_gap()
• cql_interval()
• cql_kde_model()
• cql_kde_plot()
• cql_label()
• cql_line()
• cql_mcmc_sample()
• cql_mix_curves()
• cql_number()
• cql_offset()
• cql_outlier()
• cql_outlier_model()
• cql_p()
• cql_pois()
• cql_prior()
• cql_probability()
• cql_r_combine()
• cql_r_simulate()
• cql_reservoir()
• cql_sample()
• cql_sapwood()
• cql_sapwood_model()
• cql_shift()
• cql_start()
• cql_after()
• cql_before()
• cql_combine()
• cql_first()
• cql_last()
• cql_order()
• cql_span()
• cql_sum()

Validate stratigraphs

I don't know the R graph packages well, but you'll want to use one that is able to check for cycles. I browsed ggraph and didn't see anything there, but igraph will run this check. I believe that is what @nevrome was getting at in the thread with @zachbatist when he mentioned the logic check.

Also, if you decide to push forward with this, please consider the data structures set out by Dye and Buck (2015) and used in hm. The idea there was to have hm read csv files generated by SQL queries.