extractRecord: Extract one record to raw/<KIND>.<RecordID>.csv +...

In gmsp: Ground Motion Signal Processing

Extract one record to ⁠raw/<KIND>.<RecordID>.csv⁠ + ⁠<KIND>.<RecordID>.json⁠.

Description

Pipeline: parseRecord -> mapComponents(rotate = FALSE) -> capture pre-align NP and DIR/OCID mapping -> alignComponents -> pivot WIDE by provider OCID -> md5-16 hash -> write. The function returns NULL and writes nothing in three skip paths:

1. Component classification cannot map the record (arrays with > 3 OCIDs, 2-component records, or records with no vertical channel in the vertical-component vocabulary).

2. The provider Units string cannot be normalised (.parseUnits returns NA_character_, so the scale factor K is NULL).

3. kind is left at its default NULL and .parseKind(Key$Units) returns NA_character_ (kind cannot be derived from Units).

Usage

extractRecord(.x, path, align = "max", kind = NULL)

Arguments

.x	data.table subset for ONE record.
path	Absolute path to the records root. The function writes outputs under ⁠<path>/<OwnerID>/<EventID>/<StationID>/raw/⁠. Required – no default.
align	"max" (pad to longest, default) or "min" (truncate).
kind	Optional "AT"|"VT"|"DT" override. When NULL (default) KIND is derived from Key$Units via .parseKind().

Details

KIND is one of "AT" (acceleration), "VT" (velocity), "DT" (displacement). By default it is derived from Key$Units via .parseKind(). Pass kind explicitly to override – e.g. kind = "VT" for blasting records whose Units may not be machine-parseable.

Old contents of ⁠raw/⁠ are unlinked before writing (idempotent).

JSON sidecar schema:

RecordID, OwnerID, EventID, StationID, NetworkID,
FileID            (scalar = "<KIND>.<RID>.csv"),
DIR               (array, ["H1","H2","UP"]),
OCID              (array of 3, provider channels in DIR order),
NP                (array of 3, pre-align NP per DIR),
PGA / PGV / PGD   (array of 3, peak |s| per DIR, post-align;
                   field name derived from KIND[1] -> PGA/PGV/PGD),
dt, Fs, Units     (scalars).

Value

Absolute path to the written ⁠<KIND>.<RecordID>.csv⁠, or NULL (skip).

Examples

root <- file.path(tempdir(), "gmsp-extract-example")
unlink(root, recursive = TRUE)
raw <- file.path(root, "ESM", "E1", "S1", "raw.owner")
dir.create(raw, recursive = TRUE)
writeLines(c("0 1", "0.01 2", "0.02 3"), file.path(raw, "N_acc.txt"))
writeLines(c("0 2", "0.01 3", "0.02 4"), file.path(raw, "E_acc.txt"))
writeLines(c("0 0", "0.01 1", "0.02 0"), file.path(raw, "Z_acc.txt"))
rows <- data.table::data.table(
  OwnerID = "ESM", EventID = "E1", StationID = "S1",
  NetworkID = "NW", Units = "cm",
  FileID = c("N_acc.txt", "E_acc.txt", "Z_acc.txt")
)
path <- extractRecord(rows, path = root, kind = "AT")
basename(path)

gmsp documentation built on July 18, 2026, 5:07 p.m.