Metadata-Version: 2.4
Name: spatial-vtk
Version: 0.1.4
Summary: spatial-vtk provides spatial validation tools for ground-motion simulations, with data QC, residual and metric calculations, geologic metadata integration, spatial statistics, extensive mapping capabilities, and interactive dashboards for quantifying and visualizing model performance patterns.
Author-email: Brianna Birkel <birkel@usc.edu>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/bcbirkel/spatial-vtk
Project-URL: Documentation, https://bcbirkel.github.io/spatial-vtk/
Project-URL: Repository, https://github.com/bcbirkel/spatial-vtk
Project-URL: Issues, https://github.com/bcbirkel/spatial-vtk/issues
Project-URL: Changelog, https://bcbirkel.github.io/spatial-vtk/changelog.html
Keywords: ground motion,seismology,spatial statistics,model validation,earthquake simulations,geology,mapping
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: branca>=0.7
Requires-Dist: contextily>=1.6
Requires-Dist: folium>=0.17
Requires-Dist: geopandas>=1.0
Requires-Dist: matplotlib>=3.8
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: plotly>=6
Requires-Dist: pyarrow>=15
Requires-Dist: pyproj>=3.6
Requires-Dist: PyYAML>=6.0
Requires-Dist: rasterio>=1.3
Requires-Dist: scikit-learn>=1.4
Requires-Dist: scipy>=1.11
Requires-Dist: shapely>=2.0
Requires-Dist: statsmodels>=0.14
Requires-Dist: streamlit>=1.58
Requires-Dist: streamlit-folium>=0.26
Provides-Extra: docs
Requires-Dist: ipython>=8.24; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: sphinx<9,>=8; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4,>=3; extra == "docs"
Provides-Extra: dashboard
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.29; extra == "notebooks"
Requires-Dist: nbclient>=0.10; extra == "notebooks"
Requires-Dist: nbformat>=5.10; extra == "notebooks"
Provides-Extra: waveforms
Requires-Dist: gmprocess>=2.4; extra == "waveforms"
Requires-Dist: h5py>=3.10; extra == "waveforms"
Requires-Dist: obspy>=1.4; extra == "waveforms"
Requires-Dist: pyasdf>=0.8; extra == "waveforms"
Provides-Extra: validation
Requires-Dist: build>=1.2; extra == "validation"
Requires-Dist: coverage[toml]>=7.6; extra == "validation"
Requires-Dist: ipython>=8.24; extra == "validation"
Requires-Dist: pytest>=8; extra == "validation"
Requires-Dist: twine<7,>=6.2; extra == "validation"
Dynamic: license-file

# Spatial-VTK

[![CI](https://github.com/bcbirkel/spatial-vtk/actions/workflows/ci.yml/badge.svg)](https://github.com/bcbirkel/spatial-vtk/actions/workflows/ci.yml)
[![Docs](https://github.com/bcbirkel/spatial-vtk/actions/workflows/docs.yml/badge.svg)](https://github.com/bcbirkel/spatial-vtk/actions/workflows/docs.yml)
[![PyPI](https://img.shields.io/pypi/v/spatial-vtk.svg)](https://pypi.org/project/spatial-vtk/)
[![Python](https://img.shields.io/pypi/pyversions/spatial-vtk.svg)](https://pypi.org/project/spatial-vtk/)
[![License](https://img.shields.io/pypi/l/spatial-vtk.svg)](https://github.com/bcbirkel/spatial-vtk/blob/main/LICENSE)

`spatial-vtk` provides spatial validation tools for ground-motion simulations,
with data QC, residual and metric calculations, geologic metadata integration,
spatial statistics, mapping, and dashboard preparation for understanding model
performance patterns.

![Spatial-VTK workflow](https://raw.githubusercontent.com/bcbirkel/spatial-vtk/main/ValidationToolkit_Workflow.png)

## Install

Install from PyPI:

    python -m pip install spatial-vtk

Or create the conda environment and install from a source checkout:

    conda env create -f svtk_environment.yaml
    conda activate spatial-vtk
    python -m pip install -e .

The package imports as `spatial_vtk` and installs the `svtk` command:

    python -c "import spatial_vtk; print(spatial_vtk.__version__)"
    svtk --help

## Structure

- `spatial_vtk.io`: metadata preparation, input inventories, waveform
  preprocessing, manifests, and waveform format helpers.
- `spatial_vtk.config`: repository paths, bounds, and runtime settings.
- `spatial_vtk.qc`: quality-control build, review, and summary workflows.
- `spatial_vtk.metrics`: ground-motion metric and residual calculations.
- `spatial_vtk.spatial`: metric-field preparation, spatial correlation,
  PCA spatial modes, REDCAP and residual-feature clustering, geology joins,
  pattern tests, plots, and map helpers.
- `spatial_vtk.visualize`: context figures, QC views, and dashboard data.
- `spatial_vtk.cli`: command-line entry points.

See the [public documentation](https://bcbirkel.github.io/spatial-vtk/) for
installation, package overview, examples, API reference, support, and changelog
pages.

## Reproducible source tutorials (unreleased 0.1.4rc1)

This research/alpha package is under active validation. The existing PyPI 0.1.3
release does not contain these repairs. From this repaired source checkout:

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install ".[notebooks,waveforms]"
export SVTK_NO_BASEMAP=1
python tools/execute_tutorial_notebooks.py
```

The source example bundle includes ten original MiniSEED inputs, five events,
and 30 selected stations, with checksums in `data/examples/`. Examples are not
included in the wheel. Step 1 generates processed waveforms; Step 2 performs QC;
Step 3 calculates metrics and native ln(observed / synthetic) residuals.
Steps 4–7 use those generated results; run Steps 1–3 first.
See the tutorial index and CLI workflow for launch commands.

Notebooks find the checkout from its root or `docs/examples`. For downloaded
notebooks set `SVTK_PROJECT_ROOT` to the complete example checkout. Unset
`SVTK_NO_BASEMAP` to request Esri World Imagery backgrounds.

Base metric/statistics workflows do not require an arrival picker. PhaseNet is
an optional external TensorFlow installation with an explicit command and model;
see [the integration contract](docs/phasenet.rst). The PyPI package named
`phasenet` has a different interface and is not installed by Spatial-VTK.

CI runs unit tests on Python 3.10–3.12 and executes the complete waveform-to-QC-
to-metrics tutorial on Python 3.12. Sphinx builds documentation without executing
notebooks; the notebook runner retains execution evidence separately.
