vs30extrap 0.1.0

VS30 extrapolation from shallow shear-wave velocity profiles (Hudson 2026)

vs30extrap

Python implementation of VS30 extrapolation from shallow shear-wave velocity profiles.

---

Background

The time-averaged shear-wave velocity to 30 m depth (VS30) is a key site parameter used in ground-motion models, NEHRP site classification, and seismic hazard mapping. Many velocity profiles do not extend to 30 m, requiring extrapolation.

This package implements the methods published in:

Hudson, K. S. (2026). VS30 Estimation from Shallow VS Profiles. Bulletin of the Seismological Society of America, XX, 1–21. https://doi.org/10.1785/0120250210

Two extrapolation approaches are provided:

Method	Description
constant_velocity	Assumes the velocity below the profile equals the bottom-layer velocity (ASCE 7-22 baseline).
predict	Correlation-based using log₁₀(VS30) = a + b·log₁₀(VSd), with coefficients from linear mixed-effects regression on 2 492 profiles from the VS Profile Database.

Correlation-based models are available with coefficients grouped by:

• velocity_method – measurement technique (MASW, SCPT, Downhole, …)
• basin – sedimentary basin (Los Angeles Basin, San Fernando Basin, …)
• state – U.S. state or Canadian province (California, Kentucky, …)

Installation

pip install vs30extrap

Requires Python ≥ 3.9, NumPy ≥ 1.22, and pandas ≥ 1.4.

Quick start

import vs30extrap

# --- Correlation-based prediction (recommended) ----------------------------

# OLS (no regional grouping required)
vs30, sigma = vs30extrap.predict(250.0, d=10, method='ols')

# Mixed-effects grouped by velocity measurement method
vs30, sigma = vs30extrap.predict(250.0, d=10,
                                  method='velocity_method', group='MASW')

# Mixed-effects grouped by sedimentary basin
vs30, sigma = vs30extrap.predict(250.0, d=10,
                                  method='basin',
                                  group='Los Angeles Basin (LAB)')

# Mixed-effects grouped by state
vs30, sigma = vs30extrap.predict(250.0, d=10,
                                  method='state', group='California')

# Fixed-effects only (population-level, no group_value needed)
vs30, sigma = vs30extrap.predict(250.0, d=10, method='velocity_method')

# --- Constant-velocity extrapolation (ASCE 7-22 baseline) ------------------
vs30_cv = vs30extrap.constant_velocity(250.0, d=10)

# With an explicit bottom-layer velocity
vs30_cv = vs30extrap.constant_velocity(250.0, d=10, Vs_bottom=310.0)

# --- Array inputs -----------------------------------------------------------
import numpy as np
Vsd = np.array([150.0, 250.0, 350.0, 450.0])
vs30_arr, sigma = vs30extrap.predict(Vsd, d=15, method='velocity_method',
                                      group='SCPT')

# --- Discover available groups ----------------------------------------------
vs30extrap.available_groups('velocity_method')
# ['Crosshole', 'Downhole', 'MASW', 'None', 'Reflection',
#  'Refraction', 'SASW', 'SCPT', 'Suspension Logging',
#  'Surface Wave Dispersion']

vs30extrap.available_groups('basin')
vs30extrap.available_groups('state')

API reference

vs30extrap.predict(Vsd, d, method='velocity_method', group=None)

Correlation-based VS30 estimate.

Parameter	Type	Description
Vsd	float or array	Time-averaged VS to depth d (m/s)
d	int	Depth of profile in metres (1–29)
method	str	'ols', 'velocity_method', 'basin', or 'state'
group	str or None	Group within method (see available_groups). None → fixed-effects only

Returns (vs30, sigma) where sigma is the standard deviation of log₁₀ residuals.

---

vs30extrap.constant_velocity(Vsd, d, Vs_bottom=None)

Constant-velocity extrapolation (Equation 2, Hudson 2026; ASCE 7-22).

Parameter	Type	Description
Vsd	float or array	Time-averaged VS to depth d (m/s)
d	int	Depth of profile in metres
Vs_bottom	float or array, optional	Bottom-layer velocity (m/s). Defaults to Vsd.

Returns vs30 (float or ndarray).

---

vs30extrap.available_groups(method)

List valid group strings for the given method.

Returns sorted list of strings.

Choosing a method

Situation	Recommended call
You know the measurement technique	predict(..., method='velocity_method', group='MASW')
Site is in a named sedimentary basin	predict(..., method='basin', group='Los Angeles Basin (LAB)')
Site is in a U.S. state with enough data	predict(..., method='state', group='California')
No regional information available	predict(..., method='ols')
Need ASCE 7-22 baseline for comparison	constant_velocity(...)

The paper shows that all three mixed-effects groupings outperform constant-velocity extrapolation, with the random-effects models producing smaller biases than OLS at all profile depths (Figure 5 of Hudson 2026).

Citation

If you use this package in published work, please cite the underlying paper:

@article{Hudson2026,
  author  = {Hudson, Kenneth S.},
  title   = {{VS30} Estimation from Shallow {VS} Profiles},
  journal = {Bulletin of the Seismological Society of America},
  year    = {2026},
  volume  = {XX},
  pages   = {1--21},
  doi     = {10.1785/0120250210}
}

Data source

Regression coefficients were derived from the VS Profile Database (VsPDB) (Ahdi et al., 2018; Kwak et al., 2021), queried December 2025.

License

MIT © 2026 Kenneth S. Hudson