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