Batch runners for file-based workflows • gmsp

gmsp provides scientific helpers for R objects and batch runners for saved project contracts. The executable example below uses the synthetic inputs from the package’s maintained processing test. These are software demonstration data, not earthquake observations or a recommended engineering recipe.

Work directly on one record

The installed package supplies the selection, acceleration CSV and sampling interval. readAT() reads those files and constructs the time column.

library(gmsp)
library(data.table)
#> 
#> Attaching package: 'data.table'
#> The following object is masked from 'package:base':
#> 
#>     %notin%

Example <- system.file("examples/process", package = "gmsp", mustWork = TRUE)
Selection <- fread(file.path(Example, "selection.csv"))
DT <- readAT(Selection[RecordID == "R1"], path = file.path(Example, "database/records"))
TSL <- AT2TS(DT[, .(t, H1, H2, UP)], units.source = "mm", Fmax = 25, output = "TSL")
TSL[, RSN := "R1"]
PSL <- TSL2PS(TSL, xi = 0.05, Tn = c(0.1, 0.5, 1), output = "PSL")
IMF <- TS2IMF(TSL[ID == "AT" & OCID == "H1", .(t, s)], method = "vmd", K = 2)
IM <- getIntensity(TSL, units.source = "mm", units.target = "mm")
stopifnot(nrow(TSL) > 0L, nrow(PSL) > 0L, nrow(IMF) > 0L, nrow(IM) > 0L)
TSL[, .N, by = .(ID, OCID)]
#>        ID   OCID     N
#>    <char> <char> <int>
#> 1:     AT     H1   793
#> 2:     AT     H2   793
#> 3:     AT     UP   793
#> 4:     VT     H1   793
#> 5:     VT     H2   793
#> 6:     VT     UP   793
#> 7:     DT     H1   793
#> 8:     DT     H2   793
#> 9:     DT     UP   793

The fixture’s accelerations use mm/s^2 at a 0.01-second interval. The direct calls above produce time histories, spectra, intrinsic mode functions and intensity measures. Their inputs are defined in this example rather than assumed to exist in the reader’s workspace.

Run the saved processing contract

The project contract selects stages and parameters; the runner reads and writes files. Copy the included project into a new temporary directory before running it, so the installed example remains unchanged:

Root <- tempfile("gmsp-process-")
dir.create(Root)
stopifnot(file.copy(Example, Root, recursive = TRUE))
Project <- file.path(Root, "process")
Config <- jsonlite::read_json(file.path(Project, "gmsp/process.json"))
Config
#> $processID
#> [1] "TEST"
#> 
#> $stages
#> $stages[[1]]
#> [1] "gmsp"
#> 
#> $stages[[2]]
#> [1] "trim"
#> 
#> $stages[[3]]
#> [1] "imf"
#> 
#> $stages[[4]]
#> [1] "imfTS"
#> 
#> $stages[[5]]
#> [1] "psa"
#> 
#> 
#> $path
#> $path$database
#> [1] "database"
#> 
#> $path$selection
#> [1] "selection.csv"
#> 
#> $path$stage
#> [1] "stage"
#> 
#> 
#> $recordID
#> [1] "R1"
#> 
#> $parallel
#> [1] FALSE
#> 
#> $trim
#> $trim$range
#> $trim$range[[1]]
#> [1] 0.05
#> 
#> $trim$range[[2]]
#> [1] 0.95
#> 
#> 
#> $trim$taper
#> [1] 0.2
#> 
#> 
#> $imf
#> $imf$method
#> [1] "vmd"
#> 
#> $imf$k
#> [1] 2
#> 
#> 
#> $imfTS
#> $imfTS$remove
#> [1] "IMF1"
#> 
#> 
#> $psa
#> $psa$Tn
#> $psa$Tn$values
#> $psa$Tn$values[[1]]
#> [1] 0.1
#> 
#> $psa$Tn$values[[2]]
#> [1] 0.5
#> 
#> $psa$Tn$values[[3]]
#> [1] 1
runProcess(file = "gmsp/process.json", root = Project)
#> runProcess start: process=TEST stages=gmsp,trim,imf,imfTS,psa records=1 parallel=FALSE workers=1
#> process 1/1 R1
#> Process TEST committed 1 new records and skipped 0 at database/records
Products <- file.path(Project, "database/records/A/E1/S1/TEST")
list.files(Products)
#> [1] "IMF.R1.csv"  "IMFF.R1.csv" "IMW.R1.csv"  "PSW.R1.csv"  "TSW.R1.csv"
stopifnot(all(file.exists(file.path(Products,
  paste0(c("TSW", "IMW", "IMF", "IMFF", "PSW"), ".R1.csv")))))

This contract selects R1, names the process TEST, and runs gmsp, trim, imf, imfTS and psa sequentially. Paths inside it resolve against Project. The caller receives an invisible status of zero; outputs and run evidence are written to the declared project locations.

Inspect the outputs before removing this example’s temporary copy:

unlink(Root, recursive = TRUE)

For the same workflow through the installed CLI, including creation of a writable example and commands with relative paths, see CLI installation and use.

Choose a helper or runner

Task	Direct helper	Batch runner
Select records from a project table	`selectRecords()`	`runSelect()`
Rank processed candidates against a target	response-spectrum helpers	`runStage0()`
Convert acceleration to AT / VT / DT	`AT2TS()`	`runProcess()`, stage `gmsp`
Apply a time-windowing contract	cumulative-intensity window	`runProcess()`, stage `trim`
Build intrinsic mode functions	`TS2IMF()`	`runProcess()`, stage `imf`
Build response spectra	`TSL2PS()`	`runProcess()`, stage `psa`
Match a suite to its target spectrum	response-spectrum and match helpers	`runMatch()`
Build raw QA/debug widgets	plotting helpers	`runPlot()`
Package products for delivery	file and metadata helpers	`runExport()`

Use direct helpers for in-memory analysis and runners when inputs, outputs and parameters must be traceable to a saved project contract. Each runner reads one JSON file relative to root, normally the project root. The project supplies scientific targets, selection, recipe and destinations; the processing fixture above does not supply a matching target or demonstrate every runner.

runStage0() and runMatch() form the spectral selection, shaping and scaling workflow described in spectral matching. The CLI exposes the six entry points as select, rank, process, match, plot and export; all six call package helpers directly.

Paths, append and plotting

Relative paths resolve against the project root. Windows drive-absolute and UNC paths remain absolute. Parallel processing uses forked workers on macOS and socket workers on Windows, with the selected package library and project directory. Windows progress is reported between batches; worker startup does not repeat R profiles. Stochastic methods consume their random stream; this does not promise identical EEMD results across workers or platforms.

Append skips committed records with the same recipe and producer identity and refuses conflicting or incomplete destinations. Open help("pipelineRunners", package = "gmsp") for the complete contract.

runPlot() writes optional raw QA/debug widgets from existing products. The library prepares seismic data and delegates chart construction to NGR/highcharter. Client report rendering remains outside gmsp.