Run a gmsp batch pipeline
pipelineRunners.Rdgmsp helpers such as AT2TS(), TSL2PS(), TS2IMF() and
getIntensity() work directly on R objects. The run*() functions are
optional batch runners for the same kind of work when the inputs and outputs
are files controlled by a project JSON file.
Usage
runExport(file = file.path("gmsp", "export.json"), root = getwd())
runMatch(file = file.path("gmsp", "match.json"), root = getwd())
runPlot(file = file.path("gmsp", "plot.json"), root = getwd())
runProcess(file = file.path("gmsp", "process.json"), root = getwd())
runSelect(file = file.path("gmsp", "select.json"), root = getwd())
runStage0(file = file.path("gmsp", "match.json"), root = getwd())Details
Use the direct helpers for one record, one table, or interactive analysis. Use a runner when the same operation must be repeated over a declared selection of records and the output must be reproducible from a saved JSON contract.
Runner map
runSelect()Builds record and candidate tables from raw or processed database indexes, using the filters in the project JSON.
runStage0()Builds a spectrally compatible record selection from the processed candidate pool: scores PSA against the target compatibility band declared in the match JSON, applies optional seismological screens (
candidate.pool,candidate.filter,candidate.exclude,candidate.oneRecordPerEvent), and writes the top-stage0.Nselection topath.selectiontogether with the score table and a reusable spectra cache.runProcess()Runs an approved composed processing contract for a project record set.
runMatch()Runs an approved spectral-match contract for a selected record set. This is an advanced batch workflow, not a replacement for the response-spectrum helpers.
runPlot()Builds optional raw QA/debug HTML widgets from existing products. It is not an SRK publication renderer.
runExport()Packages existing products, metadata, and approved audit files into a delivery folder.
JSON and paths
Each runner reads one JSON file. Paths inside that JSON are resolved relative
to root, normally the project root. The JSON file is a project input, not a
global package option.
A project may keep names such as gmsp/select.json or pass an explicit
JSON path. runSelect(), runStage0(), runProcess(), runMatch(),
runPlot() and runExport() execute inside R and restore the caller's
working directory on completion or error.
Record selection
runSelect() requires owners and path.selection, plus path.database
or path.index. A processed processID also requires path.process
unless it is derived from path.database; the default is "raw".
It reads the H1 rows of the index, applies filters such as PGA,
EventMagnitude and StationVs30, and excludes the record identifiers
listed in exclude. Numeric pairs define inclusive ranges; character
values define membership. units.PGA defaults to "mm/s2" and also
accepts "g" for range conversion.
By default, oneRecordPerEvent keeps the largest PGA in each event,
breaking ties by descending station identifier and then ascending record
identifier. Setting it to FALSE retains each record. Multiple criteria
entries combine their labels for records satisfying more than one entry.
With path.matchConfig, the PGA range is derived from the MCE/MDE target
and the declared record scaling bounds; an explicit PGA range is then invalid.
On success the declared selection directory is replaced with
selection.csv, candidates.csv, selection.json and summary.json.
A directory holding any other file or directory is not cleared: the run
stops and names the entries. Empty selections and invalid
contracts signal errors. Use selectRecords() for an in-memory table.
Spectral ranking
runStage0() requires a processed processID, stage0.N >= 2,
path.selection, path.data and a database location. The target identifies
an MCE/MDE curve with distinct central, lower and upper quantiles.
shape.modalFactor.min and units.source, units.target and units.psa
are required by the shared matching contract.
The runner uses saved PSW products when declared; otherwise it calculates
spectra from canonical TSW products. It orders records by band error,
upper-tail violation and relaxed error, then by record identifier.
The output directory contains stage0.psa.csv, stage0.spectral.csv
and the selection CSV. Reruns reuse records already in stage0.psa.csv;
use a separate output directory when the target or source products change.
Errors may leave completed batches or score tables in that directory.
Composed processing
runProcess() requires processID, stages, path.selection and a
database location. stages is an ordered subset of gmsp, trim, imf,
imfTS and psa; each reads its own JSON object. The operations build
canonical signals, apply a cumulative-intensity window, decompose modes,
reconstruct selected modes, and calculate spectra using the direct helpers.
path.stage defaults to gmsp/stage. recordID and maxRecords restrict
the selection. Parallel processing defaults to TRUE, with at most four
workers unless workers is explicit.
With override = FALSE, a committed record is skipped and a new record is
appended. Conflicting keys, missing committed products and uncommitted
destination products fail before computation. Stages may replace products
created earlier in the same record invocation. Process and global index
tables are validated before publication; ordinary publication failures
restore prior metadata. An ambiguous rollback retains recovery files.
Append seals the process with a signature of its recipe: the stage
parameters, the gmsp version and the R minor series (4.6, not the patch
level). A different recipe, gmsp version or R series is rejected before any
stage runs; the error names the seal, the differing recipe leaves and the
key that accepts the change. override = TRUE cannot replace a sealed
process. A legacy contract without a signature requires its exact
append.contractMD5, an explicit assertion of recipe compatibility.
append.reseal names the signature that currently seals the process. When
the current producer computes a different signature and append.reseal
names the sealed one, the append proceeds and append.json is rewritten in
the same transaction as the tables: the new recipe becomes the seal and the
previous seal is kept under history. Reseal after verifying that both
producers yield the same products for the same records; the tool cannot
infer that. The installed file hashes and the full R version are recorded
as provenance beside the seal and are never compared. Existing process
contracts and committed record files remain unchanged during append. The
signature, lock and transaction field names remain compatible with existing
process storage. Do not run readers during metadata publication. A surviving lock
or transaction after hard termination requires operator inspection.
Spectral matching
runMatch() uses the target and parameter contract described for ranking,
plus id, path.out and either path.source or the processed database.
Folder mode reads a manifest and TSW/IMF tables under data/, plus
MasterIndex and OCIDMAP tables under metadata/. Database mode reads
the corresponding products selected by processID and path.selection.
Canonical source signals must include H1, H2 and UP components.
Modal shaping calls fitModalFactor() for each record; fitRecordFactor()
fits the completed records as a suite. At least two completed records are
required. A failed record contributes error metrics while the other records
continue. The output includes signal, spectrum, intensity and modal tables
under data/; source metadata under metadata/; and factors, scores and
compatibility diagnostics under match/.
parallel = TRUE uses forked workers on macOS and socket workers on Windows;
workers limits concurrency. Windows workers inherit the selected installed
library and working directory without repeating R startup profiles. Progress
messages are checked between batches on Windows.
plot.audit and plot.standard enable optional QA widgets
and require NGR, highcharter, htmlwidgets and Pandoc. An occupied output directory requires
override = TRUE, which replaces known products and retains unrelated files.
Failures may leave products already written.
Export
runExport() requires path.out and either a path.source product folder
or a database selected by path.database or path.records.
A source folder must contain TSW.csv and IMW.csv, either directly or
under data/; PSW.csv is optional. Database mode requires recordID or
path.selection. A processed processID must declare TSW and IMW in
its saved process contract. Raw database export reads acceleration CSV/JSON
pairs and supports only ID = "AT".
recordID, ID and DIR choose records, signal quantities and components.
The latter two default to "AT" and "H1". Export writes one signal CSV
per record, quantity and component, plus inventories and available metadata.
path.plot and path.audit may name HTML trees; duplicate relative HTML
paths within each category are rejected. An explicit path.index must
name a CSV file, rather than an index directory.
An occupied output directory is rejected unless override = TRUE.
Overriding replaces the declared products and preserves other files.
Errors can leave directories or products
already written. The input JSON is copied to runExport.json on success.
Plotting and SRK reports
runPlot() reads a path.source product folder or a selected database
process. TS and PS default to TRUE; TSI and PSI enable modal
products with an IMF column. A raw database supports only TS.
ID and DIR select quantities and components for each family; line
controls positive child and master line widths. An optional target
adds an MCE/MDE curve to PSA plots. NGR, highcharter, htmlwidgets
and Pandoc are required.
path.plot chooses the output directory; an occupied directory requires
override = TRUE. Completed widgets can remain after a later error.
runPlot() writes raw self-contained QA/debug widgets. SRK client plots are
rendered outside gmsp by the report layer from materialized gmsp CSV
products. Do not use runPlot() output as final SRK report output.
Examples
if (FALSE) { # \dontrun{
# Direct helper use for one in-memory table:
TSL <- AT2TS(DT, units.source = "mm", Fmax = 25, output = "TSL")
# Batch equivalent for a project-controlled record set:
# The JSON declares its stages, for example gmsp and psa:
runProcess(file = "gmsp/process.json", root = ".")
} # }