zsylvester / stratigraph

A set of tools for visualizing stratigraphic models

stratigraph

stratigraph is a Python package for visualizing and analyzing stratigraphic models. These models ideally have the topographic surfaces through time, not just the stratigraphy, although it is possible to tweak the code so that stratigraphy-only models are visualized. The 3D visualizations rely on Mayavi.

Stratigraphic data can be visualized in time or in space. In the time domain, stratigraph can be used create time-elevation (Barrell) plots and chronostratigraphic (Wheeler) diagrams. For example, here is the stratigraph version of Joseph Barrell's time-elevation plot from 1918:

Wheeler's first chronostratigraphic diagram (Wheeler, 1964) might look something like this:

stratigraph is best suited for more complex datasets, for example the ones derived from experiments where the surface topography is carefully tracked through time. For example, this is a dip section through the deposits of the XES-02 experiment, which was run at St. Anthony Falls Laboratory, University of Minnesota:

The cross section in the upper panel is colored by water depth (not grain size); the lower panel shows the corresponding Wheeler diagram.

stratigraph can also be used to display stratigraphic models in 3D; for example, this is a meandering river model (created with 'meanderpy'):

If you want to show more of the stratigraphy, you can create an 'exploded view':

The four Jupyter notebooks in this folder illustrate the ways stratigraph can be used to visualize stratigraphy.

For more details, see this paper.

Requirements

The following packages are required and will be installed when you install stratigraph.

• matplotlib
• numpy
• mayavi
• scipy
• scikit-learn
• scikit-image
• Pillow
• shapely
• tqdm

To run the Jupyter Notebooks, you will also need jupyter and pandas. See also the requirements.yml file. This file can be used to create a virtual environment.

Installation

First install mayavi according to the installation instructions. You can also install it with Conda: conda install -c conda-forge mayavi.

stratigraph can be installed using pip:

pip install stratigraph

Citing stratigraph

If you use stratigraph in your work, please cite this paper:

Sylvester, Z., Straub, K. M., and Covault, J. A. (2024), Stratigraphy in space and time: A reproducible approach to analysis and visualization, Earth Science Reviews, v. 250, 104706. https://doi.org/10.1016/j.earscirev.2024.104706

stratigraph's Issues

Add tests

If you plan to continue developing this tool, it's probably a good idea to start adding some tests, at least of the low-level functions. This will help you avoid breaking things that currently work.

The Pytest plugin pytest-mpl might also be useful for benchmarking plots to make sure they do not change too much.

I'd be happy to set up some basic tests which you can build on.

Use dynamic versioning

This will free you from having to remember to change the version in pyproject.toml.

The way to do it is to use setuptools_scm, see for example this example project

#2 already removed it from __init__.py, where its use is considered obsolete because the best way to find the package info is in its metadata.

Add some CI

When you have tests and/or are updating regularly, it will be nice to have automated integration, eg to build the package and run the tests when you push to main.

You can also automate the release process, eg upload to PyPI.