Batch runners for file-based workflows

In gmsp: Ground Motion Signal Processing

knitr::opts_chunk$set(collapse = TRUE, comment = "#>",
                      eval = FALSE, purl = FALSE)

gmsp is primarily a signal-processing package. Its scientific helpers work directly on R objects:

library(gmsp)

TSL <- AT2TS(DT, units.source = "mm", Fmax = 25, output = "TSL")
PSL <- TSL2PS(TSL, xi = 0.05, output = "PSL")
IMF <- TS2IMF(TSL[ID == "AT" & OCID == "H1", .(t, s)], method = "vmd")
IM  <- getIntensity(TSL, units.source = "mm", units.target = "mm")

The batch runners are a file-based layer around those helpers. They are useful when the same operation must be repeated over a declared record set, and when the output must be reproducible from a saved JSON contract.

Direct helper or runner

| Task | Direct helper | Batch runner | |---|---|---| | Select records from a project table | selectRecords() | runSelect() | | Select spectrally compatible records from the processed pool | response-spectrum helpers | runStage0() | | Convert input motions to AT / VT / DT | AT2TS(), VT2TS(), DT2TS() | runGMSP() | | Apply a time-windowing contract | project-specific helper contract | runTrim() | | Build intrinsic mode functions | TS2IMF() | runIMF() | | Build response spectra | TSL2PS() | runPSA() | | Compose an approved processing task | processing helpers | runProcess() | | Run an approved spectral-match task | response-spectrum and match helpers | runMatch() | | Build raw QA/debug plot widgets from existing products | plotting helpers | runPlot() | | Package products for delivery | file and metadata helpers | runExport() |

The direct helper is the right interface for one record, a small table, or an interactive analysis. The runner is the right interface when inputs and outputs are files and the run must be traceable.

runStage0() and runMatch() form one workflow (spectral selection, modal shaping, and suite scaling against a target spectrum); the Spectral matching workflow vignette documents that flow end to end, including the JSON contract, the screening options, and the acceptance diagnostics.

Runner contract

Each runner reads one JSON file and resolves paths relative to root, normally the project root:

runGMSP(file = "gmsp/gmsp.json", root = ".")
runPSA(file = "gmsp/psa.json", root = ".")
runIMF(file = "gmsp/imf.json", root = ".")

The JSON names above are project-level names. The installed package also ships template files under:

system.file("scripts", package = "gmsp")

Those templates are examples of the expected contract. A project may keep its own JSON files with shorter names, as long as the selected runner receives the correct file path.

Minimal batch pattern

A batch workflow has three explicit parts:

1. A project-owned input table or selection.
2. One JSON file declaring paths and processing options.
3. One runner that writes declared products and copies the JSON used.

For example, the in-memory call:

TSL <- AT2TS(DT, units.source = "mm", Fmax = 25, output = "TSL")

becomes a batch task only when the project already has a record set on disk and a JSON file describing where to read from and where to write:

runGMSP(file = "gmsp/gmsp.json", root = ".")

Similarly, the in-memory response-spectrum call:

PSL <- TSL2PS(TSL, xi = 0.05, output = "PSL")

becomes:

runPSA(file = "gmsp/psa.json", root = ".")

Plotting boundary

runPlot() writes optional raw self-contained QA/debug widgets from existing products. It is not a publication renderer. SRK client report plots are rendered outside gmsp by the report layer from materialized gmsp CSV products.

Output convention

Runner outputs are file products. A durable output folder should contain:

• the data products written by the runner;
• metadata needed to identify the records;
• the JSON file used for the run;
• logs or audit products when they are part of that runner contract.

The runners do not replace the helper documentation. Use the helper vignettes to understand the signal-processing method, and use the runner documentation to operate the same methods reproducibly on file-based record sets.

gmsp documentation built on July 18, 2026, 5:07 p.m.