Repository navigation
ChronoCluster v0.1.0 – Initial Public Release
This is the first official release of ChronoCluster, a Python package for identifying and analyzing clusters in temporal or spatiotemporal point data, particularly where chronological uncertainty is a central concern. This version corresponds to the implementation used in a forthcoming publication [details TBA] and is archived on Zenodo for citation and reproducibility.
Overview
ChronoCluster is built around a custom Point class that supports both spatial coordinates and temporal distributions, allowing points to have start and end uncertainty modeled as probability distributions. This enables robust spatiotemporal analysis where points may only partially overlap in time and are not fixed at exact moments.
The package supports exploratory and model-based clustering in space and time using methods such as:
- Pairwise distance density estimation for transparent, scale-aware cluster detection.
- Bayesian 2D mixture modeling for spatial and spatiotemporal clustering.
- Spacetime heatmaps and 3D volume plots for visualizing temporal change in point patterns.
- Ripley's K, L, and G functions adapted for use with chronological uncertainty and temporality.
- Statistical comparison to CSR (Complete Spatial Randomness) and Baseline Informed Spatial Expectation (BISE) baselines using p-value heatmaps.
ChronoCluster's approach explicitly propagates temporal uncertainty using Monte Carlo simulation and includes flexible tools for:
- Probabilistically sampling points by their inclusion at specific time slices.
- Computing and visualizing clustering statistics across time.
- Evaluating statistical significance of clustering relative to null models.
Features
- A custom
Pointclass supporting continuous or degenerate (Dirac delta) temporal distributions. - Tools for modeling calibrated radiocarbon date distributions using built-in support for IntCal curves.
- Visualization tools for:
- Space-time point presence as worldlines or “pipes”
- Temporal slices of point patterns
- Clustering heatmaps and significance surfaces
- Flexible statistical pipeline for:
- Pairwise distances
- Ripley’s K, L, G functions
- P-value maps from CSR simulations
- Jupyter notebooks demonstrating workflows for:
- Exploratory cluster analysis
- Statistical testing
- Simulated and real-world datasets
Advanced Methods
ChronoCluster includes a fully integrated Bayesian 2D mixture model for cluster identification, enabling probabilistic inference of spatial clusters from temporally uncertain points. It also implements the Baseline Informed Spatial Expectation (BISE) approach—a novel alternative to Complete Spatial Randomness (CSR)—which leverages user-defined or empirical baselines for testing spatial structure. This allows researchers to evaluate clustering or dispersion relative to meaningful historical or environmental expectations rather than a purely random null.
These methods enable more flexible and context-sensitive interpretations of spatiotemporal patterning, especially in archaeological and paleoenvironmental research.
Applications
ChronoCluster was designed with archaeological, historical, and paleoenvironmental research in mind, but is broadly applicable to any discipline working with spatial point data under temporal uncertainty, such as:
- Archaeological site clustering with radiocarbon dates
- Historical site/event distributions with incomplete or approximate dates
Citation
If you use ChronoCluster in your research, please cite the Zenodo DOI associated with this release and the related publication (forthcoming). Citation metadata is included in the CITATION.cff file and on the project website.