Package 'palimpsestr'

Description

Compares estimated phase assignments against known true labels using the Adjusted Rand Index (Hubert and Arabie, 1985). Values near 1 indicate perfect agreement; values near 0 indicate random agreement.

Usage

adjusted_rand_index(object, true_labels)

Arguments

Value

A single numeric value in $[-1, 1]$.

See Also

confusion_matrix, fit_sef

Other validation: bootstrap_sef(), confusion_matrix(), cv_sef(), optimize_weights()

Examples

x <- archaeo_sim(n = 80, k = 3, seed = 1, mixing = 0.05)
fit <- fit_sef(x, k = 3, seed = 1)
adjusted_rand_index(fit, x$true_phase)

Description

Generates a synthetic excavation dataset with known latent phases, controlled spatial clustering, and configurable inter-phase mixing.

Usage

archaeo_sim(n = 150, k = 3, seed = NULL, mixing = 0.08)

Arguments

Value

A data.frame with columns: id, x, y, z, context, date_min, date_max, class, taf_score, true_phase.

See Also

fit_sef for fitting the SEF model to the output.

Examples

easy <- archaeo_sim(n = 100, k = 3, mixing = 0.05, seed = 1)
table(easy$true_phase)

hard <- archaeo_sim(n = 200, k = 4, mixing = 0.50, seed = 1)
table(hard$true_phase)

Description

Returns a data.frame combining dominant phase assignments, membership probabilities, entropy, local SEI, and energy.

Usage

as_phase_table(object)

Arguments

Value

A data.frame with one row per find.

See Also

predict_phase, phase_diagnostic_table

Other diagnostics: detect_intrusions(), ese(), pdi(), phase_diagnostic_table(), predict_phase()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
head(as_phase_table(fit))

Description

Wraps ggplotly with archaeological tooltips showing find ID, context, phase probability, dating, class, entropy, and energy.

Usage

as_plotly(gg, tooltip = "text", ...)

Arguments

Value

A plotly htmlwidget object.

See Also

gg_phasefield, gg_entropy, gg_energy, gg_intrusions

Other plotting: gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Examples

x <- archaeo_sim(n = 80, k = 3, seed = 1)
fit <- fit_sef(x, k = 3)
if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("plotly", quietly = TRUE)) {
  p <- as_plotly(gg_phasefield(fit))
}

Description

Extracts the strongest pairwise SEI connections as sf line geometries.

Usage

as_sf_links(object, quantile_threshold = 0.9, crs = NA_integer_)

Arguments

Value

An sf object with columns from, to, sei, and geometry.

See Also

as_sf_phase, sei_matrix

Other GIS: as_sf_phase()

Examples

if (requireNamespace("sf", quietly = TRUE)) {
  x <- archaeo_sim(n = 60, k = 2, seed = 1)
  fit <- fit_sef(x, k = 2)
  links <- as_sf_links(fit)
}

Description

Creates an sf point object with phase assignments and diagnostics for use in QGIS or spatial analysis.

Usage

as_sf_phase(object, crs = NA_integer_, dims = c("XY", "XYZ"))

Arguments

Value

An sf object.

See Also

as_sf_links, phase_diagnostic_table

Other GIS: as_sf_links()

Examples

if (requireNamespace("sf", quietly = TRUE)) {
  x <- archaeo_sim(n = 60, k = 2, seed = 1)
  fit <- fit_sef(x, k = 2)
  pts <- as_sf_phase(fit)
}

Description

Resamples the data with replacement, refits the model, and computes the distribution of key statistics (PDI, mean entropy, mean energy, ARI if true labels provided). Returns percentile confidence intervals.

Usage

bootstrap_sef(
  object,
  n_boot = 100,
  conf = 0.95,
  true_labels = NULL,
  verbose = TRUE
)

Arguments

Value

A data.frame with columns statistic, estimate, lower, upper, se.

See Also

fit_sef, pdi, adjusted_rand_index

Other validation: adjusted_rand_index(), confusion_matrix(), cv_sef(), optimize_weights()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2, seed = 1)
bootstrap_sef(fit, n_boot = 20)

Description

Fits the SEF model for each value of K and returns a summary table with BIC, PDI, entropy, energy, and other diagnostics.

Usage

compare_k(data, k_values = 2:6, ...)

Arguments

Value

A data.frame with one row per K value.

See Also

fit_sef, gg_compare_k

Other fitting: fit_sef(), reorder_phases(), sef_summary()

Examples

x <- archaeo_sim(n = 100, k = 3, seed = 1)
ck <- compare_k(x, k_values = 2:4)
print(ck)

Description

Cross-tabulates estimated phase assignments against known true labels. Phases are reordered to maximise diagonal agreement (Hungarian matching).

Usage

confusion_matrix(object, true_labels)

Arguments

Value

A matrix with estimated phases as rows and true phases as columns.

See Also

adjusted_rand_index

Other validation: adjusted_rand_index(), bootstrap_sef(), cv_sef(), optimize_weights()

Examples

x <- archaeo_sim(n = 80, k = 3, seed = 1, mixing = 0.05)
fit <- fit_sef(x, k = 3, seed = 1)
confusion_matrix(fit, x$true_phase)

Description

Splits the data into folds, fits on training folds, and evaluates log-likelihood on the held-out fold. Useful for comparing different K values or weight configurations.

Usage

cv_sef(data, k_values = 2:6, n_folds = 5, seed = 1, ...)

Arguments

Value

A data.frame with columns k, fold, train_loglik, test_loglik, train_pdi.

See Also

compare_k, fit_sef

Other validation: adjusted_rand_index(), bootstrap_sef(), confusion_matrix(), optimize_weights()

Examples

x <- archaeo_sim(n = 100, k = 3, seed = 1)
cv <- cv_sef(x, k_values = 2:4, n_folds = 3)
# Mean test log-likelihood per K
aggregate(test_loglik ~ k, data = cv, FUN = mean)

Description

Simulated dataset with 250 artefacts, 4 phases, and 50% mixing. Represents a heavily disturbed deposit where phases are difficult to separate.

Usage

demo_compressed

Format

A data.frame with 250 rows and 10 columns. See demo_easy for column descriptions.

Examples

data(demo_compressed)

ck <- compare_k(demo_compressed, k_values = 2:6)
print(ck)

Description

Simulated dataset with 150 artefacts, 3 phases, and 5% mixing. Represents a site where occupation phases are clearly distinguishable.

Usage

demo_easy

Format

A data.frame with 150 rows and 10 columns:

id

Artefact identifier

x, y

Planimetric coordinates (metres)

z

Depth (metres)

context

Stratigraphic unit label

date_min, date_max

Chronological interval (CE)

class

Cultural class (ceramic, lithic, bone, metal)

taf_score

Taphonomic disturbance score (0-1)

true_phase

Known phase assignment (for validation)

Examples

data(demo_easy)
fit <- fit_sef(demo_easy, k = 3)
plot_phasefield(fit)

Description

Simulated dataset with 200 artefacts, 3 phases, and 30% mixing. Represents a site with significant but resolvable depositional mixing.

Usage

demo_moderate

Format

A data.frame with 200 rows and 10 columns. See demo_easy for column descriptions.

Examples

data(demo_moderate)
fit <- fit_sef(demo_moderate, k = 3, tafonomy = "taf_score", context = "context")
summary(fit)

Description

Combines rescaled entropy, energy, and inverse local SEI into a composite intrusion probability score.

Usage

detect_intrusions(object)

Arguments

Value

A data.frame with columns id and intrusion_prob.

See Also

gg_intrusions, fit_sef

Other diagnostics: as_phase_table(), ese(), pdi(), phase_diagnostic_table(), predict_phase()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
di <- detect_intrusions(fit)
head(di[order(di$intrusion_prob, decreasing = TRUE), ])

Description

Measures local depositional disruption for each find by summing weighted dissimilarities with neighbours.

Usage

ese(
  data,
  coords = c("x", "y", "z"),
  chrono = c("date_min", "date_max"),
  class_col = "class",
  beta = c(1, 1, 1, 1),
  neighbourhood = NULL
)

Arguments

Value

A numeric vector of local energy values.

See Also

fit_sef, gg_energy

Other diagnostics: as_phase_table(), detect_intrusions(), pdi(), phase_diagnostic_table(), predict_phase()

Examples

x <- archaeo_sim(n = 30, k = 2, seed = 1)
e <- ese(x)
summary(e)

Description

Writes phase assignments, intrusion scores, US summary, and model summary to CSV files in the specified directory.

Usage

export_results(object, dir, format = "csv", prefix = "palimpsestr")

Arguments

Value

Invisibly returns a character vector of written file paths.

See Also

us_summary_table, as_phase_table

Other export: phase_transition_matrix(), us_summary_table()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2, context = "context")
export_results(fit, dir = tempdir())

Description

Estimates latent depositional phases from spatial, stratigraphic, chronological, and cultural evidence using diagonal Gaussian mixture EM.

Usage

fit_sef(
  data,
  coords = c("x", "y", "z"),
  chrono = c("date_min", "date_max"),
  class = "class",
  tafonomy = NULL,
  context = NULL,
  harris = NULL,
  k = 3,
  weights = c(ws = 1, wz = 1, wt = 1, wc = 1),
  seed = 1,
  em_iter = 100,
  em_tol = 1e-05,
  n_init = 1,
  chrono_precision = FALSE,
  taf_as_feature = FALSE,
  residuality = FALSE,
  class_scale = FALSE,
  subclass = NULL
)

Arguments

Value

An S3 object of class sef_fit.

See Also

archaeo_sim, compare_k, pdi, detect_intrusions

Other fitting: compare_k(), reorder_phases(), sef_summary()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
print(fit)


x <- archaeo_sim(n = 150, k = 3, seed = 42)
fit <- fit_sef(x, k = 3, tafonomy = "taf_score", context = "context")
summary(fit)

Description

Visualises bootstrap confidence intervals for key SEF diagnostics (PDI, entropy, energy, log-likelihood, and optionally ARI).

Usage

gg_bootstrap(bs_result)

Arguments

Value

A ggplot object.

See Also

bootstrap_sef

Other plotting: as_plotly(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Three-panel plot showing BIC, PDI, and Mean Entropy for different K values.

Usage

gg_compare_k(ck)

Arguments

Value

A ggplot object.

See Also

compare_k

Other plotting: as_plotly(), gg_bootstrap(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Plots a heatmap of the confusion matrix between estimated and known true phase assignments.

Usage

gg_confusion(object, true_labels)

Arguments

Value

A ggplot object.

See Also

confusion_matrix, adjusted_rand_index

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  x <- archaeo_sim(n = 80, k = 3, seed = 1, mixing = 0.05)
  fit <- fit_sef(x, k = 3, seed = 1)
  gg_confusion(fit, x$true_phase)
}

Description

Plots the log-likelihood at each EM iteration to verify convergence.

Usage

gg_convergence(object)

Arguments

Value

A ggplot object.

See Also

fit_sef

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  x <- archaeo_sim(n = 80, k = 3, seed = 1)
  fit <- fit_sef(x, k = 3)
  gg_convergence(fit)
}

Description

Plots mean test and training log-likelihood across K values from cv_sef output.

Usage

gg_cv(cv_result)

Arguments

Value

A ggplot object.

See Also

cv_sef, gg_compare_k

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Shows ESE values across space. High energy indicates zones where neighbouring artefacts are dissimilar (depositional disruption).

Usage

gg_energy(object, xlabel = "Easting (m)", ylabel = "Northing (m)")

Arguments

Value

A ggplot object.

See Also

gg_entropy, as_plotly for interactive version.

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Shows Shannon entropy of phase probabilities across the excavation area. High entropy = uncertain phase assignment (possible palimpsest zone).

Usage

gg_entropy(object, xlabel = "Easting (m)", ylabel = "Northing (m)")

Arguments

Value

A ggplot object.

See Also

plot_entropy for base R version, as_plotly for interactive version.

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Maps the probability that each find is an intrusion (displaced or redeposited). Top suspects are circled and labelled.

Usage

gg_intrusions(
  object,
  top_n = 5,
  xlabel = "Easting (m)",
  ylabel = "Northing (m)"
)

Arguments

Value

A ggplot object.

See Also

detect_intrusions, as_plotly for interactive version.

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Displays SEF analysis results directly on the excavation plan. Polygons represent stratigraphic units; points represent individual finds.

Usage

gg_map(
  object,
  geometries,
  layer = c("phase", "entropy", "energy", "intrusion"),
  show_labels = TRUE,
  show_points = TRUE,
  xlabel = NULL,
  ylabel = NULL
)

Arguments

Value

A ggplot object.

See Also

load_geometries, as_sf_phase

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Plots finds along the depth (z) axis, coloured by phase assignment, to visualise the stratigraphic ordering of phases.

Usage

gg_phase_profile(object)

Arguments

Value

A ggplot object.

See Also

phase_transition_matrix

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Examples

if (requireNamespace("ggplot2", quietly = TRUE)) {
  x <- archaeo_sim(n = 80, k = 3, seed = 1)
  fit <- fit_sef(x, k = 3)
  gg_phase_profile(fit)
}

Description

Plots artefact positions coloured by dominant phase, with point size proportional to assignment confidence.

Usage

gg_phasefield(object, xlabel = "Easting (m)", ylabel = "Northing (m)")

Arguments

Value

A ggplot object.

See Also

plot_phasefield for base R version, as_plotly for interactive version.

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Plots the mean test log-likelihood across weight configurations from optimize_weights output.

Usage

gg_weights(opt_result)

Arguments

Value

A ggplot object.

See Also

optimize_weights

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), plot_energy(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Description

Infers vertical ordering between stratigraphic units from the mean depth of finds in each context, and builds a penalty matrix that discourages finds from different vertical zones being assigned to the same phase.

Usage

harris_from_contexts(
  data,
  z_col = "z",
  context_col = "context",
  penalty_scale = 0.5
)

Arguments

Value

An $n \times n$ symmetric penalty matrix.

See Also

fit_sef, read_harris

Other harris: read_harris(), validate_phases_harris()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
H <- harris_from_contexts(x, z_col = "z", context_col = "context")
dim(H)

Description

Opens an interactive Shiny application for loading data, fitting the SEF model, and exploring results through plots, tables, and maps.

Usage

launch_app()

Details

The app requires the following packages (installed but not imported by palimpsestr): shiny, shinydashboard, DT. For interactive plots install plotly. For database connections install DBI plus RSQLite or RPostgres. For GIS maps install sf.

Value

Launches the Shiny app (does not return).

Examples

## Not run: 
launch_app()

## End(Not run)

Description

Reads stratigraphic unit polygons from Shapefile, GeoPackage, GeoJSON, or a PostGIS database for use with gg_map.

Usage

load_geometries(
  source,
  layer = NULL,
  query = NULL,
  us_column = "us",
  crs = NULL
)

Arguments

Value

An sf object with a us column.

See Also

gg_map, read_db

Other data-import: read_db()

Description

Aggregates the SEI matrix by row, yielding a per-observation measure of total depositional coherence with all other finds.

Usage

local_sei(sei_mat)

Arguments

Value

A numeric vector of length nrow(sei_mat).

See Also

sei_matrix

Other SEI: sei_matrix(), sei_sparse()

Examples

x <- archaeo_sim(n = 30, k = 2, seed = 1)
S <- sei_matrix(x)
lsei <- local_sei(S)
summary(lsei)

Description

Tests a grid of weight configurations and selects the one that maximises the mean held-out log-likelihood across folds. This provides a data-driven alternative to manual weight specification.

Usage

optimize_weights(
  data,
  k,
  weight_grid = NULL,
  n_folds = 3,
  seed = 1,
  verbose = TRUE,
  ...
)

Arguments

Value

A list with components:

best_weights

Named numeric vector of optimal weights.

results

Data.frame with all tested configurations and their scores.

See Also

fit_sef, cv_sef

Other validation: adjusted_rand_index(), bootstrap_sef(), confusion_matrix(), cv_sef()

Examples

x <- archaeo_sim(n = 80, k = 3, seed = 1)
opt <- optimize_weights(x, k = 3, n_folds = 3)
opt$best_weights

Description

Measures global phase separability as $1 - \bar{H} / \log(K)$. Values close to 1 indicate well-separated phases; values near 0 indicate a compressed palimpsest.

Usage

pdi(object)

Arguments

Value

A single numeric value between 0 and 1.

See Also

fit_sef, compare_k

Other diagnostics: as_phase_table(), detect_intrusions(), ese(), phase_diagnostic_table(), predict_phase()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
pdi(fit)

Description

Combines the input data with dominant phase, phase probabilities, entropy, local SEI, and energy in a single data.frame.

Usage

phase_diagnostic_table(object)

Arguments

Value

A data.frame with all input columns plus diagnostics.

See Also

as_phase_table, as_sf_phase

Other diagnostics: as_phase_table(), detect_intrusions(), ese(), pdi(), predict_phase()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
pdt <- phase_diagnostic_table(fit)
names(pdt)

Description

Computes how often finds from phase $i$ are found directly above finds from phase $j$ in the vertical sequence, revealing the stratigraphic ordering of phases.

Usage

phase_transition_matrix(object)

Arguments

Value

A $K \times K$ matrix where entry [i,j] counts transitions from phase i (above) to phase j (below).

See Also

us_summary_table

Other export: export_results(), us_summary_table()

Examples

x <- archaeo_sim(n = 80, k = 3, seed = 1)
fit <- fit_sef(x, k = 3)
phase_transition_matrix(fit)

Description

Plot local Excavation Stratigraphic Energy (base R)

Usage

plot_energy(object)

Arguments

Value

Invisibly returns the object.

See Also

gg_energy for the ggplot2 version.

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_entropy(), plot_phasefield(), plot_sei_profile()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
plot_energy(fit)

Description

Plot entropy across space (base R)

Usage

plot_entropy(object)

Arguments

Value

Invisibly returns the object.

See Also

gg_entropy for the ggplot2/plotly version.

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_phasefield(), plot_sei_profile()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
plot_entropy(fit)

Description

Plot dominant phase assignment (base R)

Usage

plot_phasefield(object)

Arguments

Value

Invisibly returns the object.

See Also

gg_phasefield for the ggplot2/plotly version.

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_sei_profile()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
plot_phasefield(fit)

Description

Plot ordered SEI profile (base R)

Usage

plot_sei_profile(object)

Arguments

Value

Invisibly returns the object.

See Also

sei_matrix, local_sei

Other plotting: as_plotly(), gg_bootstrap(), gg_compare_k(), gg_confusion(), gg_convergence(), gg_cv(), gg_energy(), gg_entropy(), gg_intrusions(), gg_map(), gg_phase_profile(), gg_phasefield(), gg_weights(), plot_energy(), plot_entropy(), plot_phasefield()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
plot_sei_profile(fit)

Description

Convenience alias for as_phase_table.

Usage

predict_phase(object)

Arguments

Value

A data.frame with probabilities and diagnostics.

See Also

as_phase_table

Other diagnostics: as_phase_table(), detect_intrusions(), ese(), pdi(), phase_diagnostic_table()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
head(predict_phase(fit))

Description

Loads find data from any DBI-compatible database and maps columns to the format expected by fit_sef.

Usage

read_db(
  conn,
  query = NULL,
  table = NULL,
  col_id = "id",
  col_x = "x",
  col_y = "y",
  col_z = "z",
  col_context = "context",
  col_date_min = "date_min",
  col_date_max = "date_max",
  col_class = "class",
  col_taf = NULL,
  schema = "custom",
  sito = NULL
)

Arguments

Value

A data.frame ready for fit_sef.

See Also

fit_sef, load_geometries

Other data-import: load_geometries()

Description

Reads a CSV file with columns from, to, and optionally weight, and converts it to an $n \times n$ penalty matrix aligned with the find-level data.

Usage

read_harris(file, contexts, default_weight = 1)

Arguments

Value

An $n \times n$ penalty matrix.

See Also

harris_from_contexts, fit_sef

Other harris: harris_from_contexts(), validate_phases_harris()

Description

Relabels phases so that phase 1 corresponds to the deepest (oldest) stratum and phase K to the shallowest (most recent). This ensures consistent, interpretable phase numbering across different runs.

Usage

reorder_phases(object)

Arguments

Value

A sef_fit object with reordered phases.

See Also

fit_sef

Other fitting: compare_k(), fit_sef(), sef_summary()

Examples

x <- archaeo_sim(n = 80, k = 3, seed = 1)
fit <- fit_sef(x, k = 3)
fit <- reorder_phases(fit)

Description

Produces a structured Markdown report covering phase composition, intrusion detection, stratigraphic unit purity, and recommendations. Available in English and Italian.

Usage

report_sef(object, lang = c("en", "it"), file = NULL)

Arguments

Value

Character string with the report text (invisibly).

See Also

fit_sef, sef_summary

Examples

x <- archaeo_sim(n = 100, k = 3, seed = 1)
fit <- fit_sef(x, k = 3)
report_sef(fit, lang = "en")

Description

Returns a named list with global diagnostics and phase counts.

Usage

sef_summary(object)

Arguments

Value

A named list.

See Also

fit_sef, pdi

Other fitting: compare_k(), fit_sef(), reorder_phases()

Examples

x <- archaeo_sim(n = 60, k = 2, seed = 1)
fit <- fit_sef(x, k = 2)
sef_summary(fit)

Description

Builds an $n \times n$ symmetric matrix quantifying pairwise depositional coherence from spatial, vertical, temporal, and cultural evidence.

Usage

sei_matrix(
  data,
  coords = c("x", "y", "z"),
  chrono = c("date_min", "date_max"),
  class_col = "class",
  weights = c(ws = 1, wz = 1, wt = 1, wc = 1),
  eps = 1e-09,
  z_floor = 0.25,
  max_dist = NULL
)

Arguments

Value

A symmetric numeric matrix with zero diagonal.

Note

SEI values are normalised within each dataset. Absolute SEI values are not directly comparable across different excavations or datasets of different sizes. Use SEI for within-dataset ranking and relative comparisons only.

See Also

local_sei, fit_sef

Other SEI: local_sei(), sei_sparse()

Examples

x <- archaeo_sim(n = 30, k = 2, seed = 1)
S <- sei_matrix(x)
dim(S)

Description

Wrapper around sei_matrix that automatically sets max_dist when the dataset exceeds a size threshold, using the 25th percentile of pairwise distances as the cutoff.

Usage

sei_sparse(
  data,
  coords = c("x", "y", "z"),
  chrono = c("date_min", "date_max"),
  class_col = "class",
  weights = c(ws = 1, wz = 1, wt = 1, wc = 1),
  eps = 1e-09,
  z_floor = 0.25,
  n_threshold = 1000
)

Arguments

Value

A numeric matrix (same as sei_matrix).

See Also

sei_matrix

Other SEI: local_sei(), sei_matrix()

Examples

x <- archaeo_sim(n = 50, k = 2, seed = 1)
S <- sei_sparse(x)

Description

Summarise a fitted SEF model

Usage

## S3 method for class 'sef_fit'
summary(object, ...)

Arguments

Value

A named list.

Description

Aggregates finds by context (US), reporting the dominant phase, purity (proportion of finds in dominant phase), mean entropy, mean energy, and intrusion count.

Usage

us_summary_table(object)

Arguments

Value

A data.frame with one row per stratigraphic unit.

See Also

export_results, phase_diagnostic_table

Other export: export_results(), phase_transition_matrix()

Examples

x <- archaeo_sim(n = 80, k = 3, seed = 1)
fit <- fit_sef(x, k = 3, context = "context")
us_summary_table(fit)

Description

Checks whether the estimated phases follow the expected vertical ordering within each stratigraphic unit pair.

Usage

validate_phases_harris(object)

Arguments

Value

A data.frame with one row per context pair, indicating whether the dominant phase ordering is consistent with depth.

See Also

harris_from_contexts, us_summary_table

Other harris: harris_from_contexts(), read_harris()

Examples

x <- archaeo_sim(n = 60, k = 3, seed = 1)
fit <- fit_sef(x, k = 3, context = "context")
validate_phases_harris(fit)

Description

Real archaeological dataset from the site of Poggio Gramignano (Lugnano in Teverina, TR, Italy), a multi-period Roman villa with an annexed Late Antique infant cemetery. The dataset contains 615 inventoried finds from 54 stratigraphic units spanning from the Pre-Roman period (7th–4th c. BCE) through the Late Antique (5th–6th c. CE).

Usage

villa_romana

Format

A data.frame with 615 rows and 9 variables:

id

Unique find identifier (VRPG_0001 to VRPG_0615)

x

Easting coordinate (metres, EPSG:3004)

y

Northing coordinate (metres, EPSG:3004)

z

Mean elevation of the stratigraphic unit (metres a.s.l.)

context

Stratigraphic unit label (e.g. US_76, US_117)

date_min

Start of chronological interval (BCE as negative, CE as positive)

date_max

End of chronological interval

class

Material class (e.g. Reperto Ceramico, Reperto Anforaceo)

taf_score

Taphonomic integrity score (0 = fully disturbed, 1 = pristine in situ)

Details

Chronological data derives from the site periodisation. Coordinates are US centroids in Monte Mario / Italy zone 2 (EPSG:3004). Elevation (z) is the mean of recorded quotes per US. Taphonomic scores were assigned by the excavator based on depositional context (primary, secondary, redeposition, backfill, disturbance).

Source

Data from the pyArchInit database of Poggio Gramignano (VRPG 3004). Taphonomic scores compiled by Roberto Montagnetti.

Examples

data(villa_romana)
str(villa_romana)
table(villa_romana$class)