---
title: "Batch runners for file-based workflows"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Batch runners for file-based workflows}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
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:

```{r direct-helper}
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:

```{r runner-call}
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:

```{r template-location, eval = TRUE}
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:

```{r helper-example}
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:

```{r batch-example}
runGMSP(file = "gmsp/gmsp.json", root = ".")
```

Similarly, the in-memory response-spectrum call:

```{r helper-spectrum}
PSL <- TSL2PS(TSL, xi = 0.05, output = "PSL")
```

becomes:

```{r batch-spectrum}
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.