Configuration API

Configuration helpers load project YAML files, resolve paths and bounds, manage default outputs, normalize labels, and keep metric settings consistent.

Package Entry Point 

Configuration helpers for paths, bounds, and public runtime defaults.

class spatial_vtk.config.MetricSettings(groups: tuple[str, ...] = ('amplitude',), metrics: tuple[str, ...] = ('PGA',), transforms: tuple[str, ...] = ('log2_residual',), components: tuple[str, ...] = ('Z',), passbands: tuple[str | tuple[float, float], ...] = (), output_mode: str = 'full', spectral: ~spatial_vtk.config.metrics.SpectralSettings = <factory>, synthetic_max_frequency_hz: float | None = None)

Resolved public metric settings.

Parameters:

groups (tuple[str, ...]) – Metric groups to calculate.
metrics (tuple[str, ...]) – Metric names to calculate.
transforms (tuple[str, ...]) – Requested comparison transforms. The output schema has room for all requested transforms.
components (tuple[str, ...]) – Waveform components or channels requested for QC and metric work.
passbands (tuple[str | tuple[float, float], ...]) – Period bands requested for QC and metric work.
output_mode (str) – One of observed, synthetic, residual, gof, or full.
spectral (spatial_vtk.config.metrics.SpectralSettings) – Spectral settings for PSA/FAS.
synthetic_max_frequency_hz (float | None) – Maximum valid synthetic frequency, if configured.

Returns:

Normalized metric settings.

Return type:

MetricSettings

class spatial_vtk.config.OutputSpec(key: str, kind: Literal['table', 'figure', 'dashboard'], filename: str, description: str = ''): One registered Spatial-VTK output artifact.

class spatial_vtk.config.SlurmSettings(python_command: str, environment_setup: tuple[str, ...] = (), partition: str = '', account: str = '', walltime: str = '12:00:00', memory: str = '8G', cpus_per_task: int = 1, max_concurrent: int = 10, job_name: str = 'svtk-job', log_dir: str = 'logs', working_directory: str = '', submit_command: str = 'sbatch', extra_directives: tuple[str, ...] = ()): User-provided SLURM resource settings.

class spatial_vtk.config.SlurmSubmission(script_path: Path, command: tuple[str, ...], stdout: str, stderr: str, returncode: int, job_id: str = ''): Result returned after submitting a SLURM script.

class spatial_vtk.config.SpatialVTKConfig(config_path: Path | None, root_dir: Path, data: dict[str, Any], run_scenario: str | None = None)

Resolved public Spatial-VTK configuration object.

Parameters:

config_path (pathlib.Path | None) – Config file path, or None for an empty config.
root_dir (pathlib.Path) – Project root used when resolving paths.
data (dict[str, Any]) – Parsed config mapping.

Returns:

Immutable config object.

Return type:

SpatialVTKConfig

activate() → SpatialVTKConfig

Make this config the in-process default for output resolution.

Parameters:: None – The config object itself supplies all values.
Returns:: This config object, so calls can be chained.
Return type:: SpatialVTKConfig
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

classmethod active() → SpatialVTKConfig

Return the active or discoverable config object.

Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

bounds_presets() → dict[str, tuple[float, float, float, float]]

Return user-defined named bounds from inline config and optional CSV.

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

property config_dir: Path: Return the directory containing the config file.

classmethod empty(*, root_dir: str | Path | None = None) → SpatialVTKConfig

Return an empty config object rooted at root_dir or the repo.

Parameters:: root_dir (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

format_template(template: str, **values: object) → str

Format a config template with this config’s directories.

Parameters:

template (str) – Required function argument.
values (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

str

Load a config object from YAML/JSON or the public search path.

Parameters:

config_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
start_dir (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
run_scenario (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.runtime.SpatialVTKConfig

path(dotted_key: str, *, must_exist: bool = False, create_parent: bool = False) → Path | None

Resolve one configured path by dotted key.

Parameters:

dotted_key (str) – Required function argument.
must_exist (bool, optional) – Optional function argument. Defaults to False.
create_parent (bool, optional) – Optional function argument. Defaults to False.

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

path_from_value(value: str | Path | None, *, must_exist: bool = False, create_parent: bool = False) → Path | None

Resolve one raw path value using this config’s directories.

Parameters:

value (str | pathlib.Path | None) – Required function argument.
must_exist (bool, optional) – Optional function argument. Defaults to False.
create_parent (bool, optional) – Optional function argument. Defaults to False.

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

path_namespace(dotted_key: str = 'paths', *, suffix: str = '_path', must_exist: bool = False) → SimpleNamespace

Return configured paths as readable namespace attributes.

Parameters:

dotted_key (str, optional) – Config section containing path values, commonly "paths".
suffix (str, optional) – Suffix added to each normalized config key. With the default, paths.observed_root becomes observed_root_path.
must_exist (bool, optional) – Raise FileNotFoundError when any resolved path does not exist.
dotted_key – Optional function argument. Defaults to 'paths'.
suffix – Optional function argument. Defaults to '_path'.
must_exist – Optional function argument. Defaults to False.

Returns:

Namespace whose attributes are resolved Path objects or None for empty path values.

Return type:

types.SimpleNamespace

Returns:

Return value produced by the function.

Return type:

types.SimpleNamespace

paths(dotted_key: str, *, must_exist: bool = False) → list[Path]

Resolve one configured scalar or list of paths by dotted key.

Parameters:

dotted_key (str) – Required function argument.
must_exist (bool, optional) – Optional function argument. Defaults to False.

Returns:

Return value produced by the function.

Return type:

list

resolve_bounds(keyword_or_extent: str | list[float] | tuple[float, ...] | None) → tuple[float, float, float, float] | None

Resolve a named bounds keyword or explicit lon/lat extent.

Parameters:: keyword_or_extent (str | list[float] | tuple[float, ...] | None) – Required function argument.
Returns:: Return value produced by the function.
Return type:: tuple[float, float, float, float] | None

run_defaults(command: str | None = None) → dict[str, Any]

Return merged run defaults for one workflow command.

Parameters:: command (str | None, optional) – Optional function argument. Defaults to None.
Returns:: Return value produced by the function.
Return type:: dict

run_scenario_names() → tuple[str, ...]

Return available top-level run scenario names.

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

section(dotted_key: str | None, default: Any = None) → Any

Return a config section by dotted key.

Parameters:

dotted_key (str | None) – Required function argument.
default (Any, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

Any

with_run_scenario(scenario_name: str) → SpatialVTKConfig

Return a new config with one named run scenario applied.

Parameters:: scenario_name (str) – Required function argument.
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

class spatial_vtk.config.SpectralSettings(periods_s: tuple[float, ...] = (), relative_amplitude_threshold: float = 0.25, min_cycles_in_record: float = 3.0, disable_relative_amplitude_qc: bool = False)

Settings that control PSA/FAS period selection and QC.

Parameters:

periods_s (tuple[float, ...]) – Requested spectral periods.
relative_amplitude_threshold (float) – Minimum fraction of the maximum spectral amplitude required for a period to be usable.
min_cycles_in_record (float) – Minimum usable cycles required to support a period.
disable_relative_amplitude_qc (bool) – Whether to disable relative spectral support checks.

Returns:

Normalized spectral settings.

Return type:

SpectralSettings

spatial_vtk.config.abbreviate_model(name: str) → str

Create a compact label from a synthetic model folder or alias.

Parameters:

name (str) – Model folder name or user-facing model alias.
name – Required function argument.

Returns:

Compact model label when known tokens are found; otherwise the input name is returned unchanged.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.active_config() → SpatialVTKConfig

Return the active Spatial-VTK config or discover one.

Parameters:: None – This function reads the in-process active config, the SVTK_CONFIG_FILE environment variable, or a standard config file in the current directory tree.
Returns:: Active or discovered config object.
Return type:: SpatialVTKConfig
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

spatial_vtk.config.apply_run_scenario(config: Mapping[str, Any], scenario_name: str | None) → dict[str, Any]

Apply one named run scenario as a top-level config overlay.

Parameters:

config (Mapping) – Parsed Spatial-VTK config mapping.
scenario_name (str | None) – Key from the top-level run_scenarios section. None returns a shallow copy of config.
config – Required function argument.
scenario_name – Required function argument.

Returns:

Config mapping with the selected scenario deep-merged over the base config.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.config.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.config.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.config.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.config.clear_active_config() → None

Clear the in-process active Spatial-VTK config.

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

spatial_vtk.config.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.config.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.config.deep_merge(base: Mapping[str, Any] | None, updates: Mapping[str, Any] | None) → dict[str, Any]

Recursively merge two dictionaries.

Parameters:

base (Optional) – Base mapping.
updates (Optional) – Values that should override base.
base – Required function argument.
updates – Required function argument.

Returns:

Merged dictionary.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.config.default_output_registry() → dict[str, dict[str, OutputSpec]]

Load the package-wide default output registry.

Parameters:: None – The registry is loaded from spatial_vtk.config.default_outputs.yaml.
Returns:: Registry grouped by tables and figures.
Return type:: dict
Returns:: Return value produced by the function.
Return type:: dict

spatial_vtk.config.display_label(value: object, label_map: dict[str, str] | None = None) → str

Return a readable label for a generic feature or metric token.

Parameters:

value (object) – Raw feature, metric, or value token.
label_map (dict[str, str] | None, optional) – Optional exact-match override labels.
value – Required function argument.
label_map – Optional function argument. Defaults to None.

Returns:

Human-readable label.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.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.config.ensure_dir(path: Path) → Path

Create one directory path when it does not already exist.

Parameters:

path (pathlib.Path) – Directory path to create.
path – Required function argument.

Returns:

The same path after ensuring it exists.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Find the active Spatial-VTK configuration file.

Parameters:

explicit_path (str | pathlib.Path | None, optional) – Direct config path. This has highest precedence.
start_dir (str | pathlib.Path | None, optional) – Directory to search for standard config filenames. Defaults to the current working directory.
explicit_path – Optional function argument. Defaults to None.
start_dir – Optional function argument. Defaults to None.

Returns:

Resolved config path, or None when no config file is available.

Return type:

pathlib.Path or None

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

spatial_vtk.config.format_run_time(seconds: float) → str

Format elapsed wall-clock seconds as a compact run-time label.

Parameters:

seconds (float) – Elapsed wall-clock seconds.
seconds – Required function argument.

Returns:

Text such as "Run time: 19.2 ms".

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.infer_output_key(function_name: str | None = None) → str

Infer an artifact key from a plotting or helper function name.

Parameters:

function_name (str | None, optional) – Optional function name. When omitted, the caller stack is inspected.
function_name – Optional function argument. Defaults to None.

Returns:

Normalized output key with prefixes such as plot_ removed.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.load_bounds_presets(csv_path: Path | None = None) → dict[str, tuple[float, float, float, float]]

Load named station-bounds presets from CSV.

Parameters:

csv_path (pathlib.Path | None, optional) – Optional override for the preset CSV path.
csv_path – Optional function argument. Defaults to None.

Returns:

Mapping from lowercase keywords to (lon_min, lon_max, lat_min, lat_max).

Return type:

dict[str, tuple[float, float, float, float]]

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.config.load_config(config_path: str | Path | None = None, *, start_dir: str | Path | None = None) → dict[str, Any]

Load one public Spatial-VTK config file.

Parameters:

config_path (str | pathlib.Path | None, optional) – Optional explicit config path.
start_dir (str | pathlib.Path | None, optional) – Optional search directory used when config_path is omitted.
config_path – Optional function argument. Defaults to None.
start_dir – Optional function argument. Defaults to None.

Returns:

Parsed config dictionary, or an empty dictionary when no config file is found.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.config.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.config.metric_group_for(metric: str) → str

Return the public metric group for one metric name.

Parameters:

metric (str) – Public metric name or legacy C-code.
metric – Required function argument.

Returns:

Metric group name.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.metric_settings_summary(settings: MetricSettings) → DataFrame

Summarize resolved metric settings as a readable table.

Parameters:

settings (spatial_vtk.config.metrics.MetricSettings) – Resolved metric settings from metrics_settings_from_config.
settings – Required function argument.

Returns:

Two-column summary table with human-readable setting names and values.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.config.metrics_settings_from_config(config: SpatialVTKConfig | None = None, *, command: str = 'metrics.calculate', overrides: dict[str, Any] | None = None) → MetricSettings

Build a metric settings object from a public config object.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Loaded Spatial-VTK config. When omitted, the active or discoverable config is used.
command (str, optional) – Dotted command key used to merge run defaults.
overrides (dict[str, Any] | None, optional) – Explicit values for this run. These override the config file and any selected run scenario.
config – Optional function argument. Defaults to None.
command – Optional function argument. Defaults to 'metrics.calculate'.
overrides – Optional function argument. Defaults to None.

Returns:

Parsed public metric settings.

Return type:

MetricSettings

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.metrics.MetricSettings

spatial_vtk.config.normalize_metric_groups(groups: tuple[str, ...] | list[str] | None) → tuple[str, ...]

Normalize metric-group selections, including the all keyword.

Parameters:

groups (tuple[str, ...] | list[str] | None) – Metric group names or all.
groups – Required function argument.

Returns:

Valid public metric group names.

Return type:

tuple[str, …]

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.config.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.config.notebook_timer(*, config: SpatialVTKConfig | None = None, default: bool = True) → Iterator[None]

Context manager that prints compact notebook run time.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to check notebooks.show_cell_timing.
default (bool, optional) – Fallback timing behavior when no config is available.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

Context manager for timing setup/bootstrap cells.

Return type:

contextlib.AbstractContextManager

Returns:

Return value produced by the function.

Return type:

Iterator

spatial_vtk.config.notebook_timing_enabled(config: SpatialVTKConfig | None = None, *, default: bool = True) → bool

Return whether notebook cell timing should be printed.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object. When omitted, the active config is used if one is available.
default (bool, optional) – Value returned when no config or setting is available.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

True when timing output should be displayed.

Return type:

bool

Returns:

Return value produced by the function.

Return type:

bool

spatial_vtk.config.output_description(key: str, *, kind: Literal['table', 'figure', 'dashboard'] | None = None) → str

Return the registered description for one output key.

Parameters:

key (str) – Required function argument.
kind (Optional, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.output_spec(key: str, *, kind: Literal['table', 'figure', 'dashboard'] | None = None) → OutputSpec

Return one output spec, falling back to a generated filename.

Parameters:

key (str) – Artifact key such as "record_coverage".
kind (Optional, optional) – Artifact kind. When omitted, the registry is searched.
key – Required function argument.
kind – Optional function argument. Defaults to None.

Returns:

Registered or generated output spec.

Return type:

OutputSpec

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.outputs.OutputSpec

spatial_vtk.config.preset_keywords(include_none: bool = False) → tuple[str, ...]

Return the available named station-bounds keywords.

Parameters:

include_none (bool, optional) – Whether to append the special "none" token.
include_none – Optional function argument. Defaults to False.

Returns:

Accepted keyword strings.

Return type:

tuple[str, …]

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.config.print_run_time(start_time: float, *, config: SpatialVTKConfig | None = None, default: bool = True) → None

Print elapsed wall-clock time when notebook timing is enabled.

Parameters:

start_time (float) – Value returned by time.perf_counter() before work started.
config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to check notebooks.show_cell_timing.
default (bool, optional) – Fallback timing behavior when no config is available.
start_time – Required function argument.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

Prints a compact run-time line when enabled.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.config.register_svtk_cell_timer(*, config: SpatialVTKConfig | None = None, default: bool = True) → None

Register automatic compact timing for later IPython code cells.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to check notebooks.show_cell_timing. When omitted, the active config is checked at the end of each cell.
default (bool, optional) – Fallback timing behavior when no config is available.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

Registers IPython pre/post cell hooks when IPython is available.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.config.register_svtk_time_magic() → None

Register the %%svtk_time IPython cell magic.

Parameters:: None – The active IPython shell is discovered automatically.
Returns:: Registers the magic when IPython is available.
Return type:: None
Returns:: Return value produced by the function.
Return type:: None

spatial_vtk.config.resolve_metric_names(metrics: tuple[str, ...] | list[str] | None, groups: tuple[str, ...] | list[str] | None = None) → tuple[str, ...]

Resolve public metric names from metric or group selections.

Parameters:

metrics (tuple[str, ...] | list[str] | None) – Explicit metric names, legacy C-codes, or all.
groups (tuple[str, ...] | list[str] | None, optional) – Metric groups used when explicit metrics are omitted.
metrics – Required function argument.
groups – Optional function argument. Defaults to None.

Returns:

Public metric names.

Return type:

tuple[str, …]

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.config.resolve_named_bounds(keyword: str | None) → tuple[float, float, float, float] | None

Resolve one named station-bounds preset.

Parameters:

keyword (str | None) – Preset keyword, or "none" / None.
keyword – Required function argument.

Returns:

(lon_min, lon_max, lat_min, lat_max), or None for "none".

Return type:

tuple[float, float, float, float] or None

Raises:

KeyError – If the requested preset keyword is unknown.

Returns:

Return value produced by the function.

Return type:

tuple[float, float, float, float] | None

Resolve an output path using explicit args, config, and defaults.

Parameters:

key (str | None, optional) – Artifact key. When omitted, a key is inferred from the caller function.
kind (Optional, optional) – Output kind: "figure", "table", or "dashboard".
outpath (str | pathlib.Path | None, optional) – Explicit output path. This always wins.
cfg (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object. When omitted, the active/discoverable config is used.
create_parent (bool, optional) – Whether to create the resolved path parent directory.
key – Optional function argument. Defaults to None.
kind – Optional function argument. Defaults to None.
outpath – Optional function argument. Defaults to None.
cfg – Optional function argument. Defaults to None.
create_parent – Optional function argument. Defaults to False.

Returns:

Resolved output path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Resolve a user-configured path or path template.

Parameters:

value (str | pathlib.Path | None) – Raw path string. None and empty strings return None.
base_dir (str | pathlib.Path | None, optional) – Directory used for relative paths and {config_dir} formatting.
root_dir (str | pathlib.Path | None, optional) – Project root used for {root_dir} formatting.
must_exist (bool, optional) – Raise FileNotFoundError when the resolved path does not exist.
create_parent (bool, optional) – Create the path’s parent directory.
value – Required function argument.
base_dir – Optional function argument. Defaults to None.
root_dir – Optional function argument. Defaults to None.
must_exist – Optional function argument. Defaults to False.
create_parent – Optional function argument. Defaults to False.

Returns:

Resolved path.

Return type:

pathlib.Path or None

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

spatial_vtk.config.resolve_run_defaults(config: Mapping[str, Any], command: str | None = None) → dict[str, Any]

Resolve defaults for one dotted workflow command.

Parameters:

config (Mapping) – Parsed Spatial-VTK config mapping.
command (str | None, optional) – Dotted command key.
config – Required function argument.
command – Optional function argument. Defaults to None.

Returns:

Merged defaults. Later command-specific blocks override broader defaults.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.config.slurm_header(settings: SlurmSettings, *, array: str | None = None) → list[str]

Build common SLURM header and environment lines.

Parameters:

settings (spatial_vtk.config.compute.SlurmSettings) – Required function argument.
array (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.config.slurm_settings_from_config(config: SpatialVTKConfig, *, section: str | None = None) → SlurmSettings

Read shared SLURM settings from a Spatial-VTK config.

compute.slurm is the shared base section. A task-specific section such as metrics.slurm or qc.slurm may override it. The older top-level slurm section remains a fallback for backward compatibility.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig) – Required function argument.
section (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.compute.SlurmSettings

spatial_vtk.config.submit_slurm_script(script_path: str | Path, settings: SlurmSettings | None = None) → SlurmSubmission

Submit a SLURM script with sbatch or settings.submit_command.

Parameters:

script_path (str | pathlib.Path) – Required function argument.
settings (spatial_vtk.config.compute.SlurmSettings | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.compute.SlurmSubmission

spatial_vtk.config.transform_columns(transforms: tuple[str, ...] | list[str] | None = None) → tuple[str, ...]

Return requested transform output columns.

Parameters:: transforms (tuple[str, ...] | list[str] | None, optional) – Optional function argument. Defaults to None.
Returns:: Return value produced by the function.
Return type:: tuple

spatial_vtk.config.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.config.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

Runtime Configuration 

Public runtime configuration loading and path resolution.

Configuration Runtime Overview 

This module gives Spatial-VTK one generic configuration surface for user projects. Config files are explicit YAML/JSON files; they define paths, run-defaults, named bounds, and workflow settings without relying on private repository defaults.

Configuration Runtime Examples 

Load a user config and resolve a configured path:: cfg = SpatialVTKConfig.from_file("spatial-vtk.yaml") metrics_dir = cfg.path("outputs.metrics", create_parent=True)

class spatial_vtk.config.runtime.SpatialVTKConfig(config_path: Path | None, root_dir: Path, data: dict[str, Any], run_scenario: str | None = None)

Resolved public Spatial-VTK configuration object.

Parameters:

config_path (pathlib.Path | None) – Config file path, or None for an empty config.
root_dir (pathlib.Path) – Project root used when resolving paths.
data (dict[str, Any]) – Parsed config mapping.

Returns:

Immutable config object.

Return type:

SpatialVTKConfig

activate() → SpatialVTKConfig

Make this config the in-process default for output resolution.

Parameters:: None – The config object itself supplies all values.
Returns:: This config object, so calls can be chained.
Return type:: SpatialVTKConfig
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

classmethod active() → SpatialVTKConfig

Return the active or discoverable config object.

Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

bounds_presets() → dict[str, tuple[float, float, float, float]]

Return user-defined named bounds from inline config and optional CSV.

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

property config_dir: Path: Return the directory containing the config file.

classmethod empty(*, root_dir: str | Path | None = None) → SpatialVTKConfig

Return an empty config object rooted at root_dir or the repo.

Parameters:: root_dir (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

format_template(template: str, **values: object) → str

Format a config template with this config’s directories.

Parameters:

template (str) – Required function argument.
values (object) – Additional keyword arguments passed to the function.

Returns:

Return value produced by the function.

Return type:

str

Load a config object from YAML/JSON or the public search path.

Parameters:

config_path (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
start_dir (str | pathlib.Path | None, optional) – Optional function argument. Defaults to None.
run_scenario (str | None, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.runtime.SpatialVTKConfig

path(dotted_key: str, *, must_exist: bool = False, create_parent: bool = False) → Path | None

Resolve one configured path by dotted key.

Parameters:

dotted_key (str) – Required function argument.
must_exist (bool, optional) – Optional function argument. Defaults to False.
create_parent (bool, optional) – Optional function argument. Defaults to False.

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

path_from_value(value: str | Path | None, *, must_exist: bool = False, create_parent: bool = False) → Path | None

Resolve one raw path value using this config’s directories.

Parameters:

value (str | pathlib.Path | None) – Required function argument.
must_exist (bool, optional) – Optional function argument. Defaults to False.
create_parent (bool, optional) – Optional function argument. Defaults to False.

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

path_namespace(dotted_key: str = 'paths', *, suffix: str = '_path', must_exist: bool = False) → SimpleNamespace

Return configured paths as readable namespace attributes.

Parameters:

dotted_key (str, optional) – Config section containing path values, commonly "paths".
suffix (str, optional) – Suffix added to each normalized config key. With the default, paths.observed_root becomes observed_root_path.
must_exist (bool, optional) – Raise FileNotFoundError when any resolved path does not exist.
dotted_key – Optional function argument. Defaults to 'paths'.
suffix – Optional function argument. Defaults to '_path'.
must_exist – Optional function argument. Defaults to False.

Returns:

Namespace whose attributes are resolved Path objects or None for empty path values.

Return type:

types.SimpleNamespace

Returns:

Return value produced by the function.

Return type:

types.SimpleNamespace

paths(dotted_key: str, *, must_exist: bool = False) → list[Path]

Resolve one configured scalar or list of paths by dotted key.

Parameters:

dotted_key (str) – Required function argument.
must_exist (bool, optional) – Optional function argument. Defaults to False.

Returns:

Return value produced by the function.

Return type:

list

resolve_bounds(keyword_or_extent: str | list[float] | tuple[float, ...] | None) → tuple[float, float, float, float] | None

Resolve a named bounds keyword or explicit lon/lat extent.

Parameters:: keyword_or_extent (str | list[float] | tuple[float, ...] | None) – Required function argument.
Returns:: Return value produced by the function.
Return type:: tuple[float, float, float, float] | None

run_defaults(command: str | None = None) → dict[str, Any]

Return merged run defaults for one workflow command.

Parameters:: command (str | None, optional) – Optional function argument. Defaults to None.
Returns:: Return value produced by the function.
Return type:: dict

run_scenario_names() → tuple[str, ...]

Return available top-level run scenario names.

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

section(dotted_key: str | None, default: Any = None) → Any

Return a config section by dotted key.

Parameters:

dotted_key (str | None) – Required function argument.
default (Any, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

Any

with_run_scenario(scenario_name: str) → SpatialVTKConfig

Return a new config with one named run scenario applied.

Parameters:: scenario_name (str) – Required function argument.
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

spatial_vtk.config.runtime.active_config() → SpatialVTKConfig

Return the active Spatial-VTK config or discover one.

Parameters:: None – This function reads the in-process active config, the SVTK_CONFIG_FILE environment variable, or a standard config file in the current directory tree.
Returns:: Active or discovered config object.
Return type:: SpatialVTKConfig
Returns:: Return value produced by the function.
Return type:: spatial_vtk.config.runtime.SpatialVTKConfig

spatial_vtk.config.runtime.apply_run_scenario(config: Mapping[str, Any], scenario_name: str | None) → dict[str, Any]

Apply one named run scenario as a top-level config overlay.

Parameters:

config (Mapping) – Parsed Spatial-VTK config mapping.
scenario_name (str | None) – Key from the top-level run_scenarios section. None returns a shallow copy of config.
config – Required function argument.
scenario_name – Required function argument.

Returns:

Config mapping with the selected scenario deep-merged over the base config.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.config.runtime.clear_active_config() → None

Clear the in-process active Spatial-VTK config.

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

spatial_vtk.config.runtime.command_chain(command: str | None) → list[str]

Return dotted command prefixes from broad to specific.

Parameters:

command (str | None) – Command key such as "metrics.calculate.batch".
command – Required function argument.

Returns:

["metrics", "metrics.calculate", "metrics.calculate.batch"].

Return type:

list[str]

Returns:

Return value produced by the function.

Return type:

list

spatial_vtk.config.runtime.deep_merge(base: Mapping[str, Any] | None, updates: Mapping[str, Any] | None) → dict[str, Any]

Recursively merge two dictionaries.

Parameters:

base (Optional) – Base mapping.
updates (Optional) – Values that should override base.
base – Required function argument.
updates – Required function argument.

Returns:

Merged dictionary.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

Find the active Spatial-VTK configuration file.

Parameters:

explicit_path (str | pathlib.Path | None, optional) – Direct config path. This has highest precedence.
start_dir (str | pathlib.Path | None, optional) – Directory to search for standard config filenames. Defaults to the current working directory.
explicit_path – Optional function argument. Defaults to None.
start_dir – Optional function argument. Defaults to None.

Returns:

Resolved config path, or None when no config file is available.

Return type:

pathlib.Path or None

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

spatial_vtk.config.runtime.format_template(template: str, *, root_dir: str | Path, config_dir: str | Path, **values: object) → str

Format one config template with standard Spatial-VTK variables.

Parameters:

template (str) – Template string.
root_dir (str | pathlib.Path) – Standard project and config directories.
config_dir (str | pathlib.Path) – Standard project and config directories.
values (object) – Additional formatting values.
template – Required function argument.
root_dir – Required function argument.
config_dir – Required function argument.
values – Additional keyword arguments passed to the function.

Returns:

Formatted template.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.runtime.get_dotted(mapping: Mapping[str, Any], dotted_key: str | None, default: Any = None) → Any

Read one dotted key from a nested mapping.

Parameters:

mapping (Mapping) – Source mapping.
dotted_key (str | None) – Key such as "outputs.metrics".
default (Any, optional) – Returned when any key part is missing.
mapping – Required function argument.
dotted_key – Required function argument.
default – Optional function argument. Defaults to None.

Returns:

Found value or default.

Return type:

object

Returns:

Return value produced by the function.

Return type:

Any

spatial_vtk.config.runtime.load_config(config_path: str | Path | None = None, *, start_dir: str | Path | None = None) → dict[str, Any]

Load one public Spatial-VTK config file.

Parameters:

config_path (str | pathlib.Path | None, optional) – Optional explicit config path.
start_dir (str | pathlib.Path | None, optional) – Optional search directory used when config_path is omitted.
config_path – Optional function argument. Defaults to None.
start_dir – Optional function argument. Defaults to None.

Returns:

Parsed config dictionary, or an empty dictionary when no config file is found.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

Resolve a user-configured path or path template.

Parameters:

value (str | pathlib.Path | None) – Raw path string. None and empty strings return None.
base_dir (str | pathlib.Path | None, optional) – Directory used for relative paths and {config_dir} formatting.
root_dir (str | pathlib.Path | None, optional) – Project root used for {root_dir} formatting.
must_exist (bool, optional) – Raise FileNotFoundError when the resolved path does not exist.
create_parent (bool, optional) – Create the path’s parent directory.
value – Required function argument.
base_dir – Optional function argument. Defaults to None.
root_dir – Optional function argument. Defaults to None.
must_exist – Optional function argument. Defaults to False.
create_parent – Optional function argument. Defaults to False.

Returns:

Resolved path.

Return type:

pathlib.Path or None

Returns:

Return value produced by the function.

Return type:

pathlib.Path | None

spatial_vtk.config.runtime.resolve_run_defaults(config: Mapping[str, Any], command: str | None = None) → dict[str, Any]

Resolve defaults for one dotted workflow command.

Parameters:

config (Mapping) – Parsed Spatial-VTK config mapping.
command (str | None, optional) – Dotted command key.
config – Required function argument.
command – Optional function argument. Defaults to None.

Returns:

Merged defaults. Later command-specific blocks override broader defaults.

Return type:

dict

Returns:

Return value produced by the function.

Return type:

dict

Paths and Outputs 

Centralized filesystem locations for spatial-vtk.

This module defines repository-relative input and output paths that are shared across the packaged workflow families.

Examples

>>> from spatial_vtk.config.paths import ROOT_DIR, default_events_csv
>>> ROOT_DIR.exists()
True

spatial_vtk.config.paths.default_event_patch_csv() → Path | None

Return the optional event-region patch CSV when present.

Returns:: Existing patch CSV path or None.
Return type:: pathlib.Path or None
Returns:: Return value produced by the function.
Return type:: Optional

spatial_vtk.config.paths.default_events_csv(name: str = 'salvus_events_m3above.csv') → Path

Return the default event catalog path.

Parameters:

name (str, optional) – Preferred event-catalog filename under inputs/metadata.
name – Optional function argument. Defaults to 'salvus_events_m3above.csv'.

Returns:

Existing event catalog path, falling back to all_events.csv.

Return type:

pathlib.Path

Raises:

FileNotFoundError – If neither the preferred catalog nor the fallback exists.

Returns:

Return value produced by the function.

Return type:

pathlib.Path

spatial_vtk.config.paths.default_geology_csv() → Path | None

Return the default station geology metadata CSV when present.

Returns:: Existing geology CSV path or None.
Return type:: pathlib.Path or None
Returns:: Return value produced by the function.
Return type:: Optional

spatial_vtk.config.paths.default_regions_geojson() → Path | None

Return the regional polygons GeoJSON when present.

Returns:: Existing regions GeoJSON path or None.
Return type:: pathlib.Path or None
Returns:: Return value produced by the function.
Return type:: Optional

spatial_vtk.config.paths.default_subbasins_geojson() → Path | None

Return the subbasin polygons path when available.

Returns:: Existing subbasins GeoJSON path or None.
Return type:: pathlib.Path or None
Returns:: Return value produced by the function.
Return type:: Optional

spatial_vtk.config.paths.ensure_dir(path: Path) → Path

Create one directory path when it does not already exist.

Parameters:

path (pathlib.Path) – Directory path to create.
path – Required function argument.

Returns:

The same path after ensuring it exists.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Default output registry and path resolution helpers.

Configuration Outputs Overview 

This module resolves standard table and figure output paths from three places: explicit function arguments, the active Spatial-VTK config, and package default filenames stored in default_outputs.yaml.

Configuration Outputs Examples 

Resolve a figure path from the active config:: path = resolve_output_path("record_coverage", kind="figure")

class spatial_vtk.config.outputs.OutputSpec(key: str, kind: Literal['table', 'figure', 'dashboard'], filename: str, description: str = ''): One registered Spatial-VTK output artifact.

spatial_vtk.config.outputs.default_output_registry() → dict[str, dict[str, OutputSpec]]

Load the package-wide default output registry.

Parameters:: None – The registry is loaded from spatial_vtk.config.default_outputs.yaml.
Returns:: Registry grouped by tables and figures.
Return type:: dict
Returns:: Return value produced by the function.
Return type:: dict

spatial_vtk.config.outputs.infer_output_key(function_name: str | None = None) → str

Infer an artifact key from a plotting or helper function name.

Parameters:

function_name (str | None, optional) – Optional function name. When omitted, the caller stack is inspected.
function_name – Optional function argument. Defaults to None.

Returns:

Normalized output key with prefixes such as plot_ removed.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.outputs.output_description(key: str, *, kind: Literal['table', 'figure', 'dashboard'] | None = None) → str

Return the registered description for one output key.

Parameters:

key (str) – Required function argument.
kind (Optional, optional) – Optional function argument. Defaults to None.

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.outputs.output_spec(key: str, *, kind: Literal['table', 'figure', 'dashboard'] | None = None) → OutputSpec

Return one output spec, falling back to a generated filename.

Parameters:

key (str) – Artifact key such as "record_coverage".
kind (Optional, optional) – Artifact kind. When omitted, the registry is searched.
key – Required function argument.
kind – Optional function argument. Defaults to None.

Returns:

Registered or generated output spec.

Return type:

OutputSpec

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.outputs.OutputSpec

Resolve an output path using explicit args, config, and defaults.

Parameters:

key (str | None, optional) – Artifact key. When omitted, a key is inferred from the caller function.
kind (Optional, optional) – Output kind: "figure", "table", or "dashboard".
outpath (str | pathlib.Path | None, optional) – Explicit output path. This always wins.
cfg (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object. When omitted, the active/discoverable config is used.
create_parent (bool, optional) – Whether to create the resolved path parent directory.
key – Optional function argument. Defaults to None.
kind – Optional function argument. Defaults to None.
outpath – Optional function argument. Defaults to None.
cfg – Optional function argument. Defaults to None.
create_parent – Optional function argument. Defaults to False.

Returns:

Resolved output path.

Return type:

pathlib.Path

Returns:

Return value produced by the function.

Return type:

pathlib.Path

Bounds 

User-defined named station-bounds presets.

Spatial-VTK does not ship project-specific map-bound keywords. If you want short names such as "my_region" for map windows or station filters, define them in a CSV file and point the configuration at that file.

Examples

>>> from spatial_vtk.config.bounds import preset_keywords
>>> isinstance(preset_keywords(), tuple)
True

spatial_vtk.config.bounds.load_bounds_presets(csv_path: Path | None = None) → dict[str, tuple[float, float, float, float]]

Load named station-bounds presets from CSV.

Parameters:

csv_path (pathlib.Path | None, optional) – Optional override for the preset CSV path.
csv_path – Optional function argument. Defaults to None.

Returns:

Mapping from lowercase keywords to (lon_min, lon_max, lat_min, lat_max).

Return type:

dict[str, tuple[float, float, float, float]]

Returns:

Return value produced by the function.

Return type:

dict

spatial_vtk.config.bounds.preset_keywords(include_none: bool = False) → tuple[str, ...]

Return the available named station-bounds keywords.

Parameters:

include_none (bool, optional) – Whether to append the special "none" token.
include_none – Optional function argument. Defaults to False.

Returns:

Accepted keyword strings.

Return type:

tuple[str, …]

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.config.bounds.resolve_named_bounds(keyword: str | None) → tuple[float, float, float, float] | None

Resolve one named station-bounds preset.

Parameters:

keyword (str | None) – Preset keyword, or "none" / None.
keyword – Required function argument.

Returns:

(lon_min, lon_max, lat_min, lat_max), or None for "none".

Return type:

tuple[float, float, float, float] or None

Raises:

KeyError – If the requested preset keyword is unknown.

Returns:

Return value produced by the function.

Return type:

tuple[float, float, float, float] | None

Metrics 

Public metric configuration parsing helpers.

Configuration Metrics Overview 

This module normalizes the metric-related portions of a Spatial-VTK config file into explicit public settings used by metric planning, QC, and workflow orchestration.

Configuration Metrics Examples 

Load metric settings from a config object:: settings = metrics_settings_from_config(config)

class spatial_vtk.config.metrics.MetricSettings(groups: tuple[str, ...] = ('amplitude',), metrics: tuple[str, ...] = ('PGA',), transforms: tuple[str, ...] = ('log2_residual',), components: tuple[str, ...] = ('Z',), passbands: tuple[str | tuple[float, float], ...] = (), output_mode: str = 'full', spectral: ~spatial_vtk.config.metrics.SpectralSettings = <factory>, synthetic_max_frequency_hz: float | None = None)

Resolved public metric settings.

Parameters:

groups (tuple[str, ...]) – Metric groups to calculate.
metrics (tuple[str, ...]) – Metric names to calculate.
transforms (tuple[str, ...]) – Requested comparison transforms. The output schema has room for all requested transforms.
components (tuple[str, ...]) – Waveform components or channels requested for QC and metric work.
passbands (tuple[str | tuple[float, float], ...]) – Period bands requested for QC and metric work.
output_mode (str) – One of observed, synthetic, residual, gof, or full.
spectral (spatial_vtk.config.metrics.SpectralSettings) – Spectral settings for PSA/FAS.
synthetic_max_frequency_hz (float | None) – Maximum valid synthetic frequency, if configured.

Returns:

Normalized metric settings.

Return type:

MetricSettings

class spatial_vtk.config.metrics.SpectralSettings(periods_s: tuple[float, ...] = (), relative_amplitude_threshold: float = 0.25, min_cycles_in_record: float = 3.0, disable_relative_amplitude_qc: bool = False)

Settings that control PSA/FAS period selection and QC.

Parameters:

periods_s (tuple[float, ...]) – Requested spectral periods.
relative_amplitude_threshold (float) – Minimum fraction of the maximum spectral amplitude required for a period to be usable.
min_cycles_in_record (float) – Minimum usable cycles required to support a period.
disable_relative_amplitude_qc (bool) – Whether to disable relative spectral support checks.

Returns:

Normalized spectral settings.

Return type:

SpectralSettings

spatial_vtk.config.metrics.metric_settings_summary(settings: MetricSettings) → DataFrame

Summarize resolved metric settings as a readable table.

Parameters:

settings (spatial_vtk.config.metrics.MetricSettings) – Resolved metric settings from metrics_settings_from_config.
settings – Required function argument.

Returns:

Two-column summary table with human-readable setting names and values.

Return type:

pandas.DataFrame

Returns:

Return value produced by the function.

Return type:

pandas.DataFrame

spatial_vtk.config.metrics.metrics_settings_from_config(config: SpatialVTKConfig | None = None, *, command: str = 'metrics.calculate', overrides: dict[str, Any] | None = None) → MetricSettings

Build a metric settings object from a public config object.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Loaded Spatial-VTK config. When omitted, the active or discoverable config is used.
command (str, optional) – Dotted command key used to merge run defaults.
overrides (dict[str, Any] | None, optional) – Explicit values for this run. These override the config file and any selected run scenario.
config – Optional function argument. Defaults to None.
command – Optional function argument. Defaults to 'metrics.calculate'.
overrides – Optional function argument. Defaults to None.

Returns:

Parsed public metric settings.

Return type:

MetricSettings

Returns:

Return value produced by the function.

Return type:

spatial_vtk.config.metrics.MetricSettings

spatial_vtk.config.metrics.transform_columns(transforms: tuple[str, ...] | list[str] | None = None) → tuple[str, ...]

Return requested transform output columns.

Parameters:: transforms (tuple[str, ...] | list[str] | None, optional) – Optional function argument. Defaults to None.
Returns:: Return value produced by the function.
Return type:: tuple

Public metric catalog used by config parsing and workflow planning.

Configuration Metric Catalog Overview 

This module defines the public metric groups, metric names, and legacy C-code aliases that Spatial-VTK accepts in configuration files.

Configuration Metric Catalog Examples 

Resolve all amplitude metrics:: resolve_metric_names(metrics=None, groups=("amplitude",))

spatial_vtk.config.metric_catalog.metric_group_for(metric: str) → str

Return the public metric group for one metric name.

Parameters:

metric (str) – Public metric name or legacy C-code.
metric – Required function argument.

Returns:

Metric group name.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.metric_catalog.normalize_metric_groups(groups: tuple[str, ...] | list[str] | None) → tuple[str, ...]

Normalize metric-group selections, including the all keyword.

Parameters:

groups (tuple[str, ...] | list[str] | None) – Metric group names or all.
groups – Required function argument.

Returns:

Valid public metric group names.

Return type:

tuple[str, …]

Returns:

Return value produced by the function.

Return type:

tuple

spatial_vtk.config.metric_catalog.normalize_metric_name(metric: str) → str

Return the public name for one metric or legacy C-code.

Parameters:

metric (str) – Public metric name or legacy C-code.
metric – Required function argument.

Returns:

Public metric name.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.metric_catalog.resolve_metric_names(metrics: tuple[str, ...] | list[str] | None, groups: tuple[str, ...] | list[str] | None = None) → tuple[str, ...]

Resolve public metric names from metric or group selections.

Parameters:

metrics (tuple[str, ...] | list[str] | None) – Explicit metric names, legacy C-codes, or all.
groups (tuple[str, ...] | list[str] | None, optional) – Metric groups used when explicit metrics are omitted.
metrics – Required function argument.
groups – Optional function argument. Defaults to None.

Returns:

Public metric names.

Return type:

tuple[str, …]

Returns:

Return value produced by the function.

Return type:

tuple

Labels and Naming 

Public display labels for metrics, transforms, and passbands.

Configuration Labels Overview 

This module keeps user-facing figures, maps, dashboards, and future CLI output from showing internal variable names. It maps public metric identifiers, legacy metric aliases, value/transform columns, and passband tokens to readable labels.

Configuration Labels Examples 

Use the helpers wherever text will be shown to a user:: metric_display_name("C5") value_column_display_name("log2_residual") band_display_label("1-3s")

spatial_vtk.config.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.config.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.config.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.config.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.config.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.config.labels.display_label(value: object, label_map: dict[str, str] | None = None) → str

Return a readable label for a generic feature or metric token.

Parameters:

value (object) – Raw feature, metric, or value token.
label_map (dict[str, str] | None, optional) – Optional exact-match override labels.
value – Required function argument.
label_map – Optional function argument. Defaults to None.

Returns:

Human-readable label.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.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.config.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.config.labels.model_display_name(model: object) → str

Return a human-readable model label.

Parameters:

model (object) – Raw model token from a metric table or configuration file.
model – Required function argument.

Returns:

Label suitable for legends, titles, dashboards, and tables.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.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.config.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.config.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

Naming helpers for public-facing model and dataset labels.

spatial_vtk.config.naming.abbreviate_model(name: str) → str

Create a compact label from a synthetic model folder or alias.

Parameters:

name (str) – Model folder name or user-facing model alias.
name – Required function argument.

Returns:

Compact model label when known tokens are found; otherwise the input name is returned unchanged.

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

Notebook Helpers 

Notebook display helpers.

Configuration Notebook Overview 

This module registers lightweight IPython helpers used by the public tutorial notebooks. The timing helpers print only wall-clock run time and can be toggled from the active Spatial-VTK configuration.

Configuration Notebook Examples 

Register automatic timing for later notebook cells:: from spatial_vtk.config.notebook import register_svtk_cell_timer register_svtk_cell_timer()

spatial_vtk.config.notebook.format_run_time(seconds: float) → str

Format elapsed wall-clock seconds as a compact run-time label.

Parameters:

seconds (float) – Elapsed wall-clock seconds.
seconds – Required function argument.

Returns:

Text such as "Run time: 19.2 ms".

Return type:

str

Returns:

Return value produced by the function.

Return type:

str

spatial_vtk.config.notebook.notebook_timer(*, config: SpatialVTKConfig | None = None, default: bool = True) → Iterator[None]

Context manager that prints compact notebook run time.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to check notebooks.show_cell_timing.
default (bool, optional) – Fallback timing behavior when no config is available.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

Context manager for timing setup/bootstrap cells.

Return type:

contextlib.AbstractContextManager

Returns:

Return value produced by the function.

Return type:

Iterator

spatial_vtk.config.notebook.notebook_timing_enabled(config: SpatialVTKConfig | None = None, *, default: bool = True) → bool

Return whether notebook cell timing should be printed.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object. When omitted, the active config is used if one is available.
default (bool, optional) – Value returned when no config or setting is available.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

True when timing output should be displayed.

Return type:

bool

Returns:

Return value produced by the function.

Return type:

bool

spatial_vtk.config.notebook.print_run_time(start_time: float, *, config: SpatialVTKConfig | None = None, default: bool = True) → None

Print elapsed wall-clock time when notebook timing is enabled.

Parameters:

start_time (float) – Value returned by time.perf_counter() before work started.
config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to check notebooks.show_cell_timing.
default (bool, optional) – Fallback timing behavior when no config is available.
start_time – Required function argument.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

Prints a compact run-time line when enabled.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.config.notebook.register_svtk_cell_timer(*, config: SpatialVTKConfig | None = None, default: bool = True) → None

Register automatic compact timing for later IPython code cells.

Parameters:

config (spatial_vtk.config.runtime.SpatialVTKConfig | None, optional) – Optional config object used to check notebooks.show_cell_timing. When omitted, the active config is checked at the end of each cell.
default (bool, optional) – Fallback timing behavior when no config is available.
config – Optional function argument. Defaults to None.
default – Optional function argument. Defaults to True.

Returns:

Registers IPython pre/post cell hooks when IPython is available.

Return type:

None

Returns:

Return value produced by the function.

Return type:

None

spatial_vtk.config.notebook.register_svtk_time_magic() → None

Register the %%svtk_time IPython cell magic.

Parameters:: None – The active IPython shell is discovered automatically.
Returns:: Registers the magic when IPython is available.
Return type:: None
Returns:: Return value produced by the function.
Return type:: None