fitModalFactor: Fit the modal shaping factors of one record

In gmsp: Ground Motion Signal Processing

Fit the modal shaping factors of one record

Description

Per-record modal shaping of the spectral-match workflow: released modal amplitudes are fitted against a target response-spectrum band (shape.modalFactor in the batch JSON contract), with energy restoration applied after the modal objective.

Usage

fitModalFactor(
  .x,
  target,
  source,
  key,
  ocid = "H1",
  xi = 0.05,
  fmax = 25,
  kNyq = 4,
  factorMin,
  factorMax = Inf,
  remove = NULL,
  includeResidue = TRUE,
  unitsSource = "mm",
  unitsTarget = "mm"
)

Arguments

.x	data.table. IMF rows for the suite (or the record): RecordID, OwnerID, EventID, StationID, OCID, t, signal, ⁠IMF*⁠ mode columns, and optionally residue. Rows are filtered to key's record and ocid.
target	data.table. Target band with columns Tn, Sa.low, Sa.mean, Sa.high; must include Tn == 0 (PGA) and positive periods, in the PSA units of .x.
source	data.table. Source TSW rows for the suite (columns RecordID, t, ⁠AT.<ocid>⁠, ...) used for the source spectra.
key	data.table. One row carrying RecordID, OwnerID, EventID, StationID of the record to fit.
ocid	character. Component to shape ("H1", "H2", "UP").
xi	numeric. Damping ratio.
fmax	numeric. Analysis bandwidth (Hz).
kNyq	numeric. Nyquist multiple.
factorMin	numeric. Lower bound of the modal factors (shape.modalFactor.min), in (0, 1].
factorMax	numeric. Upper bound of the modal factors (shape.modalFactor.max); must contain 1. Default Inf.
remove	character or integer. IMF modes excluded from the reconstruction (imf.remove).
includeResidue	logical. Keep the residue in the reconstruction.
unitsSource	character. Units of .x signals.
unitsTarget	character. Units of the shaped products.

Value

list with TSW (shaped time histories of the fitted component), PSW (shaped spectra), PSA (long table with kind = source/start/final curves), coeff (per-mode factors: b, energyFactor, stageFactor), metrics (one-row fit diagnostics), and eval (objective evaluations).

Examples

## Not run: 
Fit <- fitModalFactor(.x = IMF, target = Band, source = TSW,
                      key = Selection[1L], factorMin = 0.001)

## End(Not run)

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