Fit the modal shaping factors of one record

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

if (FALSE) { # \dontrun{
Fit <- fitModalFactor(.x = IMF, target = Band, source = TSW,
                      key = Selection[1L], factorMin = 0.001)
} # }