spatial-vtk 0.1.0__tar.gz

spatial_vtk-0.1.0/CITATION.cff

@@ -0,0 +1,161 @@
+cff-version: 1.2.0
+message: "If you use spatial-vtk, please cite the package and the data, models, and software used by your workflow."
+title: "Spatial Validation Toolkit for Ground Motion Simulations"
+authors:
+  - family-names: Birkel
+    given-names: Brianna
+    email: birkel@usc.edu
+version: 0.1.0
+license: BSD-3-Clause
+repository-code: "https://github.com/bcbirkel/spatial-vtk"
+abstract: "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."
+keywords:
+  - ground-motion simulation
+  - validation
+  - residuals
+  - spatial statistics
+  - geologic metadata
+  - mapping
+references:
+  - type: data
+    title: "Southern California Seismic Network"
+    authors:
+      - name: "California Institute of Technology and U.S. Geological Survey"
+    doi: "10.7914/SN/CI"
+    url: "https://scedc.caltech.edu/"
+    notes: "Observed waveform and station metadata source for the public LA Basin examples."
+  - type: data
+    title: "Center for Engineering Strong Motion Data"
+    authors:
+      - name: "Center for Engineering Strong Motion Data"
+    url: "https://www.strongmotioncenter.org/"
+    notes: "Strong-motion data source for the public LA Basin examples."
+  - type: software
+    title: "gmprocess"
+    authors:
+      - name: "U.S. Geological Survey"
+    url: "https://github.com/usgs/groundmotion-processing"
+    notes: "Processing software used for the observed records in the public examples."
+  - type: software
+    title: "Salvus"
+    authors:
+      - name: "Mondaic AG"
+    url: "https://mondaic.com/"
+    notes: "Waveform simulation software used to generate the synthetic records in the public examples."
+  - type: software
+    title: "Unified Community Velocity Model"
+    authors:
+      - name: "Southern California Earthquake Center"
+    url: "https://github.com/SCECcode/UCVMC"
+    notes: "Velocity-model software context for the example synthetic simulations."
+  - type: data
+    title: "CVM-S4.26.M01"
+    authors:
+      - name: "Southern California Earthquake Center"
+    url: "https://www.scec.org/research/cvm"
+    notes: "SCEC community velocity model context for the example LA Basin synthetics."
+  - type: software
+    title: "contextily"
+    authors:
+      - name: "contextily developers"
+    url: "https://contextily.readthedocs.io/"
+    notes: "Basemap tile retrieval used by static Spatial-VTK map figures."
+  - type: data
+    title: "Esri World Imagery"
+    authors:
+      - name: "Esri"
+    url: "https://www.arcgis.com/home/item.html?id=10df2279f9684e4a9f6a7f08febac2a9"
+    notes: "Default static-map basemap source used by Spatial-VTK examples."
+  - type: data
+    title: "OpenStreetMap"
+    authors:
+      - name: "OpenStreetMap contributors"
+    url: "https://www.openstreetmap.org/copyright"
+    notes: "Optional dashboard and map tile source."
+  - type: data
+    title: "CARTO basemaps"
+    authors:
+      - name: "CARTO"
+    url: "https://carto.com/basemaps/"
+    notes: "Optional dashboard basemap source."
+  - type: software
+    title: "ObsPy"
+    authors:
+      - name: "The ObsPy Development Team"
+    doi: "10.1785/gssrl.81.3.530"
+    url: "https://github.com/obspy/obspy"
+  - type: software
+    title: "PhaseNet"
+    authors:
+      - family-names: Zhu
+        given-names: Weiqiang
+      - family-names: Beroza
+        given-names: Gregory C.
+    doi: "10.1093/gji/ggy423"
+    url: "https://github.com/AI4EPS/PhaseNet"
+  - type: software
+    title: "NumPy"
+    authors:
+      - name: "NumPy developers"
+    doi: "10.1038/s41586-020-2649-2"
+    url: "https://numpy.org/"
+  - type: software
+    title: "pandas"
+    authors:
+      - name: "pandas developers"
+    doi: "10.5281/zenodo.3509134"
+    url: "https://pandas.pydata.org/"
+  - type: software
+    title: "GeoPandas"
+    authors:
+      - name: "GeoPandas developers"
+    doi: "10.5281/zenodo.3946761"
+    url: "https://geopandas.org/"
+  - type: software
+    title: "Matplotlib"
+    authors:
+      - name: "Matplotlib Development Team"
+    doi: "10.1109/MCSE.2007.55"
+    url: "https://matplotlib.org/"
+  - type: software
+    title: "SciPy"
+    authors:
+      - name: "SciPy developers"
+    doi: "10.1038/s41592-019-0686-2"
+    url: "https://scipy.org/"
+  - type: software
+    title: "scikit-learn"
+    authors:
+      - name: "scikit-learn developers"
+    doi: "10.5555/1953048.2078195"
+    url: "https://scikit-learn.org/"
+  - type: software
+    title: "statsmodels"
+    authors:
+      - name: "statsmodels developers"
+    url: "https://www.statsmodels.org/"
+  - type: software
+    title: "Shapely"
+    authors:
+      - name: "Shapely developers"
+    url: "https://shapely.readthedocs.io/"
+  - type: software
+    title: "pyproj"
+    authors:
+      - name: "pyproj developers"
+    url: "https://pyproj4.github.io/pyproj/"
+  - type: software
+    title: "Folium"
+    authors:
+      - name: "Folium developers"
+    url: "https://python-visualization.github.io/folium/"
+  - type: software
+    title: "Streamlit"
+    authors:
+      - name: "Streamlit developers"
+    url: "https://streamlit.io/"
+  - type: software
+    title: "PyArrow"
+    authors:
+      - name: "Apache Arrow developers"
+    url: "https://arrow.apache.org/docs/python/"

spatial_vtk-0.1.0/DATA_PROVENANCE.md

@@ -0,0 +1,86 @@
+# Data Provenance
+
+Spatial-VTK does not download observed waveforms or run simulations for you.
+The public examples start from waveform and metadata files that have already
+been prepared so you can focus on the validation workflow.
+
+## Example Dataset
+
+The tutorial dataset is a five-event LA Basin subset under
+`data/examples/20260605_five_event_subset/`. It includes observed and synthetic
+MiniSEED files, event metadata, station metadata, and event-station tables for
+the tutorial notebooks.
+
+The supporting `data/examples/la_basin_five_event_subset/` folder contains
+lightweight event, station, and GeoJSON files used by the data-format examples
+and regional/corridor tutorials.
+
+The example events are southern California earthquakes with public USGS event
+pages:
+
+- `ci38038071`: M 4.4, 4 km N of La Verne, CA, 2018-08-29.
+- `ci38695658`: M 4.5, 3 km WSW of South El Monte, CA, 2020-09-19.
+- `ci39812319`: M 4.3, 2 km E of Carson, CA, 2021-09-18.
+- `ci39756418`: M 4.2, 3 km SW of San Bernardino, CA, 2024-01-25.
+- `ci40699207`: M 4.4, 4 km SSE of Highland Park, CA, 2024-08-12.
+
+## Observed Records
+
+Observed records in the public examples are derived from public southern
+California waveform sources:
+
+- Southern California Seismic Network (SCSN), network code `CI`,
+  DOI `10.7914/SN/CI`.
+- Center for Engineering Strong Motion Data (CESMD).
+
+The observed records were processed with `gmprocess` before they were packaged
+for the tutorial subset. The tutorial workflow applies a configurable 1 Hz
+lowpass preprocessing step to both observed and synthetic records before QC,
+metric calculations, waveform figures, spatial analysis, and dashboards.
+
+## Synthetic Records
+
+Synthetic records in the public examples were generated with Salvus for a
+southern California CVM-SI/CVM-S4.26.M01 velocity-model context. The model and
+simulation provenance should be cited as:
+
+- Salvus, for the waveform simulation software.
+- UCVM, for the velocity-model software context.
+- SCEC CVM-S4.26.M01, for the southern California velocity-model context.
+- SCEC, for the community model and regional seismic-modeling context.
+
+The synthetic files in the example bundle are tutorial-scale MiniSEED exports,
+not a complete simulation archive.
+
+## Geospatial Files
+
+The example GeoJSON files under `data/examples/**` are small tutorial regions
+used to demonstrate polygon joins, regional contrasts, and corridor/path
+selection. They are intended to show how the package works. For a real project,
+replace them with your own mapped geologic, geomorphic, administrative, or
+analysis-region polygons and cite those sources separately.
+
+The site/geology metadata examples are derived tutorial tables that show the
+expected column structure for mapped region labels, long region names, broad
+region classes, and geomorphology classes.
+
+## Basemaps
+
+Basemap files are not redistributed in this repository or in the PyPI wheel.
+Static map figures fetch basemap tiles at render time with `contextily` and
+default to Esri World Imagery. Dashboard maps are rendered with Folium/Leaflet
+and can use Esri, CARTO, or OpenStreetMap tile layers.
+
+You need network access for basemap-backed maps unless you configure a local
+tile cache. If you use basemaps in figures or dashboards, cite the tile provider
+required by your chosen basemap source. The root `CITATION.cff` includes
+references for `contextily`, Esri World Imagery, CARTO basemaps, and
+OpenStreetMap.
+
+## Package Dependencies
+
+Spatial-VTK depends on the scientific Python and geospatial ecosystem,
+including NumPy, pandas, GeoPandas, Matplotlib, SciPy, scikit-learn,
+statsmodels, Shapely, pyproj, ObsPy, PyArrow, Folium, Streamlit, and
+contextily. The root `CITATION.cff` lists the major package dependencies and
+example-data sources that should be cited when they are material to your work.

spatial_vtk-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Brianna Birkel
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT INCLUDING
+NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

spatial_vtk-0.1.0/MANIFEST.in

@@ -0,0 +1,32 @@
+# Purpose: keep PyPI source distributions focused on installable package files.
+# Usage: python -m build --no-isolation
+
+include README.md
+include LICENSE
+include CITATION.cff
+include DATA_PROVENANCE.md
+include RELEASE_CHECKLIST.md
+include pyproject.toml
+include svtk_environment.yaml
+include ValidationToolkit_Workflow.png
+
+recursive-include src/spatial_vtk *.py
+recursive-include src/spatial_vtk *.yaml
+
+prune .github
+prune data
+prune docs
+prune docs/_build
+prune outputs
+prune tests
+prune tools
+prune .cache
+prune build
+prune dist
+prune .pytest_cache
+prune **/__pycache__
+
+exclude .DS_Store
+global-exclude *.py[cod]
+global-exclude .DS_Store
+global-exclude *.ipynb

spatial_vtk-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: spatial-vtk
+Version: 0.1.0
+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.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: phasenet>=0.2.5
+Requires-Dist: plotly>=6
+Requires-Dist: pyarrow>=15
+Requires-Dist: pyproj>=3.6
+Requires-Dist: PyYAML>=6.0
+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: waveforms
+Requires-Dist: h5py>=3.10; extra == "waveforms"
+Requires-Dist: obspy>=1.4; 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](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 documentation in `docs/` for installation, package overview, examples,
+API reference, support, and changelog pages.

spatial_vtk-0.1.0/README.md

@@ -0,0 +1,47 @@
+# 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](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 documentation in `docs/` for installation, package overview, examples,
+API reference, support, and changelog pages.

spatial_vtk-0.1.0/RELEASE_CHECKLIST.md

@@ -0,0 +1,135 @@
+# Spatial-VTK Release Checklist
+
+Use this checklist before publishing `spatial-vtk` to PyPI. Run commands from
+the public repository root unless a step says otherwise.
+
+## 1. Start Clean
+
+Confirm the public repository contains only public files:
+
+    git status --short
+    find . \( -name '.DS_Store' -o -name '.cache' -o -name '.pytest_cache' -o -name '__pycache__' -o -name '*.pyc' -o -path './outputs' -o -path './docs/_build' -o -path './build' -o -path './src/spatial_vtk.egg-info' \) -print
+    rg -n "/[p]roject2|ValidationToolkit-[r]estructured|private-[c]luster-name" .
+
+The generated-artifact search should print nothing. The private-detail search
+should print nothing except intentional public contact or documentation text.
+Also scan any changed examples for local absolute paths, usernames, or private
+model/output directories before publishing.
+
+## 2. Validate Locally
+
+Use the Spatial-VTK conda environment or another environment with the
+validation, docs, dashboard, and waveform extras installed.
+
+    python -m pip install -e ".[validation,docs,dashboard,waveforms]"
+    MPLCONFIGDIR=/tmp/mplconfig_svtk python -m pytest -q
+    python -m compileall -q src tests
+    MPLCONFIGDIR=/tmp/mplconfig_svtk python -m sphinx -W -b html docs docs/_build/html
+
+Expected result: tests pass, compileall prints no output, and Sphinx reports
+`build succeeded`.
+
+## 3. Build and Check Distributions
+
+Remove any old distributions, then build fresh archives:
+
+    rm -rf dist build src/spatial_vtk.egg-info
+    python -m build --sdist --wheel
+    python -m twine check dist/*
+
+If you are building in an offline environment where isolated builds cannot
+download `wheel`, use `python -m build --no-isolation` from an environment that
+already has the validation extras installed.
+
+Inspect the source archive and wheel to confirm only installable package files
+are included. The PyPI archives should not include notebooks, example data,
+documentation builds, review outputs, generated caches, private package names,
+or repo-only tools:
+
+    tar -tf dist/spatial_vtk-*.tar.gz | rg '(^spatial_vtk-[^/]+/(data|docs|tests|tools|outputs|\.github|\.cache|build|dist)/|\.ipynb$|__pycache__|\.pyc$|\.DS_Store)' && exit 1 || true
+
+    python - <<'PY'
+    import pathlib
+    import zipfile
+    wheels = sorted(pathlib.Path("dist").glob("*.whl"))
+    if not wheels:
+        raise SystemExit("No wheel was built.")
+    with zipfile.ZipFile(wheels[0]) as zf:
+        names = zf.namelist()
+    assert any(name.startswith("spatial_vtk/") for name in names)
+    assert "spatial_vtk/config/default_outputs.yaml" in names
+    assert any(name.startswith("spatial_vtk/visualize/dashboard/") for name in names)
+    legacy_namespace = "validation" + "_toolkit/"
+    assert not any(name.startswith(legacy_namespace) for name in names)
+    assert not any(name.startswith("data/") for name in names)
+    assert not any(name.startswith("docs/") for name in names)
+    assert not any(name.startswith("tests/") for name in names)
+    assert not any(name.startswith("tools/") for name in names)
+    assert not any(name.endswith(".ipynb") for name in names)
+    assert not any("__pycache__" in name or name.endswith(".pyc") or name.endswith(".DS_Store") for name in names)
+    print(f"checked {wheels[0].name}: {len(names)} files")
+    PY
+
+## 4. Clean Wheel Smoke Test
+
+Install the wheel into a temporary target directory and run import/CLI checks:
+
+    rm -rf /tmp/spatial_vtk_wheel_smoke
+    python -m pip install --no-deps --target /tmp/spatial_vtk_wheel_smoke dist/spatial_vtk-*.whl
+    PYTHONPATH=/tmp/spatial_vtk_wheel_smoke python -c "import spatial_vtk; print(spatial_vtk.__version__)"
+    PYTHONPATH=/tmp/spatial_vtk_wheel_smoke python -m spatial_vtk.cli --help
+
+This smoke test intentionally uses `--no-deps` and reuses the active
+environment's dependencies. It verifies package contents and entry-point code
+without creating a permanent install.
+
+## 5. TestPyPI Dry Run
+
+This step requires TestPyPI credentials or an API token.
+
+    python -m twine upload --repository testpypi dist/*
+
+Then create a fresh environment and install from TestPyPI:
+
+    python -m venv /tmp/spatial-vtk-testpypi
+    source /tmp/spatial-vtk-testpypi/bin/activate
+    python -m pip install --upgrade pip
+    python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ spatial-vtk
+    python -c "import spatial_vtk; print(spatial_vtk.__version__)"
+    svtk --help
+
+If TestPyPI installation cannot resolve a dependency, fix package metadata
+before publishing to the real PyPI.
+
+## 6. Publish to PyPI
+
+Only publish after TestPyPI succeeds.
+
+    python -m twine upload dist/*
+
+Then verify installation in a fresh environment:
+
+    python -m venv /tmp/spatial-vtk-pypi
+    source /tmp/spatial-vtk-pypi/bin/activate
+    python -m pip install --upgrade pip
+    python -m pip install spatial-vtk
+    python -c "import spatial_vtk; print(spatial_vtk.__version__)"
+    svtk --help
+
+## 7. Tag and Announce
+
+After PyPI succeeds, tag the release in GitHub:
+
+    git tag -a v0.1.0 -m "spatial-vtk 0.1.0"
+    git push origin v0.1.0
+
+Create a GitHub release from the tag. Include the PyPI link, the documentation
+link, a short feature summary, known limitations, and citation guidance.
+
+## 8. Cleanup
+
+Remove generated artifacts before the next development cycle:
+
+    rm -rf build dist docs/_build src/spatial_vtk.egg-info .pytest_cache
+    find . -name '__pycache__' -type d -prune -exec rm -rf {} +
+    find . \( -name '*.pyc' -o -name '.DS_Store' \) -type f -delete