Package Overview

Spatial-VTK is organized around the order you will usually move through a project: prepare your inputs, set project defaults, review data quality, calculate metrics, analyze spatial patterns, and make figures or dashboards.

This page is a map of the package. Use it to decide where to start, then go to the examples or API reference when you want runnable code or exact function signatures.

Workflow At A Glance

Step

Module

What You Use It For

1

io

Read waveform inputs, prepare metadata, and build inventories.

2

config

Set paths, bounds, metric choices, synthetic limits, and run scenarios.

3

qc

Build QC tables, summarize retained records, and prepare manual-review queues.

4

metrics

Calculate observed/synthetic metric values, residuals, and GOF scores.

5

spatial

Find station, event, path, geology, polygon, and corridor patterns.

6

visualize

Make context figures, QC figures, waveform figures, maps, and dashboards.

7

cli

Run the same workflows from the terminal with svtk.

io

Use io when you are turning your own files into tables Spatial-VTK can use.

Common tasks:

  • prepare station and event metadata with consistent column names

  • build observed/synthetic waveform inventories

  • preprocess waveform files once with configured filters or resampling

  • read catalog tables and synthetic model aliases

  • write artifact manifests for generated outputs

  • reshape metric tables for downstream workflows

Main areas:

  • io.metadata and io.inventory for prepared station, event, and waveform tables

  • io.waveforms, io.preprocessing, and io.synthetic_formats for waveform preprocessing and synthetic file helpers

  • io.artifacts and io.plans for reproducible output paths and metric plans

config

Use config when you want one place to define the project settings you reuse.

Common tasks:

  • resolve project paths and output folders

  • define named map bounds such as study_area

  • choose metric groups, transforms, passbands, components, and models

  • set synthetic maximum frequency limits

  • apply optional run_scenarios for repeatable variations

Start with Configuration if you are setting up a project config file.

qc

Use qc when you need to decide which records are reliable enough to keep.

Common tasks:

  • build trace and record inventories

  • apply reject rules and passband-specific checks

  • summarize retained and rejected records

  • export manual-review queues for the QC picker

Main areas:

  • qc.build for QC inventory and filtering logic

  • qc.review for manual-review tables

  • qc.summary for retention summaries and reject-rule helpers

metrics

Use metrics when you are ready to calculate waveform metrics and compare observed and synthetic records.

Common tasks:

  • calculate amplitude, duration, spectral, intensity, delay, and correlation metrics

  • compute residuals, log residuals, Anderson GOF scores, and Olsen-Mayhew GOF scores

  • run metric calculations locally, in batches, or with SLURM

  • enrich metric tables with station, event, path, and geologic metadata

  • prepare standard outputs for spatial analysis, plotting, and dashboards

Main areas:

  • metrics.calculate for metric math and table preparation

  • metrics.workflow for file-based task planning, batching, merging, and SLURM scripts

  • metrics.plot for metric-specific diagnostic figures

spatial

Use spatial when you want to understand where model performance changes across stations, events, paths, regions, or geologic settings.

Calculation tools:

  • station bias and event-centered residual fields

  • Moran’s I, permutation Moran tests, and distance-bin correlations

  • spatial holdout tests and residual-feature clustering

  • REDCAP spatial clustering

  • PCA spatial modes

  • bootstrap contrasts and geology-class joins

  • observed/synthetic spatial-pattern comparisons

Path, polygon, and corridor tools:

  • source-station geometry and distance/azimuth path summaries

  • GeoJSON station, event, and path classifications

  • polygon crossing, begins-in-polygon, and ends-in-polygon selections

  • boundary corridors built from keyword parameters

  • corridor path classification by membership, side, and path length

Plot and map tools:

  • correlograms, semivariograms, holdout diagnostics, and cluster summaries

  • PCA variance/loadings plots and PCA mode maps

  • station-bias maps, score maps, residual grids, and event residual maps

  • corridor and polygon-path maps

visualize

Use visualize when you want figures or interactive outputs rather than new tables.

Common tasks:

  • make basic station/event context maps and coverage figures

  • make QC and retention figures

  • make waveform record sections and trace-comparison figures

  • prepare dashboard datasets from long metric tables

  • launch Streamlit/Folium dashboards for metrics and QC review

Main areas:

  • visualize.context for project overview figures

  • visualize.qc for QC and retention figures

  • visualize.waveforms for record sections and waveform comparisons

  • visualize.dashboard for dashboard tables and Streamlit apps

cli

Use cli when you want to run package workflows from a terminal. The public command is svtk.

Common command groups:

  • svtk config for config discovery and inspection

  • svtk io for metadata and inventory preparation

  • svtk qc for QC review-queue exports

  • svtk metrics for metric task planning, execution, merging, and outputs

  • svtk plot, svtk map, and svtk visualize for file-backed figures

  • svtk dashboard for Streamlit dashboard launchers

See CLI API for command examples.

Where To Go Next