PaleoSTeHM - A modern, scalable Spatio-Temporal Hierarchical Modeling framework for paleo-environmental data
By Rutgers Earth System Science & Policy Lab
This repository contains the Jupyter Notebook based tutorials for PaleoSTeHM project, which will develop a framework for spatiotemporal hierarchical modeling of paleodata that builds upon modern, scalable software infrastructure for machine learning. By leveraging an existing, widely used machine-learning framework at the base level, PaleoSTeHM will be built to take advantage of current and future computational advances without modifications to the user-facing product. It will facilitate the incorporation of complex likelihood structures, including the embedding of physical simulation models, and thus pave the way for further advances in paleo-modeling.
PaleoSTeHM is a paleo-environmental modelling faced API based upon pyro, a universal probabilistic programming language supported by PyTorch on the backend. Therefore, it not only supports probabilistic programming not also the auto-differentiation and GPU acceleration. This API will provide easy-to-use models to infer the spatio or spatio-temporal variation of environmental change from geological data, with tutorials that cover the background theories and hand-on practicals.
The work described in this repository is documented in the following publication:
DOI: doi.org/10.5194/gmd-18-2609-2025
Please note that this repository is managed by Yucheng Lin and Robert Kopp. If you have any questions please contact Yucheng: yc.lin@rutgers.edu.
- Clone the PaleoSTeHM repository.
git clone https://github.com/radical-collaboration/PaleoSTeHM.git
- Create and activate a Python virtual environment, and install PaleoSTeHM's Python dependencies in it. Using conda:
cd PaleoSTeHM/
conda env create -f environment.yml
conda activate ve3PaleoSTeHM
- Load Jupyter Lab (or Jupyter Notebook) and navigate to the tutorial of interest.
jupyter-lab
The following are instructions on how to run PaleoSTeHM tutorials through Google Colab (https://colab.research.google.com/). One must have a Google account and access to Google Drive to use PaleoSTeHM in this configuration.
-
Navigate to Google Colab and select "+ New Notebook" when prompted.
-
In the new notebook copy and paste the following into cell.
from google.colab import drive
drive.mount('/content/drive')
%cd /content/drive/MyDrive
!git clone https://github.com/radical-collaboration/PaleoSTeHM.git
- Open Google Drive and navigate to the newly created PaleoSTeHM repo. Go to the tutorial you would like to run (i.e. /PaleoSTeHM/Tutorials/1.introduction/introduction.ipynb) right click and select "run from Google Colab".
pip install PaleoSTeHM
- 2024 PaleoSTeHM workshop, in collaboration with PALSEA (PALeo constraints on SEA level rise) - Day 1, Day 2.
- Basic Bayesian Statistics
- Basic Markov Chain Monte Carlo
- PaleoSTeHM background and data level modelling - Introduction to Bayesian Hierachical modelling, which consist of data level, process level and parameter level modelling. This notebook will cover data level modelling with an illustrative example of building data level model for coral-based sea-level records from the Great Barrier Reef.
- Process level and parameter level modelling - Process level and parameter level modelling tutorial, which will cover a range of process level model for paleo-environmental research, including hand-drawn model, linear model, change-point model, Gaussian Process model, physical model, and mixed physical and statistical model. Video tutorial here.
- Analysis Choice - Analysis choice tutorial, which will cover the difference between a deterministic model and a probablistic model (we will mostly use a Bayesian model), the optimization methods for deterministic model (least sqaures and gradient-based optimization) and inference method for Bayesian model, including Markov Chain Monte Carlo, Variational Bayes and Empirical Bayes. Video tutorial here.
- Gaussian Process background - Gaussian Process background tutorial, which covers the basics of Gaussian Process, including calculating squared distance matrix and covariance matrix, hyperparameter definitions and their impact, conditional probability and hyperparameter optimization. Video tutorial here.
- Gaussian Process kernels and kernel operations - Gaussian Process kernel tutorial, which introduces some popular GP kernels and instructions on how to combine different kernels. Video tutorial here.
- Incorporate temporal uncertainty in Gaussian Process - This tutorial introduce two commonly-used methods for Gaussian Process: noisy-input Gaussian Process and errors-in-variable Gaussian Process. Video tutorial here.
- Holocene sea-level analysis in New Jersey and Northern North Carolina - This tutorial will use the contents covered above in order to replicate Gaussian Process modelling results in New Jersey and Northern North Carolina as in Ashe et al., 2019.
- Spatio-temporal Gaussian Process Background - Background of building a Spatio-temporal Gaussian Process model. Video tutorial here.
- Spatio-temporal Gaussian Process with multiple kernels - Spatio-temporal Gaussian Process with multiple kernels with instructions on kernel decomposition. Video tutorial here.
- Spatio-temporal Gassusian Process with Physical Models - Spatio-temporal Gaussian Process in combination with one or multiple physical models. Video tutorial here.
-
Common Era Sea-Level Reconstruction - Reconstructing Common Era global sea-level change using method introduced in Kopp et al., 2016. Video tutorial here.
.
-
Updating Common Era sea-level curve - Updating Common Era global sea-level change by adding your own data along with Walker et al., 2022.
-
Quantify ocean temperature and thermal expansion effect - Using PaleoSTeHM temporal Gaussian Process (GP) framework to fit proxy data for ocean mean temperature from Shackleton et al. (2021) and to reproduce the time series of ocean temperature and its thermal expansion effect on global mean sea-level change from Creel et al. 2024, who used the PyMC library. .
- Automatic Spatiotemporal sea-level analysis - Automatic implementation/optimization/visulization of Holocene sea-level change using a spatiotemporal Gaussian Process model with a zero mean function.
This project is licensed under the MIT License - see the LICENSE file for details
This work is supported by the National Science Foundation under awards 2002437 and 2148265. The opinions, findings, and conclusions or recommendations expressed are those of the authors and do not necessarily reflect the views of the National Science Foundation.