GaMMA Associator Library

GaMMA core API

association

Function Signature

def association(picks, stations, config, event_idx0=0, method="BGMM", **kwargs)

Purpose

Associates seismic phase picks (P and S waves) to earthquake events using Bayesian or standard Gaussian Mixture Models. It clusters picks based on arrival time and amplitude information, then fits GMMs to estimate earthquake locations, times, and magnitudes.

1. Input Parameters

2. Required DataFrame Columns

picks DataFrame

Notes:

• Timestamps must be in UTC or converted to UTC
• Phase types are forced to lowercase internally
• Picks with amp == 0 or amp == -1 are filtered when use_amplitude=True
• The DataFrame index is used to track pick identities in the output

stations DataFrame

Notes:

• Coordinates should be in a projected local coordinate system (e.g., you can use the pyproj package)
• The id column must match the id values in the picks DataFrame (e.g., network.station. or network.station.location.channel)
• Group stations by unique id, identical attribute are collapsed to a single value and conflicting metadata are preseved as a sorted list.

3. Config Dictionary Keys

Required Keys

Notes on dims:

• Options: ["x(km)", "y(km)", "z(km)"], ["x(km)", "y(km)"], or ["x(km)"]

Notes on bfgs_bounds:

• Format: ((x_min, x_max), (y_min, y_max), (z_min, z_max), (None, None))
• The last tuple is for time (unbounded)

Velocity Model Keys

DBSCAN Pre-clustering Keys (Optional)

• dbscan_eps is obtained from estimate_eps Function

Filtering Keys (Optional)

| Key | Type | Default | Description | |-----|------|-------------| | max_sigma22 | float | 1.0 | Max phase amplitude residual in log scale (required if use_amplitude=True) | | max_sigma12 | float | 1.0 | Max covariance | | max_sigma11 | float | 2.0 | Max phase time residual (s) | | min_p_picks_per_eq | int | 0 | Min P-phase picks per event | | min_s_picks_per_eq | int | 0 |Min S-phase picks per event | | min_stations | int | 5 |Min unique stations per event |

Other Optional Keys

4. Return Values

Returns a tuple (events, assignments):

events (list[dict])

List of dictionaries, each representing an associated earthquake:

assignments (list[tuple])

List of tuples (pick_index, event_index, gamma_score):

• pick_index: Index in the original picks DataFrame
• event_index: Associated event index
• gamma_score: Probability/confidence of assignment

estimate_eps Function Documentation

Function Signature

def estimate_eps(stations, vp, sigma=2.0)

Purpose

Estimates an appropriate DBSCAN epsilon (eps) parameter for clustering seismic phase picks based on station spacing. The eps parameter controls the maximum time distance between picks that should be considered neighbors in the DBSCAN clustering algorithm.

1. Input Parameters

2. Required DataFrame Columns

stations DataFrame

3. Return Value

4. Example Usage

from gamma.utils import estimate_eps

# Assuming stations DataFrame is already prepared with x(km), y(km), z(km) columns
vp = 6.0  # P-wave velocity in km/s

# Estimate eps automatically based on station spacing
eps = estimate_eps(stations, vp, sigma=2.0)

# Use in config
config = {
    "use_dbscan": True,
    "dbscan_eps": eps,  # or use estimate_eps(stations, config["vel"]["p"])
    "dbscan_min_samples": 3,
    # ... other config options
}

Typical Usage Pattern

from gamma.utils import association, estimate_eps

# Automatic eps estimation
config["dbscan_eps"] = estimate_eps(stations, config["vel"]["p"])

# Or manual override (common in practice)
config["dbscan_eps"] = 15  # seconds

5. Practical Notes

• In example notebooks, the function is often commented out in favor of hardcoded values (10-15 seconds)
• Practitioners may prefer manual tuning for specific networks/regions
• Typical output values range from 10-20 seconds depending on station density
• Useful when optimal eps is unknown or when working with new networks

6. Related Configuration

The output is typically used with these config parameters:

config["dbscan_eps"] = estimate_eps(stations, config["vel"]["p"])
config["dbscan_min_samples"] = 3
config["dbscan_min_cluster_size"] = 500
config["dbscan_max_time_space_ratio"] = 10