CLI installation and use • gmsp

The gmsp command calls the public API of the installed R package. The CLI interprets arguments and reports failures; the library owns record selection, signal processing, matching and products. Runtime use needs only the installed package.

Requirements

Install R (at least 4.1.0) in a location supported by the installer: the current Framework or unversioned Homebrew installation on macOS, a system installation on Linux, or the current R-core registry entry on Windows. The command and the installed gmsp package share one version; gmsp --version reports the package version and the CLI in use. Matching requires Matrix and osqp. Plotting, including matching QA, requires NGR, highcharter, htmlwidgets and Pandoc. Native Windows installation uses PowerShell 5.1 or later, without Bash or WSL.

The installer installs missing declared R package requirements and verifies the exports the CLI uses. R, Pandoc and other operating-system tools must already be available when the operation needs them; the installer never installs R. Pandoc is an optional installer prerequisite but is required for the plotting operations. Receipt handling requires jsonlite visible to R.

Install from this source distribution

Run the following example from the distribution root, which contains lib/, cli/ and install/. Stay in that directory for every shell and R command on this page’s example. The installer installs the complete R package and CLI and creates gmsp-example/cli; it is an output destination, not a pre-existing input. The R package is installed into your default user library (R_LIBS_USER), resolved by R itself. --library DIR on Unix or -Library DIR on Windows selects another library, which must remain visible through normal R_LIBS/R_LIBS_USER in later sessions. Use a fresh gmsp-example directory for this example.

On macOS, in Bash:

bash install/install.sh --prefix gmsp-example/cli
gmsp-example/cli/bin/gmsp --version
gmsp-example/cli/bin/gmsp --help

On Windows, in native PowerShell:

powershell -ExecutionPolicy Bypass -File install\install.ps1 -Prefix gmsp-example\cli
& .\gmsp-example\cli\bin\gmsp.ps1 --version
& .\gmsp-example\cli\bin\gmsp.ps1 --help

These writable local destinations do not require administrator privileges. Relative installer paths resolve against the calling directory; absolute paths are also accepted. An explicit path does not have to be absolute.

Without --tarball the installer builds the package from lib/ without manuals or vignettes, even when the installed version matches or exceeds the source. To select a package-maintenance archive with those documents instead, pass --tarball FILE (Windows: -Tarball FILE), keeping the adjacent .rds record; the installer verifies the archive hash. --dependency FILE / -Dependency supplies recorded private dependency archives. Replacing the package or CLI asks once before building or installing; --yes / -Yes skips that question. --check / -Check validates prerequisites and destinations without installing. There are no public component-selection or build-directory options; package maintenance and documentation building use the separate build.R workflow.

For a permanent installation, select the CLI prefix you intend to keep; the R library defaults to your user library unless explicitly selected. On macOS a protected prefix such as /usr/local requires invoking the installer through sudo bash install/install.sh; R work runs as the invoking user and only the prefix files are written as root. The macOS/Linux installer does not change shell profiles or PATH: add the prefix’s bin directory to PATH if you want to call gmsp by name from other directories. The Windows installer adds that directory to the user PATH unless -NoPath; it does not change the PowerShell execution policy.

Run the included processing example

The package includes the synthetic records and JSON contract from its maintained processing test. They demonstrate the interface; they are not recorded earthquakes or a recommended processing recipe. In R, with the same working directory, copy them into the writable example:

stopifnot(!dir.exists("gmsp-example/process"))
stopifnot(file.copy(system.file("examples/process", package = "gmsp", mustWork = TRUE),
                    "gmsp-example", recursive = TRUE))

On macOS:

gmsp-example/cli/bin/gmsp process gmsp/process.json --root gmsp-example/process
gmsp-example/cli/bin/gmsp select --help

On Windows:

& .\gmsp-example\cli\bin\gmsp.ps1 process gmsp/process.json --root gmsp-example/process
& .\gmsp-example\cli\bin\gmsp.ps1 select --help

The supplied contract selects record R1, uses processID = "TEST" and runs gmsp, trim, imf, imfTS and psa. Products are written under gmsp-example/process/database/records/A/E1/S1/TEST; the process index is under gmsp-example/process/database/process/TEST. The command reports one committed record. An unchanged rerun skips that record.

Commands and project contracts

Command	Installed public API	Default project contract
`select`	`runSelect()`	`gmsp/select.json`
`rank`	`runStage0()`	`gmsp/match.json`
`process`	`runProcess()`	`gmsp/process.json`
`match`	`runMatch()`	`gmsp/match.json`
`plot`	`runPlot()`	`gmsp/plot.json`
`export`	`runExport()`	`gmsp/export.json`

The current directory is the default project root. --root DIR must name an existing directory; a relative DIR is resolved from the calling directory. CONFIG and relative paths inside it resolve from that project root, including when CONFIG is absolute or stored in a subdirectory. Absolute paths retain their destinations; ~ is expanded. On Windows this includes drive-absolute and UNC paths. The root selects the base of relative paths; it does not confine writes to that directory.

Use gmsp <step> [CONFIG] [--root DIR], with the step first and the root value as a separate argument. There is no --dry-run or general output-directory flag. Destinations and override belong to CONFIG. The CLI reports progress and errors; a completed runner returns status 0, while an uncaught error returns 1. It does not print a JSON result. The R runners return an invisible integer status and restore the caller’s directory.

Other operations require their own project inputs and JSON; the processing example does not supply a matching target. See batch runners and spectral matching, or open help("pipelineRunners", package = "gmsp") in R for the reference contract.

Inputs, destinations and reruns

Database mode uses path.database to derive records/, index/ and process/; explicit path.records, path.index and path.process override those locations. The actual selected paths can be outside the project. No runner automatically moves products to data/gmsp: project contracts choose their destinations. The following paths are CONFIG fields, not CLI flags.

Operation	Inputs	Materialized result and rerun behavior
`select`	Raw or processed indexes, `owners` and filter criteria; optional `path.matchConfig` derives the PGA range from a declared target.	`path.selection` is an output directory containing `selection.csv`, `candidates.csv`, `selection.json` and `summary.json`. A rerun replaces these four products; any other entry prevents clearing the directory.
`rank`	Processed database, `processID`, target under `path.data`, `stage0.N` and optional candidate screens. It reads saved PSW or derives spectra from TSW.	`path.selection` is the output CSV, or `selection.csv` inside an already existing directory. Its parent also receives `stage0.psa.csv` and `stage0.spectral.csv`. The PSA cache is appended by record; scores and selection are rewritten. Use another destination if target or source products change.
`process`	`path.selection` CSV or existing selection directory, `processID`, declared stages/recipe, and database records/indexes.	Writes per-record products to `path.records`, process tables/contracts to `path.process`, global tables to `path.index`, and work/evidence to `path.stage` (default `gmsp/stage`). Details below.
`match`	A processed database with `processID` and optional selection, or a `path.source` folder with `data/manifest.csv`, `TSW.csv`, `IMF.csv` and source metadata; target under `path.data`, `id`, units and shape parameters.	Writes directly under `path.out`: `data/`, `metadata/`, `match/`, and optional QA under `audit/` and `plot/`. It does not append `id` to `path.out`. An occupied destination requires `override: true`; files written by this run replace their names, without clearing unrelated or stale files.
`plot`	Existing folder products from `path.source`, or database products selected by `processID` and `path.selection`/`recordID`; chosen TS/PS/modal families and optional target.	HTML widgets and `runPlot.json` go to `path.plot`. If omitted, the destination is `path.source/plot` in folder mode or `gmsp/plot` otherwise. An occupied destination requires `override: true`; the output tree is not cleared.
`export`	Folder TSW/IMW and optional PSW, or selected raw/processed database products; `recordID`, `ID`, `DIR`, and optional metadata/HTML inputs.	`path.out` receives signal CSVs, `files.csv`, `unique.csv`, available IMW/PSW, `metadata/`, optional `plot/` and `audit/`, and `runExport.json`. An occupied destination requires `override: true`; the output tree is not cleared.

For a new rank destination, give an explicit CSV name such as data/gmsp/selection/selection.csv; a nonexistent path is treated as a filename, not as a directory to receive selection.csv. In rank, path.selection is an output, whereas candidate.pool optionally restricts the input pool. In process, match, plot and export, a supplied path.selection is an input. In export, an explicitly supplied path.index names a MasterIndex CSV file, rather than a database index directory.

Targets are read from MCETable.Rds for MCE or UHSTable.Rds for MDE in the declared path.data. Their selectors and units come from the project contract; these operations do not produce the Hazard inputs. GMSP consumes those tables, then materializes its own products for the report layer to read.

match writes signals/spectra/intensities and modal QA as data/TSW.csv, PSW.csv, IMW.csv, ITS.csv and IPSA.csv, with data/manifest.csv listing completed records. metadata/ holds the selection and provenance; match/ holds the target, factors, scores and compatibility tables. Individual record failures can appear in match/metrics.csv while the suite completes with status 0. Compare the manifest with the requested selection and inspect metrics; status 0 alone does not certify that every requested record completed.

Ranking, matching, plotting and export can leave directories, cached batches or completed products after a later failure. For matching, plotting and export, override permits replacement of output files; it does not provide rollback or clear the directory. Changing the root does not alter those existing behaviors.

Processing writes to the declared database

process intentionally writes the processed population into the database:

path.records/<OwnerID>/<EventID>/<StationID>/<processID>/ receives <product>.<RecordID>.csv for the selected stages, such as TSW, IMW, IMF, IMFF and PSW.
path.process/<processID>/ holds process tables such as MasterIndex.csv and IntensityTable.csv, the saved process.json and the append seal when applicable. Corresponding global tables are published under path.index.
path.stage/<processID>.selection/selection.csv records the processed selection. path.stage/<processID>.process/ keeps timestamped run evidence and the latest runProcess.json; the gmsp stage also uses its own work directory under path.stage.

With override: false, committed records are skipped and compatible new records are appended. Conflicting or incomplete destinations stop processing. For a process that is not append-pinned, override: true permits replacing declared products; it cannot replace an append-pinned process. Stages may also replace products produced earlier in the same record invocation. Metadata publication restores prior metadata after ordinary failures; ambiguous recovery retains evidence and needs inspection. Readers must not run during metadata publication. The recipe and producer seal rules follow below.

processID, such as F25 or S25, identifies saved products; its spelling does not select a numerical recipe. Products saved by earlier producers can be consumed by selection, ranking, matching, plotting and export. Processing append checks the recipe and producer seal of the process: a process sealed by another producer or another gmsp release is extended only after append.reseal names its current seal, which the rejection message reports together with the differing recipe leaves. Installation does not alter projects.

Windows drive-absolute and UNC paths are supported. Parallel processing uses socket workers on Windows and forked workers on macOS. The project contract controls the worker count. The library prepares seismic plot data and delegates chart construction to NGR/highcharter; report publication belongs to the report layer.

Update and remove the example installation

An update replaces the package and the CLI through the receipt. By default it rebuilds from this source; --tarball FILE selects a recorded package archive with its adjacent .tar.gz.rds record. On macOS:

bash install/install.sh --prefix gmsp-example/cli

On Windows:

powershell -ExecutionPolicy Bypass -File install\install.ps1 -Prefix gmsp-example\cli

The CLI manager requires its receipt to match the managed files. Foreign files, modified payloads, managed symbolic links and Windows junctions are rejected. There is no force or adoption option. An ordinary update failure restores the previous managed files; ambiguous recovery reports UNKNOWN and retains evidence.

After finishing the example, remove only its CLI. On macOS:

bash install/uninstall.sh --prefix gmsp-example/cli

On Windows:

powershell -ExecutionPolicy Bypass -File install\uninstall.ps1 -Prefix gmsp-example\cli

The R package and the processed example remain. The macOS/Linux removal does not change PATH or library environment variables; the Windows removal takes back only the user-PATH entry the installer added. A failed CLI installation does not undo a completed R package installation.