seisgo.monitoring

The monitoring module measures relative seismic velocity changes (dv/v) from ambient-noise cross-correlations using time-domain stretching or wavelet-based methods.

---

Function Summary

---

get_dvv Parameter Reference

Parameter	Default	Description
corrdata	required	seisgo.types.CorrData object containing the cross-correlation time series.
freq	required	[fmin, fmax] — frequency band for measurement (Hz).
win_len	required	Coda window length in seconds. Accepts a scalar or list for multiple windows.
ref	None	Reference trace. If None, computed by stacking all windows with stack_method.
stack_method	"linear"	Stacking method to compute the reference. See seisgo.stacking.
offset	1.0	Lag offset (s) from the main arrival (xcorr) or from zero (autocorr). Accepts a scalar or list aligned with win_len.
resolution	None	Temporal sub-stack resolution (s). Resamples the data before measuring dv/v.
vmin	1.0	Minimum group velocity (km/s) used to set the start of the coda window.
normalize	True	Normalize traces before measuring.
whiten	"no"	Spectral whitening: "no", "rma", or "phase_only".
method	"wts"	dv/v method: "wts" (wavelet stretching) or "ts" (time-domain stretching).
dvmax	0.05	Maximum search range for dv/v (5% by default).
subfreq	True	If True (wts only), return frequency-dependent dv/v.
nproc	None	Number of parallel processes. None = serial.
save	False	If True, write seisgo.types.DvvData to outdir.
format	None	Output format: "asdf" or "pickle". Auto-detected from outfile extension.

---

dv/v Methods

Wavelet-transform stretching ("wts")

The default method. Decomposes each coda window into the time–frequency domain, applies a stretching operator at each scale, and finds the stretch factor that maximises cross-correlation with the reference. Returns a dv/v value per frequency band.

Credit: adapted from Congcong Yuan (Harvard), originally by Chengxin Jiang and Marine Denolle.

Time-domain stretching ("ts")

Applies a uniform time-axis stretch to the full coda window and maximises the cross-correlation coefficient against the reference. Returns a single broadband dv/v value. Set subfreq=False automatically when method="ts".

---

Output: DvvData

get_dvv() returns a seisgo.types.DvvData object (or saves it to disk).

Key attributes:

Attribute	Description
dvv	dv/v array, shape (n_windows,) or (n_windows, n_freqs)
err	Measurement uncertainty array (same shape as dvv)
cc	Cross-correlation coefficient of each measurement
time	Timestamps of each measurement window
freq	Frequency vector (for wts) or scalar band
method	Method used ("wts" or "ts")
cc_comp	Component pair (e.g. "ZZ")

dvvdata.plot()
dvvdata.to_asdf("dvv_output.h5")