Visualization API

Visualization modules create context figures, QC and retention figures, waveform plots, reusable figure utilities, and Streamlit dashboard inputs.

Package Entry Point 

Visualization and dashboard preparation modules.

spatial_vtk.visualize.apply_figure_context(ax: Axes, df: DataFrame | None = None, *, value_col: str | None = None, title: str | None = None, max_values: int = 5, include_counts: bool = True, include_value: bool = True, include_metric: bool = True, include_model: bool = True, include_period: bool = True, include_component: bool = True, include_processing: bool = True, max_line_chars: int = 90, extra: Sequence[str] | None = None) → None

Apply a title plus concise context line to an axis.

Parameters:

ax (matplotlib.axes._axes.Axes) – Matplotlib axis to update.
df (pandas.DataFrame | None, optional) – Optional dataframe used to infer context.
value_col (str | None, optional) – Column or transform shown by the figure.
title (str | None, optional) – Primary title text.
max_values (int, optional) – Maximum distinct values to list in the context.
include_counts (bool, optional) – Whether to include rows/events/stations.
extra (collections.abc.Sequence[str] | None, optional) – Additional preformatted context strings.
ax – Required function argument.
df – Optional function argument. Defaults to None.
value_col – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to None.
max_values – Optional function argument. Defaults to 5.
include_counts – Optional function argument. Defaults to True.
include_value (bool, optional) – Optional function argument. Defaults to True.
include_metric (bool, optional) – Optional function argument. Defaults to True.
include_model (bool, optional) – Optional function argument. Defaults to True.
include_period (bool, optional) – Optional function argument. Defaults to True.
include_component (bool, optional) – Optional function argument. Defaults to True.
include_processing (bool, optional) – Optional function argument. Defaults to True.
max_line_chars (int, optional) – Optional function argument. Defaults to 90.
extra – Optional function argument. Defaults to None.

Returns:

The axis title is updated in place.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.visualize.build_dashboard_summaries(df: DataFrame, *, hex_dist: float = 10.0, hex_az: float = 10.0) → dict[str, DataFrame]

Build dashboard summary tables from long metric residual data.

Parameters:

df (pandas.DataFrame) – Wide or long metric table.
hex_dist (float, optional) – Distance bin size in kilometers for path summaries.
hex_az (float, optional) – Azimuth bin size in degrees for path summaries.
df – Required function argument.
hex_dist – Optional function argument. Defaults to 10.0.
hex_az – Optional function argument. Defaults to 10.0.

Returns:

Summary tables keyed as model_metric_band, station_rollup, event_rollup, and path_hex.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.visualize.build_record_section_rows(records: DataFrame | Iterable[Any], *, trace_col: str = 'trace', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', default_dt: float = 1.0) → DataFrame

Normalize traces or a record table to the plotting row contract.

Parameters:

records (Union) – DataFrame with trace rows or iterable of trace-like objects.
trace_col (str, optional) – Trace column used when records is a DataFrame.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
records – Required function argument.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
default_dt – Optional function argument. Defaults to 1.0.

Returns:

Table with trace, dt, station, component, and distance_km columns where available.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.build_trace_qc_overview_html(trace_summary: DataFrame | str | Path, output_root: str | Path, *, title: str = 'Trace QC Overview') → str

Build a standalone QC overview HTML document.

Parameters:

trace_summary (pandas.DataFrame | str | pathlib.Path) – Trace summary dataframe or table path.
output_root (str | pathlib.Path) – Output root recorded in the page metadata.
title (str, optional) – Page title.
trace_summary – Required function argument.
output_root – Required function argument.
title – Optional function argument. Defaults to 'Trace QC Overview'.

Returns:

HTML document string with embedded JSON records.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.context_value_label(value_col: str, df: DataFrame | None = None) → str

Return a value label with centering/ratio notes where detectable.

Parameters:

value_col (str) – Column or transform shown by the figure.
df (pandas.DataFrame | None, optional) – Optional dataframe used to inspect field_source and event-centering metadata.
value_col – Required function argument.
df – Optional function argument. Defaults to None.

Returns:

Human-readable value label.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.default_figure_paths(figure_dir: str | Path, names: tuple[str, ...] | list[str] | None = None, *, suffix: str = '.png', create_dir: bool = True) → SimpleNamespace

Return a namespace of standard figure paths.

Parameters:

figure_dir (str | pathlib.Path) – Directory where figures should be written.
names (tuple[str, ...] | list[str] | None, optional) – Optional figure basenames. When omitted, common tutorial/workflow figure names are returned.
suffix (str, optional) – File extension to append when a name has no extension.
create_dir (bool, optional) – Whether to create figure_dir.
figure_dir – Required function argument.
names – Optional function argument. Defaults to None.
suffix – Optional function argument. Defaults to '.png'.
create_dir – Optional function argument. Defaults to True.

Returns:

Namespace with one attribute per figure basename.

Return type:

types.SimpleNamespace

Returns:

Return value produced by the function.

Return type:

types.SimpleNamespace

spatial_vtk.visualize.figure_context_lines(df: DataFrame | None = None, *, value_col: str | None = None, max_values: int = 5, include_counts: bool = True, include_value: bool = True, include_metric: bool = True, include_model: bool = True, include_period: bool = True, include_component: bool = True, include_processing: bool = True, extra: Sequence[str] | None = None) → list[str]

Build concise context lines from common Spatial-VTK columns.

Parameters:

df (pandas.DataFrame | None, optional) – Optional dataframe used to infer model, metric, period band, component, and row-count context.
value_col (str | None, optional) – Column or transform shown by the figure.
max_values (int, optional) – Maximum distinct values to show before summarizing as “N values”.
include_counts (bool, optional) – Whether to include rows/events/stations when available.
extra (collections.abc.Sequence[str] | None, optional) – Additional preformatted context strings.
df – Optional function argument. Defaults to None.
value_col – Optional function argument. Defaults to None.
max_values – Optional function argument. Defaults to 5.
include_counts – Optional function argument. Defaults to True.
include_value (bool, optional) – Optional function argument. Defaults to True.
include_metric (bool, optional) – Optional function argument. Defaults to True.
include_model (bool, optional) – Optional function argument. Defaults to True.
include_period (bool, optional) – Optional function argument. Defaults to True.
include_component (bool, optional) – Optional function argument. Defaults to True.
include_processing (bool, optional) – Optional function argument. Defaults to True.
extra – Optional function argument. Defaults to None.

Returns:

Context lines suitable for a subtitle or annotation box.

Return type:

list of str

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.visualize.figure_context_text(df: DataFrame | None = None, *, value_col: str | None = None, separator: str = ' | ', **kwargs: Any) → str

Return figure context as one compact string.

Parameters:

df (pandas.DataFrame | None, optional) – Optional dataframe used to infer context.
value_col (str | None, optional) – Column or transform shown by the figure.
separator (str, optional) – Separator used between context fragments.
**kwargs – Additional options passed to figure_context_lines().
df – Optional function argument. Defaults to None.
value_col – Optional function argument. Defaults to None.
separator – Optional function argument. Defaults to ' | '.
kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

One-line context string.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

Filter one trace-QC summary table.

Parameters:

trace_df (pandas.DataFrame) – Normalized trace summary table.
event_filter (str, optional) – Optional exact event ID filter.
station_family (str, optional) – all or a station-family value.
component_filter (str, optional) – all or one component token.
station_query (str, optional) – Optional station substring.
magnitude_range (tuple[float | None, float | None] | None, optional) – Optional inclusive magnitude range.
distance_range_km (tuple[float | None, float | None] | None, optional) – Optional inclusive distance range.
date_range (tuple[pandas.Timestamp | str | None, pandas.Timestamp | str | None] | None, optional) – Optional inclusive date range.
trace_df – Required function argument.
event_filter – Optional function argument. Defaults to ''.
station_family – Optional function argument. Defaults to 'all'.
component_filter – Optional function argument. Defaults to 'all'.
station_query – Optional function argument. Defaults to ''.
magnitude_range – Optional function argument. Defaults to None.
distance_range_km – Optional function argument. Defaults to None.
date_range – Optional function argument. Defaults to None.

Returns:

Filtered table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Apply standard show/save behavior and return the figure.

Parameters:

fig (matplotlib.figure.Figure) – Matplotlib figure to finish.
output_path (str | pathlib.Path | None, optional) – Optional destination path. outpath is the preferred public keyword; output_path preserves older positional usage.
outpath (str | pathlib.Path | None, optional) – Optional destination path. outpath is the preferred public keyword; output_path preserves older positional usage.
output_key (str | None, optional) – Optional default-output registry key. When omitted and savefig is true, Spatial-VTK infers a key from the plotting function name.
cfg (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to resolve default output folders.
showfig (bool | None, optional) – Whether to display the figure. When None, figures display inside notebooks and stay quiet in scripts/tests.
savefig (bool | None, optional) – Whether to save the figure. When None, the figure is saved if a path is provided.
close (bool | None, optional) – Whether to close the figure after saving/display handling. When None, finished figures that are saved or explicitly displayed are closed after handling. This prevents notebook backends from auto- rendering a second copy after Spatial-VTK has already displayed one.
bbox_inches (str, optional) – Matplotlib bounding-box setting used by Figure.savefig.
**savefig_kwargs – Additional keyword arguments passed to Figure.savefig.
fig – Required function argument.
output_path – Optional function argument. Defaults to None.
outpath – Optional function argument. Defaults to None.
output_key – Optional function argument. Defaults to None.
cfg – Optional function argument. Defaults to None.
showfig – Optional function argument. Defaults to None.
savefig – Optional function argument. Defaults to None.
close – Optional function argument. Defaults to None.
bbox_inches – Optional function argument. Defaults to 'tight'.
savefig_kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

The input figure.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.visualize.is_log2_ratio_field(value_col: str | None, df: DataFrame | None = None) → bool

Return whether a field is interpretable as a log2 observed/synthetic ratio.

Parameters:

value_col (str | None) – Value column or transform name.
df (pandas.DataFrame | None, optional) – Optional dataframe used to inspect field_source.
value_col – Required function argument.
df – Optional function argument. Defaults to None.

Returns:

True when percent conversion with 2 ** effect - 1 is meaningful.

Return type:

bool

Returns:

Return value produced by the function.

Return type:

bool

spatial_vtk.visualize.launch_metrics_dashboard(*, metrics_root: str | Path, summary_root: str | Path, server_address: str = '127.0.0.1', server_port: int = 8501, show: bool = True, extra_args: list[str] | None = None) → Popen[Any]

Launch the Streamlit Metrics Explorer.

Parameters:

metrics_root (str | pathlib.Path) – Required function argument.
summary_root (str | pathlib.Path) – Required function argument.
server_address (str, optional) – Optional function argument. Defaults to '127.0.0.1'.
server_port (int, optional) – Optional function argument. Defaults to 8501.
show (bool, optional) – Optional function argument. Defaults to True.
extra_args (list[str] | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

subprocess.Popen

spatial_vtk.visualize.launch_qc_dashboard(*, trace_summary: str | Path | None = None, config_path: str | Path | None = None, server_address: str = '127.0.0.1', server_port: int = 8502, show: bool = True, extra_args: list[str] | None = None) → Popen[Any]

Launch the Streamlit QC Explorer.

Parameters:

trace_summary (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
config_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
server_address (str, optional) – Optional function argument. Defaults to '127.0.0.1'.
server_port (int, optional) – Optional function argument. Defaults to 8502.
show (bool, optional) – Optional function argument. Defaults to True.
extra_args (list[str] | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

subprocess.Popen

spatial_vtk.visualize.load_dashboard_metric_dataset(input_root: str | Path) → DataFrame

Load a dashboard metric Parquet dataset.

Parameters:

input_root (str | pathlib.Path) – Directory containing metrics_long.parquet or partitioned parquet files.
input_root – Required function argument.

Returns:

Combined long metric table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.log2_effect_to_percent(effect: float | int | floating[Any]) → float

Convert a log2 ratio difference to percent change.

Parameters:

effect (float | int | numpy.floating[Any]) – Difference in log2 observed/synthetic ratio units.
effect – Required function argument.

Returns:

Percent change in observed/synthetic ratio.

Return type:

float

Returns:

Return value produced by the function.

Return type:

float

spatial_vtk.visualize.plot_data_synthetic_availability(availability_df: DataFrame, output_path: str | Path | None = None, *, event_col: str = 'event_id', station_col: str = 'station', observed_col: str = 'observed_available', synthetic_col: str = 'synthetic_available', title: str = 'Observed and Synthetic Availability', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed/synthetic availability as an event-station matrix.

Parameters:

availability_df (pandas.DataFrame) – Event-station availability table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
event_col (str, optional) – Event and station identifier columns.
station_col (str, optional) – Event and station identifier columns.
observed_col (str, optional) – Boolean availability columns.
synthetic_col (str, optional) – Boolean availability columns.
title (str, optional) – Figure title.
availability_df – Required function argument.
output_path – Optional function argument. Defaults to None.
event_col – Optional function argument. Defaults to 'event_id'.
station_col – Optional function argument. Defaults to 'station'.
observed_col – Optional function argument. Defaults to 'observed_available'.
synthetic_col – Optional function argument. Defaults to 'synthetic_available'.
title – Optional function argument. Defaults to 'Observed and Synthetic Availability'.
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.visualize.plot_event_magnitude_map(events_df: DataFrame, output_path: str | Path | None = None, *, magnitude_col: str = 'magnitude', lon_col: str = 'event_lon', lat_col: str = 'event_lat', label_col: str | None = 'event_id', title: str = 'Event Magnitudes', 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 events sized and colored by magnitude.

Parameters:

events_df (pandas.DataFrame) – Event metadata table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
magnitude_col (str, optional) – Magnitude and coordinate columns.
lon_col (str, optional) – Magnitude and coordinate columns.
lat_col (str, optional) – Magnitude and coordinate columns.
label_col (str | None, optional) – Optional event label column.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
magnitude_col – Optional function argument. Defaults to 'magnitude'.
lon_col – Optional function argument. Defaults to 'event_lon'.
lat_col – Optional function argument. Defaults to 'event_lat'.
label_col – Optional function argument. Defaults to 'event_id'.
title – Optional function argument. Defaults to 'Event Magnitudes'.
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.visualize.plot_event_radial_trace_section(records_df: DataFrame, output_path: str | Path | None = None, *, trace_col: str = 'trace', station_col: str = 'station', distance_col: str = 'distance_km', azimuth_col: str = 'azimuth_deg', station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', dt_col: str = 'dt', selection: FigureSelection | None = None, normalize: bool = True, time_limit_s: float | None = 60.0, title: str = 'Event Radial Trace Section', filter_label: str | 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 traces ordered by azimuth with a station/event map panel.

Parameters:

records_df (pandas.DataFrame) – Table with waveform, geometry, and azimuth columns.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Trace and sorting/label columns.
station_col (str, optional) – Trace and sorting/label columns.
distance_col (str, optional) – Trace and sorting/label columns.
azimuth_col (str, optional) – Trace and sorting/label columns.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
dt_col (str, optional) – Sample interval column.
normalize (bool, optional) – Whether to normalize traces.
time_limit_s (float | None, optional) – Optional maximum trace time to draw in seconds. Defaults to 60 seconds.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
distance_col – Optional function argument. Defaults to 'distance_km'.
azimuth_col – Optional function argument. Defaults to 'azimuth_deg'.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
dt_col – Optional function argument. Defaults to 'dt'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
normalize – Optional function argument. Defaults to True.
time_limit_s – Optional function argument. Defaults to 60.0.
title – Optional function argument. Defaults to 'Event Radial Trace Section'.
filter_label – 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.visualize.plot_event_station_retention_heatmap(retention_df: DataFrame, output_path: str | Path | None = None, *, event_col: str = 'event_id', station_col: str = 'station', value_col: str = 'retention_percent', retained_col: str = 'retained_pairs', total_col: str = 'total_pairs', title: str = 'Event-Station Pair Retention', show_counts: bool = True, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot retained comparison percentage for each event-station pair.

Parameters:

retention_df (pandas.DataFrame) – Event-station retention table with retained and total comparison-pair counts across components, passbands, and metrics.
output_path (str | pathlib.Path | None, optional) – Optional destination figure path.
outpath (str | pathlib.Path | None, optional) – Optional destination figure path.
event_col (str, optional) – Event and station identifier columns.
station_col (str, optional) – Event and station identifier columns.
value_col (str, optional) – Percentage column used for heatmap color.
retained_col (str, optional) – Count columns used for optional in-cell labels.
total_col (str, optional) – Count columns used for optional in-cell labels.
title (str, optional) – Figure title.
show_counts (bool, optional) – Whether to label each cell with retained/total pair counts.
showfig (bool | None, optional) – Standard display/save flags.
savefig (bool | None, optional) – Standard display/save flags.
retention_df – Required function argument.
output_path – Optional function argument. Defaults to None.
event_col – Optional function argument. Defaults to 'event_id'.
station_col – Optional function argument. Defaults to 'station'.
value_col – Optional function argument. Defaults to 'retention_percent'.
retained_col – Optional function argument. Defaults to 'retained_pairs'.
total_col – Optional function argument. Defaults to 'total_pairs'.
title – Optional function argument. Defaults to 'Event-Station Pair Retention'.
show_counts – 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:

Created figure.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.visualize.plot_event_trace_comparison(records_df: DataFrame, output_path: str | Path | None = None, *, observed_col: str = 'observed', synthetic_col: str = 'synthetic', dt_col: str = 'dt', synthetic_dt_col: str = 'synthetic_dt', observed_time_offset_col: str = 'observed_time_offset_s', synthetic_time_offset_col: str = 'synthetic_time_offset_s', station_col: str = 'station', component_col: str | None = 'component', selection: FigureSelection | None = None, distance_col: str = 'distance_km', distance_limit_km: float | None = None, max_records: int | None = 30, normalize: bool = True, amplitude_gain: float | str = 1.0, amplitude_gain_multiplier: float = 1.0, time_limit_s: float | None = 60.0, title: str = 'Observed and Synthetic Trace Comparison', filter_label: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed and synthetic traces sorted by source distance.

Parameters:

records_df (pandas.DataFrame) – Table with observed and synthetic waveform arrays or ObsPy-like traces.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
observed_col (str, optional) – Waveform columns.
synthetic_col (str, optional) – Waveform columns.
dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
synthetic_dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
observed_time_offset_col (str, optional) – Optional columns giving the trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
synthetic_time_offset_col (str, optional) – Optional columns giving the trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component grouping column.
distance_col (str, optional) – Optional distance column used for vertical position.
distance_limit_km (float | None, optional) – Optional maximum source-to-station distance to include.
max_records (int | None, optional) – Maximum rows per component.
normalize (bool, optional) – Whether to normalize each waveform before plotting.
amplitude_gain (float | str, optional) – Single global gain applied to every plotted waveform after optional normalization. Use values greater than 1 to inspect unnormalized traces while preserving observed/synthetic relative amplitudes.
amplitude_gain_multiplier (float, optional) – Additional multiplier applied after resolving amplitude_gain. This is useful with amplitude_gain="auto" when traces should be drawn larger while preserving relative amplitudes.
time_limit_s (float | None, optional) – Optional maximum seconds to display from each trace start.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
observed_col – Optional function argument. Defaults to 'observed'.
synthetic_col – Optional function argument. Defaults to 'synthetic'.
dt_col – Optional function argument. Defaults to 'dt'.
synthetic_dt_col – Optional function argument. Defaults to 'synthetic_dt'.
observed_time_offset_col – Optional function argument. Defaults to 'observed_time_offset_s'.
synthetic_time_offset_col – Optional function argument. Defaults to 'synthetic_time_offset_s'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
distance_col – Optional function argument. Defaults to 'distance_km'.
distance_limit_km – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 30.
normalize – Optional function argument. Defaults to True.
amplitude_gain – Optional function argument. Defaults to 1.0.
amplitude_gain_multiplier – Optional function argument. Defaults to 1.0.
time_limit_s – Optional function argument. Defaults to 60.0.
title – Optional function argument. Defaults to 'Observed and Synthetic Trace Comparison'.
filter_label – 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.visualize.plot_observed_synthetic_record_section(records_df: DataFrame, output_path: str | Path | None = None, *, observed_col: str = 'observed', synthetic_col: str = 'synthetic', dt_col: str = 'dt', synthetic_dt_col: str = 'synthetic_dt', observed_time_offset_col: str = 'observed_time_offset_s', synthetic_time_offset_col: str = 'synthetic_time_offset_s', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', components: Iterable[str] | None = None, selection: FigureSelection | None = None, max_records: int | None = 80, normalize: bool = True, scale: float = 1.0, title: str = 'Observed and Synthetic Record Section', filter_label: str | None = None, default_dt: float = 1.0, time_limit_s: float | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed and synthetic traces on shared record-section axes.

Parameters:

records_df (pandas.DataFrame) – Table with observed and synthetic waveform columns.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
observed_col (str, optional) – Waveform columns.
synthetic_col (str, optional) – Waveform columns.
dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
synthetic_dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
observed_time_offset_col (str, optional) – Optional columns giving trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
synthetic_time_offset_col (str, optional) – Optional columns giving trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
components (Optional, optional) – Optional ordered component subset.
max_records (int | None, optional) – Maximum rows to draw per component.
normalize (bool, optional) – Whether to normalize each trace before plotting.
scale (float, optional) – Multiplicative plotting gain.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
time_limit_s (float | None, optional) – Optional maximum seconds to display from each trace start.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
observed_col – Optional function argument. Defaults to 'observed'.
synthetic_col – Optional function argument. Defaults to 'synthetic'.
dt_col – Optional function argument. Defaults to 'dt'.
synthetic_dt_col – Optional function argument. Defaults to 'synthetic_dt'.
observed_time_offset_col – Optional function argument. Defaults to 'observed_time_offset_s'.
synthetic_time_offset_col – Optional function argument. Defaults to 'synthetic_time_offset_s'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
components – Optional function argument. Defaults to None.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 80.
normalize – Optional function argument. Defaults to True.
scale – Optional function argument. Defaults to 1.0.
title – Optional function argument. Defaults to 'Observed and Synthetic Record Section'.
filter_label – Optional function argument. Defaults to None.
default_dt – Optional function argument. Defaults to 1.0.
time_limit_s – 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.visualize.plot_post_qc_station_event_map(records_df: DataFrame, output_path: str | Path | None = None, *, station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', status_col: str = 'qc_status', pass_values: tuple[str, ...] = ('pass', 'passed', 'keep', 'kept'), title: str = 'Post-QC Station and Event Coverage', 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 retained and rejected station-event coverage after QC.

Parameters:

records_df (pandas.DataFrame) – Event-station table with station and event coordinates.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
status_col (str, optional) – QC status column.
pass_values (tuple, optional) – Status values treated as retained.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
status_col – Optional function argument. Defaults to 'qc_status'.
pass_values – Optional function argument. Defaults to ('pass', 'passed', 'keep', 'kept').
title – Optional function argument. Defaults to 'Post-QC Station and Event Coverage'.
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.visualize.plot_qc_drop_cause_diagnostics(qc_df: DataFrame, output_path: str | Path | None = None, *, reason_col: str = 'qc_reason', status_col: str | None = 'qc_status', fail_values: tuple[str, ...] = ('fail', 'failed', 'reject', 'rejected'), group_col: str | None = None, max_reasons: int = 12, title: str = 'QC Drop Causes', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot the most common QC rejection reasons.

Parameters:

qc_df (pandas.DataFrame) – QC table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
reason_col (str, optional) – Rejection-reason column.
status_col (str | None, optional) – Optional QC status column used to keep only rejected rows before counting causes. Set to None when the input table already contains only rejected rows.
fail_values (tuple, optional) – Status labels treated as rejected when status_col is present.
group_col (str | None, optional) – Optional grouping column, commonly source or component. When omitted, the figure summarizes each rejection reason once, which avoids mixing independent concepts such as reason categories and components.
max_reasons (int, optional) – Maximum reason categories to show.
title (str, optional) – Figure title.
qc_df – Required function argument.
output_path – Optional function argument. Defaults to None.
reason_col – Optional function argument. Defaults to 'qc_reason'.
status_col – Optional function argument. Defaults to 'qc_status'.
fail_values – Optional function argument. Defaults to ('fail', 'failed', 'reject', 'rejected').
group_col – Optional function argument. Defaults to None.
max_reasons – Optional function argument. Defaults to 12.
title – Optional function argument. Defaults to 'QC Drop Causes'.
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.visualize.plot_record_section(records: DataFrame | Iterable[Any], output_path: str | Path | None = None, *, trace_col: str = 'trace', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', components: Iterable[str] | None = None, selection: FigureSelection | None = None, max_records: int | None = 80, normalize: bool = True, scale: float = 1.0, title: str = 'Record Section', filter_label: str | None = None, default_dt: float = 1.0, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot one or more component record sections.

Parameters:

records (Union) – Record table or iterable of trace-like objects.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Trace column for DataFrame inputs.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
components (Optional, optional) – Optional ordered component subset.
max_records (int | None, optional) – Maximum traces to draw per component.
normalize (bool, optional) – Whether to normalize each trace before plotting.
scale (float, optional) – Multiplicative plotting gain.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
records – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
components – Optional function argument. Defaults to None.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 80.
normalize – Optional function argument. Defaults to True.
scale – Optional function argument. Defaults to 1.0.
title – Optional function argument. Defaults to 'Record Section'.
filter_label – Optional function argument. Defaults to None.
default_dt – Optional function argument. Defaults to 1.0.
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.visualize.plot_retention_summary(qc_df: DataFrame, output_path: str | Path | None = None, *, group_col: str = 'stage', status_col: str = 'qc_status', count_col: str | None = None, title: str = 'QC Retention Summary', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot pass/fail retention counts by workflow stage.

Parameters:

qc_df (pandas.DataFrame) – QC summary table.
output_path (str | pathlib.Path | None, optional) – Optional destination figure path. outpath is preferred for new code.
outpath (str | pathlib.Path | None, optional) – Optional destination figure path. outpath is preferred for new code.
group_col (str, optional) – Stage or grouping column.
status_col (str, optional) – QC status column.
count_col (str | None, optional) – Optional precomputed count column.
title (str, optional) – Figure title.
qc_df – Required function argument.
output_path – Optional function argument. Defaults to None.
group_col – Optional function argument. Defaults to 'stage'.
status_col – Optional function argument. Defaults to 'qc_status'.
count_col – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to 'QC Retention Summary'.
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:

Created figure.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.visualize.plot_station_event_beachball_map(events_df: DataFrame, output_path: str | Path | None = None, *, stations_df: DataFrame | None = None, event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', strike_col: str = 'strike', dip_col: str = 'dip', rake_col: str = 'rake', magnitude_col: str = 'magnitude', color_by_magnitude: bool = True, magnitude_cmap: str = 'autumn_r', station_lon_col: str = 'lon', station_lat_col: str = 'lat', title: str = 'Event Focal Mechanisms', add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, close: bool | None = None, outpath: str | Path | None = None) → Figure

Plot focal mechanism beachballs when ObsPy is available.

Parameters:

events_df (pandas.DataFrame) – Event metadata with coordinates and optional strike/dip/rake.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
stations_df (pandas.DataFrame | None, optional) – Optional station metadata for context.
event_lon_col (str, optional) – Event coordinate and focal mechanism columns.
event_lat_col (str, optional) – Event coordinate and focal mechanism columns.
strike_col (str, optional) – Event coordinate and focal mechanism columns.
dip_col (str, optional) – Event coordinate and focal mechanism columns.
rake_col (str, optional) – Event coordinate and focal mechanism columns.
magnitude_col (str, optional) – Event magnitude column used to color beachball compressional quadrants.
color_by_magnitude (bool, optional) – Whether to color compressional beachball quadrants by magnitude.
magnitude_cmap (str, optional) – Matplotlib colormap name for magnitude coloring.
station_lon_col (str, optional) – Station coordinate columns.
station_lat_col (str, optional) – Station coordinate columns.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
stations_df – Optional function argument. Defaults to None.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
strike_col – Optional function argument. Defaults to 'strike'.
dip_col – Optional function argument. Defaults to 'dip'.
rake_col – Optional function argument. Defaults to 'rake'.
magnitude_col – Optional function argument. Defaults to 'magnitude'.
color_by_magnitude – Optional function argument. Defaults to True.
magnitude_cmap – Optional function argument. Defaults to 'autumn_r'.
station_lon_col – Optional function argument. Defaults to 'lon'.
station_lat_col – Optional function argument. Defaults to 'lat'.
title – Optional function argument. Defaults to 'Event Focal Mechanisms'.
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.
close (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.visualize.plot_station_event_network_map(stations_df: DataFrame, events_df: DataFrame, output_path: str | Path | None = None, *, station_lon_col: str = 'lon', station_lat_col: str = 'lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', network_col: str = 'network', title: str = 'Station Networks and Events', 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 station networks and event locations on one map.

Parameters:

stations_df (pandas.DataFrame) – Station and event metadata tables.
events_df (pandas.DataFrame) – Station and event metadata tables.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
network_col (str, optional) – Station network/category column.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
stations_df – Required function argument.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
station_lon_col – Optional function argument. Defaults to 'lon'.
station_lat_col – Optional function argument. Defaults to 'lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
network_col – Optional function argument. Defaults to 'network'.
title – Optional function argument. Defaults to 'Station Networks and Events'.
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.visualize.plot_station_event_waveform_map(records_df: DataFrame, output_path: str | Path | None = None, *, waveform_col: str = 'trace', station_col: str = 'station', station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', component_col: str | None = 'component', selection: FigureSelection | None = None, dt_col: str = 'dt', time_offset_col: str | None = 'auto', time_limits_s: tuple[float, float] | None = None, time_limit_s: float | None = None, distance_col: str = 'distance_km', sort_by_distance: bool = True, max_traces: int = 12, normalize: bool = True, title: str = 'Station-Event Waveform Map', filter_label: str | 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 station/event geometry beside waveform traces.

Parameters:

records_df (pandas.DataFrame) – Table with station/event coordinates and waveform arrays.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
waveform_col (str, optional) – Waveform array or trace-like column.
station_col (str, optional) – Station label column.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
component_col (str | None, optional) – Optional component label column.
dt_col (str, optional) – Sample interval column.
time_offset_col (str | None, optional) – Optional column with trace start time in seconds relative to event origin. The default "auto" uses observed_time_offset_s for observed waveforms and synthetic_time_offset_s for synthetic waveforms when those columns are available, so trace plots are aligned with t=0 at the event origin without exposing timing metadata in tutorial code.
time_limits_s (tuple[float, float] | None, optional) – Optional x-axis limits in seconds. time_limit_s is shorthand for (0, time_limit_s).
time_limit_s (float | None, optional) – Optional x-axis limits in seconds. time_limit_s is shorthand for (0, time_limit_s).
distance_col (str, optional) – Distance column and whether traces should be sorted from nearest at the bottom to farthest at the top.
sort_by_distance (bool, optional) – Distance column and whether traces should be sorted from nearest at the bottom to farthest at the top.
max_traces (int, optional) – Maximum traces to show.
normalize (bool, optional) – Whether to normalize each waveform.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
waveform_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
component_col – Optional function argument. Defaults to 'component'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
dt_col – Optional function argument. Defaults to 'dt'.
time_offset_col – Optional function argument. Defaults to 'auto'.
time_limits_s – Optional function argument. Defaults to None.
time_limit_s – Optional function argument. Defaults to None.
distance_col – Optional function argument. Defaults to 'distance_km'.
sort_by_distance – Optional function argument. Defaults to True.
max_traces – Optional function argument. Defaults to 12.
normalize – Optional function argument. Defaults to True.
title – Optional function argument. Defaults to 'Station-Event Waveform Map'.
filter_label – 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.visualize.plot_trace_inventory_samples(sample_df: DataFrame, output_path: str | Path | None = None, *, trace_col: str = 'trace', station_col: str = 'station', event_col: str = 'event_id', component_col: str = 'component', status_col: str = 'qc_status', dt_col: str = 'dt', selection: FigureSelection | None = None, max_traces: int = 12, title: str = 'Trace Inventory Samples', filter_label: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot sample traces from a QC inventory.

Parameters:

sample_df (pandas.DataFrame) – Table with trace arrays or trace-like objects.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Trace column.
station_col (str, optional) – Label columns.
event_col (str, optional) – Label columns.
component_col (str, optional) – Label columns.
status_col (str, optional) – Label columns.
dt_col (str, optional) – Sample interval column.
max_traces (int, optional) – Maximum traces to display.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
sample_df – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
event_col – Optional function argument. Defaults to 'event_id'.
component_col – Optional function argument. Defaults to 'component'.
status_col – Optional function argument. Defaults to 'qc_status'.
dt_col – Optional function argument. Defaults to 'dt'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_traces – Optional function argument. Defaults to 12.
title – Optional function argument. Defaults to 'Trace Inventory Samples'.
filter_label – 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.visualize.plot_waveform_overlay_matrix(records_df: DataFrame, output_path: str | Path | None = None, *, trace_col: str = 'trace', group_col: str = 'group', station_col: str = 'station', distance_col: str = 'distance_km', station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', dt_col: str = 'dt', selection: FigureSelection | None = None, max_groups: int = 6, max_traces_per_group: int = 8, sort_by_distance: bool = True, time_limit_s: float | None = 60.0, normalize: bool = True, title: str = 'Observed Waveform Overlays', filter_label: str | 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 selected waveform groups with a shared map panel.

Parameters:

records_df (pandas.DataFrame) – Selected waveform rows. Selection should be done upstream by spatial or cluster helper functions.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Waveform column.
group_col (str, optional) – Cluster, polygon, corridor, or other selected group column.
station_col (str, optional) – Station label column.
distance_col (str, optional) – Source-to-station distance column used for default trace sorting and station labels when available.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
dt_col (str, optional) – Sample interval column.
max_groups (int, optional) – Maximum groups to show.
max_traces_per_group (int, optional) – Maximum traces per group.
sort_by_distance (bool, optional) – Whether to sort traces from nearest to farthest within each group, with the nearest trace plotted at the bottom.
time_limit_s (float | None, optional) – Optional x-axis limit in seconds. Set to None to show the full trace.
normalize (bool, optional) – Whether to normalize traces.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
group_col – Optional function argument. Defaults to 'group'.
station_col – Optional function argument. Defaults to 'station'.
distance_col – Optional function argument. Defaults to 'distance_km'.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
dt_col – Optional function argument. Defaults to 'dt'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_groups – Optional function argument. Defaults to 6.
max_traces_per_group – Optional function argument. Defaults to 8.
sort_by_distance – Optional function argument. Defaults to True.
time_limit_s – Optional function argument. Defaults to 60.0.
normalize – Optional function argument. Defaults to True.
title – Optional function argument. Defaults to 'Observed Waveform Overlays'.
filter_label – 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.visualize.prepare_dashboard_metric_table(df: DataFrame, *, residual_mode: str = 'logratio') → DataFrame

Prepare a metric table for dashboard summaries.

Parameters:

df (pandas.DataFrame) – Wide or long metric table.
residual_mode (str, optional) – Residual mode used when converting wide tables.
df – Required function argument.
residual_mode – Optional function argument. Defaults to 'logratio'.

Returns:

Long metric residual table with dashboard-compatible columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.queue_rows_from_filtered_trace_df(filtered_trace_df: DataFrame) → list[dict[str, str]]

Convert filtered trace rows into manual-review queue records.

Parameters:

filtered_trace_df (pandas.DataFrame) – Filtered trace summary table.
filtered_trace_df – Required function argument.

Returns:

Deduplicated queue rows keyed by event and station.

Return type:

list[dict[str, str]]

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.visualize.savefig(fig: Figure, outpath: str | Path, *, close: bool = False, bbox_inches: str = 'tight', **kwargs: Any) → Path

Save a Matplotlib figure and return the written path.

Parameters:

fig (matplotlib.figure.Figure) – Matplotlib figure to save.
outpath (str | pathlib.Path) – Destination image path.
close (bool, optional) – Whether to close the figure after saving.
bbox_inches (str, optional) – Matplotlib bounding-box setting used by Figure.savefig.
**kwargs – Additional keyword arguments passed to Figure.savefig.
fig – Required function argument.
outpath – Required function argument.
close – Optional function argument. Defaults to False.
bbox_inches – Optional function argument. Defaults to 'tight'.
kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Write dashboard-ready long metric data as Parquet.

Parameters:

tables (pandas.DataFrame | str | pathlib.Path | collections.abc.Sequence[pandas.DataFrame | str | pathlib.Path]) – One table, path, or sequence of tables/paths.
output_root (str | pathlib.Path | None, optional) – Output directory for metrics_long.parquet or partitioned files. When omitted, the standard metrics_dashboard path is resolved from the active config.
residual_mode (str, optional) – Residual mode used when converting wide tables.
partitioned (bool, optional) – Whether to partition by model, band, and metric.
tables – Required function argument.
output_root – Optional function argument. Defaults to None.
residual_mode – Optional function argument. Defaults to 'logratio'.
partitioned – Optional function argument. Defaults to False.

Returns:

Dataset root directory.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.visualize.write_dashboard_summaries(summaries: dict[str, DataFrame], output_dir: str | Path, *, format: str = 'parquet') → dict[str, Path]

Write dashboard summary tables to a directory.

Parameters:

summaries (dict) – Required function argument.
output_dir (str | pathlib.Path) – Required function argument.
format (str, optional) – Optional function argument. Defaults to 'parquet'.

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.visualize.write_dashboard_summary_dataset(input_root: str | Path | None = None, output_root: str | Path | None = None, *, hex_dist: float = 10.0, hex_az: float = 10.0, format: str = 'parquet') → dict[str, Path]

Build and write dashboard summary tables from a metric dataset.

Parameters:

input_root (str | pathlib.Path | None, optional) – Dashboard metric dataset root. When omitted, the standard metrics_dashboard path is resolved from the active config.
output_root (str | pathlib.Path | None, optional) – Output directory for summary tables. When omitted, the standard dashboard_summaries path is resolved from the active config.
hex_dist (float, optional) – Distance-bin size in kilometers.
hex_az (float, optional) – Azimuth-bin size in degrees.
format (str, optional) – Output format, "parquet" or "csv".
input_root – Optional function argument. Defaults to None.
output_root – Optional function argument. Defaults to None.
hex_dist – Optional function argument. Defaults to 10.0.
hex_az – Optional function argument. Defaults to 10.0.
format – Optional function argument. Defaults to 'parquet'.

Returns:

Written summary paths by table name.

Return type:

dict[str, pathlib.Path]

Returns:

Return value produced by the function.

Return type:

dict

Write a standalone QC overview HTML file.

Parameters:

trace_summary (pandas.DataFrame | str | pathlib.Path) – Trace summary dataframe or table path.
output_path (str | pathlib.Path) – Destination HTML path.
output_root (str | pathlib.Path | None, optional) – Optional output root recorded in the HTML metadata.
title (str, optional) – Page title.
trace_summary – Required function argument.
output_path – Required function argument.
output_root – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to 'Trace QC Overview'.

Returns:

pathlib.Path
Written HTML path.

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Context Figures 

Basic context figures for Spatial-VTK tutorials and workflows.

Context Overview 

This module draws early workflow figures that help users understand station, event, and record coverage before calculating validation metrics.

spatial_vtk.visualize.context.figures.build_record_coverage_table(event_station_df: DataFrame, *, observed_start_col: str = 'observed_start_s', observed_end_col: str = 'observed_end_s', synthetic_start_col: str = 'synthetic_start_s', synthetic_end_col: str = 'synthetic_end_s') → DataFrame

Validate and normalize a measured record-coverage table.

Parameters:

event_station_df (pandas.DataFrame) – Event-station records with measured observed/synthetic start and end columns in seconds relative to event origin.
observed_start_col (str, optional) – Observed record start/end columns in seconds.
observed_end_col (str, optional) – Observed record start/end columns in seconds.
synthetic_start_col (str, optional) – Synthetic record start/end columns in seconds.
synthetic_end_col (str, optional) – Synthetic record start/end columns in seconds.
event_station_df – Required function argument.
observed_start_col – Optional function argument. Defaults to 'observed_start_s'.
observed_end_col – Optional function argument. Defaults to 'observed_end_s'.
synthetic_start_col – Optional function argument. Defaults to 'synthetic_start_s'.
synthetic_end_col – Optional function argument. Defaults to 'synthetic_end_s'.

Returns:

Validated record table with measured timing columns and durations.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Build a paired record-coverage table from waveform QC rows.

Parameters:

trace_qc_df (pandas.DataFrame | str | pathlib.Path) – Waveform QC table with one row per source/event/station/component/ passband and timing columns such as trace_start_s and trace_end_s.
event_station_df (pandas.DataFrame | str | pathlib.Path | None, optional) – Optional event-station metadata used to add distance and readable event labels.
component (str | None, optional) – Optional component to select before pairing source rows.
passband (str | None, optional) – Optional passband label to select before pairing source rows.
observed_source (str, optional) – Source labels used for observed and synthetic rows.
synthetic_source (str, optional) – Source labels used for observed and synthetic rows.
trace_qc_df – Required function argument.
event_station_df – Optional function argument. Defaults to None.
component – Optional function argument. Defaults to None.
passband – Optional function argument. Defaults to None.
observed_source – Optional function argument. Defaults to 'observed'.
synthetic_source – Optional function argument. Defaults to 'synthetic'.

Returns:

Coverage table with observed/synthetic start, end, and duration columns accepted by plot_record_coverage().

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.context.figures.build_record_coverage_table_from_trace_metadata(trace_metadata_df: DataFrame | str | Path, *, event_station_df: DataFrame | str | Path | None = None, component: str | None = None, observed_source: str = 'observed', synthetic_source: str = 'synthetic', source_type_col: str = 'source_type', on_missing_source: str = 'drop', on_missing_metadata: str = 'drop') → DataFrame

Build paired record coverage from processed trace metadata.

Parameters:

trace_metadata_df (pandas.DataFrame | str | pathlib.Path) – Trace metadata table from preprocessing with event, station, source, start time, and end time columns.
event_station_df (pandas.DataFrame | str | pathlib.Path | None, optional) – Event-station metadata with event origin time in start plus optional distance and readable event-label columns.
component (str | None, optional) – Optional component to select before pairing observed/synthetic traces.
observed_source (str, optional) – Source labels used for observed and synthetic rows.
synthetic_source (str, optional) – Source labels used for observed and synthetic rows.
source_type_col (str, optional) – Column naming the waveform source. If absent, the source is inferred from the trace metadata source or file path columns.
on_missing_source (str, optional) – "drop" keeps complete observed/synthetic pairs only. "raise" raises when a selected event-station record is missing either source.
on_missing_metadata (str, optional) – "drop" skips trace event/station groups that are absent from event_station_df. "raise" preserves strict validation.
trace_metadata_df – Required function argument.
event_station_df – Optional function argument. Defaults to None.
component – Optional function argument. Defaults to None.
observed_source – Optional function argument. Defaults to 'observed'.
synthetic_source – Optional function argument. Defaults to 'synthetic'.
source_type_col – Optional function argument. Defaults to 'source_type'.
on_missing_source – Optional function argument. Defaults to 'drop'.
on_missing_metadata – Optional function argument. Defaults to 'drop'.

Returns:

Coverage table with measured observed/synthetic start, end, and duration columns in seconds relative to event origin.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.context.figures.plot_distance_amplitude_diagnostics(records_df: DataFrame, output_path: str | Path | None = None, *, distance_col: str = 'distance_km', observed_col: str = 'observed_peak_abs', synthetic_col: str = 'synthetic_peak_abs', component_col: str | None = 'component', selection: FigureSelection | None = None, event_col: str | None = 'event_id', title: str = 'Distance Versus Amplitude', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot amplitude decay diagnostics for observed and synthetic records.

Parameters:

records_df (pandas.DataFrame) – Table with distance and amplitude columns.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
distance_col (str, optional) – Distance column in kilometers.
observed_col (str, optional) – Observed and synthetic amplitude columns.
synthetic_col (str, optional) – Observed and synthetic amplitude columns.
component_col (str | None, optional) – Optional component facet column.
event_col (str | None, optional) – Optional event color/grouping column.
title (str, optional) – Figure title.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
distance_col – Optional function argument. Defaults to 'distance_km'.
observed_col – Optional function argument. Defaults to 'observed_peak_abs'.
synthetic_col – Optional function argument. Defaults to 'synthetic_peak_abs'.
component_col – Optional function argument. Defaults to 'component'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
event_col – Optional function argument. Defaults to 'event_id'.
title – Optional function argument. Defaults to 'Distance Versus Amplitude'.
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

Plot station counts by event.

Parameters:

event_station_df (pandas.DataFrame) – Prepared event-station table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
title (str, optional) – Figure title.
event_station_df – Required function argument.
output_path – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to 'Event Coverage'.
showfig (bool | None, optional) – Optional function argument. Defaults to None.
savefig (bool | None, optional) – Optional function argument. Defaults to None.
close (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.visualize.context.figures.plot_event_trace_comparison(records_df: DataFrame, output_path: str | Path | None = None, *, observed_col: str = 'observed', synthetic_col: str = 'synthetic', dt_col: str = 'dt', synthetic_dt_col: str = 'synthetic_dt', observed_time_offset_col: str = 'observed_time_offset_s', synthetic_time_offset_col: str = 'synthetic_time_offset_s', station_col: str = 'station', component_col: str | None = 'component', selection: FigureSelection | None = None, distance_col: str = 'distance_km', distance_limit_km: float | None = None, max_records: int | None = 30, normalize: bool = True, amplitude_gain: float | str = 1.0, amplitude_gain_multiplier: float = 1.0, time_limit_s: float | None = 60.0, title: str = 'Observed and Synthetic Trace Comparison', filter_label: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed and synthetic traces sorted by source distance.

Parameters:

records_df (pandas.DataFrame) – Table with observed and synthetic waveform arrays or ObsPy-like traces.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
observed_col (str, optional) – Waveform columns.
synthetic_col (str, optional) – Waveform columns.
dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
synthetic_dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
observed_time_offset_col (str, optional) – Optional columns giving the trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
synthetic_time_offset_col (str, optional) – Optional columns giving the trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component grouping column.
distance_col (str, optional) – Optional distance column used for vertical position.
distance_limit_km (float | None, optional) – Optional maximum source-to-station distance to include.
max_records (int | None, optional) – Maximum rows per component.
normalize (bool, optional) – Whether to normalize each waveform before plotting.
amplitude_gain (float | str, optional) – Single global gain applied to every plotted waveform after optional normalization. Use values greater than 1 to inspect unnormalized traces while preserving observed/synthetic relative amplitudes.
amplitude_gain_multiplier (float, optional) – Additional multiplier applied after resolving amplitude_gain. This is useful with amplitude_gain="auto" when traces should be drawn larger while preserving relative amplitudes.
time_limit_s (float | None, optional) – Optional maximum seconds to display from each trace start.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
observed_col – Optional function argument. Defaults to 'observed'.
synthetic_col – Optional function argument. Defaults to 'synthetic'.
dt_col – Optional function argument. Defaults to 'dt'.
synthetic_dt_col – Optional function argument. Defaults to 'synthetic_dt'.
observed_time_offset_col – Optional function argument. Defaults to 'observed_time_offset_s'.
synthetic_time_offset_col – Optional function argument. Defaults to 'synthetic_time_offset_s'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
distance_col – Optional function argument. Defaults to 'distance_km'.
distance_limit_km – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 30.
normalize – Optional function argument. Defaults to True.
amplitude_gain – Optional function argument. Defaults to 1.0.
amplitude_gain_multiplier – Optional function argument. Defaults to 1.0.
time_limit_s – Optional function argument. Defaults to 60.0.
title – Optional function argument. Defaults to 'Observed and Synthetic Trace Comparison'.
filter_label – 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.visualize.context.figures.plot_record_coverage(records_df: DataFrame, output_path: str | Path | None = None, *, event_col: str = 'event_id', event_label_col: str = 'event_name', station_col: str = 'station', distance_col: str = 'distance_km', observed_start_col: str = 'observed_start_s', observed_end_col: str = 'observed_end_s', synthetic_start_col: str = 'synthetic_start_s', synthetic_end_col: str = 'synthetic_end_s', include_event_in_label: bool = True, max_records: int | None = 40, title: str = 'Record Coverage', showfig: bool | None = None, savefig: bool | None = None, close: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed and synthetic record time coverage by station.

Parameters:

records_df (pandas.DataFrame) – Table with one row per event-station record.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
event_col (str, optional) – Event identifier and optional readable event label columns.
event_label_col (str, optional) – Event identifier and optional readable event label columns.
station_col (str, optional) – Station label column.
distance_col (str, optional) – Optional distance column used for sorting and labels.
observed_start_col (str, optional) – Observed record start/end columns in seconds.
observed_end_col (str, optional) – Observed record start/end columns in seconds.
synthetic_start_col (str, optional) – Synthetic record start/end columns in seconds.
synthetic_end_col (str, optional) – Synthetic record start/end columns in seconds.
include_event_in_label (bool, optional) – Whether y-axis labels include event labels in addition to stations.
max_records (int | None, optional) – Maximum rows to draw.
title (str, optional) – Figure title.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
event_col – Optional function argument. Defaults to 'event_id'.
event_label_col – Optional function argument. Defaults to 'event_name'.
station_col – Optional function argument. Defaults to 'station'.
distance_col – Optional function argument. Defaults to 'distance_km'.
observed_start_col – Optional function argument. Defaults to 'observed_start_s'.
observed_end_col – Optional function argument. Defaults to 'observed_end_s'.
synthetic_start_col – Optional function argument. Defaults to 'synthetic_start_s'.
synthetic_end_col – Optional function argument. Defaults to 'synthetic_end_s'.
include_event_in_label – Optional function argument. Defaults to True.
max_records – Optional function argument. Defaults to 40.
title – Optional function argument. Defaults to 'Record Coverage'.
showfig (bool | None, optional) – Optional function argument. Defaults to None.
savefig (bool | None, optional) – Optional function argument. Defaults to None.
close (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

Plot event counts by station.

Parameters:

event_station_df (pandas.DataFrame) – Prepared event-station table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
title (str, optional) – Figure title.
max_stations (int, optional) – Maximum number of stations to show.
event_station_df – Required function argument.
output_path – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to 'Station Coverage'.
max_stations – Optional function argument. Defaults to 40.
showfig (bool | None, optional) – Optional function argument. Defaults to None.
savefig (bool | None, optional) – Optional function argument. Defaults to None.
close (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.visualize.context.figures.plot_station_event_context(stations_df: DataFrame, events_df: DataFrame, output_path: str | Path | None = None, *, title: str = 'Station and Event Coverage', bounds: tuple[float, float, float, float] | None = None, auto_bounds_buffer_fraction: float = 0.1, auto_bounds_min_buffer_deg: float = 0.03, annotate_stations: bool = False, annotate_events: bool = False, station_label_col: str = 'station', event_label_col: str = 'event_id', label_fontsize: float = 6.5, label_offset_fraction: float = 0.012, add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, close: bool | None = None, outpath: str | Path | None = None) → Figure

Plot station and event locations on one context map.

Parameters:

stations_df (pandas.DataFrame) – Prepared station metadata with lat and lon.
events_df (pandas.DataFrame) – Prepared event metadata with event_lat and event_lon.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
title (str, optional) – Figure title.
bounds (tuple[float, float, float, float] | None, optional) – Optional (west, east, south, north) map bounds.
auto_bounds_buffer_fraction (float, optional) – Fractional padding around the station/event coordinate range when bounds is omitted.
auto_bounds_min_buffer_deg (float, optional) – Minimum longitude/latitude padding in degrees when bounds is omitted.
annotate_stations (bool, optional) – Whether to draw station and event labels next to markers.
annotate_events (bool, optional) – Whether to draw station and event labels next to markers.
station_label_col (str, optional) – Metadata columns used for station and event labels.
event_label_col (str, optional) – Metadata columns used for station and event labels.
label_fontsize (float, optional) – Text size for optional marker annotations.
label_offset_fraction (float, optional) – Label offset as a fraction of the current map width/height.
add_basemap (bool, optional) – Whether to add a contextily basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra keyword arguments passed to the shared basemap helper.
stations_df – Required function argument.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to 'Station and Event Coverage'.
bounds – Optional function argument. Defaults to None.
auto_bounds_buffer_fraction – Optional function argument. Defaults to 0.1.
auto_bounds_min_buffer_deg – Optional function argument. Defaults to 0.03.
annotate_stations – Optional function argument. Defaults to False.
annotate_events – Optional function argument. Defaults to False.
station_label_col – Optional function argument. Defaults to 'station'.
event_label_col – Optional function argument. Defaults to 'event_id'.
label_fontsize – Optional function argument. Defaults to 6.5.
label_offset_fraction – Optional function argument. Defaults to 0.012.
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.
close (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

spatial_vtk.visualize.context.figures.plot_study_domain_map(stations_df: DataFrame, events_df: DataFrame, output_path: str | Path | None = None, *, title: str | None = None, bounds: tuple[float, float, float, float] | None = None, color_by: str | None = 'magnitude', annotate_events: bool = False, 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 a station/event overview map for the study domain.

Parameters:

stations_df (pandas.DataFrame) – Station metadata with latitude/longitude columns.
events_df (pandas.DataFrame) – Event metadata with event latitude/longitude columns.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
title (str | None, optional) – Optional figure title.
bounds (tuple[float, float, float, float] | None, optional) – Optional (west, east, south, north) map bounds.
color_by (str | None, optional) – Optional event column used for marker color.
annotate_events (bool, optional) – Whether to label event markers by event id.
add_basemap (bool, optional) – Whether to draw a contextily basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra keyword arguments passed to the shared basemap helper.
stations_df – Required function argument.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to None.
bounds – Optional function argument. Defaults to None.
color_by – Optional function argument. Defaults to 'magnitude'.
annotate_events – Optional function argument. Defaults to False.
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.visualize.context.figures.summarize_coverage(event_station_df: DataFrame) → dict[str, int | None]

Summarize event-station coverage for notebook manifests.

Parameters:

event_station_df (pandas.DataFrame) – Prepared event-station table.
event_station_df – Required function argument.

Returns:

Basic row, event, station, and missing-coordinate counts.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

Context map figure helpers.

Context Overview 

This module draws overview maps for events, stations, networks, and optional focal mechanisms from explicit metadata tables.

Context Examples 

Plot event magnitudes:: plot_event_magnitude_map(events, "event_magnitudes.png")

spatial_vtk.visualize.context.maps.plot_event_magnitude_map(events_df: DataFrame, output_path: str | Path | None = None, *, magnitude_col: str = 'magnitude', lon_col: str = 'event_lon', lat_col: str = 'event_lat', label_col: str | None = 'event_id', title: str = 'Event Magnitudes', 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 events sized and colored by magnitude.

Parameters:

events_df (pandas.DataFrame) – Event metadata table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
magnitude_col (str, optional) – Magnitude and coordinate columns.
lon_col (str, optional) – Magnitude and coordinate columns.
lat_col (str, optional) – Magnitude and coordinate columns.
label_col (str | None, optional) – Optional event label column.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
magnitude_col – Optional function argument. Defaults to 'magnitude'.
lon_col – Optional function argument. Defaults to 'event_lon'.
lat_col – Optional function argument. Defaults to 'event_lat'.
label_col – Optional function argument. Defaults to 'event_id'.
title – Optional function argument. Defaults to 'Event Magnitudes'.
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.visualize.context.maps.plot_station_event_beachball_map(events_df: DataFrame, output_path: str | Path | None = None, *, stations_df: DataFrame | None = None, event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', strike_col: str = 'strike', dip_col: str = 'dip', rake_col: str = 'rake', magnitude_col: str = 'magnitude', color_by_magnitude: bool = True, magnitude_cmap: str = 'autumn_r', station_lon_col: str = 'lon', station_lat_col: str = 'lat', title: str = 'Event Focal Mechanisms', add_basemap: bool = True, basemap_source: str = 'Esri.WorldImagery', basemap_kwargs: dict[str, Any] | None = None, showfig: bool | None = None, savefig: bool | None = None, close: bool | None = None, outpath: str | Path | None = None) → Figure

Plot focal mechanism beachballs when ObsPy is available.

Parameters:

events_df (pandas.DataFrame) – Event metadata with coordinates and optional strike/dip/rake.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
stations_df (pandas.DataFrame | None, optional) – Optional station metadata for context.
event_lon_col (str, optional) – Event coordinate and focal mechanism columns.
event_lat_col (str, optional) – Event coordinate and focal mechanism columns.
strike_col (str, optional) – Event coordinate and focal mechanism columns.
dip_col (str, optional) – Event coordinate and focal mechanism columns.
rake_col (str, optional) – Event coordinate and focal mechanism columns.
magnitude_col (str, optional) – Event magnitude column used to color beachball compressional quadrants.
color_by_magnitude (bool, optional) – Whether to color compressional beachball quadrants by magnitude.
magnitude_cmap (str, optional) – Matplotlib colormap name for magnitude coloring.
station_lon_col (str, optional) – Station coordinate columns.
station_lat_col (str, optional) – Station coordinate columns.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
stations_df – Optional function argument. Defaults to None.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
strike_col – Optional function argument. Defaults to 'strike'.
dip_col – Optional function argument. Defaults to 'dip'.
rake_col – Optional function argument. Defaults to 'rake'.
magnitude_col – Optional function argument. Defaults to 'magnitude'.
color_by_magnitude – Optional function argument. Defaults to True.
magnitude_cmap – Optional function argument. Defaults to 'autumn_r'.
station_lon_col – Optional function argument. Defaults to 'lon'.
station_lat_col – Optional function argument. Defaults to 'lat'.
title – Optional function argument. Defaults to 'Event Focal Mechanisms'.
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.
close (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.visualize.context.maps.plot_station_event_network_map(stations_df: DataFrame, events_df: DataFrame, output_path: str | Path | None = None, *, station_lon_col: str = 'lon', station_lat_col: str = 'lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', network_col: str = 'network', title: str = 'Station Networks and Events', 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 station networks and event locations on one map.

Parameters:

stations_df (pandas.DataFrame) – Station and event metadata tables.
events_df (pandas.DataFrame) – Station and event metadata tables.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
network_col (str, optional) – Station network/category column.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
stations_df – Required function argument.
events_df – Required function argument.
output_path – Optional function argument. Defaults to None.
station_lon_col – Optional function argument. Defaults to 'lon'.
station_lat_col – Optional function argument. Defaults to 'lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
network_col – Optional function argument. Defaults to 'network'.
title – Optional function argument. Defaults to 'Station Networks and Events'.
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

Quality Control Figures 

QC overview filtering and lightweight HTML export helpers.

Quality Control Overview 

This module prepares QC summary tables for notebook/docs inspection and manual review queues without launching a dashboard server.

Quality Control Examples 

Filter a QC summary and build queue rows:: queue = queue_rows_from_filtered_trace_df(filter_trace_summary(summary, component_filter="Z"))

spatial_vtk.visualize.qc.overview.build_trace_qc_overview_html(trace_summary: DataFrame | str | Path, output_root: str | Path, *, title: str = 'Trace QC Overview') → str

Build a standalone QC overview HTML document.

Parameters:

trace_summary (pandas.DataFrame | str | pathlib.Path) – Trace summary dataframe or table path.
output_root (str | pathlib.Path) – Output root recorded in the page metadata.
title (str, optional) – Page title.
trace_summary – Required function argument.
output_root – Required function argument.
title – Optional function argument. Defaults to 'Trace QC Overview'.

Returns:

HTML document string with embedded JSON records.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

Filter one trace-QC summary table.

Parameters:

trace_df (pandas.DataFrame) – Normalized trace summary table.
event_filter (str, optional) – Optional exact event ID filter.
station_family (str, optional) – all or a station-family value.
component_filter (str, optional) – all or one component token.
station_query (str, optional) – Optional station substring.
magnitude_range (tuple[float | None, float | None] | None, optional) – Optional inclusive magnitude range.
distance_range_km (tuple[float | None, float | None] | None, optional) – Optional inclusive distance range.
date_range (tuple[pandas.Timestamp | str | None, pandas.Timestamp | str | None] | None, optional) – Optional inclusive date range.
trace_df – Required function argument.
event_filter – Optional function argument. Defaults to ''.
station_family – Optional function argument. Defaults to 'all'.
component_filter – Optional function argument. Defaults to 'all'.
station_query – Optional function argument. Defaults to ''.
magnitude_range – Optional function argument. Defaults to None.
distance_range_km – Optional function argument. Defaults to None.
date_range – Optional function argument. Defaults to None.

Returns:

Filtered table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.qc.overview.load_trace_qc_summary(table: DataFrame | str | Path) → DataFrame

Load a trace QC summary table.

Parameters:

table (pandas.DataFrame | str | pathlib.Path) – DataFrame, CSV path, or parquet path.
table – Required function argument.

Returns:

Normalized summary table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.qc.overview.normalize_trace_qc_summary(df: DataFrame) → DataFrame

Normalize trace QC summary columns used by overview helpers.

Parameters:

df (pandas.DataFrame) – Raw trace summary table.
df – Required function argument.

Returns:

Normalized copy with typed date, numeric, and text columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.qc.overview.queue_rows_from_filtered_trace_df(filtered_trace_df: DataFrame) → list[dict[str, str]]

Convert filtered trace rows into manual-review queue records.

Parameters:

filtered_trace_df (pandas.DataFrame) – Filtered trace summary table.
filtered_trace_df – Required function argument.

Returns:

Deduplicated queue rows keyed by event and station.

Return type:

list[dict[str, str]]

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.visualize.qc.overview.trace_qc_records(trace_df: DataFrame) → list[dict[str, object]]

Convert a trace-QC table to JSON-safe records.

Parameters:

trace_df (pandas.DataFrame) – Trace summary dataframe.
trace_df – Required function argument.

Returns:

JSON-safe records.

Return type:

list[dict[str, object]]

Returns:

Return value produced by the function.

Return type:

list

Write a standalone QC overview HTML file.

Parameters:

trace_summary (pandas.DataFrame | str | pathlib.Path) – Trace summary dataframe or table path.
output_path (str | pathlib.Path) – Destination HTML path.
output_root (str | pathlib.Path | None, optional) – Optional output root recorded in the HTML metadata.
title (str, optional) – Page title.
trace_summary – Required function argument.
output_path – Required function argument.
output_root – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to 'Trace QC Overview'.

Returns:

pathlib.Path
Written HTML path.

Returns:

Return value produced by the function.

Return type:

pathlib.Path

QC and retention figure helpers.

Quality Control Retention Overview 

This module draws public, dataframe-driven QC review figures without depending on private runtime profiles or production output layouts.

Quality Control Retention Examples 

Plot retention counts:: fig = plot_retention_summary(qc_summary) plot_retention_summary(qc_summary, savefig=True, outpath="retention.png")

spatial_vtk.visualize.qc.retention.plot_data_synthetic_availability(availability_df: DataFrame, output_path: str | Path | None = None, *, event_col: str = 'event_id', station_col: str = 'station', observed_col: str = 'observed_available', synthetic_col: str = 'synthetic_available', title: str = 'Observed and Synthetic Availability', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed/synthetic availability as an event-station matrix.

Parameters:

availability_df (pandas.DataFrame) – Event-station availability table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
event_col (str, optional) – Event and station identifier columns.
station_col (str, optional) – Event and station identifier columns.
observed_col (str, optional) – Boolean availability columns.
synthetic_col (str, optional) – Boolean availability columns.
title (str, optional) – Figure title.
availability_df – Required function argument.
output_path – Optional function argument. Defaults to None.
event_col – Optional function argument. Defaults to 'event_id'.
station_col – Optional function argument. Defaults to 'station'.
observed_col – Optional function argument. Defaults to 'observed_available'.
synthetic_col – Optional function argument. Defaults to 'synthetic_available'.
title – Optional function argument. Defaults to 'Observed and Synthetic Availability'.
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.visualize.qc.retention.plot_post_qc_station_event_map(records_df: DataFrame, output_path: str | Path | None = None, *, station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', status_col: str = 'qc_status', pass_values: tuple[str, ...] = ('pass', 'passed', 'keep', 'kept'), title: str = 'Post-QC Station and Event Coverage', 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 retained and rejected station-event coverage after QC.

Parameters:

records_df (pandas.DataFrame) – Event-station table with station and event coordinates.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
status_col (str, optional) – QC status column.
pass_values (tuple, optional) – Status values treated as retained.
title (str, optional) – Figure title.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
status_col – Optional function argument. Defaults to 'qc_status'.
pass_values – Optional function argument. Defaults to ('pass', 'passed', 'keep', 'kept').
title – Optional function argument. Defaults to 'Post-QC Station and Event Coverage'.
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.visualize.qc.retention.plot_qc_drop_cause_diagnostics(qc_df: DataFrame, output_path: str | Path | None = None, *, reason_col: str = 'qc_reason', status_col: str | None = 'qc_status', fail_values: tuple[str, ...] = ('fail', 'failed', 'reject', 'rejected'), group_col: str | None = None, max_reasons: int = 12, title: str = 'QC Drop Causes', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot the most common QC rejection reasons.

Parameters:

qc_df (pandas.DataFrame) – QC table.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
reason_col (str, optional) – Rejection-reason column.
status_col (str | None, optional) – Optional QC status column used to keep only rejected rows before counting causes. Set to None when the input table already contains only rejected rows.
fail_values (tuple, optional) – Status labels treated as rejected when status_col is present.
group_col (str | None, optional) – Optional grouping column, commonly source or component. When omitted, the figure summarizes each rejection reason once, which avoids mixing independent concepts such as reason categories and components.
max_reasons (int, optional) – Maximum reason categories to show.
title (str, optional) – Figure title.
qc_df – Required function argument.
output_path – Optional function argument. Defaults to None.
reason_col – Optional function argument. Defaults to 'qc_reason'.
status_col – Optional function argument. Defaults to 'qc_status'.
fail_values – Optional function argument. Defaults to ('fail', 'failed', 'reject', 'rejected').
group_col – Optional function argument. Defaults to None.
max_reasons – Optional function argument. Defaults to 12.
title – Optional function argument. Defaults to 'QC Drop Causes'.
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.visualize.qc.retention.plot_retention_summary(qc_df: DataFrame, output_path: str | Path | None = None, *, group_col: str = 'stage', status_col: str = 'qc_status', count_col: str | None = None, title: str = 'QC Retention Summary', showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot pass/fail retention counts by workflow stage.

Parameters:

qc_df (pandas.DataFrame) – QC summary table.
output_path (str | pathlib.Path | None, optional) – Optional destination figure path. outpath is preferred for new code.
outpath (str | pathlib.Path | None, optional) – Optional destination figure path. outpath is preferred for new code.
group_col (str, optional) – Stage or grouping column.
status_col (str, optional) – QC status column.
count_col (str | None, optional) – Optional precomputed count column.
title (str, optional) – Figure title.
qc_df – Required function argument.
output_path – Optional function argument. Defaults to None.
group_col – Optional function argument. Defaults to 'stage'.
status_col – Optional function argument. Defaults to 'qc_status'.
count_col – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to 'QC Retention Summary'.
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:

Created figure.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

Trace inventory sample figure helpers.

Quality Control Samples Overview 

This module draws compact sample waveform figures from explicit trace rows so users can visually inspect retained and rejected records during QC.

Quality Control Samples Examples 

Plot sample traces:: plot_trace_inventory_samples(sample_df, "qc_samples.png")

spatial_vtk.visualize.qc.samples.plot_trace_inventory_samples(sample_df: DataFrame, output_path: str | Path | None = None, *, trace_col: str = 'trace', station_col: str = 'station', event_col: str = 'event_id', component_col: str = 'component', status_col: str = 'qc_status', dt_col: str = 'dt', selection: FigureSelection | None = None, max_traces: int = 12, title: str = 'Trace Inventory Samples', filter_label: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot sample traces from a QC inventory.

Parameters:

sample_df (pandas.DataFrame) – Table with trace arrays or trace-like objects.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Trace column.
station_col (str, optional) – Label columns.
event_col (str, optional) – Label columns.
component_col (str, optional) – Label columns.
status_col (str, optional) – Label columns.
dt_col (str, optional) – Sample interval column.
max_traces (int, optional) – Maximum traces to display.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
sample_df – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
event_col – Optional function argument. Defaults to 'event_id'.
component_col – Optional function argument. Defaults to 'component'.
status_col – Optional function argument. Defaults to 'qc_status'.
dt_col – Optional function argument. Defaults to 'dt'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_traces – Optional function argument. Defaults to 12.
title – Optional function argument. Defaults to 'Trace Inventory Samples'.
filter_label – 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

Waveform Figures 

Observed/synthetic trace comparison figures.

Waveform Comparison Overview 

This module hosts waveform-oriented trace comparison APIs. The implementation currently reuses the tested public context helper while making the preferred module path spatial_vtk.visualize.waveforms.

spatial_vtk.visualize.waveforms.comparison.plot_event_trace_comparison(records_df: DataFrame, output_path: str | Path | None = None, *, observed_col: str = 'observed', synthetic_col: str = 'synthetic', dt_col: str = 'dt', synthetic_dt_col: str = 'synthetic_dt', observed_time_offset_col: str = 'observed_time_offset_s', synthetic_time_offset_col: str = 'synthetic_time_offset_s', station_col: str = 'station', component_col: str | None = 'component', selection: FigureSelection | None = None, distance_col: str = 'distance_km', distance_limit_km: float | None = None, max_records: int | None = 30, normalize: bool = True, amplitude_gain: float | str = 1.0, amplitude_gain_multiplier: float = 1.0, time_limit_s: float | None = 60.0, title: str = 'Observed and Synthetic Trace Comparison', filter_label: str | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed and synthetic traces sorted by source distance.

Parameters:

records_df (pandas.DataFrame) – Table with observed and synthetic waveform arrays or ObsPy-like traces.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
observed_col (str, optional) – Waveform columns.
synthetic_col (str, optional) – Waveform columns.
dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
synthetic_dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
observed_time_offset_col (str, optional) – Optional columns giving the trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
synthetic_time_offset_col (str, optional) – Optional columns giving the trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component grouping column.
distance_col (str, optional) – Optional distance column used for vertical position.
distance_limit_km (float | None, optional) – Optional maximum source-to-station distance to include.
max_records (int | None, optional) – Maximum rows per component.
normalize (bool, optional) – Whether to normalize each waveform before plotting.
amplitude_gain (float | str, optional) – Single global gain applied to every plotted waveform after optional normalization. Use values greater than 1 to inspect unnormalized traces while preserving observed/synthetic relative amplitudes.
amplitude_gain_multiplier (float, optional) – Additional multiplier applied after resolving amplitude_gain. This is useful with amplitude_gain="auto" when traces should be drawn larger while preserving relative amplitudes.
time_limit_s (float | None, optional) – Optional maximum seconds to display from each trace start.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
observed_col – Optional function argument. Defaults to 'observed'.
synthetic_col – Optional function argument. Defaults to 'synthetic'.
dt_col – Optional function argument. Defaults to 'dt'.
synthetic_dt_col – Optional function argument. Defaults to 'synthetic_dt'.
observed_time_offset_col – Optional function argument. Defaults to 'observed_time_offset_s'.
synthetic_time_offset_col – Optional function argument. Defaults to 'synthetic_time_offset_s'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
distance_col – Optional function argument. Defaults to 'distance_km'.
distance_limit_km – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 30.
normalize – Optional function argument. Defaults to True.
amplitude_gain – Optional function argument. Defaults to 1.0.
amplitude_gain_multiplier – Optional function argument. Defaults to 1.0.
time_limit_s – Optional function argument. Defaults to 60.0.
title – Optional function argument. Defaults to 'Observed and Synthetic Trace Comparison'.
filter_label – 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

Selected waveform overlay figures.

spatial_vtk.visualize.waveforms.overlays.plot_waveform_overlay_matrix(records_df: DataFrame, output_path: str | Path | None = None, *, trace_col: str = 'trace', group_col: str = 'group', station_col: str = 'station', distance_col: str = 'distance_km', station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', dt_col: str = 'dt', selection: FigureSelection | None = None, max_groups: int = 6, max_traces_per_group: int = 8, sort_by_distance: bool = True, time_limit_s: float | None = 60.0, normalize: bool = True, title: str = 'Observed Waveform Overlays', filter_label: str | 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 selected waveform groups with a shared map panel.

Parameters:

records_df (pandas.DataFrame) – Selected waveform rows. Selection should be done upstream by spatial or cluster helper functions.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Waveform column.
group_col (str, optional) – Cluster, polygon, corridor, or other selected group column.
station_col (str, optional) – Station label column.
distance_col (str, optional) – Source-to-station distance column used for default trace sorting and station labels when available.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
dt_col (str, optional) – Sample interval column.
max_groups (int, optional) – Maximum groups to show.
max_traces_per_group (int, optional) – Maximum traces per group.
sort_by_distance (bool, optional) – Whether to sort traces from nearest to farthest within each group, with the nearest trace plotted at the bottom.
time_limit_s (float | None, optional) – Optional x-axis limit in seconds. Set to None to show the full trace.
normalize (bool, optional) – Whether to normalize traces.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
group_col – Optional function argument. Defaults to 'group'.
station_col – Optional function argument. Defaults to 'station'.
distance_col – Optional function argument. Defaults to 'distance_km'.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
dt_col – Optional function argument. Defaults to 'dt'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_groups – Optional function argument. Defaults to 6.
max_traces_per_group – Optional function argument. Defaults to 8.
sort_by_distance – Optional function argument. Defaults to True.
time_limit_s – Optional function argument. Defaults to 60.0.
normalize – Optional function argument. Defaults to True.
title – Optional function argument. Defaults to 'Observed Waveform Overlays'.
filter_label – 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

Event radial trace section figures.

spatial_vtk.visualize.waveforms.radial_sections.plot_event_radial_trace_section(records_df: DataFrame, output_path: str | Path | None = None, *, trace_col: str = 'trace', station_col: str = 'station', distance_col: str = 'distance_km', azimuth_col: str = 'azimuth_deg', station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', dt_col: str = 'dt', selection: FigureSelection | None = None, normalize: bool = True, time_limit_s: float | None = 60.0, title: str = 'Event Radial Trace Section', filter_label: str | 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 traces ordered by azimuth with a station/event map panel.

Parameters:

records_df (pandas.DataFrame) – Table with waveform, geometry, and azimuth columns.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Trace and sorting/label columns.
station_col (str, optional) – Trace and sorting/label columns.
distance_col (str, optional) – Trace and sorting/label columns.
azimuth_col (str, optional) – Trace and sorting/label columns.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
dt_col (str, optional) – Sample interval column.
normalize (bool, optional) – Whether to normalize traces.
time_limit_s (float | None, optional) – Optional maximum trace time to draw in seconds. Defaults to 60 seconds.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
distance_col – Optional function argument. Defaults to 'distance_km'.
azimuth_col – Optional function argument. Defaults to 'azimuth_deg'.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
dt_col – Optional function argument. Defaults to 'dt'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
normalize – Optional function argument. Defaults to True.
time_limit_s – Optional function argument. Defaults to 60.0.
title – Optional function argument. Defaults to 'Event Radial Trace Section'.
filter_label – 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

Record-section waveform figures.

Waveform Record Sections Overview 

This module exposes record-section APIs under the waveform visualization group. The existing spatial_vtk.visualize.record_sections module remains as a compatibility path.

spatial_vtk.visualize.waveforms.record_sections.build_record_section_rows(records: DataFrame | Iterable[Any], *, trace_col: str = 'trace', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', default_dt: float = 1.0) → DataFrame

Normalize traces or a record table to the plotting row contract.

Parameters:

records (Union) – DataFrame with trace rows or iterable of trace-like objects.
trace_col (str, optional) – Trace column used when records is a DataFrame.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
records – Required function argument.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
default_dt – Optional function argument. Defaults to 1.0.

Returns:

Table with trace, dt, station, component, and distance_km columns where available.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.waveforms.record_sections.normalize_trace(data: ndarray) → ndarray

Normalize one trace by peak absolute amplitude.

Parameters:

data (numpy.ndarray) – Waveform samples.
data – Required function argument.

Returns:

Normalized samples.

Return type:

numpy.ndarray

Returns:

Return value produced by the function.

Return type:

numpy.ndarray

spatial_vtk.visualize.waveforms.record_sections.plot_observed_synthetic_record_section(records_df: DataFrame, output_path: str | Path | None = None, *, observed_col: str = 'observed', synthetic_col: str = 'synthetic', dt_col: str = 'dt', synthetic_dt_col: str = 'synthetic_dt', observed_time_offset_col: str = 'observed_time_offset_s', synthetic_time_offset_col: str = 'synthetic_time_offset_s', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', components: Iterable[str] | None = None, selection: FigureSelection | None = None, max_records: int | None = 80, normalize: bool = True, scale: float = 1.0, title: str = 'Observed and Synthetic Record Section', filter_label: str | None = None, default_dt: float = 1.0, time_limit_s: float | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed and synthetic traces on shared record-section axes.

Parameters:

records_df (pandas.DataFrame) – Table with observed and synthetic waveform columns.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
observed_col (str, optional) – Waveform columns.
synthetic_col (str, optional) – Waveform columns.
dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
synthetic_dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
observed_time_offset_col (str, optional) – Optional columns giving trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
synthetic_time_offset_col (str, optional) – Optional columns giving trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
components (Optional, optional) – Optional ordered component subset.
max_records (int | None, optional) – Maximum rows to draw per component.
normalize (bool, optional) – Whether to normalize each trace before plotting.
scale (float, optional) – Multiplicative plotting gain.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
time_limit_s (float | None, optional) – Optional maximum seconds to display from each trace start.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
observed_col – Optional function argument. Defaults to 'observed'.
synthetic_col – Optional function argument. Defaults to 'synthetic'.
dt_col – Optional function argument. Defaults to 'dt'.
synthetic_dt_col – Optional function argument. Defaults to 'synthetic_dt'.
observed_time_offset_col – Optional function argument. Defaults to 'observed_time_offset_s'.
synthetic_time_offset_col – Optional function argument. Defaults to 'synthetic_time_offset_s'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
components – Optional function argument. Defaults to None.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 80.
normalize – Optional function argument. Defaults to True.
scale – Optional function argument. Defaults to 1.0.
title – Optional function argument. Defaults to 'Observed and Synthetic Record Section'.
filter_label – Optional function argument. Defaults to None.
default_dt – Optional function argument. Defaults to 1.0.
time_limit_s – 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.visualize.waveforms.record_sections.plot_record_section(records: DataFrame | Iterable[Any], output_path: str | Path | None = None, *, trace_col: str = 'trace', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', components: Iterable[str] | None = None, selection: FigureSelection | None = None, max_records: int | None = 80, normalize: bool = True, scale: float = 1.0, title: str = 'Record Section', filter_label: str | None = None, default_dt: float = 1.0, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot one or more component record sections.

Parameters:

records (Union) – Record table or iterable of trace-like objects.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Trace column for DataFrame inputs.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
components (Optional, optional) – Optional ordered component subset.
max_records (int | None, optional) – Maximum traces to draw per component.
normalize (bool, optional) – Whether to normalize each trace before plotting.
scale (float, optional) – Multiplicative plotting gain.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
records – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
components – Optional function argument. Defaults to None.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 80.
normalize – Optional function argument. Defaults to True.
scale – Optional function argument. Defaults to 1.0.
title – Optional function argument. Defaults to 'Record Section'.
filter_label – Optional function argument. Defaults to None.
default_dt – Optional function argument. Defaults to 1.0.
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.visualize.waveforms.record_sections.save_record_section_figure(fig: Figure, output_path: str | Path, *, close: bool = True, dpi: int = 180) → Path

Save a record-section figure and return the written path.

Parameters:

fig (matplotlib.figure.Figure) – Matplotlib figure.
output_path (str | pathlib.Path) – Destination image path.
close (bool, optional) – Whether to close the figure after saving.
dpi (int, optional) – Raster resolution.
fig – Required function argument.
output_path – Required function argument.
close – Optional function argument. Defaults to True.
dpi – Optional function argument. Defaults to 180.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.visualize.waveforms.record_sections.trace_component(trace: Any) → str

Return the component suffix from an ObsPy-like trace.

Parameters:

trace (Any) – Trace object with optional stats.channel metadata.
trace – Required function argument.

Returns:

Uppercase component suffix, or an empty string when unavailable.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.waveforms.record_sections.trace_station(trace: Any) → str

Return a compact station label from an ObsPy-like trace.

Parameters:

trace (Any) – Trace object with optional network/station/location metadata.
trace – Required function argument.

Returns:

Station label.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.waveforms.record_sections.trace_to_array(value: Any, *, default_dt: float = 1.0) → tuple[ndarray, float]

Convert an array-like value or ObsPy-like trace to waveform samples.

Parameters:

value (Any) – Numeric array or trace object with data and optional stats.
default_dt (float, optional) – Sample interval used when metadata are unavailable.
value – Required function argument.
default_dt – Optional function argument. Defaults to 1.0.

Returns:

(samples, dt_seconds).

Return type:

tuple

Returns:

Return value produced by the function.

Return type:

tuple

Station-event waveform map figures.

Waveform Station Event Overview 

This module draws a map of one event and its stations beside waveform panels. It accepts explicit records and does not discover private waveform roots.

spatial_vtk.visualize.waveforms.station_event.plot_station_event_waveform_map(records_df: DataFrame, output_path: str | Path | None = None, *, waveform_col: str = 'trace', station_col: str = 'station', station_lon_col: str = 'sta_lon', station_lat_col: str = 'sta_lat', event_lon_col: str = 'event_lon', event_lat_col: str = 'event_lat', component_col: str | None = 'component', selection: FigureSelection | None = None, dt_col: str = 'dt', time_offset_col: str | None = 'auto', time_limits_s: tuple[float, float] | None = None, time_limit_s: float | None = None, distance_col: str = 'distance_km', sort_by_distance: bool = True, max_traces: int = 12, normalize: bool = True, title: str = 'Station-Event Waveform Map', filter_label: str | 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 station/event geometry beside waveform traces.

Parameters:

records_df (pandas.DataFrame) – Table with station/event coordinates and waveform arrays.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
waveform_col (str, optional) – Waveform array or trace-like column.
station_col (str, optional) – Station label column.
station_lon_col (str, optional) – Coordinate columns.
station_lat_col (str, optional) – Coordinate columns.
event_lon_col (str, optional) – Coordinate columns.
event_lat_col (str, optional) – Coordinate columns.
component_col (str | None, optional) – Optional component label column.
dt_col (str, optional) – Sample interval column.
time_offset_col (str | None, optional) – Optional column with trace start time in seconds relative to event origin. The default "auto" uses observed_time_offset_s for observed waveforms and synthetic_time_offset_s for synthetic waveforms when those columns are available, so trace plots are aligned with t=0 at the event origin without exposing timing metadata in tutorial code.
time_limits_s (tuple[float, float] | None, optional) – Optional x-axis limits in seconds. time_limit_s is shorthand for (0, time_limit_s).
time_limit_s (float | None, optional) – Optional x-axis limits in seconds. time_limit_s is shorthand for (0, time_limit_s).
distance_col (str, optional) – Distance column and whether traces should be sorted from nearest at the bottom to farthest at the top.
sort_by_distance (bool, optional) – Distance column and whether traces should be sorted from nearest at the bottom to farthest at the top.
max_traces (int, optional) – Maximum traces to show.
normalize (bool, optional) – Whether to normalize each waveform.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
add_basemap (bool, optional) – Whether to draw a basemap.
basemap_source (str, optional) – Contextily provider selector.
basemap_kwargs (dict[str, Any] | None, optional) – Extra basemap keyword arguments.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
waveform_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
station_lon_col – Optional function argument. Defaults to 'sta_lon'.
station_lat_col – Optional function argument. Defaults to 'sta_lat'.
event_lon_col – Optional function argument. Defaults to 'event_lon'.
event_lat_col – Optional function argument. Defaults to 'event_lat'.
component_col – Optional function argument. Defaults to 'component'.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
dt_col – Optional function argument. Defaults to 'dt'.
time_offset_col – Optional function argument. Defaults to 'auto'.
time_limits_s – Optional function argument. Defaults to None.
time_limit_s – Optional function argument. Defaults to None.
distance_col – Optional function argument. Defaults to 'distance_km'.
sort_by_distance – Optional function argument. Defaults to True.
max_traces – Optional function argument. Defaults to 12.
normalize – Optional function argument. Defaults to True.
title – Optional function argument. Defaults to 'Station-Event Waveform Map'.
filter_label – 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

Dashboard Helpers 

Plotly chart builders for Streamlit dashboards.

spatial_vtk.visualize.dashboard.charts.build_metric_heatmap_figure(df: DataFrame, *, value_col: str, title: str = 'Model-Metric Summary')

Build a model-by-metric heatmap.

Parameters:

df (pandas.DataFrame) – Required function argument.
value_col (str) – Required function argument.
title (str, optional) – Optional function argument. Defaults to 'Model-Metric Summary'.

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.visualize.dashboard.charts.build_path_heatmap_figure(df: DataFrame, *, value_col: str, title: str = 'Path Summary')

Build a distance-by-azimuth heatmap.

Parameters:

df (pandas.DataFrame) – Required function argument.
value_col (str) – Required function argument.
title (str, optional) – Optional function argument. Defaults to 'Path Summary'.

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.visualize.dashboard.charts.build_qc_bar_figure(df: DataFrame, *, column: str, title: str | None = None)

Build a count bar chart for one QC categorical column.

Parameters:

df (pandas.DataFrame) – Required function argument.
column (str) – Required function argument.
title (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.visualize.dashboard.charts.build_qc_histogram_figure(df: DataFrame, *, value_col: str, title: str | None = None, clip_iqr: bool = False, bounds: tuple[float | None, float | None] | None = None)

Build a QC histogram with optional display clipping.

Parameters:

df (pandas.DataFrame) – Required function argument.
value_col (str) – Required function argument.
title (str | None, optional) – Optional function argument. Defaults to None.
clip_iqr (bool, optional) – Optional function argument. Defaults to False.
bounds (tuple[float | None, float | None] | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.visualize.dashboard.charts.build_value_histogram_figure(df: DataFrame, *, value_col: str, title: str | None = None)

Build a histogram for one metric value column.

Parameters:

df (pandas.DataFrame) – Required function argument.
value_col (str) – Required function argument.
title (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.visualize.dashboard.charts.build_value_vs_distance_figure(df: DataFrame, *, value_col: str, distance_col: str = 'distance_km', title: str | None = None)

Build a value-versus-distance scatter plot.

Parameters:

df (pandas.DataFrame) – Required function argument.
value_col (str) – Required function argument.
distance_col (str, optional) – Optional function argument. Defaults to 'distance_km'.
title (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

Any

Dashboard data contracts and loading helpers.

Dashboard Contracts Overview 

This module validates the tables consumed by the Streamlit dashboards. It keeps schema errors clear and independent from the dashboard UI.

class spatial_vtk.visualize.dashboard.contracts.MetricsDashboardPaths(metrics_root: Path, summary_root: Path): Paths used by the metrics dashboard.

class spatial_vtk.visualize.dashboard.contracts.QCDashboardPaths(trace_summary: Path): Paths used by the QC dashboard.

spatial_vtk.visualize.dashboard.contracts.load_dashboard_summary_tables(summary_root: str | Path) → dict[str, DataFrame]

Load standard metrics dashboard summary tables from one directory.

Parameters:: summary_root (str | pathlib.Path) – Required function argument.
Returns:: Return value produced by the function.
Return type:: dict

spatial_vtk.visualize.dashboard.contracts.load_metric_long_table(metrics_root: str | Path) → DataFrame

Load the dashboard long metric table from a dataset root.

Parameters:: metrics_root (str | pathlib.Path) – Required function argument.
Returns:: Return value produced by the function.
Return type:: pandas.DataFrame

spatial_vtk.visualize.dashboard.contracts.read_dashboard_table(table: DataFrame | str | Path) → DataFrame

Read a dashboard table from a DataFrame, Parquet, or CSV input.

Parameters:: table (pandas.DataFrame | str | pathlib.Path) – Required function argument.
Returns:: Return value produced by the function.
Return type:: pandas.DataFrame

spatial_vtk.visualize.dashboard.contracts.validate_dashboard_tables(tables: dict[str, DataFrame]) → dict[str, DataFrame]

Validate standard metrics dashboard tables.

Parameters:: tables (dict) – Required function argument.
Returns:: Return value produced by the function.
Return type:: dict

spatial_vtk.visualize.dashboard.contracts.validate_map_columns(df: DataFrame, *, table_name: str, lon_candidates: tuple[str, ...], lat_candidates: tuple[str, ...]) → tuple[str, str]

Return longitude and latitude columns or raise a clear error.

Parameters:

df (pandas.DataFrame) – Required function argument.
table_name (str) – Required function argument.
lon_candidates (tuple) – Required function argument.
lat_candidates (tuple) – Required function argument.

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.visualize.dashboard.contracts.validate_trace_qc_dashboard_table(trace_df: DataFrame) → DataFrame

Validate the trace-QC dashboard input table.

Parameters:: trace_df (pandas.DataFrame) – Required function argument.
Returns:: Return value produced by the function.
Return type:: pandas.DataFrame

Dashboard dataset export helpers.

Dashboard Export Overview 

This module converts wide or long metric tables into dashboard-ready Parquet datasets and reloads those datasets for summary generation.

Dashboard Export Examples 

Write one dashboard dataset:: path = write_dashboard_metric_dataset(metrics_df, "dashboard_data")

spatial_vtk.visualize.dashboard.export.add_dashboard_path_geometry(df: DataFrame) → DataFrame

Add distance, azimuth, and backazimuth columns when coordinates exist.

Parameters:

df (pandas.DataFrame) – Long metric table with event and station coordinates.
df – Required function argument.

Returns:

Copy with distance_km, azimuth_deg, and backazimuth_deg when enough coordinate columns are present.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.dashboard.export.forward_azimuth_deg(lat1: Any, lon1: Any, lat2: Any, lon2: Any) → ndarray

Calculate forward azimuth from event to station.

Parameters:

lat1 (Any) – Source coordinates in degrees.
lon1 (Any) – Source coordinates in degrees.
lat2 (Any) – Target coordinates in degrees.
lon2 (Any) – Target coordinates in degrees.
lat1 – Required function argument.
lon1 – Required function argument.
lat2 – Required function argument.
lon2 – Required function argument.

Returns:

Azimuth values in degrees clockwise from north.

Return type:

numpy.ndarray

Returns:

Return value produced by the function.

Return type:

numpy.ndarray

spatial_vtk.visualize.dashboard.export.haversine_km(lat1: Any, lon1: Any, lat2: Any, lon2: Any) → ndarray

Calculate great-circle distance in kilometers.

Parameters:

lat1 (Any) – Scalar or array-like coordinates in degrees.
lon1 (Any) – Scalar or array-like coordinates in degrees.
lat2 (Any) – Scalar or array-like coordinates in degrees.
lon2 (Any) – Scalar or array-like coordinates in degrees.
lat1 – Required function argument.
lon1 – Required function argument.
lat2 – Required function argument.
lon2 – Required function argument.

Returns:

Distance values in kilometers.

Return type:

numpy.ndarray

Returns:

Return value produced by the function.

Return type:

numpy.ndarray

spatial_vtk.visualize.dashboard.export.load_dashboard_metric_dataset(input_root: str | Path) → DataFrame

Load a dashboard metric Parquet dataset.

Parameters:

input_root (str | pathlib.Path) – Directory containing metrics_long.parquet or partitioned parquet files.
input_root – Required function argument.

Returns:

Combined long metric table.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.dashboard.export.safe_path_token(value: object) → str

Return a conservative token for partition paths.

Parameters:

value (object) – Value to include in a path component.
value – Required function argument.

Returns:

Sanitized path token.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

Write dashboard-ready long metric data as Parquet.

Parameters:

tables (pandas.DataFrame | str | pathlib.Path | collections.abc.Sequence[pandas.DataFrame | str | pathlib.Path]) – One table, path, or sequence of tables/paths.
output_root (str | pathlib.Path | None, optional) – Output directory for metrics_long.parquet or partitioned files. When omitted, the standard metrics_dashboard path is resolved from the active config.
residual_mode (str, optional) – Residual mode used when converting wide tables.
partitioned (bool, optional) – Whether to partition by model, band, and metric.
tables – Required function argument.
output_root – Optional function argument. Defaults to None.
residual_mode – Optional function argument. Defaults to 'logratio'.
partitioned – Optional function argument. Defaults to False.

Returns:

Dataset root directory.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.visualize.dashboard.export.write_dashboard_summary_dataset(input_root: str | Path | None = None, output_root: str | Path | None = None, *, hex_dist: float = 10.0, hex_az: float = 10.0, format: str = 'parquet') → dict[str, Path]

Build and write dashboard summary tables from a metric dataset.

Parameters:

input_root (str | pathlib.Path | None, optional) – Dashboard metric dataset root. When omitted, the standard metrics_dashboard path is resolved from the active config.
output_root (str | pathlib.Path | None, optional) – Output directory for summary tables. When omitted, the standard dashboard_summaries path is resolved from the active config.
hex_dist (float, optional) – Distance-bin size in kilometers.
hex_az (float, optional) – Azimuth-bin size in degrees.
format (str, optional) – Output format, "parquet" or "csv".
input_root – Optional function argument. Defaults to None.
output_root – Optional function argument. Defaults to None.
hex_dist – Optional function argument. Defaults to 10.0.
hex_az – Optional function argument. Defaults to 10.0.
format – Optional function argument. Defaults to 'parquet'.

Returns:

Written summary paths by table name.

Return type:

dict[str, pathlib.Path]

Returns:

Return value produced by the function.

Return type:

dict

Export helpers for Streamlit dashboard selections.

spatial_vtk.visualize.dashboard.exports.normalize_manual_review_queue(rows: list[dict[str, object]]) → list[dict[str, str]]

Normalize queue rows for the manual QC picker.

Parameters:: rows (list) – Required function argument.
Returns:: Return value produced by the function.
Return type:: list

spatial_vtk.visualize.dashboard.exports.queue_to_csv_bytes(rows: list[dict[str, object]]) → bytes

Return normalized manual-review queue rows as CSV bytes.

Parameters:: rows (list) – Required function argument.
Returns:: Return value produced by the function.
Return type:: bytes

spatial_vtk.visualize.dashboard.exports.write_dashboard_filtered_export(df: DataFrame, output_path: str | Path) → Path

Write filtered dashboard rows to CSV, Parquet, or JSON.

Parameters:

df (pandas.DataFrame) – Required function argument.
output_path (str | pathlib.Path) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.visualize.dashboard.exports.write_manual_review_queue(filtered_trace_df: DataFrame | list[dict[str, object]], output_path: str | Path) → Path

Write a manual QC picker queue from filtered dashboard rows.

The output CSV uses the event/station queue columns consumed by the manual QC picker. Additional missing columns are filled with blank strings.

Parameters:

filtered_trace_df (pandas.DataFrame | list[dict[str, object]]) – Required function argument.
output_path (str | pathlib.Path) – Required function argument.

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Pure filtering helpers for dashboard tables.

Filter one metrics dashboard table.

Parameters:

df (pandas.DataFrame) – Required function argument.
models (collections.abc.Iterable[str] | None, optional) – Optional function argument. Defaults to None.
metric (str | None, optional) – Optional function argument. Defaults to None.
bands (collections.abc.Iterable[str] | None, optional) – Optional function argument. Defaults to None.
value_column (str | None, optional) – Optional function argument. Defaults to None.
vs30_range (tuple[float | None, float | None] | None, optional) – Optional function argument. Defaults to None.
distance_range_km (tuple[float | None, float | None] | None, optional) – Optional function argument. Defaults to None.
magnitude_range (tuple[float | None, float | None] | None, optional) – Optional function argument. Defaults to None.
station_query (str, optional) – Optional function argument. Defaults to ''.
event_query (str, optional) – Optional function argument. Defaults to ''.
component (str | None, optional) – Optional function argument. Defaults to None.
min_count (int | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Filter one trace-QC dashboard table.

Parameters:

trace_df (pandas.DataFrame) – Required function argument.
event_filter (str, optional) – Optional function argument. Defaults to ''.
station_family (str, optional) – Optional function argument. Defaults to 'all'.
component_filter (str, optional) – Optional function argument. Defaults to 'all'.
station_query (str, optional) – Optional function argument. Defaults to ''.
magnitude_range (tuple[float | None, float | None] | None, optional) – Optional function argument. Defaults to None.
distance_range_km (tuple[float | None, float | None] | None, optional) – Optional function argument. Defaults to None.
date_range (tuple[pandas.Timestamp | str | None, pandas.Timestamp | str | None] | None, optional) – Optional function argument. Defaults to None.
metadata_warning (str, optional) – Optional function argument. Defaults to ''.
reject_reason (str, optional) – Optional function argument. Defaults to ''.
band (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Dashboard compatibility exports for public label helpers.

spatial_vtk.visualize.dashboard.labels.available_dashboard_value_columns(df: DataFrame, *, prefer_medians: bool = True) → list[str]

Return value columns that can color or plot dashboard data.

Parameters:

df (pandas.DataFrame) – Dashboard data table.
prefer_medians (bool, optional) – Whether median summary columns should appear before row-level columns.
df – Required function argument.
prefer_medians – Optional function argument. Defaults to True.

Returns:

Existing numeric value columns in display order.

Return type:

list[str]

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.visualize.dashboard.labels.band_display_label(band: object, configured_labels: dict[str, str] | None = None) → str

Return a human-readable passband label.

Parameters:

band (object) – Raw band token such as "1-3s", "1-3 sec", or "all".
configured_labels (dict[str, str] | None, optional) – Optional labels keyed by raw band token.
band – Required function argument.
configured_labels – Optional function argument. Defaults to None.

Returns:

User-facing period-band label.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.dashboard.labels.band_display_options(bands: Iterable[object], configured_labels: dict[str, str] | None = None) → dict[str, str]

Return display labels keyed by raw band token.

Parameters:

bands (collections.abc.Iterable) – Raw band tokens.
configured_labels (dict[str, str] | None, optional) – Optional explicit labels.
bands – Required function argument.
configured_labels – Optional function argument. Defaults to None.

Returns:

Labels keyed by the original string token.

Return type:

dict[str, str]

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.visualize.dashboard.labels.column_display_lookup(columns: Iterable[object], label_map: dict[str, str] | None = None) → dict[str, str]

Return human-readable labels for dataframe columns.

Parameters:

columns (collections.abc.Iterable) – Raw dataframe column names.
label_map (dict[str, str] | None, optional) – Optional exact-match override labels.
columns – Required function argument.
label_map – Optional function argument. Defaults to None.

Returns:

Mapping from raw column names to display labels.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.visualize.dashboard.labels.column_display_name(column: object, label_map: dict[str, str] | None = None) → str

Return a human-readable dataframe column header.

Parameters:

column (object) – Raw dataframe column name.
label_map (dict[str, str] | None, optional) – Optional exact-match override labels.
column – Required function argument.
label_map – Optional function argument. Defaults to None.

Returns:

Column label suitable for table previews, dashboards, and exports.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.dashboard.labels.display_table(df: DataFrame, *, columns: Iterable[str] | None = None, max_rows: int | None = None, label_map: dict[str, str] | None = None) → DataFrame

Return a copy of a dataframe with human-readable values and headers.

Parameters:

df (pandas.DataFrame) – Source dataframe.
columns (collections.abc.Iterable[str] | None, optional) – Optional preferred raw columns. Missing columns are ignored.
max_rows (int | None, optional) – Optional row limit.
label_map (dict[str, str] | None, optional) – Optional exact-match override labels for column headers.
df – Required function argument.
columns – Optional function argument. Defaults to None.
max_rows – Optional function argument. Defaults to None.
label_map – Optional function argument. Defaults to None.

Returns:

Display copy with metric names, period bands, value-column names, and column headers converted to user-facing labels.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.dashboard.labels.metric_display_name(metric: object) → str

Return a human-readable metric label.

Parameters:

metric (object) – Public metric name, legacy C-code, or period-specific metric token.
metric – Required function argument.

Returns:

Label suitable for figure titles, legends, and dashboards.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.dashboard.labels.normalize_metric_name(metric: object) → str

Return the public metric name for a metric token.

Parameters:

metric (object) – Public metric name, legacy C-code, or raw table token.
metric – Required function argument.

Returns:

Public metric token when known.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.dashboard.labels.transform_display_options(transforms: Iterable[str] = ('residual', 'log2_residual', 'ln_residual', 'anderson_2004_gof', 'olsen_mayhew_gof')) → dict[str, str]

Return human-readable labels for transform names.

Parameters:

transforms (collections.abc.Iterable, optional) – Transform column names.
transforms – Optional function argument. Defaults to ('residual', 'log2_residual', 'ln_residual', 'anderson_2004_gof', 'olsen_mayhew_gof').

Returns:

Mapping from raw transform names to display labels.

Return type:

dict[str, str]

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.visualize.dashboard.labels.value_column_display_name(column: object) → str

Return a human-readable metric value or transform-column label.

Parameters:

column (object) – Raw dataframe column name.
column – Required function argument.

Returns:

Label suitable for an axis, colorbar, selector, or popup.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

Launch helpers for Streamlit dashboards.

spatial_vtk.visualize.dashboard.launch.build_streamlit_command(entrypoint: str | Path, *, server_address: str = '127.0.0.1', server_port: int = 8501, show: bool = True, extra_args: list[str] | None = None) → list[str]

Build the command used to run one Streamlit dashboard.

Parameters:

entrypoint (str | pathlib.Path) – Required function argument.
server_address (str, optional) – Optional function argument. Defaults to '127.0.0.1'.
server_port (int, optional) – Optional function argument. Defaults to 8501.
show (bool, optional) – Optional function argument. Defaults to True.
extra_args (list[str] | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.visualize.dashboard.launch.launch_metrics_dashboard(*, metrics_root: str | Path, summary_root: str | Path, server_address: str = '127.0.0.1', server_port: int = 8501, show: bool = True, extra_args: list[str] | None = None) → Popen[Any]

Launch the Streamlit Metrics Explorer.

Parameters:

metrics_root (str | pathlib.Path) – Required function argument.
summary_root (str | pathlib.Path) – Required function argument.
server_address (str, optional) – Optional function argument. Defaults to '127.0.0.1'.
server_port (int, optional) – Optional function argument. Defaults to 8501.
show (bool, optional) – Optional function argument. Defaults to True.
extra_args (list[str] | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

subprocess.Popen

spatial_vtk.visualize.dashboard.launch.launch_qc_dashboard(*, trace_summary: str | Path | None = None, config_path: str | Path | None = None, server_address: str = '127.0.0.1', server_port: int = 8502, show: bool = True, extra_args: list[str] | None = None) → Popen[Any]

Launch the Streamlit QC Explorer.

Parameters:

trace_summary (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
config_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
server_address (str, optional) – Optional function argument. Defaults to '127.0.0.1'.
server_port (int, optional) – Optional function argument. Defaults to 8502.
show (bool, optional) – Optional function argument. Defaults to True.
extra_args (list[str] | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

subprocess.Popen

spatial_vtk.visualize.dashboard.launch.launch_streamlit_dashboard(entrypoint: str | Path, *, server_address: str = '127.0.0.1', server_port: int = 8501, show: bool = True, extra_args: list[str] | None = None, env: dict[str, str] | None = None) → Popen[Any]

Start one Streamlit dashboard process.

Parameters:

entrypoint (str | pathlib.Path) – Required function argument.
server_address (str, optional) – Optional function argument. Defaults to '127.0.0.1'.
server_port (int, optional) – Optional function argument. Defaults to 8501.
show (bool, optional) – Optional function argument. Defaults to True.
extra_args (list[str] | None, optional) – Optional function argument. Defaults to None.
env (dict[str, str] | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

subprocess.Popen

Folium map builders for Streamlit dashboards.

spatial_vtk.visualize.dashboard.maps.build_event_folium_map(df: DataFrame, *, value_col: str, basemap: str = 'Carto Light', geojson_paths: list[str | Path] | None = None, marker_cluster: bool = True, max_markers: int = 2000) → Any

Build an event metric map from a dashboard event table.

Parameters:

df (pandas.DataFrame) – Required function argument.
value_col (str) – Required function argument.
basemap (str, optional) – Optional function argument. Defaults to 'Carto Light'.
geojson_paths (list[str | pathlib.Path] | None, optional) – Optional function argument. Defaults to None.
marker_cluster (bool, optional) – Optional function argument. Defaults to True.
max_markers (int, optional) – Optional function argument. Defaults to 2000.

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.visualize.dashboard.maps.build_station_folium_map(df: DataFrame, *, value_col: str, basemap: str = 'Carto Light', geojson_paths: list[str | Path] | None = None, marker_cluster: bool = True, max_markers: int = 2000) → Any

Build a station metric map from a dashboard station table.

Parameters:

df (pandas.DataFrame) – Required function argument.
value_col (str) – Required function argument.
basemap (str, optional) – Optional function argument. Defaults to 'Carto Light'.
geojson_paths (list[str | pathlib.Path] | None, optional) – Optional function argument. Defaults to None.
marker_cluster (bool, optional) – Optional function argument. Defaults to True.
max_markers (int, optional) – Optional function argument. Defaults to 2000.

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.visualize.dashboard.maps.render_folium_html(map_obj: Any) → str

Render one Folium map to HTML.

Parameters:: map_obj (Any) – Required function argument.
Returns:: Return value produced by the function.
Return type:: str

Streamlit Metrics Explorer entrypoint.

Dashboard Streamlit Metrics Overview 

This module is executed by Streamlit to explore dashboard-ready metric tables. Filtering, plotting, and map construction are delegated to normal package helpers so the app stays thin and testable.

spatial_vtk.visualize.dashboard.streamlit_metrics.main() → None

Run the Streamlit Metrics Explorer.

Returns:: Return value produced by the function.
Return type:: None

Streamlit QC Explorer entrypoint.

spatial_vtk.visualize.dashboard.streamlit_qc.main() → None

Run the Streamlit QC Explorer.

Returns:: Return value produced by the function.
Return type:: None

Dashboard preparation tables for long metric residual data.

spatial_vtk.visualize.dashboard.tables.build_dashboard_summaries(df: DataFrame, *, hex_dist: float = 10.0, hex_az: float = 10.0) → dict[str, DataFrame]

Build dashboard summary tables from long metric residual data.

Parameters:

df (pandas.DataFrame) – Wide or long metric table.
hex_dist (float, optional) – Distance bin size in kilometers for path summaries.
hex_az (float, optional) – Azimuth bin size in degrees for path summaries.
df – Required function argument.
hex_dist – Optional function argument. Defaults to 10.0.
hex_az – Optional function argument. Defaults to 10.0.

Returns:

Summary tables keyed as model_metric_band, station_rollup, event_rollup, and path_hex.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.visualize.dashboard.tables.prepare_dashboard_metric_table(df: DataFrame, *, residual_mode: str = 'logratio') → DataFrame

Prepare a metric table for dashboard summaries.

Parameters:

df (pandas.DataFrame) – Wide or long metric table.
residual_mode (str, optional) – Residual mode used when converting wide tables.
df – Required function argument.
residual_mode – Optional function argument. Defaults to 'logratio'.

Returns:

Long metric residual table with dashboard-compatible columns.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.dashboard.tables.write_dashboard_summaries(summaries: dict[str, DataFrame], output_dir: str | Path, *, format: str = 'parquet') → dict[str, Path]

Write dashboard summary tables to a directory.

Parameters:

summaries (dict) – Required function argument.
output_dir (str | pathlib.Path) – Required function argument.
format (str, optional) – Optional function argument. Defaults to 'parquet'.

Returns:

Return value produced by the function.

Return type:

dict

Shared Figure Utilities 

Shared figure context labels for Spatial-VTK plots.

Figure Context Overview 

This module builds short, human-readable context strings for figures so saved PNGs remain understandable outside the notebook, dashboard, or script that created them.

Figure Context Examples 

Add a compact context line under a plot title:: apply_figure_context(ax, metrics, value_col="log2_residual")

spatial_vtk.visualize.figure_context.add_below_axes_table(ax: Axes, *, rows: Sequence[Sequence[object]], columns: Sequence[str], col_widths: Sequence[float] | None = None, font_size: float = 7.5, max_visible_rows: int = 6) → None

Add a compact summary table below a Matplotlib axis.

Parameters:

ax (matplotlib.axes._axes.Axes) – Axis that owns the table.
rows (collections.abc.Sequence) – Body rows to display.
columns (collections.abc.Sequence) – Column headers.
col_widths (collections.abc.Sequence[float] | None, optional) – Optional relative column widths.
font_size (float, optional) – Table text size.
max_visible_rows (int, optional) – Maximum rows shown before an omitted-count row is appended.
ax – Required function argument.
rows – Required function argument.
columns – Required function argument.
col_widths – Optional function argument. Defaults to None.
font_size – Optional function argument. Defaults to 7.5.
max_visible_rows – Optional function argument. Defaults to 6.

Returns:

The figure layout and axis table are updated in place.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.visualize.figure_context.apply_figure_context(ax: Axes, df: DataFrame | None = None, *, value_col: str | None = None, title: str | None = None, max_values: int = 5, include_counts: bool = True, include_value: bool = True, include_metric: bool = True, include_model: bool = True, include_period: bool = True, include_component: bool = True, include_processing: bool = True, max_line_chars: int = 90, extra: Sequence[str] | None = None) → None

Apply a title plus concise context line to an axis.

Parameters:

ax (matplotlib.axes._axes.Axes) – Matplotlib axis to update.
df (pandas.DataFrame | None, optional) – Optional dataframe used to infer context.
value_col (str | None, optional) – Column or transform shown by the figure.
title (str | None, optional) – Primary title text.
max_values (int, optional) – Maximum distinct values to list in the context.
include_counts (bool, optional) – Whether to include rows/events/stations.
extra (collections.abc.Sequence[str] | None, optional) – Additional preformatted context strings.
ax – Required function argument.
df – Optional function argument. Defaults to None.
value_col – Optional function argument. Defaults to None.
title – Optional function argument. Defaults to None.
max_values – Optional function argument. Defaults to 5.
include_counts – Optional function argument. Defaults to True.
include_value (bool, optional) – Optional function argument. Defaults to True.
include_metric (bool, optional) – Optional function argument. Defaults to True.
include_model (bool, optional) – Optional function argument. Defaults to True.
include_period (bool, optional) – Optional function argument. Defaults to True.
include_component (bool, optional) – Optional function argument. Defaults to True.
include_processing (bool, optional) – Optional function argument. Defaults to True.
max_line_chars (int, optional) – Optional function argument. Defaults to 90.
extra – Optional function argument. Defaults to None.

Returns:

The axis title is updated in place.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.visualize.figure_context.context_value_label(value_col: str, df: DataFrame | None = None) → str

Return a value label with centering/ratio notes where detectable.

Parameters:

value_col (str) – Column or transform shown by the figure.
df (pandas.DataFrame | None, optional) – Optional dataframe used to inspect field_source and event-centering metadata.
value_col – Required function argument.
df – Optional function argument. Defaults to None.

Returns:

Human-readable value label.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.figure_context.figure_context_lines(df: DataFrame | None = None, *, value_col: str | None = None, max_values: int = 5, include_counts: bool = True, include_value: bool = True, include_metric: bool = True, include_model: bool = True, include_period: bool = True, include_component: bool = True, include_processing: bool = True, extra: Sequence[str] | None = None) → list[str]

Build concise context lines from common Spatial-VTK columns.

Parameters:

df (pandas.DataFrame | None, optional) – Optional dataframe used to infer model, metric, period band, component, and row-count context.
value_col (str | None, optional) – Column or transform shown by the figure.
max_values (int, optional) – Maximum distinct values to show before summarizing as “N values”.
include_counts (bool, optional) – Whether to include rows/events/stations when available.
extra (collections.abc.Sequence[str] | None, optional) – Additional preformatted context strings.
df – Optional function argument. Defaults to None.
value_col – Optional function argument. Defaults to None.
max_values – Optional function argument. Defaults to 5.
include_counts – Optional function argument. Defaults to True.
include_value (bool, optional) – Optional function argument. Defaults to True.
include_metric (bool, optional) – Optional function argument. Defaults to True.
include_model (bool, optional) – Optional function argument. Defaults to True.
include_period (bool, optional) – Optional function argument. Defaults to True.
include_component (bool, optional) – Optional function argument. Defaults to True.
include_processing (bool, optional) – Optional function argument. Defaults to True.
extra – Optional function argument. Defaults to None.

Returns:

Context lines suitable for a subtitle or annotation box.

Return type:

list of str

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.visualize.figure_context.figure_context_text(df: DataFrame | None = None, *, value_col: str | None = None, separator: str = ' | ', **kwargs: Any) → str

Return figure context as one compact string.

Parameters:

df (pandas.DataFrame | None, optional) – Optional dataframe used to infer context.
value_col (str | None, optional) – Column or transform shown by the figure.
separator (str, optional) – Separator used between context fragments.
**kwargs – Additional options passed to figure_context_lines().
df – Optional function argument. Defaults to None.
value_col – Optional function argument. Defaults to None.
separator – Optional function argument. Defaults to ' | '.
kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

One-line context string.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.figure_context.is_log2_ratio_field(value_col: str | None, df: DataFrame | None = None) → bool

Return whether a field is interpretable as a log2 observed/synthetic ratio.

Parameters:

value_col (str | None) – Value column or transform name.
df (pandas.DataFrame | None, optional) – Optional dataframe used to inspect field_source.
value_col – Required function argument.
df – Optional function argument. Defaults to None.

Returns:

True when percent conversion with 2 ** effect - 1 is meaningful.

Return type:

bool

Returns:

Return value produced by the function.

Return type:

bool

spatial_vtk.visualize.figure_context.log2_effect_to_percent(effect: float | int | floating[Any]) → float

Convert a log2 ratio difference to percent change.

Parameters:

effect (float | int | numpy.floating[Any]) – Difference in log2 observed/synthetic ratio units.
effect – Required function argument.

Returns:

Percent change in observed/synthetic ratio.

Return type:

float

Returns:

Return value produced by the function.

Return type:

float

spatial_vtk.visualize.figure_context.title_with_subtitle(title: str, subtitle: str | None = None) → str

Return a figure title with an optional second subtitle line.

Parameters:

title (str) – Primary title line.
subtitle (str | None, optional) – Optional concise context line, such as a waveform filter description.
title – Required function argument.
subtitle – Optional function argument. Defaults to None.

Returns:

title alone, or title followed by subtitle on the next line.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.figure_context.value_color_settings(values: Sequence[float] | ndarray | Series, value_col: str | None, df: DataFrame | None = None, *, diverging_cmap: str = 'seismic', sequential_cmap: str = 'viridis') → tuple[str, float, float]

Return a consistent colormap and color limits for plotted values.

Parameters:

values (collections.abc.Sequence[float] | numpy.ndarray | pandas.Series) – Numeric values being plotted.
value_col (str | None) – Value column or transform name.
df (pandas.DataFrame | None, optional) – Optional dataframe used to inspect generic spatial field metadata.
diverging_cmap (str, optional) – Colormaps used for signed residual-like/log/centered values and positive/score-like values.
sequential_cmap (str, optional) – Colormaps used for signed residual-like/log/centered values and positive/score-like values.
values – Required function argument.
value_col – Required function argument.
df – Optional function argument. Defaults to None.
diverging_cmap – Optional function argument. Defaults to 'seismic'.
sequential_cmap – Optional function argument. Defaults to 'viridis'.

Returns:

Colormap name, lower color limit, and upper color limit.

Return type:

tuple[str, float, float]

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.visualize.figure_context.value_requires_model(value_col: str | None, df: DataFrame | None = None) → bool

Return whether a plotted value depends on synthetic model output.

Parameters:

value_col (str | None) – Value column or transform name.
df (pandas.DataFrame | None, optional) – Optional dataframe used to inspect field_source for generic spatial field columns.
value_col – Required function argument.
df – Optional function argument. Defaults to None.

Returns:

True when model context should be shown or explicitly selected.

Return type:

bool

Returns:

Return value produced by the function.

Return type:

bool

spatial_vtk.visualize.figure_context.value_uses_zero_reference(value_col: str | None, df: DataFrame | None = None) → bool

Return whether a value should use a zero reference/diverging scale.

Parameters:

value_col (str | None) – Value column or transform name.
df (pandas.DataFrame | None, optional) – Optional dataframe used to inspect field_source.
value_col – Required function argument.
df – Optional function argument. Defaults to None.

Returns:

True for residuals, centered fields, delays, errors, and signed improvements; false for observed/synthetic amplitudes and GOF scores.

Return type:

bool

Returns:

Return value produced by the function.

Return type:

bool

Shared Matplotlib figure display and save helpers.

Figure I/O Overview 

This module keeps Spatial-VTK plotting functions consistent in notebooks, scripts, and CLI calls. Plot functions return a Matplotlib figure, can display automatically in notebooks, and can save either through a one-line plotting call or a separate savefig call.

Figure I/O Examples 

Create and display a figure in a notebook:: fig = plot_retention_summary(retention_table)
Save a returned figure:: savefig(fig, outpath="retention_summary.png")
Show and save in one call:: plot_retention_summary(retention_table, showfig=True, savefig=True, outpath="retention_summary.png")

spatial_vtk.visualize.figure_io.default_figure_paths(figure_dir: str | Path, names: tuple[str, ...] | list[str] | None = None, *, suffix: str = '.png', create_dir: bool = True) → SimpleNamespace

Return a namespace of standard figure paths.

Parameters:

figure_dir (str | pathlib.Path) – Directory where figures should be written.
names (tuple[str, ...] | list[str] | None, optional) – Optional figure basenames. When omitted, common tutorial/workflow figure names are returned.
suffix (str, optional) – File extension to append when a name has no extension.
create_dir (bool, optional) – Whether to create figure_dir.
figure_dir – Required function argument.
names – Optional function argument. Defaults to None.
suffix – Optional function argument. Defaults to '.png'.
create_dir – Optional function argument. Defaults to True.

Returns:

Namespace with one attribute per figure basename.

Return type:

types.SimpleNamespace

Returns:

Return value produced by the function.

Return type:

types.SimpleNamespace

Apply standard show/save behavior and return the figure.

Parameters:

fig (matplotlib.figure.Figure) – Matplotlib figure to finish.
output_path (str | pathlib.Path | None, optional) – Optional destination path. outpath is the preferred public keyword; output_path preserves older positional usage.
outpath (str | pathlib.Path | None, optional) – Optional destination path. outpath is the preferred public keyword; output_path preserves older positional usage.
output_key (str | None, optional) – Optional default-output registry key. When omitted and savefig is true, Spatial-VTK infers a key from the plotting function name.
cfg (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to resolve default output folders.
showfig (bool | None, optional) – Whether to display the figure. When None, figures display inside notebooks and stay quiet in scripts/tests.
savefig (bool | None, optional) – Whether to save the figure. When None, the figure is saved if a path is provided.
close (bool | None, optional) – Whether to close the figure after saving/display handling. When None, finished figures that are saved or explicitly displayed are closed after handling. This prevents notebook backends from auto- rendering a second copy after Spatial-VTK has already displayed one.
bbox_inches (str, optional) – Matplotlib bounding-box setting used by Figure.savefig.
**savefig_kwargs – Additional keyword arguments passed to Figure.savefig.
fig – Required function argument.
output_path – Optional function argument. Defaults to None.
outpath – Optional function argument. Defaults to None.
output_key – Optional function argument. Defaults to None.
cfg – Optional function argument. Defaults to None.
showfig – Optional function argument. Defaults to None.
savefig – Optional function argument. Defaults to None.
close – Optional function argument. Defaults to None.
bbox_inches – Optional function argument. Defaults to 'tight'.
savefig_kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

The input figure.

Return type:

matplotlib.figure.Figure

Returns:

Return value produced by the function.

Return type:

matplotlib.figure.Figure

spatial_vtk.visualize.figure_io.savefig(fig: Figure, outpath: str | Path, *, close: bool = False, bbox_inches: str = 'tight', **kwargs: Any) → Path

Save a Matplotlib figure and return the written path.

Parameters:

fig (matplotlib.figure.Figure) – Matplotlib figure to save.
outpath (str | pathlib.Path) – Destination image path.
close (bool, optional) – Whether to close the figure after saving.
bbox_inches (str, optional) – Matplotlib bounding-box setting used by Figure.savefig.
**kwargs – Additional keyword arguments passed to Figure.savefig.
fig – Required function argument.
outpath – Required function argument.
close – Optional function argument. Defaults to False.
bbox_inches – Optional function argument. Defaults to 'tight'.
kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Shared scatter-fit helpers for Spatial-VTK figures.

Fit Overview 

This module centralizes optional fitted-line behavior for scatter-style plots so public plotting functions expose the same fit keywords and legend labels.

Fit Examples 

Draw a LOWESS line on an axis:: draw_scatter_fit(ax, x, y, fit_method="lowess", color="tab:blue")

spatial_vtk.visualize.fit.FitMethod: alias of object

spatial_vtk.visualize.fit.draw_scatter_fit(ax: Axes, x: ndarray, y: ndarray, *, fit_method: object, lowess_frac: float = 0.65, color: object = 'black', label: str | None = None, linewidth: float = 1.3, alpha: float = 0.88) → None

Draw an optional fitted line for one scatter group.

Parameters:

ax (matplotlib.axes._axes.Axes) – Target Matplotlib axis.
x (numpy.ndarray) – Numeric finite x/y arrays.
y (numpy.ndarray) – Numeric finite x/y arrays.
fit_method (object) – "point-to-point", "best", "linear", "inverse", "inverse-square", "quadratic", "exponential-decay", "lowess", a callable, or None.
lowess_frac (float, optional) – Fraction of points used by LOWESS.
color (object, optional) – Matplotlib display controls.
label (str | None, optional) – Matplotlib display controls.
linewidth (float, optional) – Matplotlib display controls.
alpha (float, optional) – Matplotlib display controls.
ax – Required function argument.
x – Required function argument.
y – Required function argument.
fit_method – Required function argument.
lowess_frac – Optional function argument. Defaults to 0.65.
color – Optional function argument. Defaults to 'black'.
label – Optional function argument. Defaults to None.
linewidth – Optional function argument. Defaults to 1.3.
alpha – Optional function argument. Defaults to 0.88.

Returns:

The fitted line is added to ax when possible.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.visualize.fit.fit_line_stats(x: ndarray, y: ndarray, fit_x: ndarray, fit_y: ndarray) → tuple[float, float]

Return overall fit-line slope and observed-vs-fit Pearson r.

Parameters:

x (numpy.ndarray) – Required function argument.
y (numpy.ndarray) – Required function argument.
fit_x (numpy.ndarray) – Required function argument.
fit_y (numpy.ndarray) – Required function argument.

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.visualize.fit.fit_method_has_legend(fit_method: object) → bool

Return whether a fit mode should force a visible legend.

Parameters:: fit_method (object) – Required function argument.
Returns:: Return value produced by the function.
Return type:: bool

spatial_vtk.visualize.fit.normalize_fit_method(method: object) → str

Normalize a public fit keyword.

Parameters:: method (object) – Required function argument.
Returns:: Return value produced by the function.
Return type:: str

spatial_vtk.visualize.fit.scatter_fit_display_name(method_name: str) → str

Return a readable fit method name for legends.

Parameters:: method_name (str) – Required function argument.
Returns:: Return value produced by the function.
Return type:: str

Record-section figure helpers for Spatial-VTK.

Record Sections Overview 

This module draws generic record-section figures from explicit waveform tables. It is intentionally independent of private data roots and accepts arrays, ObsPy-like traces, or table rows prepared by upstream package functions.

spatial_vtk.visualize.record_sections.build_record_section_rows(records: DataFrame | Iterable[Any], *, trace_col: str = 'trace', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', default_dt: float = 1.0) → DataFrame

Normalize traces or a record table to the plotting row contract.

Parameters:

records (Union) – DataFrame with trace rows or iterable of trace-like objects.
trace_col (str, optional) – Trace column used when records is a DataFrame.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
records – Required function argument.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
default_dt – Optional function argument. Defaults to 1.0.

Returns:

Table with trace, dt, station, component, and distance_km columns where available.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.visualize.record_sections.normalize_trace(data: ndarray) → ndarray

Normalize one trace by peak absolute amplitude.

Parameters:

data (numpy.ndarray) – Waveform samples.
data – Required function argument.

Returns:

Normalized samples.

Return type:

numpy.ndarray

Returns:

Return value produced by the function.

Return type:

numpy.ndarray

spatial_vtk.visualize.record_sections.plot_observed_synthetic_record_section(records_df: DataFrame, output_path: str | Path | None = None, *, observed_col: str = 'observed', synthetic_col: str = 'synthetic', dt_col: str = 'dt', synthetic_dt_col: str = 'synthetic_dt', observed_time_offset_col: str = 'observed_time_offset_s', synthetic_time_offset_col: str = 'synthetic_time_offset_s', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', components: Iterable[str] | None = None, selection: FigureSelection | None = None, max_records: int | None = 80, normalize: bool = True, scale: float = 1.0, title: str = 'Observed and Synthetic Record Section', filter_label: str | None = None, default_dt: float = 1.0, time_limit_s: float | None = None, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot observed and synthetic traces on shared record-section axes.

Parameters:

records_df (pandas.DataFrame) – Table with observed and synthetic waveform columns.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
observed_col (str, optional) – Waveform columns.
synthetic_col (str, optional) – Waveform columns.
dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
synthetic_dt_col (str, optional) – Row-level sample interval columns for array-backed observed and synthetic waveforms.
observed_time_offset_col (str, optional) – Optional columns giving trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
synthetic_time_offset_col (str, optional) – Optional columns giving trace start time in seconds relative to the event origin. When present, the x-axis is event-origin-relative.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
components (Optional, optional) – Optional ordered component subset.
max_records (int | None, optional) – Maximum rows to draw per component.
normalize (bool, optional) – Whether to normalize each trace before plotting.
scale (float, optional) – Multiplicative plotting gain.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
time_limit_s (float | None, optional) – Optional maximum seconds to display from each trace start.
records_df – Required function argument.
output_path – Optional function argument. Defaults to None.
observed_col – Optional function argument. Defaults to 'observed'.
synthetic_col – Optional function argument. Defaults to 'synthetic'.
dt_col – Optional function argument. Defaults to 'dt'.
synthetic_dt_col – Optional function argument. Defaults to 'synthetic_dt'.
observed_time_offset_col – Optional function argument. Defaults to 'observed_time_offset_s'.
synthetic_time_offset_col – Optional function argument. Defaults to 'synthetic_time_offset_s'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
components – Optional function argument. Defaults to None.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 80.
normalize – Optional function argument. Defaults to True.
scale – Optional function argument. Defaults to 1.0.
title – Optional function argument. Defaults to 'Observed and Synthetic Record Section'.
filter_label – Optional function argument. Defaults to None.
default_dt – Optional function argument. Defaults to 1.0.
time_limit_s – 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.visualize.record_sections.plot_record_section(records: DataFrame | Iterable[Any], output_path: str | Path | None = None, *, trace_col: str = 'trace', station_col: str = 'station', component_col: str | None = 'component', distance_col: str = 'distance_km', components: Iterable[str] | None = None, selection: FigureSelection | None = None, max_records: int | None = 80, normalize: bool = True, scale: float = 1.0, title: str = 'Record Section', filter_label: str | None = None, default_dt: float = 1.0, showfig: bool | None = None, savefig: bool | None = None, outpath: str | Path | None = None) → Figure

Plot one or more component record sections.

Parameters:

records (Union) – Record table or iterable of trace-like objects.
output_path (str | pathlib.Path | None, optional) – Destination figure path.
trace_col (str, optional) – Trace column for DataFrame inputs.
station_col (str, optional) – Station label column.
component_col (str | None, optional) – Optional component column.
distance_col (str, optional) – Optional distance column.
components (Optional, optional) – Optional ordered component subset.
max_records (int | None, optional) – Maximum traces to draw per component.
normalize (bool, optional) – Whether to normalize each trace before plotting.
scale (float, optional) – Multiplicative plotting gain.
title (str, optional) – Figure title.
filter_label (str | None, optional) – Optional second title line describing any bandpass or lowpass filter.
default_dt (float, optional) – Sample interval used for array inputs without metadata.
records – Required function argument.
output_path – Optional function argument. Defaults to None.
trace_col – Optional function argument. Defaults to 'trace'.
station_col – Optional function argument. Defaults to 'station'.
component_col – Optional function argument. Defaults to 'component'.
distance_col – Optional function argument. Defaults to 'distance_km'.
components – Optional function argument. Defaults to None.
selection (spatial_vtk.visualize.selection.FigureSelection | None, optional) – Optional function argument. Defaults to None.
max_records – Optional function argument. Defaults to 80.
normalize – Optional function argument. Defaults to True.
scale – Optional function argument. Defaults to 1.0.
title – Optional function argument. Defaults to 'Record Section'.
filter_label – Optional function argument. Defaults to None.
default_dt – Optional function argument. Defaults to 1.0.
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.visualize.record_sections.row_sample_interval(row: Series, column: str | None, default: float = 1.0) → float

Read a finite positive sample interval from a dataframe row.

Parameters:

row (pandas.Series) – Record row that may contain sample interval metadata.
column (str | None) – Column containing sample interval values in seconds.
default (float, optional) – Fallback sample interval.
row – Required function argument.
column – Required function argument.
default – Optional function argument. Defaults to 1.0.

Returns:

Sample interval in seconds.

Return type:

float

Returns:

Return value produced by the function.

Return type:

float

spatial_vtk.visualize.record_sections.row_time_offset(row: Series, column: str | None, default: float = 0.0) → float

Read a finite trace time offset from a dataframe row.

Parameters:

row (pandas.Series) – Record row that may contain time-offset metadata.
column (str | None) – Column containing seconds relative to the event origin.
default (float, optional) – Fallback offset in seconds.
row – Required function argument.
column – Required function argument.
default – Optional function argument. Defaults to 0.0.

Returns:

Time offset in seconds.

Return type:

float

Returns:

Return value produced by the function.

Return type:

float

spatial_vtk.visualize.record_sections.save_record_section_figure(fig: Figure, output_path: str | Path, *, close: bool = True, dpi: int = 180) → Path

Save a record-section figure and return the written path.

Parameters:

fig (matplotlib.figure.Figure) – Matplotlib figure.
output_path (str | pathlib.Path) – Destination image path.
close (bool, optional) – Whether to close the figure after saving.
dpi (int, optional) – Raster resolution.
fig – Required function argument.
output_path – Required function argument.
close – Optional function argument. Defaults to True.
dpi – Optional function argument. Defaults to 180.

Returns:

Written figure path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.visualize.record_sections.trace_component(trace: Any) → str

Return the component suffix from an ObsPy-like trace.

Parameters:

trace (Any) – Trace object with optional stats.channel metadata.
trace – Required function argument.

Returns:

Uppercase component suffix, or an empty string when unavailable.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.record_sections.trace_station(trace: Any) → str

Return a compact station label from an ObsPy-like trace.

Parameters:

trace (Any) – Trace object with optional network/station/location metadata.
trace – Required function argument.

Returns:

Station label.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.visualize.record_sections.trace_to_array(value: Any, *, default_dt: float = 1.0) → tuple[ndarray, float]

Convert an array-like value or ObsPy-like trace to waveform samples.

Parameters:

value (Any) – Numeric array or trace object with data and optional stats.
default_dt (float, optional) – Sample interval used when metadata are unavailable.
value – Required function argument.
default_dt – Optional function argument. Defaults to 1.0.

Returns:

(samples, dt_seconds).

Return type:

tuple

Returns:

Return value produced by the function.

Return type:

tuple

Config-driven row selection helpers for public figures and dashboards.

Selection Overview 

This module applies the active Spatial-VTK configuration to dataframe-backed figures without making every plotting function parse config files itself.

Selection Examples 

Resolve and apply defaults before plotting:: selection = FigureSelection.from_config(config, command="visualize.context") plot_df = selection.apply(records)

class spatial_vtk.visualize.selection.FigureSelection(components: tuple[str, ...] = (), passbands: tuple[str, ...] = (), events: tuple[str, ...] = (), stations: tuple[str, ...] = (), bounds: tuple[float, float, float, float] | None = None, band_labels: dict[str, str] = <factory>)

Resolved row-selection settings for figure inputs.

Parameters:

components (tuple[str, ...]) – Component tokens to keep, or an empty tuple to keep all components.
passbands (tuple[str, ...]) – Passband tokens to keep, or an empty tuple to keep all passbands.
events (tuple[str, ...]) – Event identifiers to keep, or an empty tuple to keep all events.
stations (tuple[str, ...]) – Station identifiers to keep, or an empty tuple to keep all stations.
bounds (tuple[float, float, float, float] | None) – Optional (lon_min, lon_max, lat_min, lat_max) map bounds.
band_labels (dict[str, str]) – Optional display labels keyed by raw passband tokens.

Returns:

Immutable selection object.

Return type:

FigureSelection

apply(df: DataFrame, *, component_col: str = 'component', band_cols: tuple[str, ...] = ('band', 'passband', 'dominant_band_label'), event_col: str = 'event_id', station_col: str = 'station') → DataFrame

Apply configured component, passband, event, and station filters.

Parameters:

df (pandas.DataFrame) – Input table.
component_col (str, optional) – Column names used for filtering when present.
band_cols (tuple, optional) – Column names used for filtering when present.
event_col (str, optional) – Column names used for filtering when present.
station_col (str, optional) – Column names used for filtering when present.
df – Required function argument.
component_col – Optional function argument. Defaults to 'component'.
band_cols – Optional function argument. Defaults to ('band', 'passband', 'dominant_band_label').
event_col – Optional function argument. Defaults to 'event_id'.
station_col – Optional function argument. Defaults to 'station'.

Returns:

Filtered copy with reset index.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

Resolve figure-selection settings from config plus overrides.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | str | pathlib.Path | None, optional) – Config object, config path, or None for no config.
command (str, optional) – Dotted command used to merge run defaults.
components (Optional, optional) – Explicit overrides. When omitted, matching config values are used.
passbands (Optional, optional) – Explicit overrides. When omitted, matching config values are used.
events (Optional, optional) – Explicit overrides. When omitted, matching config values are used.
stations (Optional, optional) – Explicit overrides. When omitted, matching config values are used.
bounds (Union, optional) – Explicit overrides. When omitted, matching config values are used.
config – Optional function argument. Defaults to None.
command – Optional function argument. Defaults to 'visualize'.
components – Optional function argument. Defaults to None.
passbands – Optional function argument. Defaults to None.
events – Optional function argument. Defaults to None.
stations – Optional function argument. Defaults to None.
bounds – Optional function argument. Defaults to None.

Returns:

Selection object ready to apply to a dataframe.

Return type:

FigureSelection

Returns:

Return value produced by the function.

Return type:

spatial_vtk.visualize.selection.FigureSelection

class spatial_vtk.visualize.selection.FigureSpatialSelection(station_region_col: str | None = None, station_regions: tuple[str, ...] = (), station_region_relation: Literal['inside', 'outside', 'both'] = 'inside', event_region_col: str | None = None, event_regions: tuple[str, ...] = (), event_region_relation: Literal['inside', 'outside', 'both'] = 'inside', station_bounds: tuple[float, float, float, float] | None = None, station_bounds_relation: Literal['inside', 'outside', 'both'] = 'inside', event_bounds: tuple[float, float, float, float] | None = None, event_bounds_relation: Literal['inside', 'outside', 'both'] = 'inside', station_corridor_col: str | None = None, station_corridors: tuple[str, ...] = (), station_corridor_relation: Literal['inside', 'outside', 'both'] = 'inside', event_corridor_col: str | None = None, event_corridors: tuple[str, ...] = (), event_corridor_relation: Literal['inside', 'outside', 'both'] = 'inside', label: str | None = None)

Resolved station/event spatial subset settings for figure inputs.

Parameters:

station_region_col – Columns containing region labels, usually added by GeoJSON joins.
event_region_col – Columns containing region labels, usually added by GeoJSON joins.
station_regions – Region labels to select. Empty values mean any non-empty region label.
event_regions – Region labels to select. Empty values mean any non-empty region label.
station_region_relation – Whether to keep rows inside, outside, or on both sides of the selected region labels.
event_region_relation – Whether to keep rows inside, outside, or on both sides of the selected region labels.
station_bounds – Optional (west, east, south, north) boxes for station/event points.
event_bounds – Optional (west, east, south, north) boxes for station/event points.
station_corridor_col – Columns containing corridor labels or booleans.
event_corridor_col – Columns containing corridor labels or booleans.

Returns:

Immutable spatial selection object.

Return type:

FigureSpatialSelection

apply(df: DataFrame, *, require_match: bool = True) → tuple[DataFrame, str | None]

Apply station/event spatial filters to a dataframe.

Parameters:

df (pandas.DataFrame) – Input table with station/event region, corridor, or coordinate columns.
require_match (bool, optional) – Whether to raise if configured selectors remove every row.
df – Required function argument.
require_match – Optional function argument. Defaults to True.

Returns:

Filtered table and readable subset label.

Return type:

tuple[pandas.DataFrame, str or None]

Returns:

Return value produced by the function.

Return type:

tuple

classmethod from_inputs(spatial_selection: FigureSpatialSelection | dict[str, Any] | None = None, **overrides: Any) → FigureSpatialSelection | None

Build a spatial selector from an object, mapping, and overrides.

Parameters:

spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, Any] | None, optional) – Existing selector or dictionary of selector fields.
**overrides – Explicit keyword overrides from a plotting function.
spatial_selection – Optional function argument. Defaults to None.
overrides (Any) – Additional keyword arguments passed to the function.

Returns:

A selector when any spatial control is configured.

Return type:

FigureSpatialSelection or None

Returns:

Return value produced by the function.

Return type:

spatial_vtk.visualize.selection.FigureSpatialSelection | None

spatial_vtk.visualize.selection.apply_figure_spatial_selection(df: DataFrame, spatial_selection: FigureSpatialSelection | dict[str, Any] | None = None, *, require_match: bool = True, **kwargs: Any) → tuple[DataFrame, str | None]

Apply optional station/event region, bounds, or corridor filtering.

Parameters:

df (pandas.DataFrame) – Input table.
spatial_selection (spatial_vtk.visualize.selection.FigureSpatialSelection | dict[str, Any] | None, optional) – Selector object or dictionary.
require_match (bool, optional) – Whether an active selector should raise when it removes every row.
**kwargs – Selector fields accepted by FigureSpatialSelection.
df – Required function argument.
spatial_selection – Optional function argument. Defaults to None.
require_match – Optional function argument. Defaults to True.
kwargs (Any) – Additional keyword arguments passed to the function.

Returns:

Filtered dataframe and readable subset label.

Return type:

tuple[pandas.DataFrame, str or None]

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.visualize.selection.configured_band_options(config: SpatialVTKConfig | str | Path | None = None, *, command: str = 'visualize', fallback_df: DataFrame | None = None) → list[str]

Return configured passband tokens with dataframe-detected fallback.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | str | pathlib.Path | None, optional) – Config object, config path, or None.
command (str, optional) – Dotted command used to merge run defaults.
fallback_df (pandas.DataFrame | None, optional) – Optional table used when no passbands are configured.
config – Optional function argument. Defaults to None.
command – Optional function argument. Defaults to 'visualize'.
fallback_df – Optional function argument. Defaults to None.

Returns:

Raw passband tokens sorted by display label.

Return type:

list[str]

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.visualize.selection.filter_by_bands(df: DataFrame, bands: Iterable[object], *, band_cols: tuple[str, ...] = ('band', 'passband', 'dominant_band_label')) → DataFrame

Filter a dataframe by any supported band/passband column.

Parameters:

df (pandas.DataFrame) – Input table.
bands (Iterable) – Raw band tokens or labels to keep.
band_cols (tuple, optional) – Candidate band columns.
df – Required function argument.
bands – Required function argument.
band_cols – Optional function argument. Defaults to ('band', 'passband', 'dominant_band_label').

Returns:

Filtered table when a band column exists; otherwise the original rows.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame