Batch runners for file-based workflows

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")
#> [1] "/private/var/folders/kd/rphyx8vs1t91vfqlq8mfqyqr0000gn/T/RtmpQDTODl/Rinst2bccfcd536b/gmsp/scripts"

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