Spatial Analysis API

Spatial modules prepare metric fields, calculate spatial statistics, work with GeoJSON regions and corridors, and create maps and spatial diagnostic plots.

Package Entry Point

Spatial calculations, plots, and map helpers.

Calculate

Prepare metric tables for spatial statistics.

Calculation Prepare Stats Overview

This module turns wide observed/synthetic metric tables into event-centered fields and station-level summaries used by spatial autocorrelation, clustering, and geology-class tests.

spatial_vtk.spatial.calculate.prepare_stats.available_metrics(df: DataFrame) → list[str]

Return metric families available in a normalized metrics table.

Parameters:

• df (pandas.DataFrame) – Metrics table.

• df – Required function argument.

Returns:

Metric stems such as C5 and PSA_T1.

Return type:

list of str

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.spatial.calculate.prepare_stats.build_metric_field(df: DataFrame, metric: str | None = None, *, field_mode: str | None = None, value_column: str | None = None) → DataFrame

Build an event-station analysis field for one metric.

Parameters:

• df (pandas.DataFrame) – Normalized metrics table.

• metric (str | None, optional) – Metric stem. When omitted, spatial.metric from the active config is used.

• field_mode (str | None, optional) – Value selector for the field. For long metric tables this is usually a transform column such as "log2_residual". For wide metric tables, "auto", "log2_ratio", or "score" are supported.

• value_column (str | None, optional) – Clearer alias for field_mode when selecting a long-table value column.

• df – Required function argument.

• metric – Optional function argument. Defaults to None.

• field_mode – Optional function argument. Defaults to None.

• value_column – Optional function argument. Defaults to None.

Returns:

Field table with field_value and metadata columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.build_station_feature_table(centered_df: DataFrame, *, station_col: str = 'station', lat_col: str = 'lat', lon_col: str = 'lon', feature_id_col: str = 'event_id', value_col: str = 'field_centered', aggfunc: str = 'mean') → DataFrame

Build a station-feature matrix for clustering and PCA.

Parameters:

• centered_df (pandas.DataFrame) – Event-centered metric field table.

• station_col (str, optional) – Columns identifying stations and station coordinates.

• lat_col (str, optional) – Columns identifying stations and station coordinates.

• lon_col (str, optional) – Columns identifying stations and station coordinates.

• feature_id_col (str, optional) – Column whose values become feature columns, usually event_id.

• value_col (str, optional) – Numeric value summarized for each station-feature pair.

• aggfunc (str, optional) – Aggregation used when more than one row exists per station-feature pair.

• centered_df – Required function argument.

• station_col – Optional function argument. Defaults to 'station'.

• lat_col – Optional function argument. Defaults to 'lat'.

• lon_col – Optional function argument. Defaults to 'lon'.

• feature_id_col – Optional function argument. Defaults to 'event_id'.

• value_col – Optional function argument. Defaults to 'field_centered'.

• aggfunc – Optional function argument. Defaults to 'mean'.

Returns:

One row per station with coordinate columns and one numeric feature column per feature id.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.center_field_by_event(field_df: DataFrame, *, min_stations_per_event: int | None = None, remove_event_mean: bool | None = None) → DataFrame

Center a metric field within each event.

Parameters:

• field_df (pandas.DataFrame) – Event-station metric field.

• min_stations_per_event (int | None, optional) – Minimum number of stations required for an event.

• remove_event_mean (bool | None, optional) – When false, keep raw values in field_centered. When omitted, spatial.remove_event_mean from the active config is used.

• field_df – Required function argument.

• min_stations_per_event – Optional function argument. Defaults to None.

• remove_event_mean – Optional function argument. Defaults to None.

Returns:

Event-centered field table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.center_field_by_reference_mask(field_df: DataFrame, reference_mask: Series | ndarray | list[bool], *, min_stations_per_event: int = 3) → DataFrame

Center event fields using a selected reference subset.

Parameters:

• field_df (pandas.DataFrame) – Event-station metric field.

• reference_mask (pandas.Series | numpy.ndarray | list[bool]) – Boolean mask marking rows used to estimate each event mean.

• min_stations_per_event (int, optional) – Minimum number of reference stations required for an event.

• field_df – Required function argument.

• reference_mask – Required function argument.

• min_stations_per_event – Optional function argument. Defaults to 3.

Returns:

Copy with event means and centered fields.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.collapse_and_event_demean(df: DataFrame) → DataFrame

Collapse component rows and subtract each event mean.

Parameters:

• df (pandas.DataFrame) – Long event-station table with value_raw and class columns.

• df – Required function argument.

Returns:

Event-station table with event-demeaned value.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.collapse_and_reference_demean(df: DataFrame, *, reference: str = 'pooled') → DataFrame

Collapse rows and subtract pooled or per-dataset event references.

Parameters:

• df (pandas.DataFrame) – Long observed/synthetic event-station table.

• reference (str, optional) – "pooled" subtracts one observed+synthetic event mean; "independent" subtracts separate means by dataset.

• df – Required function argument.

• reference – Optional function argument. Defaults to 'pooled'.

Returns:

Event-station table with anomaly values.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.normalize_metrics_table(df: DataFrame, *, source_path: str | Path | None = None, default_model: str | None = None) → DataFrame

Normalize supported metrics tables to a common spatial-statistics schema.

Parameters:

• df (pandas.DataFrame) – Metrics table with observed/synthetic values and station coordinates.

• source_path (str | pathlib.Path | None, optional) – Optional path used to infer a model label when no model column exists.

• default_model (str | None, optional) – Optional model label that overrides path inference.

• df – Required function argument.

• source_path – Optional function argument. Defaults to None.

• default_model – Optional function argument. Defaults to None.

Returns:

Copy with canonical model, band, component, event, station, and coordinate columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.resolve_metric_name(metric: str, df: DataFrame) → str

Resolve a user metric token to an available metric family.

Parameters:

• metric (str) – Requested metric token.

• df (pandas.DataFrame) – Metrics table.

• metric – Required function argument.

• df – Required function argument.

Returns:

Canonical metric family name.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.spatial.calculate.prepare_stats.summarize_event_locations(field_df: DataFrame) → DataFrame

Summarize one coordinate point per event.

Parameters:

• field_df (pandas.DataFrame) – Metric field table with event coordinate columns.

• field_df – Required function argument.

Returns:

Event coordinate and station-count table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.prepare_stats.summarize_station_bias(field_df: DataFrame, *, min_events_per_station: int | None = None, value_col: str | None = None, center_by_event: bool | None = None, min_stations_per_event: int | None = None) → DataFrame

Summarize persistent station bias from raw or event-centered fields.

Parameters:

• field_df (pandas.DataFrame) – Raw metric field table with field_value or event-centered field table with field_centered.

• min_events_per_station (int | None, optional) – Minimum distinct events needed to retain a station. When omitted, spatial.min_events_per_station from the active config is used.

• value_col (str | None, optional) – Explicit value column to summarize. When omitted, the helper uses field_centered if present, otherwise raw field_value.

• center_by_event (bool | None, optional) – When true, first remove the per-event mean before station summaries. When omitted, an existing field_centered column is used as-is, and raw fields are summarized without event centering.

• min_stations_per_event (int | None, optional) – Minimum station support used only when center_by_event=True.

• field_df – Required function argument.

• min_events_per_station – Optional function argument. Defaults to None.

• value_col – Optional function argument. Defaults to None.

• center_by_event – Optional function argument. Defaults to None.

• min_stations_per_event – Optional function argument. Defaults to None.

Returns:

Station-level bias table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Spatial autocorrelation, distance-bin summaries, and holdout diagnostics.

class spatial_vtk.spatial.calculate.correlation.CorrelationLengthFit(correlation_length_km: float, effective_range_km: float, method: str, n_bins_used: int)

Container for exponential correlation-length estimates.

class spatial_vtk.spatial.calculate.correlation.MoranResult(n: int, k: int, moran_i: float, p_two_sided: float, permutations: int)

Container for global Moran’s I output.

spatial_vtk.spatial.calculate.correlation.assign_spatial_blocks(station_df: DataFrame, *, block_size_km: float = 50.0) → DataFrame

Assign stations to simple Cartesian spatial blocks.

Parameters:

• station_df (pandas.DataFrame) – Required function argument.

• block_size_km (float, optional) – Optional function argument. Defaults to 50.0.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.correlation.build_directional_distance_bin_summary(centered_df: DataFrame, **kwargs) → DataFrame

Build a direction-resolved correlogram and semivariogram summary.

Parameters:

• centered_df (pandas.DataFrame) – Required function argument.

• kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.correlation.build_distance_bin_summary(centered_df: DataFrame, **kwargs) → DataFrame

Build an isotropic correlogram and semivariogram summary.

Parameters:

• centered_df (pandas.DataFrame) – Required function argument.

• kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.correlation.build_pair_summaries(centered_df: DataFrame, *, bin_width_km: float = 10.0, max_distance_km: float = 200.0, max_pairs_per_event: int = 20000, direction_bin_width_deg: float = 45.0, random_seed: int = 42) → tuple[DataFrame, DataFrame]

Build isotropic and direction-resolved pair summaries.

Parameters:

• centered_df (pandas.DataFrame) – Event-centered field table with field_centered and field_z.

• bin_width_km (float, optional) – Distance-bin configuration.

• max_distance_km (float, optional) – Distance-bin configuration.

• max_pairs_per_event (int, optional) – Maximum station pairs sampled for each event.

• direction_bin_width_deg (float, optional) – Direction-sector width for anisotropy summaries.

• random_seed (int, optional) – Seed for pair sampling.

• centered_df – Required function argument.

• bin_width_km – Optional function argument. Defaults to 10.0.

• max_distance_km – Optional function argument. Defaults to 200.0.

• max_pairs_per_event – Optional function argument. Defaults to 20000.

• direction_bin_width_deg – Optional function argument. Defaults to 45.0.

• random_seed – Optional function argument. Defaults to 42.

Returns:

Isotropic distance-bin summary and directional distance-bin summary.

Return type:

tuple of pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.correlation.build_station_catalog(field_df: DataFrame) → DataFrame

Build a unique station catalog from an event-station field.

Parameters:

field_df (pandas.DataFrame) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.correlation.compute_global_morans_i(station_df: DataFrame, *, value_column: str = 'mean_centered', lat_column: str = 'lat', lon_column: str = 'lon', k: int | None = None, permutations: int | None = None, random_seed: int | None = None) → MoranResult | None

Compute global Moran’s I for station-level values.

Parameters:

• station_df (pandas.DataFrame) – Station table with coordinates and a value column.

• value_column (str, optional) – Column names used for values and coordinates.

• lat_column (str, optional) – Column names used for values and coordinates.

• lon_column (str, optional) – Column names used for values and coordinates.

• k (int | None, optional) – Number of nearest spatial neighbors.

• permutations (int | None, optional) – Number of random permutations for a two-sided p-value.

• random_seed (int | None, optional) – Seed for reproducible permutation tests.

• station_df – Required function argument.

• value_column – Optional function argument. Defaults to 'mean_centered'.

• lat_column – Optional function argument. Defaults to 'lat'.

• lon_column – Optional function argument. Defaults to 'lon'.

• k – Optional function argument. Defaults to None.

• permutations – Optional function argument. Defaults to None.

• random_seed – Optional function argument. Defaults to None.

Returns:

Moran’s I result, or None when too few valid stations exist.

Return type:

MoranResult or None

Returns:

Return value produced by the function.

Return type:

spatial_vtk.spatial.calculate.correlation.MoranResult | None

spatial_vtk.spatial.calculate.correlation.evaluate_spatial_block_holdouts(field_df: DataFrame, *, block_size_km: float = 50.0, min_block_stations: int = 3, min_stations_per_event: int = 3, min_events_per_station: int = 3, prediction_k: int = 8, prediction_distance_power: float = 2.0, max_folds: int | None = None) → tuple[DataFrame, DataFrame, DataFrame]

Evaluate station-bias generalization with leave-one-spatial-block-out folds.

Parameters:

• field_df (pandas.DataFrame) – Required function argument.

• block_size_km (float, optional) – Optional function argument. Defaults to 50.0.

• min_block_stations (int, optional) – Optional function argument. Defaults to 3.

• min_stations_per_event (int, optional) – Optional function argument. Defaults to 3.

• min_events_per_station (int, optional) – Optional function argument. Defaults to 3.

• prediction_k (int, optional) – Optional function argument. Defaults to 8.

• prediction_distance_power (float, optional) – Optional function argument. Defaults to 2.0.

• max_folds (int | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.correlation.fit_exponential_correlation_length(distance_df: DataFrame, *, min_pairs_per_bin: int = 20) → CorrelationLengthFit | None

Fit an exponential correlation length to a binned correlogram.

Parameters:

• distance_df (pandas.DataFrame) – Required function argument.

• min_pairs_per_bin (int, optional) – Optional function argument. Defaults to 20.

Returns:

Return value produced by the function.

Return type:

spatial_vtk.spatial.calculate.correlation.CorrelationLengthFit | None

spatial_vtk.spatial.calculate.correlation.moran_result_to_frame(result: MoranResult | None) → DataFrame

Convert one Moran’s I result into a dataframe.

Parameters:

• result (spatial_vtk.spatial.calculate.correlation.MoranResult | None) – Output from compute_global_morans_i.

• result – Required function argument.

Returns:

One-row Moran summary, or an empty table with the expected columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.correlation.predict_station_bias_idw(train_station_df: DataFrame, test_station_df: DataFrame, *, knn: int = 8, distance_power: float = 2.0) → DataFrame

Predict held-out station bias from nearby training stations using IDW.

Parameters:

• train_station_df (pandas.DataFrame) – Required function argument.

• test_station_df (pandas.DataFrame) – Required function argument.

• knn (int, optional) – Optional function argument. Defaults to 8.

• distance_power (float, optional) – Optional function argument. Defaults to 2.0.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.correlation.summarize_directional_fits(directional_df: DataFrame, *, min_pairs_per_bin: int = 20) → DataFrame

Fit one exponential correlation length per directional sector.

Parameters:

• directional_df (pandas.DataFrame) – Required function argument.

• min_pairs_per_bin (int, optional) – Optional function argument. Defaults to 20.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Station residual-feature clustering and REDCAP regionalization.

class spatial_vtk.spatial.calculate.clustering.ClusterSolutionSummary(n_clusters: int, silhouette: float, inertia: float, n_samples: int, n_features: int)

Container for one residual-clustering solution.

spatial_vtk.spatial.calculate.clustering.assign_redcap_clusters(station_summary: DataFrame, *, value_col: str = 'avg_observed_metric_distance_scaled_event_demeaned', min_k: int = 2, max_k: int = 8, n_neighbors: int = 2, location_weight: float = 0.1, residual_weight: float = 2.0, lon_col: str = 'station_longitude', lat_col: str = 'station_latitude') → tuple[DataFrame, DataFrame]

Assign spatially constrained REDCAP clusters to station residuals.

Parameters:

• station_summary (pandas.DataFrame) – Station-level table with coordinate and residual columns.

• value_col (str, optional) – Residual or metric-anomaly value used in the regionalization.

• min_k (int, optional) – Candidate regional cluster-count range.

• max_k (int, optional) – Candidate regional cluster-count range.

• n_neighbors (int, optional) – Spatial neighbors used to build the constraint graph.

• location_weight (float, optional) – Weights applied to standardized coordinate and residual features.

• residual_weight (float, optional) – Weights applied to standardized coordinate and residual features.

• lon_col (str, optional) – Coordinate column names.

• lat_col (str, optional) – Coordinate column names.

• station_summary – Required function argument.

• value_col – Optional function argument. Defaults to 'avg_observed_metric_distance_scaled_event_demeaned'.

• min_k – Optional function argument. Defaults to 2.

• max_k – Optional function argument. Defaults to 8.

• n_neighbors – Optional function argument. Defaults to 2.

• location_weight – Optional function argument. Defaults to 0.1.

• residual_weight – Optional function argument. Defaults to 2.0.

• lon_col – Optional function argument. Defaults to 'station_longitude'.

• lat_col – Optional function argument. Defaults to 'station_latitude'.

Returns:

Clustered station table and candidate-score table.

Return type:

tuple of pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.clustering.build_joint_metric_fingerprint(station_bias_lookup: dict[str, DataFrame], *, min_metrics_per_station: int = 2) → DataFrame

Build a station-by-metric feature matrix from station-bias summaries.

Parameters:

• station_bias_lookup (dict) – Required function argument.

• min_metrics_per_station (int, optional) – Optional function argument. Defaults to 2.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.clustering.build_spatial_neighbor_graph(coords: ndarray, *, n_neighbors: int) → dict[int, set[int]]

Build a connected nearest-neighbor graph for REDCAP constraints.

Parameters:

• coords (numpy.ndarray) – Required function argument.

• n_neighbors (int) – Required function argument.

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.spatial.calculate.clustering.build_station_event_fingerprint(centered_df: DataFrame, station_df: DataFrame, *, min_events_per_station: int = 3) → DataFrame

Build a station-by-event feature matrix for one metric.

Parameters:

• centered_df (pandas.DataFrame) – Event-centered residual field.

• station_df (pandas.DataFrame) – Station-bias table.

• min_events_per_station (int, optional) – Minimum event support per station.

• centered_df – Required function argument.

• station_df – Required function argument.

• min_events_per_station – Optional function argument. Defaults to 3.

Returns:

Station metadata plus event feature columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.clustering.connected_components(adjacency: dict[int, set[int]]) → list[list[int]]

Return connected components from an undirected adjacency dictionary.

Parameters:

adjacency (dict) – Required function argument.

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.spatial.calculate.clustering.redcap_labels(regions: dict[int, dict[str, object]], n_stations: int) → ndarray

Convert active REDCAP regions into a station-label vector.

Parameters:

• regions (dict) – Required function argument.

• n_stations (int) – Required function argument.

Returns:

Return value produced by the function.

Return type:

numpy.ndarray

spatial_vtk.spatial.calculate.clustering.redcap_merge_cost(left: dict[str, object], right: dict[str, object]) → float

Return Ward-style merge cost for two candidate REDCAP regions.

Parameters:

• left (dict) – Required function argument.

• right (dict) – Required function argument.

Returns:

Return value produced by the function.

Return type:

float

spatial_vtk.spatial.calculate.clustering.run_residual_feature_clustering(feature_df: DataFrame, *, cluster_min_k: int | None = None, cluster_max_k: int | None = None, min_nonmissing_per_row: int = 1, random_seed: int | None = None) → tuple[DataFrame, DataFrame, DataFrame, DataFrame, ClusterSolutionSummary | None, list[str]]

Cluster station residual fingerprints with K-means and silhouette selection.

Parameters:

• feature_df (pandas.DataFrame) – Required function argument.

• cluster_min_k (int | None, optional) – Optional function argument. Defaults to None.

• cluster_max_k (int | None, optional) – Optional function argument. Defaults to None.

• min_nonmissing_per_row (int, optional) – Optional function argument. Defaults to 1.

• random_seed (int | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.clustering.summarize_cluster_assignments(assignments_df: DataFrame) → DataFrame

Summarize station counts and spatial spread for cluster assignments.

Parameters:

assignments_df (pandas.DataFrame) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.clustering.summarize_cluster_feature_values(assignments_df: DataFrame, raw_feature_df: DataFrame, *, feature_columns: list[str]) → DataFrame

Summarize raw feature values within each cluster.

Parameters:

• assignments_df (pandas.DataFrame) – Required function argument.

• raw_feature_df (pandas.DataFrame) – Required function argument.

• feature_columns (list) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.clustering.summarize_joint_station_bias(joint_fingerprint_df: DataFrame) → DataFrame

Summarize one cross-metric station-bias value for each station.

Parameters:

joint_fingerprint_df (pandas.DataFrame) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

PCA spatial-mode calculations for station residual fingerprints.

PCA Calculations Overview

This module extracts orthogonal station-level spatial modes from event, metric, or residual-feature matrices. Rows represent stations and columns represent residual features such as event-centered metric values.

class spatial_vtk.spatial.calculate.pca.PCASpatialModeResult(station_scores: DataFrame, feature_loadings: DataFrame, explained_variance: DataFrame, feature_columns: list[str])

Container for PCA spatial-mode outputs.

spatial_vtk.spatial.calculate.pca.compute_pca_spatial_modes(feature_df: DataFrame, *, feature_columns: Sequence[str] | None = None, metadata_columns: Sequence[str] = ('station', 'lat', 'lon'), n_components: int | None = None, min_nonmissing_per_station: int = 1, standardize: bool = True, component_prefix: str = 'PC') → PCASpatialModeResult

Compute PCA spatial modes from a station-feature table.

Parameters:

• feature_df (pandas.DataFrame) – Table with one row per station and residual-feature columns.

• feature_columns (Optional, optional) – Optional explicit feature columns. When omitted, numeric non-metadata columns are used.

• metadata_columns (Sequence, optional) – Columns copied into the station-score output.

• n_components (int | None, optional) – Requested number of principal components.

• min_nonmissing_per_station (int, optional) – Minimum number of finite feature values required to keep a station.

• standardize (bool, optional) – Whether to z-score features before PCA.

• component_prefix (str, optional) – Prefix used for component labels, such as "PC".

• feature_df – Required function argument.

• feature_columns – Optional function argument. Defaults to None.

• metadata_columns – Optional function argument. Defaults to ('station', 'lat', 'lon').

• n_components – Optional function argument. Defaults to None.

• min_nonmissing_per_station – Optional function argument. Defaults to 1.

• standardize – Optional function argument. Defaults to True.

• component_prefix – Optional function argument. Defaults to 'PC'.

Returns:

Station score table, feature loading table, explained-variance table, and the feature columns used in the model.

Return type:

PCASpatialModeResult

Returns:

Return value produced by the function.

Return type:

spatial_vtk.spatial.calculate.pca.PCASpatialModeResult

Geology-class joins and station-level spatial/geology tests.

spatial_vtk.spatial.calculate.geology.add_station_geology_classes(df: DataFrame, *, region_records: list[dict[str, object]], target_region_geom: object, edge_buffer_km: float, lon_col: str = 'station_longitude', lat_col: str = 'station_latitude') → DataFrame

Add target-region edge-zone and mapped-region labels to station rows.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• region_records (list) – Required function argument.

• target_region_geom (object) – Required function argument.

• edge_buffer_km (float) – Required function argument.

• lon_col (str, optional) – Optional function argument. Defaults to 'station_longitude'.

• lat_col (str, optional) – Optional function argument. Defaults to 'station_latitude'.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.bootstrap_contrast(events: DataFrame, *, group_col: str, left_values: tuple[str, ...], right_values: tuple[str, ...], n_bootstrap: int, rng: Generator, min_stations_per_group: int = 3, statistic: str = 'mean') → dict[str, float | int | str]

Calculate a station-level contrast with event bootstrap uncertainty.

Parameters:

• events (pandas.DataFrame) – Event-station table with station_name, event_id, value, and the configured geology class column.

• group_col (str) – Geology or metadata class column.

• left_values (tuple) – Class labels compared as left minus right.

• right_values (tuple) – Class labels compared as left minus right.

• n_bootstrap (int) – Number of event-bootstrap draws.

• rng (numpy.random._generator.Generator) – NumPy random generator used for reproducible resampling.

• min_stations_per_group (int, optional) – Minimum finite station means required on each side.

• statistic (str, optional) – Station-summary statistic for each side. Choose "mean" or "median".

• events – Required function argument.

• group_col – Required function argument.

• left_values – Required function argument.

• right_values – Required function argument.

• n_bootstrap – Required function argument.

• rng – Required function argument.

• min_stations_per_group – Optional function argument. Defaults to 3.

• statistic – Optional function argument. Defaults to 'mean'.

Returns:

Effect, confidence interval, p-value, and support counts.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.spatial.calculate.geology.bootstrap_contrast_table(events: DataFrame, *, station_metadata: DataFrame | None = None, station_col: str = 'station', event_col: str = 'event_id', value_col: str = 'field_centered', group_col: str | None = None, left_values: tuple[str, ...] | None = None, right_values: tuple[str, ...] | None = None, baseline_values: tuple[str, ...] | None = None, compare_values: tuple[str, ...] | list[str] | list[tuple[str, ...]] | None = None, class_values: tuple[str, ...] | list[str] | None = None, min_stations_per_group: int | None = None, n_bootstrap: int | None = None, random_seed: int | None = None, statistic: str | None = None, outpath: str | Path | None = None) → DataFrame

Calculate geology contrasts and return a table.

Parameters:

• events (pandas.DataFrame) – Event-station residual table.

• station_metadata (pandas.DataFrame | None, optional) – Optional station metadata table containing the grouping column.

• station_col (str, optional) – Columns identifying station, event, and residual value.

• event_col (str, optional) – Columns identifying station, event, and residual value.

• value_col (str, optional) – Columns identifying station, event, and residual value.

• group_col (str | None, optional) – Metadata class column used for the contrast. When omitted, spatial.geology_group_column from the active config is used.

• left_values (tuple[str, ...] | None, optional) – Class labels compared as left minus right. These names describe the two class sets being compared; they are not map directions. The reported effect is statistic(left_values) - statistic(right_values). When omitted, configured geology contrast classes are used.

• right_values (tuple[str, ...] | None, optional) – Class labels compared as left minus right. These names describe the two class sets being compared; they are not map directions. The reported effect is statistic(left_values) - statistic(right_values). When omitted, configured geology contrast classes are used.

• baseline_values (tuple[str, ...] | None, optional) – Optional baseline mode. When baseline_values is provided, one contrast row is generated for each comparison class or class group: comparison - baseline. compare_values can be a list of class names for separate comparisons or a list of tuples for grouped comparisons. class_values can limit or order the plotted/classes considered when compare_values is omitted.

• compare_values (tuple[str, ...] | list[str] | list[tuple[str, ...]] | None, optional) – Optional baseline mode. When baseline_values is provided, one contrast row is generated for each comparison class or class group: comparison - baseline. compare_values can be a list of class names for separate comparisons or a list of tuples for grouped comparisons. class_values can limit or order the plotted/classes considered when compare_values is omitted.

• class_values (tuple[str, ...] | list[str] | None, optional) – Optional baseline mode. When baseline_values is provided, one contrast row is generated for each comparison class or class group: comparison - baseline. compare_values can be a list of class names for separate comparisons or a list of tuples for grouped comparisons. class_values can limit or order the plotted/classes considered when compare_values is omitted.

• min_stations_per_group (int | None, optional) – Minimum station count required on each side of the contrast. When omitted, the active config value is used.

• n_bootstrap (int | None, optional) – Number of event-bootstrap draws. When omitted, the active config value is used.

• random_seed (int | None, optional) – Seed for reproducible bootstrap sampling. When omitted, the active config value is used.

• statistic (str | None, optional) – Station-summary statistic for each contrast. Choose "mean" or "median".

• outpath (str | pathlib.Path | None, optional) – Optional CSV output path.

• events – Required function argument.

• station_metadata – Optional function argument. Defaults to None.

• station_col – Optional function argument. Defaults to 'station'.

• event_col – Optional function argument. Defaults to 'event_id'.

• value_col – Optional function argument. Defaults to 'field_centered'.

• group_col – Optional function argument. Defaults to None.

• left_values – Optional function argument. Defaults to None.

• right_values – Optional function argument. Defaults to None.

• baseline_values – Optional function argument. Defaults to None.

• compare_values – Optional function argument. Defaults to None.

• class_values – Optional function argument. Defaults to None.

• min_stations_per_group – Optional function argument. Defaults to None.

• n_bootstrap – Optional function argument. Defaults to None.

• random_seed – Optional function argument. Defaults to None.

• statistic – Optional function argument. Defaults to None.

• outpath – Optional function argument. Defaults to None.

Returns:

Contrast table with one row per comparison. The table includes class sets, contrast labels, effect direction, percent effects when the field is a log2 observed/synthetic ratio, and significance flags.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.build_c_events(df: DataFrame, c_metrics: list[str], passbands: list[str], *, anomaly_reference: str = 'pooled') → DataFrame

Build matched observed and synthetic event-station rows for C metrics.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• c_metrics (list) – Required function argument.

• passbands (list) – Required function argument.

• anomaly_reference (str, optional) – Optional function argument. Defaults to 'pooled'.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.build_observed_c_events(df: DataFrame, c_metrics: list[str], passbands: list[str]) → DataFrame

Build event-demeaned observed anomaly rows for C metrics.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• c_metrics (list) – Required function argument.

• passbands (list) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.build_observed_psa_events(df: DataFrame, psa_metrics: list[str]) → DataFrame

Build event-demeaned observed anomaly rows for raw PSA periods.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• psa_metrics (list) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.build_psa_events(df: DataFrame, psa_metrics: list[str], *, anomaly_reference: str = 'pooled') → DataFrame

Build matched observed and synthetic event-station rows for PSA periods.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• psa_metrics (list) – Required function argument.

• anomaly_reference (str, optional) – Optional function argument. Defaults to 'pooled'.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.build_residual_c_events(df: DataFrame, c_metrics: list[str], passbands: list[str]) → DataFrame

Build event-demeaned log2 observed/synthetic residual rows for C metrics.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• c_metrics (list) – Required function argument.

• passbands (list) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.build_residual_psa_events(df: DataFrame, psa_metrics: list[str]) → DataFrame

Build event-demeaned log2 observed/synthetic residual rows for PSA periods.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• psa_metrics (list) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.discover_metric_stems(columns: Iterable[str], *, require_syn: bool) → tuple[list[str], list[str]]

Discover C-metric and PSA metric stems in a metrics table.

Parameters:

• columns (Iterable) – Required function argument.

• require_syn (bool) – Required function argument.

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.geology.hypocentral_distance(df: DataFrame) → ndarray

Compute hypocentral event-station distances in kilometers.

Parameters:

df (pandas.DataFrame) – Required function argument.

Returns:

Return value produced by the function.

Return type:

numpy.ndarray

spatial_vtk.spatial.calculate.geology.load_region_geometries(geojson_path: str | Path, *, region_name: str | None = None) → tuple[list[dict[str, object]], object]

Load mapped-region records and a target-region geometry from GeoJSON.

Parameters:

• geojson_path (str | pathlib.Path) – Required function argument.

• region_name (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.geology.matched_piece(subset: DataFrame, *, metric: str, suffix: str, bin_label: str) → DataFrame

Convert matched observed/synthetic rows into one dataset’s anomaly rows.

Parameters:

• subset (pandas.DataFrame) – Required function argument.

• metric (str) – Required function argument.

• suffix (str) – Required function argument.

• bin_label (str) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.moran_permutation_test(station_values: DataFrame, *, k: int, permutations: int, rng: Generator) → dict[str, float | int]

Compute Moran’s I and a permutation p-value from station values.

Parameters:

• station_values (pandas.DataFrame) – Required function argument.

• k (int) – Required function argument.

• permutations (int) – Required function argument.

• rng (numpy.random._generator.Generator) – Required function argument.

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.spatial.calculate.geology.normalize_residual_schema(df: DataFrame) → DataFrame

Normalize event and coordinate columns in a residual metrics table.

Parameters:

df (pandas.DataFrame) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geology.run_geology_spatial_tests(events: DataFrame, stations: DataFrame, *, contrasts: list[tuple[str, tuple[str, ...], tuple[str, ...], str]] | None = None, bootstrap_samples: int = 500, permutation_samples: int = 999, moran_neighbors: int = 8, seed: int = 20260529) → tuple[DataFrame, DataFrame]

Run contrast and Moran tests for each dataset, metric, and bin.

Parameters:

• events (pandas.DataFrame) – Required function argument.

• stations (pandas.DataFrame) – Required function argument.

• contrasts (list[tuple[str, tuple[str, ...], tuple[str, ...], str]] | None, optional) – Optional function argument. Defaults to None.

• bootstrap_samples (int, optional) – Optional function argument. Defaults to 500.

• permutation_samples (int, optional) – Optional function argument. Defaults to 999.

• moran_neighbors (int, optional) – Optional function argument. Defaults to 8.

• seed (int, optional) – Optional function argument. Defaults to 20260529.

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.geology.station_summary(events: DataFrame, *, min_events: int) → DataFrame

Average event-station anomalies to station-level summaries.

Parameters:

• events (pandas.DataFrame) – Required function argument.

• min_events (int) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

General GeoJSON metadata, path relation, and polygon-summary helpers.

exception spatial_vtk.spatial.calculate.geojson.GeoJSONNoOverlapError

Raised when selected GeoJSON polygons do not overlap the supplied data.

class spatial_vtk.spatial.calculate.geojson.GeoJSONPathControl(relation: Literal['crosses_boundary', 'begins_in', 'ends_in', 'station_inside', 'event_inside'] = 'crosses_boundary', selector: object = 'all', direction: Literal['either', 'inside_to_outside', 'outside_to_inside'] = 'either', start_role: str = 'event', end_role: str = 'station')

First-class configuration for GeoJSON path membership calculations.

Parameters:

• relation (Literal['crosses_boundary', 'begins_in', 'ends_in', 'station_inside', 'event_inside']) – Relation to evaluate: "crosses_boundary", "begins_in", or "ends_in".

• selector (object) – Polygon selector. Use "all", one polygon name/safe token, a set of names/tokens, or a mapping of property names to allowed values.

• direction (Literal['either', 'inside_to_outside', 'outside_to_inside']) – Direction filter for boundary crossings. "inside_to_outside" means the event/start point is inside the polygon and the station/end point is outside; "outside_to_inside" is the reverse.

• start_role – Data roles used for path start and end coordinates.

• end_role – Data roles used for path start and end coordinates.

spatial_vtk.spatial.calculate.geojson.add_geojson_metadata_to_metrics(metrics_df: DataFrame, geojson_path: str | Path | None = None, *, target: Literal['station', 'event', 'path'] = 'station', selector: object = 'all', relation: Literal['crosses_boundary', 'begins_in', 'ends_in', 'station_inside', 'event_inside'] = 'crosses_boundary', direction: Literal['either', 'inside_to_outside', 'outside_to_inside'] = 'either', require_overlap: bool = True) → DataFrame

Add GeoJSON-derived metadata to metric rows.

Parameters:

• metrics_df (pandas.DataFrame) – Metric, residual, or path table with station/event coordinates.

• geojson_path (str | pathlib.Path | None, optional) – GeoJSON polygon file. When omitted, paths.region_geojson from the active config is used.

• target (Literal, optional) – "station" or "event" for point membership; "path" for source-station relation classification.

• selector (object, optional) – Polygon selector.

• relation (Literal, optional) – Path relation controls used when target="path".

• direction (Literal, optional) – Path relation controls used when target="path".

• require_overlap (bool, optional) – Whether to raise a clear error if polygons do not overlap the data.

• metrics_df – Required function argument.

• geojson_path – Optional function argument. Defaults to None.

• target – Optional function argument. Defaults to 'station'.

• selector – Optional function argument. Defaults to 'all'.

• relation – Optional function argument. Defaults to 'crosses_boundary'.

• direction – Optional function argument. Defaults to 'either'.

• require_overlap – Optional function argument. Defaults to True.

Returns:

Metric table with GeoJSON metadata columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geojson.annotate_points_with_geojson(df: DataFrame, geojson_path: str | Path, *, point: Literal['station', 'event'], selector: object = 'all', lon_col: str | None = None, lat_col: str | None = None, prefix: str | None = None, include_per_polygon: bool = True, require_overlap: bool = True) → DataFrame

Add GeoJSON polygon membership columns for station or event points.

Parameters:

• df (pandas.DataFrame) – Table containing point coordinates.

• geojson_path (str | pathlib.Path) – GeoJSON polygon file. It is only loaded by this GeoJSON-specific function; the basic workflow does not require this file.

• point (Literal) – Point role to annotate: "station" or "event".

• selector (object, optional) – Polygon selector: all, one polygon, a set of polygons, or property filters.

• lon_col (str | None, optional) – Optional coordinate columns. When omitted, common station/event columns are inferred.

• lat_col (str | None, optional) – Optional coordinate columns. When omitted, common station/event columns are inferred.

• prefix (str | None, optional) – Output column prefix. Defaults to station_geojson or event_geojson.

• include_per_polygon (bool, optional) – Whether to add one boolean column per selected polygon.

• require_overlap (bool, optional) – Raise GeoJSONNoOverlapError when no supplied points fall inside or touch the selected polygons.

• df – Required function argument.

• geojson_path – Required function argument.

• point – Required function argument.

• selector – Optional function argument. Defaults to 'all'.

• lon_col – Optional function argument. Defaults to None.

• lat_col – Optional function argument. Defaults to None.

• prefix – Optional function argument. Defaults to None.

• include_per_polygon – Optional function argument. Defaults to True.

• require_overlap – Optional function argument. Defaults to True.

Returns:

Copy of df with membership labels and boolean flags.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geojson.apply_geojson_path_control(df: DataFrame, geojson_path: str | Path, control: GeoJSONPathControl, **kwargs) → DataFrame

Apply a reusable GeoJSON path-control object to a table.

Parameters:

• df (pandas.DataFrame) – Source-station table.

• geojson_path (str | pathlib.Path) – GeoJSON polygon file.

• control (spatial_vtk.spatial.calculate.geojson.GeoJSONPathControl) – GeoJSON path relation configuration.

• **kwargs – Additional keyword arguments forwarded to classify_paths_with_geojson().

• df – Required function argument.

• geojson_path – Required function argument.

• control – Required function argument.

• kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Classified path table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geojson.classify_paths_with_geojson(df: DataFrame, geojson_path: str | Path, *, relation: Literal['crosses_boundary', 'begins_in', 'ends_in', 'station_inside', 'event_inside'] = 'crosses_boundary', selector: object = 'all', direction: Literal['either', 'inside_to_outside', 'outside_to_inside'] = 'either', start_role: str = 'event', end_role: str = 'station', start_lon_col: str | None = None, start_lat_col: str | None = None, end_lon_col: str | None = None, end_lat_col: str | None = None, prefix: str = 'path_geojson', include_per_polygon: bool = True, require_overlap: bool = True) → DataFrame

Classify source-station paths relative to selected GeoJSON polygons.

Parameters:

• df (pandas.DataFrame) – Table containing event/start and station/end coordinates.

• geojson_path (str | pathlib.Path) – GeoJSON polygon file. It is optional for the basic workflow and only required by this function.

• relation (Literal, optional) – "crosses_boundary", "begins_in", "ends_in", "station_inside", or "event_inside".

• selector (object, optional) – One polygon, a set of polygons, all polygons, or property filters.

• direction (Literal, optional) – Direction filter for crossing relation.

• start_role (str, optional) – Coordinate roles used when explicit columns are not provided.

• end_role (str, optional) – Coordinate roles used when explicit columns are not provided.

• start_lon_col (str | None, optional) – Optional coordinate columns for path start and end.

• start_lat_col (str | None, optional) – Optional coordinate columns for path start and end.

• end_lon_col (str | None, optional) – Optional coordinate columns for path start and end.

• end_lat_col (str | None, optional) – Optional coordinate columns for path start and end.

• prefix (str, optional) – Output column prefix.

• include_per_polygon (bool, optional) – Whether to add one match column per selected polygon.

• require_overlap (bool, optional) – Raise GeoJSONNoOverlapError when the selected polygons have no qualifying relation to the paths.

• df – Required function argument.

• geojson_path – Required function argument.

• relation – Optional function argument. Defaults to 'crosses_boundary'.

• selector – Optional function argument. Defaults to 'all'.

• direction – Optional function argument. Defaults to 'either'.

• start_role – Optional function argument. Defaults to 'event'.

• end_role – Optional function argument. Defaults to 'station'.

• start_lon_col – Optional function argument. Defaults to None.

• start_lat_col – Optional function argument. Defaults to None.

• end_lon_col – Optional function argument. Defaults to None.

• end_lat_col – Optional function argument. Defaults to None.

• prefix – Optional function argument. Defaults to 'path_geojson'.

• include_per_polygon – Optional function argument. Defaults to True.

• require_overlap – Optional function argument. Defaults to True.

Returns:

Copy of df with path relation flags, labels, and crossing direction.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geojson.load_geojson_polygons(geojson_path: str | Path) → list[PolygonFeature]

Load Polygon and MultiPolygon features from a GeoJSON file.

Parameters:

• geojson_path (str | pathlib.Path) – Path to a GeoJSON FeatureCollection, Feature, Polygon, or MultiPolygon.

• geojson_path – Required function argument.

Returns:

Named polygon features in longitude/latitude coordinates.

Return type:

list of PolygonFeature

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.spatial.calculate.geojson.select_geojson_polygons(features: Sequence[PolygonFeature], selector: object = 'all') → list[PolygonFeature]

Select one, many, or all GeoJSON polygon features.

Parameters:

• features (collections.abc.Sequence) – Loaded polygon features.

• selector (object, optional) – "all"/None for all features; a single name or safe token; an iterable of names/tokens; or a mapping from property name to allowed property values.

• features – Required function argument.

• selector – Optional function argument. Defaults to 'all'.

Returns:

Selected features.

Return type:

list of PolygonFeature

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.spatial.calculate.geojson.summarize_metrics_by_geojson(df: DataFrame, *, label_col: str | None = None, value_col: str | None = None, group_cols: Sequence[str] = ('model', 'metric', 'band'), savecsv: bool = False, outpath: str | Path | None = None) → DataFrame

Aggregate metric values by GeoJSON polygon labels.

Parameters:

• df (pandas.DataFrame) – Table with a semicolon-delimited GeoJSON label column.

• label_col (str | None, optional) – Label column produced by this module, such as station_geojson_labels or path_geojson_labels. When omitted, the first available standard GeoJSON label column is used.

• value_col (str | None, optional) – Numeric value to summarize. When omitted, spatial.value_column from the active config is used.

• group_cols (collections.abc.Sequence, optional) – Additional grouping columns.

• savecsv (bool, optional) – Whether to write the summary as a CSV file.

• outpath (str | pathlib.Path | None, optional) – Output path used when savecsv is true.

• df – Required function argument.

• label_col – Optional function argument. Defaults to None.

• value_col – Optional function argument. Defaults to None.

• group_cols – Optional function argument. Defaults to ('model', 'metric', 'band').

• savecsv – Optional function argument. Defaults to False.

• outpath – Optional function argument. Defaults to None.

Returns:

Polygon-level count, mean, median, standard deviation, and IQR.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Clear public wrappers for GeoJSON polygon-edge corridor calculations.

class spatial_vtk.spatial.calculate.corridors.BoundaryCorridorConfig(selector: object = 'all', mode: str = 'through_boundary', along_boundary_width_km: float = 10.0, inside_length_km: float = 15.0, outside_length_km: float = 15.0, edge_average_window_km: float = 10.0, anchor: ~spatial_vtk.spatial.calculate.corridors.CorridorAnchorConfig = <factory>, require_overlap: bool = True)

Configuration for parameterized polygon-boundary corridors.

Parameters:

• selector (object) – Polygon selector: "all", one name/token, a set of names/tokens, or a property-filter mapping.

• mode (str) – "inward", "outward", or "through_boundary".

• along_boundary_width_km (float) – Corridor width parallel to the polygon boundary.

• inside_length_km – Corridor lengths normal to the boundary. mode controls which side is used unless both are intentionally supplied.

• outside_length_km – Corridor lengths normal to the boundary. mode controls which side is used unless both are intentionally supplied.

• edge_average_window_km (float) – Boundary window used to estimate tangent/normal direction.

• anchor (spatial_vtk.spatial.calculate.corridors.CorridorAnchorConfig) – Boundary anchor-selection settings.

• require_overlap (bool) – Raise when no corridors can be created for the requested polygons.

Returns:

Immutable corridor-geometry settings.

Return type:

BoundaryCorridorConfig

class spatial_vtk.spatial.calculate.corridors.CorridorAnchorConfig(source: str = 'all_boundary_segments', strategy: str = 'all', id_value: str | list[str] | tuple[str, ...] | None = None, query: str | None = None, sort_column: str | None = None, top_n: int | None = None, lon: float | None = None, lat: float | None = None, segment_spacing_km: float | None = None)

Configuration for choosing where polygon-boundary corridors are placed.

Parameters:

• source (str) – "all_boundary_segments", "station", "event", or "coordinate".

• strategy (str) – Anchor strategy for station/event sources. Supported values are "all", "id", "query", "max", "min", "max_records", and "largest_magnitude".

• id_value (str | list[str] | tuple[str, ...] | None) – One ID or list of IDs for strategy="id".

• query (str | None) – Pandas query expression for strategy="query".

• sort_column (str | None) – Metadata column used for "max" and "min".

• top_n (int | None) – Number of station/event anchors to keep after ranking.

• lon – Coordinate anchor for source="coordinate".

• lat – Coordinate anchor for source="coordinate".

• segment_spacing_km (float | None) – Boundary-center spacing for source="all_boundary_segments".

Returns:

Immutable anchor-selection settings.

Return type:

CorridorAnchorConfig

class spatial_vtk.spatial.calculate.corridors.CorridorSelectionConfig(station_filter: str = 'any', event_filter: str = 'any', side_filter: str = 'any', path_filter: str = 'any', min_path_length_km: float = 0.0, min_path_fraction: float = 0.0)

Configuration for selecting station/event/path rows by corridors.

Parameters:

• station_filter – "any", "inside_corridor", or "outside_corridor".

• event_filter – "any", "inside_corridor", or "outside_corridor".

• side_filter (str) – "any", "opposite_polygon_sides", or "same_polygon_side" using station/event position relative to the source polygon.

• path_filter (str) – "any" or "passes_through_corridor".

• min_path_length_km (float) – Minimum path length through the corridor. Set to 0 to accept any intersection.

• min_path_fraction (float) – Minimum fraction of the corridor’s longest approximate crossing. Set to 0 to accept any intersection.

Returns:

Immutable row-selection settings.

Return type:

CorridorSelectionConfig

class spatial_vtk.spatial.calculate.corridors.PolygonCorridorConfig(selector: object = 'all', near_edge_fraction: float = 0.1, near_edge_width_km: float | None = None, corridor_length_km: float = 30.0, corridor_width_km: float = 10.0, edge_average_window_km: float = 10.0, corridor_shape: str = 'rectangle', corridor_half_angle_deg: float = 30.0, require_overlap: bool = True)

Configuration for station-normal polygon-edge corridors.

Parameters:

• selector (object) – Polygon selector: "all", one name/token, a set of names/tokens, or a property-filter mapping.

• near_edge_fraction – Station edge qualification. Use a fixed width in kilometers when supplied; otherwise a fraction of local polygon width is used.

• near_edge_width_km – Station edge qualification. Use a fixed width in kilometers when supplied; otherwise a fraction of local polygon width is used.

• corridor_length_km – Rectangle corridor dimensions. Triangle corridors use length only.

• corridor_width_km – Rectangle corridor dimensions. Triangle corridors use length only.

• edge_average_window_km (float) – Boundary window used to estimate tangent/normal direction.

• corridor_shape (str) – "rectangle" or "triangle".

• corridor_half_angle_deg (float) – Triangle half-angle in degrees.

• require_overlap (bool) – Raise a clear error if selected polygons do not yield any corridor selections for the station table.

spatial_vtk.spatial.calculate.corridors.build_boundary_corridors(geojson_path: str | Path, *, config: BoundaryCorridorConfig | None = None, station_df: DataFrame | None = None, event_df: DataFrame | None = None, records_df: DataFrame | None = None, station_col: str = 'station', event_col: str = 'event_id') → DataFrame

Build parameterized corridors anchored to selected polygon boundaries.

Parameters:

• geojson_path (str | pathlib.Path) – Polygon GeoJSON path.

• config (spatial_vtk.spatial.calculate.corridors.BoundaryCorridorConfig | None, optional) – Boundary-corridor configuration.

• station_df (pandas.DataFrame | None, optional) – Optional station/event metadata used by station/event anchor strategies.

• event_df (pandas.DataFrame | None, optional) – Optional station/event metadata used by station/event anchor strategies.

• records_df (pandas.DataFrame | None, optional) – Optional event-station record table used for max_records anchors.

• station_col (str, optional) – Station and event ID columns in the input tables.

• event_col (str, optional) – Station and event ID columns in the input tables.

• geojson_path – Required function argument.

• config – Optional function argument. Defaults to None.

• station_df – Optional function argument. Defaults to None.

• event_df – Optional function argument. Defaults to None.

• records_df – Optional function argument. Defaults to None.

• station_col – Optional function argument. Defaults to 'station'.

• event_col – Optional function argument. Defaults to 'event_id'.

Returns:

Corridor table with polygon, anchor, dimensions, and Shapely geometry columns. corridor_geometry is in lon/lat.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.corridors.build_station_edge_corridors(station_df: DataFrame, geojson_path: str | Path, *, config: PolygonCorridorConfig | None = None, station_col: str = 'station', network_col: str = 'network', lon_col: str | None = None, lat_col: str | None = None) → DataFrame

Build station-specific corridors normal to selected polygon edges.

Parameters:

• station_df (pandas.DataFrame) – Station table with station coordinates.

• geojson_path (str | pathlib.Path) – Polygon GeoJSON path.

• config (spatial_vtk.spatial.calculate.corridors.PolygonCorridorConfig | None, optional) – Corridor configuration.

• station_col (str, optional) – Station and network columns.

• network_col (str, optional) – Station and network columns.

• lon_col (str | None, optional) – Optional coordinate columns. Common station coordinate names are inferred when omitted.

• lat_col (str | None, optional) – Optional coordinate columns. Common station coordinate names are inferred when omitted.

• station_df – Required function argument.

• geojson_path – Required function argument.

• config – Optional function argument. Defaults to None.

• station_col – Optional function argument. Defaults to 'station'.

• network_col – Optional function argument. Defaults to 'network'.

• lon_col – Optional function argument. Defaults to None.

• lat_col – Optional function argument. Defaults to None.

Returns:

Corridor table with station, polygon, edge, anchor, and geometry columns. The corridor_geometry column contains Shapely polygons.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.corridors.classify_records_by_corridors(records_df: DataFrame, corridors_df: DataFrame, *, config: CorridorSelectionConfig | None = None, station_lon_col: str | None = None, station_lat_col: str | None = None, event_lon_col: str | None = None, event_lat_col: str | None = None) → DataFrame

Classify event-station path rows against corridor footprints.

Parameters:

• records_df (pandas.DataFrame) – Event-station table with station and event coordinates.

• corridors_df (pandas.DataFrame) – Corridor table from build_boundary_corridors() or build_station_edge_corridors().

• config (spatial_vtk.spatial.calculate.corridors.CorridorSelectionConfig | None, optional) – Selection rules. Defaults keep any row/corridor pair.

• station_lon_col (str | None, optional) – Optional coordinate column overrides.

• station_lat_col (str | None, optional) – Optional coordinate column overrides.

• event_lon_col (str | None, optional) – Optional coordinate column overrides.

• event_lat_col (str | None, optional) – Optional coordinate column overrides.

• records_df – Required function argument.

• corridors_df – Required function argument.

• config – Optional function argument. Defaults to None.

• station_lon_col – Optional function argument. Defaults to None.

• station_lat_col – Optional function argument. Defaults to None.

• event_lon_col – Optional function argument. Defaults to None.

• event_lat_col – Optional function argument. Defaults to None.

Returns:

One row per matching input row/corridor pair, with corridor metadata, point-membership flags, polygon-side flags, and path-through-corridor length.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.corridors.select_events_in_corridors(events_df: DataFrame, corridors_df: DataFrame, *, event_col: str = 'event_id', lon_col: str | None = None, lat_col: str | None = None, min_depth_km: float | None = None, max_depth_km: float | None = None) → DataFrame

Select event rows inside each corridor footprint.

Parameters:

• events_df (pandas.DataFrame) – Event table.

• corridors_df (pandas.DataFrame) – Corridor table from build_station_edge_corridors().

• event_col (str, optional) – Event identifier column.

• lon_col (str | None, optional) – Optional event coordinate columns. Common event coordinate names are inferred when omitted.

• lat_col (str | None, optional) – Optional event coordinate columns. Common event coordinate names are inferred when omitted.

• min_depth_km (float | None, optional) – Optional inclusive depth filters.

• max_depth_km (float | None, optional) – Optional inclusive depth filters.

• events_df – Required function argument.

• corridors_df – Required function argument.

• event_col – Optional function argument. Defaults to 'event_id'.

• lon_col – Optional function argument. Defaults to None.

• lat_col – Optional function argument. Defaults to None.

• min_depth_km – Optional function argument. Defaults to None.

• max_depth_km – Optional function argument. Defaults to None.

Returns:

Matching event-corridor rows.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.corridors.select_records_by_corridors(records_df: DataFrame, corridors_df: DataFrame, *, config: CorridorSelectionConfig | None = None, station_lon_col: str | None = None, station_lat_col: str | None = None, event_lon_col: str | None = None, event_lat_col: str | None = None) → DataFrame

Return event-station rows that match corridor selection rules.

Parameters:

• records_df (pandas.DataFrame) – Event-station table.

• corridors_df (pandas.DataFrame) – Corridor table.

• config (spatial_vtk.spatial.calculate.corridors.CorridorSelectionConfig | None, optional) – Corridor selection settings.

• station_lon_col (str | None, optional) – Optional coordinate column overrides.

• station_lat_col (str | None, optional) – Optional coordinate column overrides.

• event_lon_col (str | None, optional) – Optional coordinate column overrides.

• event_lat_col (str | None, optional) – Optional coordinate column overrides.

• records_df – Required function argument.

• corridors_df – Required function argument.

• config – Optional function argument. Defaults to None.

• station_lon_col – Optional function argument. Defaults to None.

• station_lat_col – Optional function argument. Defaults to None.

• event_lon_col – Optional function argument. Defaults to None.

• event_lat_col – Optional function argument. Defaults to None.

Returns:

Matching row/corridor pairs.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.corridors.summarize_corridor_event_counts(corridor_events: DataFrame) → DataFrame

Summarize how many events fall in each station/polygon corridor.

Parameters:

corridor_events (pandas.DataFrame) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

General spatial geometry helpers.

spatial_vtk.spatial.calculate.geometry.add_source_station_geometry(df: DataFrame, *, event_lat_col: str = 'event_lat', event_lon_col: str = 'event_lon', station_lat_col: str = 'sta_lat', station_lon_col: str = 'sta_lon') → DataFrame

Add distance, azimuth, and backazimuth to source-station rows.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• event_lat_col (str, optional) – Optional function argument. Defaults to 'event_lat'.

• event_lon_col (str, optional) – Optional function argument. Defaults to 'event_lon'.

• station_lat_col (str, optional) – Optional function argument. Defaults to 'sta_lat'.

• station_lon_col (str, optional) – Optional function argument. Defaults to 'sta_lon'.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.geometry.forward_azimuth_deg(lat1, lon1, lat2, lon2)

Return forward azimuth from point 1 to point 2 in degrees.

Parameters:

• lat1 (Any) – Required function argument.

• lon1 (Any) – Required function argument.

• lat2 (Any) – Required function argument.

• lon2 (Any) – Required function argument.

Returns:

Return value produced by the function.

Return type:

Any

Path-oriented summaries for source-station metric rows.

spatial_vtk.spatial.calculate.paths.build_path_table(df: DataFrame, *, residual_mode: str = 'logratio') → DataFrame

Prepare metric rows for source-station path analysis.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• residual_mode (str, optional) – Optional function argument. Defaults to 'logratio'.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.paths.summarize_residuals_by_path_bin(path_df: DataFrame, *, distance_bin_km: float = 10.0, azimuth_bin_deg: float = 30.0) → DataFrame

Summarize residuals by distance and azimuth bins.

Parameters:

• path_df (pandas.DataFrame) – Required function argument.

• distance_bin_km (float, optional) – Optional function argument. Defaults to 10.0.

• azimuth_bin_deg (float, optional) – Optional function argument. Defaults to 30.0.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Observed/synthetic spatial pattern comparison helpers.

spatial_vtk.spatial.calculate.patterns.build_pattern_similarity_station_anomalies(metrics: DataFrame, *, metric: str, passband: str, component: str | None = None, model: str | None = None, station_col: str = 'station', observed_col: str = 'value_obs', synthetic_col: str = 'value_syn') → DataFrame

Build observed/synthetic station-anomaly rows for pattern plots.

Parameters:

• metrics (pandas.DataFrame) – Long metric table with observed and synthetic metric-value columns.

• metric (str) – Metric name and period band to select.

• passband (str) – Metric name and period band to select.

• component (str | None, optional) – Optional component and model filters.

• model (str | None, optional) – Optional component and model filters.

• station_col (str, optional) – Station identifier column in metrics.

• observed_col (str, optional) – Columns containing observed and synthetic metric values.

• synthetic_col (str, optional) – Columns containing observed and synthetic metric values.

• metrics – Required function argument.

• metric – Required function argument.

• passband – Required function argument.

• component – Optional function argument. Defaults to None.

• model – Optional function argument. Defaults to None.

• station_col – Optional function argument. Defaults to 'station'.

• observed_col – Optional function argument. Defaults to 'value_obs'.

• synthetic_col – Optional function argument. Defaults to 'value_syn'.

Returns:

Long table with station_name, dataset, metric, bin, and mean-centered value columns for plotting and similarity statistics.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.patterns.normalize_metrics_schema(df: DataFrame) → DataFrame

Normalize a synthetic-overlap metrics table for pattern comparisons.

Parameters:

• df (pandas.DataFrame) – Metrics table with observed/synthetic columns and coordinates.

• df – Required function argument.

Returns:

Copy with normalized event id, passband, and numeric coordinates.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.patterns.pattern_similarity(stations: DataFrame) → DataFrame

Compare observed and synthetic station-anomaly patterns.

Parameters:

• stations (pandas.DataFrame) – Station-level anomaly table containing dataset values observed and synthetic.

• stations – Required function argument.

Returns:

Similarity statistics by metric and bin.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Geometry helpers for polygon-edge station corridor sections.

Calculation Polygon Edges Overview

This module owns the pure geometry used by the polygon-edge station-section workflow. It loads Polygon/MultiPolygon GeoJSON features, associates stations with the nearest outer shell edge, computes local shell width while ignoring holes, builds station-specific normal corridors, and selects events inside those corridors.

Calculation Polygon Edges Examples

Load features and select near-edge stations without touching waveform files:

features = load_polygon_features("inputs/geospatial/regions_updated.geojson") matches = select_near_edge_stations(features[0], station_df)

class spatial_vtk.spatial.calculate.polygon_edges.LocalShell(feature_name: str, shell_index: int, shell_lonlat: Polygon, shell_projected: Polygon, shell_outer_projected: Polygon, exterior_line_projected: LineString, to_projected: Transformer, to_lonlat: Transformer)

Projected shell geometry and transformers for one polygon component.

Parameters:

• feature_name (str) – Parent feature name.

• shell_index (int) – Zero-based shell component index within the feature.

• shell_lonlat (shapely.geometry.polygon.Polygon) – Original shell polygon in longitude/latitude.

• shell_projected (shapely.geometry.polygon.Polygon) – Projected shell polygon with holes preserved.

• shell_outer_projected (shapely.geometry.polygon.Polygon) – Projected polygon made from only the exterior ring.

• exterior_line_projected (shapely.geometry.linestring.LineString) – Projected exterior ring LineString.

• to_projected (pyproj.transformer.Transformer) – Transformer from lon/lat to local meters.

• to_lonlat (pyproj.transformer.Transformer) – Transformer from local meters back to lon/lat.

class spatial_vtk.spatial.calculate.polygon_edges.PolygonFeature(name: str, geometry: Polygon | MultiPolygon, shells: tuple[Polygon, ...], properties: dict[str, object])

One named GeoJSON polygon feature with shell components preserved.

Parameters:

• name (str) – Deduplicated display name for the feature.

• geometry (shapely.geometry.polygon.Polygon | shapely.geometry.multipolygon.MultiPolygon) – Original Shapely Polygon or MultiPolygon geometry in lon/lat.

• shells (tuple[shapely.geometry.polygon.Polygon, ...]) – Individual Polygon shell components. For a Polygon this is one item; for a MultiPolygon this contains each component.

• properties (dict[str, object]) – Original GeoJSON feature properties.

class spatial_vtk.spatial.calculate.polygon_edges.StationEdgeSelection(feature_name: str, station: str, network: str, shell_index: int, station_lat: float, station_lon: float, station_side: str, anchor_lon: float, anchor_lat: float, local_shell_width_km: float, near_edge_threshold_km: float, distance_to_edge_km: float, corridor_length_km: float, corridor_thickness_km: float, edge_average_window_km: float, corridor_shape: str, corridor_half_angle_deg: float, corridor_lonlat: Polygon, tangent_xy: tuple[float, float], inward_normal_xy: tuple[float, float])

One station that qualifies as near a polygon’s outer edge.

Parameters:

• feature_name – Identifiers for the polygon feature and station.

• station – Identifiers for the polygon feature and station.

• network – Identifiers for the polygon feature and station.

• shell_index (int) – Shell component used for nearest-edge association.

• station_lat – Station coordinates in decimal degrees.

• station_lon – Station coordinates in decimal degrees.

• station_side (str) – "inside" when the station lies inside the actual polygon shell, otherwise "outside". A station in a hole is outside.

• anchor_lon – Nearest outer-boundary point in lon/lat.

• anchor_lat – Nearest outer-boundary point in lon/lat.

• local_shell_width_km (float) – Distance from the anchor point to the opposite outer shell along the inward normal.

• near_edge_threshold_km (float) – Threshold used to accept this station.

• distance_to_edge_km (float) – Station-to-anchor distance.

• corridor_length_km – Dimensions of the station-specific corridor. Triangle corridors use corridor_length_km as the side length and leave corridor_thickness_km as zero because they are angular wedges.

• corridor_thickness_km – Dimensions of the station-specific corridor. Triangle corridors use corridor_length_km as the side length and leave corridor_thickness_km as zero because they are angular wedges.

• edge_average_window_km (float) – Exterior-edge window used to average the tangent for normal corridors.

• corridor_shape (str) – Corridor footprint shape: "rectangle" or "triangle".

• corridor_half_angle_deg (float) – Half angle in degrees for triangle corridors.

• corridor_lonlat (shapely.geometry.polygon.Polygon) – Corridor footprint polygon in lon/lat.

• tangent_xy – Unit vectors in local projected coordinates.

• inward_normal_xy – Unit vectors in local projected coordinates.

spatial_vtk.spatial.calculate.polygon_edges.build_station_corridor(local_shell: LocalShell, *, anchor: Point, station_point: Point, tangent: tuple[float, float], inward_normal: tuple[float, float], station_side: str, local_width_km: float, corridor_length_km: float = 30.0, corridor_thickness_km: float = 10.0) → tuple[Polygon, float]

Build a station-specific normal corridor in lon/lat.

Parameters:

• local_shell (spatial_vtk.spatial.calculate.polygon_edges.LocalShell) – Local shell context.

• anchor (shapely.geometry.point.Point) – Projected exterior-boundary point.

• station_point (shapely.geometry.point.Point) – Projected station point.

• tangent (tuple) – Unit vectors in projected coordinates.

• inward_normal (tuple) – Unit vectors in projected coordinates.

• station_side (str) – "inside" or "outside".

• local_width_km (float) – Local shell width in kilometers.

• corridor_length_km (float, optional) – Requested corridor dimensions.

• corridor_thickness_km (float, optional) – Requested corridor dimensions.

• local_shell – Required function argument.

• anchor – Required function argument.

• station_point – Required function argument.

• tangent – Required function argument.

• inward_normal – Required function argument.

• station_side – Required function argument.

• local_width_km – Required function argument.

• corridor_length_km – Optional function argument. Defaults to 30.0.

• corridor_thickness_km – Optional function argument. Defaults to 10.0.

Returns:

(corridor_lonlat, effective_length_km).

Return type:

tuple

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.polygon_edges.build_station_triangle_corridor(local_shell: LocalShell, *, anchor: Point, station_point: Point, inward_normal: tuple[float, float], station_side: str, corridor_length_km: float = 30.0, half_angle_deg: float = 30.0) → tuple[Polygon, float]

Build a triangular station-side event-selection wedge in lon/lat.

Parameters:

• local_shell (spatial_vtk.spatial.calculate.polygon_edges.LocalShell) – Local shell context.

• anchor (shapely.geometry.point.Point) – Projected exterior-boundary point used as the triangle vertex.

• station_point (shapely.geometry.point.Point) – Projected station point. The triangle centerline is chosen to pass through this point when possible.

• inward_normal (tuple) – Inward normal unit vector in projected coordinates.

• station_side (str) – "inside" or "outside".

• corridor_length_km (float, optional) – Length of each triangle side in kilometers.

• half_angle_deg (float, optional) – Half angle on either side of the centerline in degrees.

• local_shell – Required function argument.

• anchor – Required function argument.

• station_point – Required function argument.

• inward_normal – Required function argument.

• station_side – Required function argument.

• corridor_length_km – Optional function argument. Defaults to 30.0.

• half_angle_deg – Optional function argument. Defaults to 30.0.

Returns:

(corridor_lonlat, effective_side_length_km).

Return type:

tuple

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.polygon_edges.event_rows_in_corridor(events_df: DataFrame, corridor_lonlat: Polygon, *, min_depth_km: float | None = None, max_depth_km: float | None = None) → DataFrame

Select event rows inside a corridor footprint and optional depth range.

Parameters:

• events_df (pandas.DataFrame) – Runtime event catalog with event coordinates and depth.

• corridor_lonlat (shapely.geometry.polygon.Polygon) – Corridor footprint polygon in lon/lat.

• min_depth_km (float | None, optional) – Optional inclusive depth limits.

• max_depth_km (float | None, optional) – Optional inclusive depth limits.

• events_df – Required function argument.

• corridor_lonlat – Required function argument.

• min_depth_km – Optional function argument. Defaults to None.

• max_depth_km – Optional function argument. Defaults to None.

Returns:

Matching rows preserving input columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.spatial.calculate.polygon_edges.inverse_project_point(local_shell: LocalShell, x: float, y: float) → tuple[float, float]

Convert one projected point back to lon/lat.

Parameters:

• local_shell (spatial_vtk.spatial.calculate.polygon_edges.LocalShell) – Local shell context.

• x (float) – Projected coordinates in meters.

• y (float) – Projected coordinates in meters.

• local_shell – Required function argument.

• x – Required function argument.

• y – Required function argument.

Returns:

(lon, lat).

Return type:

tuple

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.polygon_edges.load_polygon_features(geojson_path: str | Path) → list[PolygonFeature]

Load named Polygon/MultiPolygon features from a GeoJSON file.

Parameters:

• geojson_path (str | pathlib.Path) – GeoJSON path containing Polygon or MultiPolygon features.

• geojson_path – Required function argument.

Returns:

Named features with individual shell components preserved.

Return type:

list of PolygonFeature

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.spatial.calculate.polygon_edges.local_shell_width_km(local_shell: LocalShell, anchor: Point, inward_normal: tuple[float, float]) → float

Measure shell width from an anchor to the opposite exterior shell.

Parameters:

• local_shell (spatial_vtk.spatial.calculate.polygon_edges.LocalShell) – Local shell context.

• anchor (shapely.geometry.point.Point) – Projected exterior-boundary point.

• inward_normal (tuple) – Inward normal unit vector.

• local_shell – Required function argument.

• anchor – Required function argument.

• inward_normal – Required function argument.

Returns:

Width in kilometers. Holes are ignored.

Return type:

float

Returns:

Return value produced by the function.

Return type:

float

spatial_vtk.spatial.calculate.polygon_edges.project_point(local_shell: LocalShell, lon: float, lat: float) → Point

Project a lon/lat point into one shell’s local metric CRS.

Parameters:

• local_shell (spatial_vtk.spatial.calculate.polygon_edges.LocalShell) – Local shell context.

• lon (float) – Geographic coordinates.

• lat (float) – Geographic coordinates.

• local_shell – Required function argument.

• lon – Required function argument.

• lat – Required function argument.

Returns:

Projected point in meters.

Return type:

shapely.geometry.Point

Returns:

Return value produced by the function.

Return type:

shapely.geometry.point.Point

spatial_vtk.spatial.calculate.polygon_edges.safe_name_token(value: object) → str

Return a deterministic filesystem-safe token for one label.

Parameters:

• value (object) – Raw label such as a polygon or station name.

• value – Required function argument.

Returns:

Lowercase token containing letters, numbers, and underscores.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.spatial.calculate.polygon_edges.select_near_edge_stations(feature: PolygonFeature, station_df: DataFrame, *, near_edge_fraction: float = 0.1, near_edge_width_km: float | None = None, corridor_length_km: float = 30.0, corridor_thickness_km: float = 10.0, edge_average_window_km: float = 10.0, corridor_shape: str = 'rectangle', corridor_half_angle_deg: float = 30.0) → list[StationEdgeSelection]

Select stations near the nearest exterior shell edge of a feature.

Parameters:

• feature (spatial_vtk.spatial.calculate.polygon_edges.PolygonFeature) – Polygon feature.

• station_df (pandas.DataFrame) – Station table with station, station_lat, station_lon, and optional network.

• near_edge_fraction (float, optional) – Edge qualification rule.

• near_edge_width_km (float | None, optional) – Edge qualification rule.

• corridor_length_km (float, optional) – Corridor dimensions. Triangle mode uses corridor_length_km as the side length and ignores thickness.

• corridor_thickness_km (float, optional) – Corridor dimensions. Triangle mode uses corridor_length_km as the side length and ignores thickness.

• edge_average_window_km (float, optional) – Exterior-edge distance window used to average the boundary tangent.

• corridor_shape (str, optional) – Corridor footprint shape: "rectangle" or "triangle".

• corridor_half_angle_deg (float, optional) – Half angle in degrees for triangle corridors.

• feature – Required function argument.

• station_df – Required function argument.

• near_edge_fraction – Optional function argument. Defaults to 0.1.

• near_edge_width_km – Optional function argument. Defaults to None.

• corridor_length_km – Optional function argument. Defaults to 30.0.

• corridor_thickness_km – Optional function argument. Defaults to 10.0.

• edge_average_window_km – Optional function argument. Defaults to 10.0.

• corridor_shape – Optional function argument. Defaults to 'rectangle'.

• corridor_half_angle_deg – Optional function argument. Defaults to 30.0.

Returns:

Qualified stations.

Return type:

list of StationEdgeSelection

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.spatial.calculate.polygon_edges.station_edge_selection_for_shell(feature: PolygonFeature, shell_index: int, *, station: str, network: str, station_lat: float, station_lon: float, near_edge_fraction: float = 0.1, near_edge_width_km: float | None = None, corridor_length_km: float = 30.0, corridor_thickness_km: float = 10.0, edge_average_window_km: float = 10.0, corridor_shape: str = 'rectangle', corridor_half_angle_deg: float = 30.0) → StationEdgeSelection | None

Evaluate one station against one polygon shell.

Parameters:

• feature (spatial_vtk.spatial.calculate.polygon_edges.PolygonFeature) – Polygon feature and component.

• shell_index (int) – Polygon feature and component.

• station (str) – Station metadata.

• network (str) – Station metadata.

• station_lat (float) – Station metadata.

• station_lon (float) – Station metadata.

• near_edge_fraction (float, optional) – Edge qualification rule.

• near_edge_width_km (float | None, optional) – Edge qualification rule.

• corridor_length_km (float, optional) – Corridor dimensions. Triangle mode uses corridor_length_km as the side length and ignores thickness.

• corridor_thickness_km (float, optional) – Corridor dimensions. Triangle mode uses corridor_length_km as the side length and ignores thickness.

• edge_average_window_km (float, optional) – Exterior-edge distance window used to average the boundary tangent.

• corridor_shape (str, optional) – "rectangle" for the legacy station-centered rectangle or "triangle" for an angular wedge from the nearest boundary point.

• corridor_half_angle_deg (float, optional) – Half angle in degrees for triangle corridors.

• feature – Required function argument.

• shell_index – Required function argument.

• station – Required function argument.

• network – Required function argument.

• station_lat – Required function argument.

• station_lon – Required function argument.

• near_edge_fraction – Optional function argument. Defaults to 0.1.

• near_edge_width_km – Optional function argument. Defaults to None.

• corridor_length_km – Optional function argument. Defaults to 30.0.

• corridor_thickness_km – Optional function argument. Defaults to 10.0.

• edge_average_window_km – Optional function argument. Defaults to 10.0.

• corridor_shape – Optional function argument. Defaults to 'rectangle'.

• corridor_half_angle_deg – Optional function argument. Defaults to 30.0.

Returns:

Selection when the station qualifies, otherwise None.

Return type:

StationEdgeSelection or None

Returns:

Return value produced by the function.

Return type:

spatial_vtk.spatial.calculate.polygon_edges.StationEdgeSelection | None

Horizontal component rotation helpers.

spatial_vtk.spatial.calculate.rotation.rotate_ne_to_rt(north, east, backazimuth_deg: float) → tuple[ndarray, ndarray]

Rotate north/east components to radial/transverse components.

Parameters:

• north (Any) – North and east component samples.

• east (Any) – North and east component samples.

• backazimuth_deg (float) – Backazimuth from station to source in degrees.

• north – Required function argument.

• east – Required function argument.

• backazimuth_deg – Required function argument.

Returns:

Radial and transverse component arrays.

Return type:

tuple of numpy.ndarray

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.calculate.rotation.rotate_rt_to_ne(radial, transverse, backazimuth_deg: float) → tuple[ndarray, ndarray]

Rotate radial/transverse components back to north/east components.

Parameters:

• radial (Any) – Required function argument.

• transverse (Any) – Required function argument.

• backazimuth_deg (float) – Required function argument.

Returns:

Return value produced by the function.

Return type:

tuple

Configuration helpers for spatial-statistics workflows.

Calculation Settings Overview

This module resolves spatial-analysis settings from the active Spatial-VTK configuration so notebooks and scripts do not need repeated config plumbing.

Calculation Settings Examples

Read active spatial settings:

settings = spatial_statistics_settings_from_config()

class spatial_vtk.spatial.calculate.settings.SpatialStatisticsSettings(metric: str = 'all', value_column: str = 'log2_residual', remove_event_mean: bool = True, min_stations_per_event: int = 2, min_events_per_station: int = 1, moran_neighbors: int = 2, moran_permutations: int = 99, distance_bin_width_km: float = 20.0, cluster_min_k: int = 2, cluster_max_k: int = 4, pca_components: int = 2, geology_group_column: str = 'mapped_region_type', geology_left_values: tuple[str, ...] = ('Basin',), geology_right_values: tuple[str, ...] = ('Mountains',), geology_min_stations_per_group: int = 3, geology_bootstrap_samples: int = 100, geology_statistic: str = 'mean', random_seed: int = 42, region_geojson_path: Path | None = None)

Resolved settings for spatial-statistics calculations.

Parameters:

• metric (str) – Metric name or "all" used when building a spatial field.

• value_column (str) – Metric value, residual, or score column used as the spatial field.

• remove_event_mean (bool) – Whether event means should be removed when centering a field.

• min_stations_per_event – Minimum support thresholds for event centering and station summaries.

• min_events_per_station – Minimum support thresholds for event centering and station summaries.

• moran_neighbors – Moran’s I nearest-neighbor and permutation-test settings.

• moran_permutations – Moran’s I nearest-neighbor and permutation-test settings.

• distance_bin_width_km (float) – Distance-bin width for correlation summaries.

• cluster_min_k – Cluster-count search range.

• cluster_max_k – Cluster-count search range.

• pca_components (int) – Requested number of PCA spatial modes.

• geology_group_column – Geology contrast classes.

• geology_left_values – Geology contrast classes.

• geology_right_values – Geology contrast classes.

• geology_min_stations_per_group (int) – Minimum station count required on each side of a geology contrast.

• geology_bootstrap_samples (int) – Bootstrap draws used for geology contrasts.

• geology_statistic (str) – Station-summary statistic used for geology contrasts.

• random_seed (int) – Reproducibility seed for stochastic spatial calculations.

• region_geojson_path (pathlib.Path | None) – Optional configured GeoJSON polygon path.

spatial_vtk.spatial.calculate.settings.spatial_statistics_settings_from_config(cfg: SpatialVTKConfig | None = None) → SpatialStatisticsSettings

Resolve spatial-statistics settings from a config.

Parameters:

• cfg (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config. When omitted, the active/discoverable config is used.

• cfg – Optional function argument. Defaults to None.

Returns:

Resolved spatial settings with package defaults filled in.

Return type:

SpatialStatisticsSettings

Returns:

Return value produced by the function.

Return type:

spatial_vtk.spatial.calculate.settings.SpatialStatisticsSettings

Workflow helpers for spatial-statistics tutorial and CLI outputs.

Calculation Workflow Overview

This module names the standard spatial-statistics output tables so notebooks, scripts, and CLI wrappers can share the same file layout.

Calculation Workflow Examples

Create standard paths for spatial outputs:

paths = spatial_statistics_output_paths("outputs/tutorials/step_04")

spatial_vtk.spatial.calculate.workflow.spatial_statistics_output_paths(output_dir: str | Path) → SimpleNamespace

Return standard Step 4 spatial-statistics output paths.

Parameters:

• output_dir (str | pathlib.Path) – Directory where spatial-statistics tables should be written.

• output_dir – Required function argument.

Returns:

Namespace with one attribute per standard output table.

Return type:

types.SimpleNamespace

Returns:

Return value produced by the function.

Return type:

types.SimpleNamespace

Plots

Plot wrappers for spatial correlation and clustering results.

Plotting Correlation Overview

This module draws lightweight review figures from public spatial-statistics tables. It does not discover files, run analyses, or depend on private artifact registries.

spatial_vtk.spatial.plot.correlation.plot_block_holdout_scatter(prediction_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Spatial Block Holdout', fit_method: object = None, fit: object = None, lowess_frac: float = 0.65, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, **spatial_kwargs: object) → Figure

Plot predicted versus observed held-out station bias.

Parameters:

• prediction_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Spatial Block Holdout'.

• fit_method (object, optional) – Optional function argument. Defaults to None.

• fit (object, optional) – Optional function argument. Defaults to None.

• lowess_frac (float, optional) – Optional function argument. Defaults to 0.65.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.correlation.plot_cluster_feature_heatmap(feature_summary_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Cluster Feature Summary', feature_order: Sequence[str] | None = None, feature_label_map: Mapping[str, str] | None = None, value_column: str = 'feature_mean', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot a cluster-by-feature heatmap from cluster feature summaries.

Parameters:

• feature_summary_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Cluster Feature Summary'.

• feature_order (Optional, optional) – Optional function argument. Defaults to None.

• feature_label_map (Optional, optional) – Optional function argument. Defaults to None.

• value_column (str, optional) – Optional function argument. Defaults to 'feature_mean'.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.correlation.plot_cluster_solution_scores(score_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Cluster Solution Scores', k_column: str = 'n_clusters', score_column: str = 'silhouette', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot silhouette score versus candidate cluster count.

Parameters:

• score_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Cluster Solution Scores'.

• k_column (str, optional) – Optional function argument. Defaults to 'n_clusters'.

• score_column (str, optional) – Optional function argument. Defaults to 'silhouette'.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.correlation.plot_correlogram(distance_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Spatial Correlogram', fit: CorrelationLengthFit | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot an empirical distance-binned correlogram.

Parameters:

• distance_df (pandas.DataFrame) – Output from build_distance_bin_summary.

• output_path (str | pathlib.Path | None, optional) – Figure path to write.

• title (str, optional) – Figure title.

• fit (spatial_vtk.spatial.calculate.correlation.CorrelationLengthFit | None, optional) – Optional exponential correlation-length fit.

• distance_df – Required function argument.

• output_path – Optional function argument. Defaults to None.

• title – Optional function argument. Defaults to 'Spatial Correlogram'.

• fit – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.correlation.plot_directional_correlogram(directional_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Directional Correlogram', fit_df: DataFrame | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot distance-binned correlations split by station-pair orientation.

Parameters:

• directional_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Directional Correlogram'.

• fit_df (pandas.DataFrame | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.correlation.plot_distance_correlation_by_metric(distance_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Spatial Correlation by Distance', metric_col: str = 'metric', distance_col: str = 'distance_center_km', correlation_col: str = 'mean_pair_correlation', pair_count_col: str = 'pair_count', significance_df: DataFrame | None = None, significance_metric_col: str = 'metric', p_col: str | None = None, alpha: float = 0.05, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot distance-binned spatial correlation for one or more metrics.

Parameters:

• distance_df (pandas.DataFrame) – Distance-bin correlation table, usually from build_distance_bin_summary with a metric column added.

• output_path (str | pathlib.Path | None, optional) – Figure path to write.

• title (str, optional) – Figure title.

• metric_col (str, optional) – Column names used for the metric grouping, distance bin center, binned correlation value, and number of station pairs.

• distance_col (str, optional) – Column names used for the metric grouping, distance bin center, binned correlation value, and number of station pairs.

• correlation_col (str, optional) – Column names used for the metric grouping, distance bin center, binned correlation value, and number of station pairs.

• pair_count_col (str, optional) – Column names used for the metric grouping, distance bin center, binned correlation value, and number of station pairs.

• significance_df (pandas.DataFrame | None, optional) – Optional Moran or permutation test table used to mark significant metrics. The table should include a metric column and a p-value column.

• significance_metric_col (str, optional) – Significance table column names and p-value threshold.

• p_col (str | None, optional) – Significance table column names and p-value threshold.

• alpha (float, optional) – Significance table column names and p-value threshold.

• distance_df – Required function argument.

• output_path – Optional function argument. Defaults to None.

• title – Optional function argument. Defaults to 'Spatial Correlation by Distance'.

• metric_col – Optional function argument. Defaults to 'metric'.

• distance_col – Optional function argument. Defaults to 'distance_center_km'.

• correlation_col – Optional function argument. Defaults to 'mean_pair_correlation'.

• pair_count_col – Optional function argument. Defaults to 'pair_count'.

• significance_df – Optional function argument. Defaults to None.

• significance_metric_col – Optional function argument. Defaults to 'metric'.

• p_col – Optional function argument. Defaults to None.

• alpha – Optional function argument. Defaults to 0.05.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Figure containing one line per metric.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.correlation.plot_pattern_similarity(stations: DataFrame, output_path: str | Path | None = None, *, metric: str, bin_label: str, title: str | None = None, fit_method: object = 'linear', fit: object = None, lowess_frac: float = 0.65, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, **spatial_kwargs: object) → Figure

Plot observed versus synthetic station anomaly values for one metric/bin.

Parameters:

• stations (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• metric (str) – Required function argument.

• bin_label (str) – Required function argument.

• title (str | None, optional) – Optional function argument. Defaults to None.

• fit_method (object, optional) – Optional function argument. Defaults to 'linear'.

• fit (object, optional) – Optional function argument. Defaults to None.

• lowess_frac (float, optional) – Optional function argument. Defaults to 0.65.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.correlation.plot_semivariogram(distance_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Semivariogram', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot an empirical distance-binned semivariogram.

Parameters:

• distance_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Semivariogram'.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Non-map spatial metric plots.

spatial_vtk.spatial.plot.metrics.plot_azimuthal_residuals(df: DataFrame, output_path: str | Path | None = None, *, azimuth_col: str = 'azimuth_deg', value_col: str = 'residual', group_col: str | None = 'model', spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, station_region_col: str | None = None, station_regions: Sequence[str] | str | None = None, station_region_relation: str = 'inside', event_region_col: str | None = None, event_regions: Sequence[str] | str | None = None, event_region_relation: str = 'inside', station_bounds: tuple[float, float, float, float] | None = None, station_bounds_relation: str = 'inside', event_bounds: tuple[float, float, float, float] | None = None, event_bounds_relation: str = 'inside', station_corridor_col: str | None = None, station_corridors: Sequence[str] | str | None = None, station_corridor_relation: str = 'inside', event_corridor_col: str | None = None, event_corridors: Sequence[str] | str | None = None, event_corridor_relation: str = 'inside', station_subset_label: str | None = None, event_subset_label: str | None = None, title: str = 'Azimuthal Residuals', fit_method: str | Callable[[ndarray, ndarray], tuple[ndarray, ndarray] | DataFrame] | None = None, fit: str | Callable[[ndarray, ndarray], tuple[ndarray, ndarray] | DataFrame] | None = None, lowess_frac: float = 0.65, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot residuals against source-station azimuth.

Inputs are metric rows with azimuth and residual columns. When fit_method is supplied, points are shown with a shared fitted curve such as "lowess" instead of connecting every point directly. The output is a Matplotlib figure.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• azimuth_col (str, optional) – Optional function argument. Defaults to 'azimuth_deg'.

• value_col (str, optional) – Optional function argument. Defaults to 'residual'.

• group_col (str | None, optional) – Optional function argument. Defaults to 'model'.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• station_region_col (str | None, optional) – Optional function argument. Defaults to None.

• station_regions (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• station_region_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_region_col (str | None, optional) – Optional function argument. Defaults to None.

• event_regions (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• event_region_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• station_bounds_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• event_bounds_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_corridor_col (str | None, optional) – Optional function argument. Defaults to None.

• station_corridors (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• station_corridor_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_corridor_col (str | None, optional) – Optional function argument. Defaults to None.

• event_corridors (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• event_corridor_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_subset_label (str | None, optional) – Optional function argument. Defaults to None.

• event_subset_label (str | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Azimuthal Residuals'.

• fit_method (str | collections.abc.Callable[[numpy.ndarray, numpy.ndarray], tuple[numpy.ndarray, numpy.ndarray] | pandas.DataFrame] | None, optional) – Optional function argument. Defaults to None.

• fit (str | collections.abc.Callable[[numpy.ndarray, numpy.ndarray], tuple[numpy.ndarray, numpy.ndarray] | pandas.DataFrame] | None, optional) – Optional function argument. Defaults to None.

• lowess_frac (float, optional) – Optional function argument. Defaults to 0.65.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.metrics.plot_geology_contrast(events: DataFrame, output_path: str | Path | None = None, *, station_metadata: DataFrame | None = None, contrast_df: DataFrame | None = None, station_col: str = 'station', value_col: str = 'field_centered', group_col: str | None = None, left_values: tuple[str, ...] | None = None, right_values: tuple[str, ...] | None = None, baseline_values: tuple[str, ...] | None = None, compare_values: tuple[str, ...] | list[str] | list[tuple[str, ...]] | None = None, class_values: tuple[str, ...] | list[str] | None = None, statistic: str | None = None, title: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot two-sided or baseline-relative geology residual contrasts.

Parameters:

• events (pandas.DataFrame) – Event-station residual table.

• output_path (str | pathlib.Path | None, optional) – Optional figure path for older positional usage.

• station_metadata (pandas.DataFrame | None, optional) – Optional station metadata table containing the grouping column.

• contrast_df (pandas.DataFrame | None, optional) – Optional output from bootstrap_contrast_table used to annotate the effect, confidence interval, and p-value.

• station_col (str, optional) – Station and residual-value columns.

• value_col (str, optional) – Station and residual-value columns.

• group_col (str | None, optional) – Metadata class column. When omitted, the active config value is used.

• left_values (tuple[str, ...] | None, optional) – Class labels compared as mean(left) - mean(right). These names are comparison sides, not map directions.

• right_values (tuple[str, ...] | None, optional) – Class labels compared as mean(left) - mean(right). These names are comparison sides, not map directions.

• baseline_values (tuple[str, ...] | None, optional) – Optional baseline mode. When baseline_values is set, the plot shows the baseline class and each comparison class. The contrast table and annotation report comparison - baseline for each comparison.

• compare_values (tuple[str, ...] | list[str] | list[tuple[str, ...]] | None, optional) – Optional baseline mode. When baseline_values is set, the plot shows the baseline class and each comparison class. The contrast table and annotation report comparison - baseline for each comparison.

• class_values (tuple[str, ...] | list[str] | None, optional) – Optional baseline mode. When baseline_values is set, the plot shows the baseline class and each comparison class. The contrast table and annotation report comparison - baseline for each comparison.

• statistic (str | None, optional) – Station-summary statistic used for bootstrap contrasts. Choose "mean" or "median".

• title (str | None, optional) – Optional figure title.

• showfig (bool | None, optional) – Standard Spatial-VTK display and save controls.

• savefig (bool | None, optional) – Standard Spatial-VTK display and save controls.

• outpath (str | pathlib.Path | None, optional) – Standard Spatial-VTK display and save controls.

• events – Required function argument.

• output_path – Optional function argument. Defaults to None.

• station_metadata – Optional function argument. Defaults to None.

• contrast_df – Optional function argument. Defaults to None.

• station_col – Optional function argument. Defaults to 'station'.

• value_col – Optional function argument. Defaults to 'field_centered'.

• group_col – Optional function argument. Defaults to None.

• left_values – Optional function argument. Defaults to None.

• right_values – Optional function argument. Defaults to None.

• baseline_values – Optional function argument. Defaults to None.

• compare_values – Optional function argument. Defaults to None.

• class_values – Optional function argument. Defaults to None.

• statistic – Optional function argument. Defaults to None.

• title – Optional function argument. Defaults to None.

• showfig – Optional function argument. Defaults to None.

• savefig – Optional function argument. Defaults to None.

• outpath – Optional function argument. Defaults to None.

Returns:

Figure showing the residual distributions for configured classes.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.metrics.plot_path_bin_summary(path_summary_df: DataFrame, output_path: str | Path | None = None, *, distance_col: str = 'distance_bin_km', azimuth_col: str = 'azimuth_bin_deg', value_col: str = 'mean_residual', title: str = 'Path-Bin Residual Summary', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot distance/azimuth binned residual values as a heatmap.

Parameters:

• path_summary_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• distance_col (str, optional) – Optional function argument. Defaults to 'distance_bin_km'.

• azimuth_col (str, optional) – Optional function argument. Defaults to 'azimuth_bin_deg'.

• value_col (str, optional) – Optional function argument. Defaults to 'mean_residual'.

• title (str, optional) – Optional function argument. Defaults to 'Path-Bin Residual Summary'.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.metrics.plot_polar_residuals(df: DataFrame, output_path: str | Path | None = None, *, azimuth_col: str = 'azimuth_deg', radius_col: str = 'distance_km', value_col: str = 'residual', facet_col: str | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, station_region_col: str | None = None, station_regions: Sequence[str] | str | None = None, station_region_relation: str = 'inside', event_region_col: str | None = None, event_regions: Sequence[str] | str | None = None, event_region_relation: str = 'inside', station_bounds: tuple[float, float, float, float] | None = None, station_bounds_relation: str = 'inside', event_bounds: tuple[float, float, float, float] | None = None, event_bounds_relation: str = 'inside', station_corridor_col: str | None = None, station_corridors: Sequence[str] | str | None = None, station_corridor_relation: str = 'inside', event_corridor_col: str | None = None, event_corridors: Sequence[str] | str | None = None, event_corridor_relation: str = 'inside', station_subset_label: str | None = None, event_subset_label: str | None = None, title: str = 'Polar Residuals', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot residuals on polar azimuth/distance axes.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• azimuth_col (str, optional) – Optional function argument. Defaults to 'azimuth_deg'.

• radius_col (str, optional) – Optional function argument. Defaults to 'distance_km'.

• value_col (str, optional) – Optional function argument. Defaults to 'residual'.

• facet_col (str | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• station_region_col (str | None, optional) – Optional function argument. Defaults to None.

• station_regions (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• station_region_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_region_col (str | None, optional) – Optional function argument. Defaults to None.

• event_regions (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• event_region_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• station_bounds_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• event_bounds_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_corridor_col (str | None, optional) – Optional function argument. Defaults to None.

• station_corridors (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• station_corridor_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_corridor_col (str | None, optional) – Optional function argument. Defaults to None.

• event_corridors (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• event_corridor_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_subset_label (str | None, optional) – Optional function argument. Defaults to None.

• event_subset_label (str | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Polar Residuals'.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.metrics.plot_residual_correlation(correlation_df: DataFrame, output_path: str | Path | None = None, *, x_col: str = 'feature_value', y_col: str = 'residual', group_col: str | None = None, fit_method: str | Callable[[ndarray, ndarray], tuple[ndarray, ndarray] | DataFrame] | None = None, lowess_frac: float = 0.65, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, station_region_col: str | None = None, station_regions: Sequence[str] | str | None = None, station_region_relation: str = 'inside', event_region_col: str | None = None, event_regions: Sequence[str] | str | None = None, event_region_relation: str = 'inside', station_bounds: tuple[float, float, float, float] | None = None, station_bounds_relation: str = 'inside', event_bounds: tuple[float, float, float, float] | None = None, event_bounds_relation: str = 'inside', station_corridor_col: str | None = None, station_corridors: Sequence[str] | str | None = None, station_corridor_relation: str = 'inside', event_corridor_col: str | None = None, event_corridors: Sequence[str] | str | None = None, event_corridor_relation: str = 'inside', title: str = 'Residual Correlation', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot residuals against a spatial or geologic feature.

Parameters:

• correlation_df (pandas.DataFrame) – Input table containing x and y columns.

• output_path (str | pathlib.Path | None, optional) – Optional destination for saving the figure.

• outpath (str | pathlib.Path | None, optional) – Optional destination for saving the figure.

• x_col (str, optional) – Columns plotted on the x and y axes.

• y_col (str, optional) – Columns plotted on the x and y axes.

• group_col (str | None, optional) – Optional column used to color points and fit one line per group.

• fit_method (str | collections.abc.Callable[[numpy.ndarray, numpy.ndarray], tuple[numpy.ndarray, numpy.ndarray] | pandas.DataFrame] | None, optional) – Optional line-fitting mode. Supported strings are "point-to-point", "best", "linear", "inverse", "inverse-square", "quadratic", "exponential-decay", and "lowess". A callable can also be supplied; it receives finite x and y arrays and should return either (x_fit, y_fit) or a dataframe with x and y columns.

• lowess_frac (float, optional) – Fraction of points used by LOWESS when fit_method="lowess".

• correlation_df – Required function argument.

• output_path – Optional function argument. Defaults to None.

• x_col – Optional function argument. Defaults to 'feature_value'.

• y_col – Optional function argument. Defaults to 'residual'.

• group_col – Optional function argument. Defaults to None.

• fit_method – Optional function argument. Defaults to None.

• lowess_frac – Optional function argument. Defaults to 0.65.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• station_region_col (str | None, optional) – Optional function argument. Defaults to None.

• station_regions (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• station_region_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_region_col (str | None, optional) – Optional function argument. Defaults to None.

• event_regions (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• event_region_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• station_bounds_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• event_bounds_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• station_corridor_col (str | None, optional) – Optional function argument. Defaults to None.

• station_corridors (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• station_corridor_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• event_corridor_col (str | None, optional) – Optional function argument. Defaults to None.

• event_corridors (collections.abc.Sequence[str] | str | None, optional) – Optional function argument. Defaults to None.

• event_corridor_relation (str, optional) – Optional function argument. Defaults to 'inside'.

• title (str, optional) – Optional function argument. Defaults to 'Residual Correlation'.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath – Optional function argument. Defaults to None.

Returns:

The finished figure.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Plot wrappers for PCA spatial-mode diagnostics.

PCA Plots Overview

This module draws non-map PCA diagnostics from public spatial-mode outputs: explained-variance summaries and feature-loading bars.

spatial_vtk.spatial.plot.pca.plot_pca_explained_variance(explained_variance_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'PCA Explained Variance', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot explained variance by PCA mode.

Parameters:

• explained_variance_df (pandas.DataFrame) – Output explained_variance table from compute_pca_spatial_modes.

• output_path (str | pathlib.Path | None, optional) – Figure path to write.

• title (str, optional) – Figure title.

• explained_variance_df – Required function argument.

• output_path – Optional function argument. Defaults to None.

• title – Optional function argument. Defaults to 'PCA Explained Variance'.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.plot.pca.plot_pca_feature_loadings(feature_loadings_df: DataFrame, output_path: str | Path | None = None, *, mode: str = 'PC1', top_n: int = 12, feature_label_map: Mapping[str, str] | None = None, title: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot the strongest feature loadings for one PCA mode.

Parameters:

• feature_loadings_df (pandas.DataFrame) – Output feature_loadings table from compute_pca_spatial_modes.

• output_path (str | pathlib.Path | None, optional) – Figure path to write.

• mode (str, optional) – Mode label to plot, such as "PC1".

• top_n (int, optional) – Number of strongest absolute loadings to draw.

• feature_label_map (Optional, optional) – Optional mapping from raw feature tokens to display labels.

• title (str | None, optional) – Optional figure title.

• feature_loadings_df – Required function argument.

• output_path – Optional function argument. Defaults to None.

• mode – Optional function argument. Defaults to 'PC1'.

• top_n – Optional function argument. Defaults to 12.

• feature_label_map – Optional function argument. Defaults to None.

• title – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Maps

Shared helpers for adding consistent basemaps to geographic figures.

Mapping Basemaps Overview

This module centralizes the package’s simple lon/lat basemap behavior so map figures default to an Esri imagery basemap and fall back cleanly when contextily or remote tiles are unavailable.

spatial_vtk.spatial.map.basemaps.add_contextily_basemap(ax: Any, *, crs: str = 'EPSG:4326', primary_source: str = 'Esri.WorldImagery', fallback_sources: Iterable[str] = ('Esri.WorldTopoMap', 'OpenStreetMap.Mapnik', 'CartoDB.Positron'), zoom: int | None = None, attribution: bool = False, cache_dir: str | Path | None = None, cache_download: bool = True, on_error: str = 'warn') → tuple[bool, str]

Add a tiled basemap with provider fallbacks.

Parameters:

• ax (Any) – Matplotlib axes with geographic longitude/latitude limits already set.

• crs (str, optional) – CRS string describing the current axes coordinates.

• primary_source (str, optional) – Preferred provider name. Defaults to Esri imagery.

• fallback_sources (Iterable, optional) – Additional providers to try before falling back to a static background.

• zoom (int | None, optional) – Optional contextily zoom level.

• attribution (bool, optional) – Whether to draw tile attribution text.

• cache_dir (str | pathlib.Path | None, optional) – Optional local cache directory for downloaded rasters. When omitted, the helper uses .cache/contextily under the repository root.

• cache_download (bool, optional) – Whether to save the preferred provider raster into the cache when the local file is missing and network tile access is available.

• on_error (str, optional) – Error handling when no tiled or cached basemap can be drawn. "warn" emits a warning and draws a static fallback, "raise" raises a RuntimeError, and "ignore" only draws the fallback.

• ax – Required function argument.

• crs – Optional function argument. Defaults to 'EPSG:4326'.

• primary_source – Optional function argument. Defaults to 'Esri.WorldImagery'.

• fallback_sources – Optional function argument. Defaults to ('Esri.WorldTopoMap', 'OpenStreetMap.Mapnik', 'CartoDB.Positron').

• zoom – Optional function argument. Defaults to None.

• attribution – Optional function argument. Defaults to False.

• cache_dir – Optional function argument. Defaults to None.

• cache_download – Optional function argument. Defaults to True.

• on_error – Optional function argument. Defaults to 'warn'.

Returns:

(success, source_name). When success is False, a static background has already been drawn and source_name contains the last error string.

Return type:

tuple

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.spatial.map.basemaps.basemap_cache_path_for_extent(*, west: float, south: float, east: float, north: float, source_name: str = 'Esri.WorldImagery', zoom: int = 8, cache_dir: str | Path | None = None) → Path

Return the deterministic cache path for one basemap extent.

Parameters:

• west (float) – Required function argument.

• south (float) – Required function argument.

• east (float) – Required function argument.

• north (float) – Required function argument.

• source_name (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• zoom (int, optional) – Optional function argument. Defaults to 8.

• cache_dir (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.spatial.map.basemaps.cache_contextily_basemap_raster(*, west: float, south: float, east: float, north: float, source_name: str = 'Esri.WorldImagery', zoom: int = 8, cache_dir: str | Path | None = None, ll: bool = True) → Path

Download and cache one basemap raster for later offline reuse.

Parameters:

• west (float) – Bounds for the requested raster. For lon/lat inputs, keep ll=True.

• south (float) – Bounds for the requested raster. For lon/lat inputs, keep ll=True.

• east (float) – Bounds for the requested raster. For lon/lat inputs, keep ll=True.

• north (float) – Bounds for the requested raster. For lon/lat inputs, keep ll=True.

• source_name (str, optional) – Contextily provider name. Defaults to Esri.WorldImagery.

• zoom (int, optional) – Tile zoom level.

• cache_dir (str | pathlib.Path | None, optional) – Optional cache directory. Defaults to .cache/contextily.

• ll (bool, optional) – Whether the bounds are longitude/latitude.

• west – Required function argument.

• south – Required function argument.

• east – Required function argument.

• north – Required function argument.

• source_name – Optional function argument. Defaults to 'Esri.WorldImagery'.

• zoom – Optional function argument. Defaults to 8.

• cache_dir – Optional function argument. Defaults to None.

• ll – Optional function argument. Defaults to True.

Returns:

Written GeoTIFF path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.spatial.map.basemaps.default_basemap_cache_dir() → Path

Return the default local cache directory for basemap rasters.

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.spatial.map.basemaps.draw_static_basemap_fallback(ax: Any) → None

Draw a lightweight static background when tiled basemaps are unavailable.

Parameters:

• ax (Any) – Matplotlib axes with longitude on x and latitude on y.

• ax – Required function argument.

Returns:

The helper mutates ax in place.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

Map wrappers for station bias, clustering, and holdout results.

Mapping Correlation Overview

This module draws map figures from public spatial-statistics tables. Basemaps are enabled by default through the package’s contextily helper, but callers can disable them for tests or fully offline rendering.

spatial_vtk.spatial.map.correlation.plot_block_holdout_error_map(prediction_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Spatial Block Holdout Error', bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot held-out station prediction errors on a lon/lat map.

Parameters:

• prediction_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Spatial Block Holdout Error'.

• bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.correlation.plot_block_holdout_summary(prediction_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Spatial Block Holdout Summary', bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot held-out station-bias errors and observed/predicted agreement.

Parameters:

• prediction_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Spatial Block Holdout Summary'.

• bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.correlation.plot_cluster_map(assignments_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Residual Clusters', cluster_col: str = 'cluster_id', bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot station cluster assignments on a lon/lat map.

Parameters:

• assignments_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Residual Clusters'.

• cluster_col (str, optional) – Optional function argument. Defaults to 'cluster_id'.

• bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.correlation.plot_cluster_summary(assignments_df: DataFrame, score_df: DataFrame, feature_summary_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Residual Cluster Summary', cluster_col: str = 'cluster_id', k_column: str = 'n_clusters', score_column: str = 'silhouette', feature_label_map: dict[str, str] | None = None, event_df: DataFrame | None = None, clustered_value_label: str | None = None, bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot station cluster assignments and silhouette scores together.

Parameters:

• assignments_df (pandas.DataFrame) – Required function argument.

• score_df (pandas.DataFrame) – Required function argument.

• feature_summary_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Residual Cluster Summary'.

• cluster_col (str, optional) – Optional function argument. Defaults to 'cluster_id'.

• k_column (str, optional) – Optional function argument. Defaults to 'n_clusters'.

• score_column (str, optional) – Optional function argument. Defaults to 'silhouette'.

• feature_label_map (dict[str, str] | None, optional) – Optional function argument. Defaults to None.

• event_df (pandas.DataFrame | None, optional) – Optional function argument. Defaults to None.

• clustered_value_label (str | None, optional) – Optional function argument. Defaults to None.

• bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.correlation.plot_redcap_cluster_map(redcap_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'REDCAP Clusters', value_col: str = 'avg_observed_metric_distance_scaled_event_demeaned', bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot station values beside REDCAP cluster assignments.

Parameters:

• redcap_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'REDCAP Clusters'.

• value_col (str, optional) – Optional function argument. Defaults to 'avg_observed_metric_distance_scaled_event_demeaned'.

• bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.correlation.plot_station_bias_map(station_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Station Bias', value_col: str = 'mean_centered', value_label: str | None = None, bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot station bias values on a lon/lat map.

Inputs are a station-level summary table with coordinates and a numeric bias column. The output is a Matplotlib figure with an optional basemap and a colorbar whose label can be overridden when the summarized field needs a more specific description than the column name provides.

Parameters:

• station_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Station Bias'.

• value_col (str, optional) – Optional function argument. Defaults to 'mean_centered'.

• value_label (str | None, optional) – Optional function argument. Defaults to None.

• bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Map GeoJSON polygon regions with station and event context.

GeoJSON Maps Overview

This module provides a first-class plotting helper for inspecting polygon regions used by Spatial-VTK GeoJSON and corridor workflows.

GeoJSON Maps Examples

Plot configured regions with station and event context:

plot_geojson_polygons_map("regions.geojson", stations_df=stations, events_df=events)

spatial_vtk.spatial.map.geojson.plot_geojson_polygons_map(geojson_path: str | Path, output_path: str | Path | None = None, *, selector: object = 'all', stations_df: DataFrame | None = None, events_df: DataFrame | None = None, title: str = 'GeoJSON Regions', add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, label_polygons: bool = True, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot selected GeoJSON polygons with optional station/event points.

Parameters:

• geojson_path (str | pathlib.Path) – Path to a GeoJSON file containing Polygon or MultiPolygon features.

• output_path (str | pathlib.Path | None, optional) – Optional destination figure path.

• selector (object, optional) – Polygon selector accepted by select_geojson_polygons().

• stations_df (pandas.DataFrame | None, optional) – Optional context tables with station and event coordinates.

• events_df (pandas.DataFrame | None, optional) – Optional context tables with station and event coordinates.

• title (str, optional) – Figure title.

• add_basemap (bool, optional) – Whether to draw a basemap underneath the polygon layers.

• basemap_source (str, optional) – Basemap provider settings forwarded to the shared basemap helper.

• basemap_kwargs (dict[str, Any] | None, optional) – Basemap provider settings forwarded to the shared basemap helper.

• label_polygons (bool, optional) – Whether to annotate polygon names at their representative points.

• showfig (bool | None, optional) – Standard Spatial-VTK figure display/save controls.

• savefig (bool | None, optional) – Standard Spatial-VTK figure display/save controls.

• outpath (str | pathlib.Path | None, optional) – Standard Spatial-VTK figure display/save controls.

• geojson_path – Required function argument.

• output_path – Optional function argument. Defaults to None.

• selector – Optional function argument. Defaults to 'all'.

• stations_df – Optional function argument. Defaults to None.

• events_df – Optional function argument. Defaults to None.

• title – Optional function argument. Defaults to 'GeoJSON Regions'.

• add_basemap – Optional function argument. Defaults to True.

• basemap_source – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs – Optional function argument. Defaults to None.

• label_polygons – Optional function argument. Defaults to True.

• showfig – Optional function argument. Defaults to None.

• savefig – Optional function argument. Defaults to None.

• outpath – Optional function argument. Defaults to None.

Returns:

The created figure.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Geographic metric map figures.

spatial_vtk.spatial.map.metrics.plot_metric_map_by_model(df: DataFrame, output_path: str | Path | None = None, *, model_col: str = 'model', value_col: str = 'residual', lon_col: str = 'sta_lon', lat_col: str = 'sta_lat', max_models: int = 4, title: str = 'Metric Map by Model', add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot station metric maps faceted by model.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• model_col (str, optional) – Optional function argument. Defaults to 'model'.

• value_col (str, optional) – Optional function argument. Defaults to 'residual'.

• lon_col (str, optional) – Optional function argument. Defaults to 'sta_lon'.

• lat_col (str, optional) – Optional function argument. Defaults to 'sta_lat'.

• max_models (int, optional) – Optional function argument. Defaults to 4.

• title (str, optional) – Optional function argument. Defaults to 'Metric Map by Model'.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.metrics.plot_model_improvement_map(df: DataFrame, output_path: str | Path | None = None, *, improvement_col: str = 'improvement', title: str = 'Model Improvement Map', **kwargs) → Figure

Plot model improvement values on a map.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• improvement_col (str, optional) – Optional function argument. Defaults to 'improvement'.

• title (str, optional) – Optional function argument. Defaults to 'Model Improvement Map'.

• kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.metrics.plot_residual_grid(grid_df: DataFrame, output_path: str | Path | None = None, *, lon_col: str = 'lon', lat_col: str = 'lat', value_col: str = 'residual', cell_size_deg: float | tuple[float, float] | None = None, title: str = 'Residual Grid', add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot gridded residual values on geographic axes.

Inputs are lon/lat/value rows where lon/lat are grid-cell centers. When cell_size_deg is set, rows are aggregated onto that lon/lat cell size before plotting so the map boxes have an explicit visual footprint. Returns a Matplotlib figure.

Parameters:

• grid_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• lon_col (str, optional) – Optional function argument. Defaults to 'lon'.

• lat_col (str, optional) – Optional function argument. Defaults to 'lat'.

• value_col (str, optional) – Optional function argument. Defaults to 'residual'.

• cell_size_deg (float | tuple[float, float] | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'Residual Grid'.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.metrics.plot_score_map(df: DataFrame, output_path: str | Path | None = None, *, score_col: str = 'score', **kwargs) → Figure

Plot station or path scores on a map.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• score_col (str, optional) – Optional function argument. Defaults to 'score'.

• kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.metrics.plot_station_metric_map(df: DataFrame, output_path: str | Path | None = None, *, value_col: str = 'residual', lon_col: str = 'sta_lon', lat_col: str = 'sta_lat', corridors_df: DataFrame | None = None, events_df: DataFrame | None = None, records_df: DataFrame | None = None, geojson_path: str | Path | None = None, polygon_selector: object = 'all', polygon_alpha: float = 0.16, label_polygons: bool = False, event_alpha: float = 0.78, title: str = 'Station Metric Map', add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None, spatial_selection: FigureSpatialSelection | dict[str, object] | None = None, **spatial_kwargs: object) → Figure

Plot station-level metric values on a map.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• value_col (str, optional) – Optional function argument. Defaults to 'residual'.

• lon_col (str, optional) – Optional function argument. Defaults to 'sta_lon'.

• lat_col (str, optional) – Optional function argument. Defaults to 'sta_lat'.

• corridors_df (pandas.DataFrame | None, optional) – Optional function argument. Defaults to None.

• events_df (pandas.DataFrame | None, optional) – Optional function argument. Defaults to None.

• records_df (pandas.DataFrame | None, optional) – Optional function argument. Defaults to None.

• geojson_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• polygon_selector (object, optional) – Optional function argument. Defaults to 'all'.

• polygon_alpha (float, optional) – Optional function argument. Defaults to 0.16.

• label_polygons (bool, optional) – Optional function argument. Defaults to False.

• event_alpha (float, optional) – Optional function argument. Defaults to 0.78.

• title (str, optional) – Optional function argument. Defaults to 'Station Metric Map'.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, object] | None, optional) – Optional function argument. Defaults to None.

• spatial_kwargs (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Map wrappers for PCA spatial modes.

PCA Maps Overview

This module maps station scores from PCA spatial-mode outputs. Basemaps are enabled by default through the package’s shared contextily helper.

spatial_vtk.spatial.map.pca.plot_pca_mode_map(station_scores_df: DataFrame, output_path: str | Path | None = None, *, mode: str = 'PC1', score_col: str | None = None, title: str | None = None, bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot one PCA station-score mode on a lon/lat map.

Parameters:

• station_scores_df (pandas.DataFrame) – Station score table from compute_pca_spatial_modes.

• output_path (str | pathlib.Path | None, optional) – Figure path to write.

• mode (str, optional) – Mode label, such as "PC1". Used to infer score_col.

• score_col (str | None, optional) – Optional explicit score column. Defaults to "<mode>_score".

• title (str | None, optional) – Optional figure title.

• bounds (tuple[float, float, float, float] | None, optional) – Optional (west, east, south, north) map bounds.

• add_basemap (bool, optional) – Whether to add a contextily basemap layer.

• basemap_source (str, optional) – Contextily provider selector.

• basemap_kwargs (dict[str, Any] | None, optional) – Extra keyword arguments passed to the shared basemap helper.

• station_scores_df – Required function argument.

• output_path – Optional function argument. Defaults to None.

• mode – Optional function argument. Defaults to 'PC1'.

• score_col – Optional function argument. Defaults to None.

• title – Optional function argument. Defaults to None.

• bounds – Optional function argument. Defaults to None.

• add_basemap – Optional function argument. Defaults to True.

• basemap_source – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.spatial.map.pca.plot_pca_summary(station_scores_df: DataFrame, explained_variance_df: DataFrame, feature_loadings_df: DataFrame, output_path: str | Path | None = None, *, mode: str = 'PC1', score_col: str | None = None, feature_label_map: Mapping[str, str] | None = None, station_feature_df: DataFrame | None = None, station_feature_col: str | None = None, station_feature_fit_method: object = 'linear', station_feature_lowess_frac: float = 0.65, station_col: str = 'station', station_feature_title: str | None = None, event_df: DataFrame | None = None, title: str = 'PCA Spatial Mode Summary', bounds: tuple[float, float, float, float] | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot PCA station scores, explained variance, and an interpretation panel.

Parameters:

• station_scores_df (pandas.DataFrame) – Required function argument.

• explained_variance_df (pandas.DataFrame) – Required function argument.

• feature_loadings_df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• mode (str, optional) – Optional function argument. Defaults to 'PC1'.

• score_col (str | None, optional) – Optional function argument. Defaults to None.

• feature_label_map (collections.abc.Mapping[str, str] | None, optional) – Optional function argument. Defaults to None.

• station_feature_df (pandas.DataFrame | None, optional) – Optional function argument. Defaults to None.

• station_feature_col (str | None, optional) – Optional function argument. Defaults to None.

• station_feature_fit_method (object, optional) – Optional function argument. Defaults to 'linear'.

• station_feature_lowess_frac (float, optional) – Optional function argument. Defaults to 0.65.

• station_col (str, optional) – Optional function argument. Defaults to 'station'.

• station_feature_title (str | None, optional) – Optional function argument. Defaults to None.

• event_df (pandas.DataFrame | None, optional) – Optional function argument. Defaults to None.

• title (str, optional) – Optional function argument. Defaults to 'PCA Spatial Mode Summary'.

• bounds (tuple[float, float, float, float] | None, optional) – Optional function argument. Defaults to None.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Path Maps

Map polygon-boundary corridors with station and event context.

spatial_vtk.spatial.map.path.corridors.plot_corridor_map(corridors_df: DataFrame, output_path: str | Path | None = None, *, stations_df: DataFrame | None = None, events_df: DataFrame | None = None, records_df: DataFrame | None = None, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, highlight_anchor: bool = False, title: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot corridor footprints with optional station, event, and path context.

Parameters:

• corridors_df (pandas.DataFrame) – Corridor table with a corridor_geometry Shapely polygon column.

• output_path (str | pathlib.Path | None, optional) – Figure path.

• stations_df (pandas.DataFrame | None, optional) – Optional station/event context tables.

• events_df (pandas.DataFrame | None, optional) – Optional station/event context tables.

• records_df (pandas.DataFrame | None, optional) – Optional event-station path table.

• add_basemap (bool, optional) – Whether to draw a contextily basemap. Defaults to True for public map outputs; tests may disable it for offline rendering.

• basemap_source (str, optional) – Basemap provider settings.

• basemap_kwargs (dict[str, Any] | None, optional) – Basemap provider settings.

• highlight_anchor (bool, optional) – Whether to highlight station/event anchor rows used to place the corridor. Falls back to the boundary anchor point if the source point table is not available.

• title (str | None, optional) – Optional figure title.

• corridors_df – Required function argument.

• output_path – Optional function argument. Defaults to None.

• stations_df – Optional function argument. Defaults to None.

• events_df – Optional function argument. Defaults to None.

• records_df – Optional function argument. Defaults to None.

• add_basemap – Optional function argument. Defaults to True.

• basemap_source – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs – Optional function argument. Defaults to None.

• highlight_anchor – Optional function argument. Defaults to False.

• title – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Figure object.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Map source-station residual patterns for one event or metric selection.

spatial_vtk.spatial.map.path.residuals.plot_event_residual_map(df: DataFrame, output_path: str | Path | None = None, *, event_id: str | None = None, metric: str | None = None, value_col: str = 'residual', add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, title: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot station residuals for one event/metric selection.

Map figures add a basemap by default, following the repository figure rule. Tests may pass add_basemap=False for fully offline rendering.

Parameters:

• df (pandas.DataFrame) – Required function argument.

• output_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

• event_id (str | None, optional) – Optional function argument. Defaults to None.

• metric (str | None, optional) – Optional function argument. Defaults to None.

• value_col (str, optional) – Optional function argument. Defaults to 'residual'.

• add_basemap (bool, optional) – Optional function argument. Defaults to True.

• basemap_source (str, optional) – Optional function argument. Defaults to 'Esri.WorldImagery'.

• basemap_kwargs (dict[str, Any] | None, optional) – Optional function argument. Defaults to None.

• title (str | None, optional) – Optional function argument. Defaults to None.

• showfig (bool | None, optional) – Optional function argument. Defaults to None.

• savefig (bool | None, optional) – Optional function argument. Defaults to None.

• outpath (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure