Metadata-Version: 2.1
Name: stratigraph
Version: 0.1.0
Summary: Stratigraphic visualization and analysis
Author-email: Zoltan Sylvester <zoltan.sylvester@beg.utexas.edu>
License: MIT License
        
        Copyright (c) 2024 Zoltan Sylvester
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/zsylvester/stratigraph
Project-URL: Bug Tracker, https://github.com/zsylvester/stratigraph/issues
Keywords: geology,geoscience,stratigraphy,chronostratigraphy,visualization
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Development Status :: 4 - Beta
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy <2.0
Requires-Dist: scipy
Requires-Dist: scikit-learn
Requires-Dist: scikit-image
Requires-Dist: shapely
Requires-Dist: pillow
Requires-Dist: matplotlib
Requires-Dist: mayavi
Requires-Dist: tqdm

<img src="images/stratigraph_logo.png" width="400">

## 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](https://docs.enthought.com/mayavi/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:

<img src="images/barrell_fig_100.png" width="600">

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

<img src="images/wheeler_reconstruction.png" width="600">

`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:

<img src="images/XES02_3D_dip_section_130.png" width="600">

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'):

<img src="images/meanderpy_model_1_v_small.jpg" width="600">

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

<img src="images/TWDB_17_1_exploded_view.png" width="600">

The four Jupyter notebooks in [this folder](notebooks) illustrate the ways `stratigraph` can be used to visualize stratigraphy.

For more details, see [this paper](https://doi.org/10.1016/j.earscirev.2024.104706).

## 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](https://docs.enthought.com/mayavi/mayavi/installation.html). You can also install it with Conda: `conda install -c conda-forge mayavi`.

`stratigraph` can be installed using `pip`:

```shell
pip install stratigraph
```

## Citing stratigraph

If you use `stratigraph` in your work, please cite this paper:
<blockquote>
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. <a href="https://doi.org/10.1016/j.earscirev.2024.104706">https://doi.org/10.1016/j.earscirev.2024.104706</a>
</blockquote>
