archeofrag.gui




archeofrag.gui aids in assessing the distinctions between observed archaeological spatial units (e.g. layers) and their formation process by examining the refitting relationships between fragments of objects contained in these units. This application complements and draws upon the archeofrag R package, which implements the TSAR method (Topological Study of Archaeological Refitting). The TSAR method covers not just the quantity of refitting relationships, but also their corresponding distribution and topology.

It relies on strong principles about archeological data:

  • Physical refits only give evidence of common origin: fragments are considered as parts of the same original object only if they physically refit to each other (relationships based on other factors such as motif style, estimation of chemical composition, etc. are excluded).
  • The spatial location of isolated objects is uncertain: the association between an object and the spatial unit where it was found is a weak relationship, due to the many factors which might have moved it since its deposition. For this reason, the analysis focuses on fragments with at least one refitting relationship, that provides minimal support about their inclusion in a spatial unit.
These principles reduce the quantity of relevant and usable data, but ensure analytical robustness in return.

Input Data

Use the menu on the left to upload your 'relations' and 'fragments' data as CSV files.

  • The relationships table must have a row for each refitting relationship and two columns containing the identifiers of each pair of refitting fragments, respectively;
  • The fragments table must have a row for each fragment and, at least, a column for fragments' unique identifiers and a column for the spatial units they belong to. Optionally, columns with morphometric data (e.g. length, surface) and with the fragments' X, Y, Z coordinates can be used.
Alternatively, load one of the real-world example datasets (or explore Rubish Site data).

Variable selection

Use the menu on the left to select:

  • the spatial variable to consider (i.e. the spatial unit containing the fragments),
  • the pair of spatial units to consider: this selection determines the plot generated in the 'Visualisation' tab and the simulation presets in the 'Simulation' tab.

Measurements

In this tab, statistics are reported for all pairs of spatial units for the selected 'Spatial variable': number of fragments and refitting relationships, etc. The cohesion and admixture values are calculated using the TSAR method. Tables and figures facilitate the exploration of the results.

Comparison with simulated data

This tab presents functions to investigate the formation process of the selected pair of spatial units. Simulation is used to compare it to similar artificial data while controlling differences in some parameters. Here, the chosen pair of spatial units is compared to simulated data generated under two formation hypotheses:

  • H1, the archaeological material studied comes from a single deposition event.
  • H2, the material was deposited during two deposition events.
Using the archeofrag R package, other hypotheses can be tested by adjusting the simulator parameters.


Weighting options

Use the morphometry variable to include any sort of morpho-metrical information about the objects in the computation (e.g. length, surface, volume, weight). Use at least two coordinates to include physical distances between the object found places in the computation (whatever the unit: metre, centimetre, inch, etc.). Details about the method are given in Plutniak et al. 2023.

Note that these weighting options are not supported by the simulation function, which computes cohesion values from the topology of the connection relationships only.

Stats by pair of spatial units

  • Fragments balance: considering only the fragments with connection relationships within their spatial unit, the proportion of fragments in the spatial unit whose label comes first alphanumerically.
  • Objects balance: considering only the fragments with connection relationships within their spatial unit, the proportion of objects (i.e. sets of refitted fragments) in the spatial unit whose label comes first alphanumerically.
  • Cohesion: for a pair of spatial units, the measure of the consistency of each unit, how it is 'self-adherent' to itself (see Plutniak 2021).
  • Cohesion diff.(erence): for a pair of spatial units, highest cohesion value - lowest cohesion value. (See the 'Spatial units optimisation' tab for details.)

Dissimilarity between spatial units

The dissimilarity between spatial units A and B is calculated as 1 - admixture(A, B). Results can be normalised (feature scaling) by ticking the box.

The higher the dissimilarity value, the more likely it is that these two archaeological units correspond to different depositional units. Theoretically, a spatial unit is expected to be more similar to those near it.

In the case of stratigraphic layers, a layer is expected to be more related to the layers directly above and below it. The dendrogram's branches are ordered alphanumerically according to their label (following the stratigraphic order of the layers). Anomalies are revealed when, despite this ordering constraint, the expected order of superposition is not observed in the result (see Plutniak et al. 2023).



Fragmentation graph



Explore spatial units merging

Presentation

It happens that archaeological spatial units should be merged for analysis, for example stratigraphic layers. But which ones? archeofrag.gui helps you determine merging solutions that generating the more balanced series of spatial units. Here 'balanced' means that there is as much archaeological information about every spatial units to support their recognition as archaeologically significant.

An ideal situation, where equal information is known about a series of distinct spatial units would result in spatial units with cohesion values = 0.5 and admixture = 0. (Here, 'information' means information about the number of fragments and the distribution of their refitting relationships.) In such a case, for every pair of units, the difference between the two cohesion values would be 0. Consequently, looking for spatial divisions minimising the difference between pairs of cohesion values inform us about archaeologically relevant merging of spatial units.

It 1) determines the series of possible spatial units merging, 2) generates the corresponding fragmentation graphs, 3) computes the cohesion value of each unit for all possible pairs of spatial units (as in the 'Measurements' tab), 4) summarises these values by measuring their median and median absolute deviation.

Instructions

  • Select the spatial units to consider for possible merging. Due to combinatorial explosion, the maximum number of units is limited to 7 (in this case, and depending on graph size, computation might be slow). Note that the merging of spatial units is evaluated regardless of their relative position (adjacent or not) in the archaeological space.
  • In the results, merged spatial units are indicated by the '+' symbol. Results are decreasingly ordered according to the median value of the differences between cohesion values: the lower the median, the more balanced the archaeological information about the series of spatial units. In addition, the median of the admixture values is also reported: the higher the value, the more mixed the spatial units. Use the dynamic table to explore the combinations and find out which optimal merging solution fits best with archaeological interpretation.



Select up to 7 spatial units and launch the computation:


Results


  • Sp. unit: spatial units. Merged spatial units are associated with a '+' symbol.
  • Cohesion difference: for a pair of spatial units, highest cohesion value - lowest cohesion value.
  • MAD: median absolute deviation.

Introduction to the simulation of site and assemblage formation



Time aspects

Any archaeological investigation regards three temporal components:
  • Deposition event: the point in time when unaltered material objects were abandoned.
  • Alteration phase: the period of time during which those material objects were fragmented and moved.
  • Excavation event: the point in time when those altered material objects are observed in space.
Note that components in this model are theoretical and an analytical simplification (e.g. defining deposition as an event and not a phase).

Material objects

In the archaeological study process, archaeologists use excavation data from a location to reconstruct and learn about past state(s) of this location. In practice:

  1. When excavating (at t0), sets of fragmented objects associated with spatial units are observed.
  2. Studying refitting relationships between fragments at the lab, a theoretical state of the assemblage is reconstructed, corresponding to a moment in the alteration phase (t-1).
  3. Because fragments are often missing, assumptions are made about the assemblage's possible completion state at an earlier moment, the deposition event (t-2).

Simulations

Simulation can be used to study the formation process between two points in time:

  • From the reconstructed point in the alteration process to the excavation event (t-1 to t0): this simulation covers only a part of the formation process but is only grounded on archaeological observation and does not require any additional assumption.
  • From the deposition event to the excavation event (t-2 to t-1): this simulation covers the entire formation process but requires assumptions about the initial state of the assemblage at the deposition event.

Testing formation scenarios

Hypotheses about two aspects of formation processes are of particular interest and can be studied by generating series of fragmentation graphs to compare: the number of deposition events and the direction of fragments transport between the first and second spatial units considered.

Combining these parameters allows to explore and test 6 formation scenarios (A to F):

Deposition events    Transport direction
1 ⇔ 2 1 ⇒ 2 1 ⇐ 2
One (H1) A C E
Two (H2) B D F

1. Number of deposition events

Fragmentation graphs can be generated for two hypotheses regarding the number of deposition events involved in the formation of the considered pair of spatial units:

  1. The objects were buried during one deposition event forming a single spatial unit, were subsequently fragmented and moved, and were discovered in two spatial units according to the archaeologists;
  2. The objects were buried during two deposition events forming two spatial units, were subsequently fragmented and moved, and were discovered in two spatial units according to the archaeologists.

2. Direction of fragments transport

The Unidirectional transport from unit... parameter makes it possible to constrain, or let free, the direction of fragments transport between the two spatial units under study.

For more details about the formation model implemented in the archeofrag simulator see Plutniak 2021, Fig. 7 in particular.



From (a moment in) the Alteration phase to the Excavation event

Presentation

This tool enables simulating the formation process of two spatial units. Its advantages method includes:

  • Robustness: the parameters are based on observed evidence, no assumptions are required.
  • Fast computation: it can be run on a personal computer.
However, it simulates what might have happen during a period of time from an undetermined moment in the 'alteration phase' to the excavation event (it does not cover not the assemblage's entire timespan from the deposition event to the excavation event).

Instructions

  • Select the pair of spatial units to compare in the sidebar menu.
  • The parameters of the simulation are automatically filled with the values measured on the graph corresponding to the two spatial units chosen (number of objects, fragments balance, planarity, etc.). However, those parameters can be edited to test other hypotheses. The final number of refitting relationships is not constrained.
  • Optionally, set an amount of 'Information loss' to simulate the non-observation of connection relationships or fragments, respectively.
  • Set the number of simulated graphs to generate for each hypothesis, and click on the 'Run' button.

Results

The table below summarises the results for some parameters, indicating:

  • whether the simulated values for H1 and H2 are significantly different (Wilcoxon test, 'H1 != H2?' and 'p.value' columns), and
  • whether the observed value is lower / within / higher than the interquartile range of values simulated for H1 and H2, respectively ('Obs. value/H1' and 'Obs. value/H2' columns).
Charts are generated to compare parameter values measured on the empirical fragmentation graph and on the artificial graphs:
  • The value observed on the empirical graph is represented by a vertical bar,
  • The distributions of values for each hypothesis are represented by dark (H1) and light (H2) grey shades, respectively (except for cohesion).

Model parameters set up

Initial state

Formation process

Final state

Information loss

Computation set up

Results

Cohesion by spatial unit

Comparing cohesion values is the main purpose of the TSAR method. Because cohesion is a complex measurement combining multiple aspects, this is where differences between compared hypotheses might be more evident and useful for archaeological interpretation. For each hypothesis (top and bottom part of the chart), compare the cohesion values observed for each spatial unit on the empirical graph (purple and yellow vertical bars) and the simulated values (density curves and boxplots).

Admixture

The admixture value summarises a pair of cohesion values. Less informative, it is nevertheless simpler and convenient to examine.

Fragments balance

Fragments balance, here, is a descriptive statistic simply defined as the proportion of fragments included in the first spatial unit, whatever their initial spatial unit (see code in 'R code' tab). Note that this definition differs from that of 'estimated' fragments balance value presented in the 'Measurements' tab and used to set up the simulation. The rationale behind this is to test whether the empirical balance can be obtained in simulated results from a guessed estimated initial balance.

Relationships count

The number of connection relationships (edges of the graph) is not constrained in this use of the simulator. Consequently, the edge count variability can be used to compare the empirical and simulated fragmentation graphs. Note that this variable is not essential in the TSAR method.

Connection strength

In the TSAR method, attributing values to the connection relationships ('edge weighting'), to represent their 'strength', is a crucial step before computing cohesion. In this regard, three statistics are calculated on the edge weights of the simulated graphs to complement the exploration of the simulated results: their median, median absolute deviation, and sum. When comparing results generated about different hypotheses, the distribution of these statistics can help distinguish between graphs mostly made of 'weak' or 'strong' connection relationships.




R code for the Alteration -> Excavation simulation

The following R code runs the 'Alteration to Excavation' simulation with the current settings and returns a series of values for the two hypotheses about the initial number of spatial units:
  • admixture
  • cohesion value for the spatial units 1 and 2
  • number of refitting relations
  • fragments balance
  • summary statstics for the relationship weights (sum, median, and standard deviation)




From the Deposition event to the Excavation event

Introduction to openMOLE's HD Origin Space Exploration method

The problem

Simulating a formation process from the Deposition event to the Excavation event requires making assumptions about the non-observed part of the archaeological information (due, for example, to the partial excavation of the site, transport of material objects to other places, information loss, etc.). Estimating missing information raises difficult issues because the range of possibilities is extensive, leading to combinatorial explosions. How many objects did this site originally included? How many fragments of this vessel are missing and not observed?

Origin Space Exploration

Model exploration methods address those cases. In particular, the High Dimension Origin Space Exploration method (HDOSE) enables determining the possible combinations of a model's initial parameters, overcoming combinatorial explosions. Conducting an HDOSE analysis requires defining:

  1. Origin values: the ranges of possible initial values for each parameter of the model.
  2. Objective values: the values corresponding to an observed state of a model (e.g. the values describing the state of the model at t0).
The HDOSE procedure returns the combinations of origin values that best generate the observed state (at t0) and, consequently, the most probable initial state(s) at t-2. Note that this approach requires to define the virtual total number of fragments and simulate the loss of part of it.

The HDOSE method is available from the openMOLE software.

Instructions

archeofrag.gui does not include the HDOSE method. However, it allows to set-up and generate the (Scala and R) code embedding the archeofrag formation model into the openMOLE framework, making this workflow smoother to use.

  1. Define the range of origin values to explore for each variable. Note that some values are automatically filed using the parameters of the selected pair of spatial units.
  2. Select the objective variables: the HDOSE procedure will return the combinations of variables that generate the values of those variables. Optionally, a tolerance percentage can be set for each value to allow approximation.
  3. Execute the generated code in openMOLE.

Origin variables: ranges of values to explore

Initial state

Formation process

Final state

Objective variables: archaeologically observed values

To define a variable as an objective tick its box. By default, the algorithm will search solutions that fit to the exact values. However, to accept surrounding values, use the corresponding slider to define a tolerance percentage.

Relevance of spatial units

Entities count

Alteration processes

Distribution of materials in the two spatial units

Computation set up




About archeofrag

To cite archeofrag or archeofrag.gui, please use Plutniak 2022a.

The open source programming code of this software is available on the CRAN and on github.

About the TSAR method

Datasets

  • Bout des Vergnes: Ihuel, E. (dir.), M. Baillet, A. Barbeyron, M. Brenet, H. Camus, E. Claud, N. Mercier., A. Michel, F. Sellami. 2020. Le Bout des Vergnes, Bergerac (Dordogne, Nouvelle-Aquitaine), Contournement ouest de Bergerac, RD 709, Excavation report, Perigueux.
  • Chauzeys: Chadelle J.-P. (dir.), M. Baillet, A. Barbeyron, M. Brenet, H. Camus, E. Claud, F. Jude, S. Kreutzer, A. Michel, N. Mercier, M. Rabanit, S. Save, F. Sellami, A. Vaughan-Williams. 2021. Chauzeys, Saint-Medard-de-Mussidan (Dordogne, Nouvelle-Aquitaine), Excavation report, Perigueux.
  • Cuzoul: Gardeur M. 2025. 'Bone refits from the Cuzoul de Gramat Mesolithic layers (archaeological site, France)', Zenodo, doi: 10.5281/zenodo.14975910.
  • Font-Juvenal: Caro J. 2024. 'Font-Juvenal_Refiting', Zenodo, doi: 10.5281/zenodo.14515444.
  • Fumane: Falcucci A. 2025. 'Refitting the context: accepted paper b (v0.1.3)', Zenodo, doi: 10.5281/zenodo.15017627.
  • Grande Rivoire: Angelin A. 2025. 'Refitting data from La Grande Rivoire prehistoric site', Zenodo, doi: 10.5281/zenodo.14609875.
  • Liang Abu: Plutniak S. 2021. 'Refitting Pottery Fragments from the Liang Abu Rockshelter, Borneo', Zenodo, doi: 10.5281/zenodo.4719577
  • Tai Cave and Tai South: Caro J., Plutniak S. 2022. 'Refitting and Matching Neolithic Pottery Fragments from the Tai site, France', Zenodo, doi: 10.5281/zenodo.7408706.