Baker and Jayaram inter-period residual correlation

Computes the empirical Pearson correlation between logarithmic spectral-acceleration prediction residuals at two oscillator periods using Baker and Jayaram (2008). Use this helper when a calculation needs one pairwise inter-period coefficient. It does not construct or validate a correlation matrix and does not sample spectral accelerations.

Usage

rhoBJ(Tn, T0 = 0.01)

Arguments

Tn

A finite numeric scalar giving one oscillator period, in seconds.

T0

A finite numeric scalar giving the other oscillator period, in seconds. The default is 0.01, which the package uses as a numerical proxy for peak ground acceleration (PGA).

Value

A length-one, dimensionless numeric Pearson correlation coefficient. Larger positive values indicate that residuals at the two periods tend to vary together. Equal periods return approximately one.

Details

The result is symmetric: exchanging Tn and T0 does not change the coefficient. The published equation depends on the period pair, not on magnitude or distance arguments. Let Tmin = min(T0, Tn) and Tmax = max(T0, Tn). With ln denoting the natural logarithm, the implementation evaluates Equations 5 and 6 of Baker and Jayaram (2008):

C1 = 1 - cos(pi / 2 - 0.366 * ln(Tmax / max(Tmin, 0.109)))
C2 = 1 - 0.105 * (1 - 1 / (1 + exp(100 * Tmax - 5))) *
     (Tmax - Tmin) / (Tmax - 0.0099), if Tmax < 0.2; otherwise 0
C3 = C2, if Tmax < 0.109; otherwise C1
C4 = C1 + 0.5 * (sqrt(C3) - C3) * (1 + cos(pi * Tmin / 0.109))

rho = C2,          if Tmax < 0.109
      C1,          otherwise if Tmin > 0.109
      min(C2, C4), otherwise if Tmax < 0.2
      C4,          otherwise

The paper supports periods from 0.01 through 10 seconds and describes this equation as an empirical fit with no physical interpretation. It should not be extrapolated. For a positive period outside that interval, rhoBJ() emits a warning but still returns the extrapolated value.

As a package-specific convention, each input less than or equal to zero is silently replaced by 0.01 seconds before calculation. The paper does not define this coercion. Inputs must otherwise be length-one, finite values; vectors, missing values, non-finite positive values, and incompatible values such as character strings produce an error.

The function does not use random numbers, mutate inputs, or read or write files. Its only successful-call side effect is the out-of-domain warning described above.

References

Baker, J. W., and Jayaram, N. (2008). Correlation of Spectral Acceleration Values from NGA Ground Motion Models. Earthquake Spectra, 24(1), 299-317. doi:10.1193/1.2857544 .

See also

fitSaF(), fitSaFMixture(), and fitDnModel() are package callers of rhoBJ(). Their use of pairwise coefficients is governed by their separate contracts.

Examples

RhoPGA <- rhoBJ(Tn = 0.3)
RhoPGA  # about 0.795: positive residual association
#> [1] 0.7953519

rhoBJ(Tn = 0.5, T0 = 0.5)  # about 1: the same period
#> [1] 1
identical(rhoBJ(Tn = 0.3, T0 = 0.5),
          rhoBJ(Tn = 0.5, T0 = 0.3))  # TRUE: symmetric
#> [1] TRUE