Metadata-Version: 2.4
Name: vs30extrap
Version: 0.1.0
Summary: VS30 extrapolation from shallow shear-wave velocity profiles (Hudson 2026)
Author-email: "Kenneth S. Hudson" <kenneth.s.hudson@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/khud27/vs30extrap
Project-URL: Bug Tracker, https://github.com/khud27/vs30extrap/issues
Project-URL: Paper DOI, https://doi.org/10.1785/0120250210
Keywords: seismology,geotechnical,site-characterization,VS30,shear-wave velocity,NEHRP,seismic hazard
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Requires-Dist: pandas>=1.4
Dynamic: license-file

# vs30extrap

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

[![PyPI version](https://img.shields.io/pypi/v/vs30extrap.svg)](https://pypi.org/project/vs30extrap/)
[![Python versions](https://img.shields.io/pypi/pyversions/vs30extrap.svg)](https://pypi.org/project/vs30extrap/)
[![CI](https://github.com/khud27/vs30extrap/actions/workflows/ci.yml/badge.svg)](https://github.com/khud27/vs30extrap/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![DOI](https://img.shields.io/badge/DOI-10.1785%2F0120250210-blue)](https://doi.org/10.1785/0120250210)

---

## 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](https://vspdb.org). |

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

```bash
pip install vs30extrap
```

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

## Quick start

```python
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:

```bibtex
@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)](https://vspdb.org) (Ahdi et al., 2018;
Kwak et al., 2021), queried December 2025.

## License

[MIT](LICENSE) © 2026 Kenneth S. Hudson
