seisgo.anisotropy

The anisotropy module implements the BANX method for measuring seismic azimuthal anisotropy from ambient-noise cross-correlations.

Note

The BANX implementation was adapted from original MATLAB code by Jorge C. Castellanos-Martinez. Please cite the following when using this module:

Castellanos, J. C., Perry-Houts, J., Clayton, R. W., Kim, Y., Stanciu, A. C., Niday, B., & Humphreys, E. (2020). Seismic anisotropy reveals crustal flow driven by mantle vertical loading in the Pacific NW. Science Advances, 6(28). https://doi.org/10.1126/sciadv.abb0476

Function Summary

`do_BANX` Parameter Reference

Geometry and station selection

Parameter	Default	Description
`stationdict_all`	required	`dict` mapping station name → `[lat, lon]` for all stations.
`reference_site`	required	Name of the reference station (receiver-cluster centre).
`period_band`	required	`[T_min, T_max]` — analysis period band (s).
`reference_velocity`	required	Reference phase velocity (km/s) for the period band.
`datadir`	required	Directory containing ASDF cross-correlation files.
`min_stations`	`10`	Minimum stations in the receiver cluster.
`min_radius_scaling`	`1`	Minimum cluster radius = scaling × (T_min × v_ref).
`max_radius_scaling`	`1.5`	Maximum cluster radius = scaling × (T_max × v_ref).
`min_distance_scaling`	`2.5`	Minimum source distance = scaling × (T_max × v_ref).

Data processing

Parameter	Default	Description
`sampling_rate`	`None`	Target sampling rate (sps). Must be an integer ratio of the input rate.
`min_snr`	`5`	Minimum SNR for trace inclusion.
`signal_window_velocity`	`None`	Group velocity for signal-window prediction. Default: 80% of `reference_velocity`.
`signal_extent_scaling`	`3`	Signal window half-width = scaling × T_max.
`taper_length_scaling`	`5`	Taper length = scaling × T_max.
`doublesided`	`True`	Cross-correlation data contains both negative and positive lags.
`cc_comp`	`"ZZ"`	Cross-correlation component pair.

Beamforming

Parameter	Default	Description
`max_slowness`	`0.5`	Maximum slowness (s/km) in the beamforming search grid.
`slowness_step`	`0.005`	Slowness grid spacing (s/km).
`velocity_perturbation`	`0.4`	Fraction of `reference_velocity` defining the allowed velocity range.

Quality control

Parameter	Default	Description
`azimuth_step`	`6`	Back-azimuth bin width (°) for QC histogram.
`min_baz_measurements`	`3`	Minimum measurements per azimuth bin to count as a “good” bin.
`min_good_bazbin`	`5`	Minimum number of good azimuth bins required for curve fitting.
`min_beam_sharpness`	`0`	Minimum beam-sharpness ratio. `0` disables this filter.

Plotting

Parameter	Default	Description
`show_fig`	`True`	Display figures interactively.
`plot_moveout`	`True`	Plot waveform moveout for each source–cluster pair.
`plot_clustermap`	`True`	Plot station map for each source–cluster pair.
`map_engine`	`"cartopy"`	Map backend: `"cartopy"` or `"gmt"`.
`map_region`	`None`	`[lon_min, lon_max, lat_min, lat_max]`. Auto-computed if `None`.
`receiver_box`	`None`	Draw a bounding box: `[lon_min, lon_max, lat_min, lat_max]`.
`plot_beampower`	`True`	Plot the slowness-space beam power image.
`plot_station_result`	`True`	Plot velocity vs. BAZ scatter and fitted anisotropy curve.

Anisotropy model

The velocity–azimuth relationship modelled by compute_anisotropy():

\[v(\theta) = A_0 + A_1 \cos(2\theta) + A_2 \sin(2\theta)\]

\(A_0\) — isotropic (background) velocity
\(A_1, A_2\) — anisotropy coefficients
Strength: \(\rho = \sqrt{A_1^2 + A_2^2} / A_0 \times 100\%\)
Fast direction: \(\Theta = \frac{1}{2} \arctan(A_2 / A_1)\) (°, from N)

Reference: Smith & Dahlen (1973), JGR, 78, 3321–3333.