Skip to content

Detections

The detections of a run, as loaded with EventCatalog.load_rundir(). See read the detections in Python.

EventCatalog pydantic-model

Bases: BaseModel

Fields:

n_events property 

n_events: int

Number of detections.

sort 

sort() -> None

Sort the detections by time.

get_event 

get_event(uid: UUID) -> EventDetection

Get an event by its UUID.

Parameters:

Name Type Description Default
uid UUID

The event UUID.

 required

Returns:

Name Type Description
EventDetection EventDetection

The event detection object.

filter_events_by_time async 

filter_events_by_time(
    start_time: datetime | None, end_time: datetime | None
) -> None

Filter the detections based on the given time range.

Parameters:

Name Type Description Default
start_time datetime | None

Start time of the time range.

 required
end_time datetime | None

End time of the time range.

 required

add async 

add(
    detection: EventDetection, jitter_location: float = 0.0
) -> None

Add a detection to the catalog.

Parameters:

Name Type Description Default
detection EventDetection

The detection to add.

 required
jitter_location float

Randomize the location of the detection by this many meters. This is only exported to the CSV and Pyrocko detections. Defaults to 0.0.

 0.0

save_semblance_trace async 

save_semblance_trace(trace: Trace) -> None

Add semblance trace to detection and save to file.

Data is multiplied by 1e3 and saved as int32 to leverage MiniSEED STEIM compression.

Parameters:

Name Type Description Default
trace Trace

semblance trace.

 required

last_modification classmethod 

last_modification(rundir: Path) -> datetime

Last modification of the event file.

Returns:

Name Type Description
datetime datetime

Last modification of the event file.

load_rundir classmethod 

load_rundir(rundir: Path) -> EventCatalog

Load detections from files in the detections directory.

check async 

check(repair: bool = True) -> None

Check the catalog for errors and inconsistencies.

Parameters:

Name Type Description Default
repair bool

If True, attempt to repair the catalog. Defaults to True.

 True

prepare 

prepare(csv_header: list[str] | None = None) -> None

Prepare the search run.

save_detection async 

save_detection(
    detection: EventDetection,
    update: bool = False,
    jitter_location: float = 0.0,
) -> None

Dump a detection data to file.

After the detection is dumped, the receivers are dumped to a separate file and the receivers cache is cleared.

Parameters:

Name Type Description Default
detection EventDetection

The detection to save.

 required
update bool

Whether to update an existing detection or append a new one.

 False
jitter_location float

The amount of spatial jitter to apply to the exported detection. Defaults to 0.0.

 0.0

Raises:

Type Description
ValueError

If the detection index is not set and update is True.

save async 

save() -> None

Save catalog to current rundir.

export_detections async 

export_detections(jitter_location: float = 0.0) -> None

Export detections to CSV and Pyrocko event lists in the current rundir.

Parameters:

Name Type Description Default
jitter_location float

The amount of jitter in [m] to apply to the detection locations. Defaults to 0.0.

 0.0

export_csv async 

export_csv(
    file: Path,
    jitter_location: float = 0.0,
    additional_data: list[dict] | None = None,
) -> None

Export detections to a CSV file.

Parameters:

Name Type Description Default
file Path

The output filename.

 required
jitter_location float

Randomize the location of each detection by this many meters. Defaults to 0.0.

 0.0
additional_data list[dict]

Additional data to include in the CSV. Defaults to None.

 None

as_pyrocko_events 

as_pyrocko_events() -> list[Event]

Convert the detections to Pyrocko Event objects.

Returns:

Type Description
list[Event]

list[Event]: A list of Pyrocko Event objects.

get_pyrocko_markers 

get_pyrocko_markers(
    modelled: bool = True, observed: bool = True
) -> list[EventMarker | PhaseMarker]

Get Pyrocko phase pick markers for all detections.

Parameters:

Name Type Description Default
modelled bool

Include modelled picks. Defaults to True.

 True
observed bool

Include observed picks. Defaults to True.

 True

Returns:

Type Description
list[EventMarker | PhaseMarker]

list[EventMarker | PhaseMarker]: A list of Pyrocko PhaseMarker.

export_pyrocko_events 

export_pyrocko_events(
    filename: Path, jitter_location: float = 0.0
) -> None

Export Pyrocko events for all detections to a file.

Parameters:

Name Type Description Default
filename Path

output filename

 required
jitter_location float

Randomize the location of each detection by this many meters. Defaults to 0.0.

 0.0

export_pyrocko_markers 

export_pyrocko_markers(filename: Path) -> None

Export Pyrocko markers for all detections to a file.

Parameters:

Name Type Description Default
filename Path

output filename

 required

export_gpkg async 

export_gpkg(filename: Path) -> None

Save the catalog as a GeoPackage file.

Parameters:

Name Type Description Default
filename Path

The output filename.

 required

EventDetection pydantic-model

Bases: Location

Fields:

Validators:

  • materialize_receivers
  • migrate_features → features

time pydantic-field 

time: AwareDatetime

Detection time

semblance pydantic-field 

semblance: PositiveFloat

Detection semblance

n_stations pydantic-field 

n_stations: int = 0

Number of stations in the detection.

distance_border pydantic-field 

distance_border: PositiveFloat

Distance to the nearest border in meters. Only distance to NW, SW and bottom border is considered.

in_bounds pydantic-field 

in_bounds: bool = True

Is detection in bounds, and inside the configured border.

uncertainty pydantic-field 

uncertainty: DetectionUncertainty | None = None

Detection uncertainty.

magnitudes pydantic-field 

magnitudes: list[EventMagnitudeType] = []

Event magnitudes.

features pydantic-field 

features: list[EventFeaturesType] = []

Event features.

magnitude property 

magnitude: EventMagnitude | None

Returns the magnitude of the event.

If there are no magnitudes available, returns None.

receivers property writable 

receivers: EventReceivers

Retrieves the event receivers associated with the detection.

Returns:

Name Type Description
EventReceivers EventReceivers

The event receivers associated with the detection.

Raises:

Type Description
AttributeError

If the receivers cannot be fetched without a set rundir and detection index.
ValueError

If the receivers cannot be fetched due to missing rundir and index, or if there is a UID mismatch between the fetched receivers and the detection.

n_picks property 

n_picks: int

Number of phase picks in the detection.

rms property 

rms: float | None

Root mean square of the traveltime delays of the observed arrivals.

lat pydantic-field 

lat: float

Latitude in degrees.

lon pydantic-field 

lon: float

Longitude in degrees.

east_shift pydantic-field 

east_shift: float = 0.0

East shift towards geographical reference in meters.

north_shift pydantic-field 

north_shift: float = 0.0

North shift towards geographical reference in meters.

elevation pydantic-field 

elevation: float = 0.0

Elevation in meters.

depth pydantic-field 

depth: float = 0.0

Depth in meters, positive is down.

effective_lat_lon property 

effective_lat_lon: tuple[float, float]

Shift-corrected lat/lon pair of the location.

set_receiver_cache 

set_receiver_cache(receiver_cache: ReceiverCache) -> None

Set the receiver cache for the detection model.

Parameters:

Name Type Description Default
receiver_cache ReceiverCache

The receiver cache instance.

 required

clear_receivers 

clear_receivers()

Clear the receivers associated with the detection to free memory.

write_csv_line 

write_csv_line(
    file: Path,
    header: list[str] | None = None,
    jitter_location: float = 0.0,
) -> None

Save the detection as a CSV line.

Parameters:

Name Type Description Default
file Path

The path to the CSV file.

 required
header list[str]

The header to include in the CSV line. Defaults to None.

 None
jitter_location float

The amount of spatial jitter to apply. Defaults to 0.0.

 0.0

write_pyrocko_event 

write_pyrocko_event(
    file: Path, jitter_location: float = 0.0
) -> None

Write the detection as a Pyrocko event to a file.

Parameters:

Name Type Description Default
file Path

The path to the output file.

 required
jitter_location float

The amount of spatial jitter to apply. Defaults to 0.0.

 0.0

set_index 

set_index(index: int, force: bool = False) -> None

Set the index of the detection.

Parameters:

Name Type Description Default
index int

The index to set.

 required
force bool

Whether to force the index to be set. Defaults to False.

 False

Returns:

Type Description
None

None

set_uncertainty 

set_uncertainty(uncertainty: DetectionUncertainty) -> None

Set detection uncertainty.

Parameters:

Name Type Description Default
uncertainty DetectionUncertainty

detection uncertainty

 required

add_magnitude 

add_magnitude(magnitude: EventMagnitude) -> None

Add magnitude to detection.

Parameters:

Name Type Description Default
magnitude EventMagnitudeType

magnitude

 required

add_feature 

add_feature(feature: EventFeature) -> None

Add feature to the feature set.

Parameters:

Name Type Description Default
feature EventFeature

Feature to add

 required

get_receiver_azimuths 

get_receiver_azimuths(
    observed_only: bool = True,
) -> dict[str, float]

Get receiver azimuths.

Parameters:

Name Type Description Default
observed_only bool

Return only observed azimuths. Defaults to False.

 True

Returns:

Type Description
dict[str, float]

dict[str, float]: Receiver azimuths

get_azimuthal_coverage 

get_azimuthal_coverage(observed_only: bool = True) -> float

Get azimuthal coverage of the detection.

This is the reverse of the azimuthal gap: 360 - azimuthal_gap.

Parameters:

Name Type Description Default
observed_only bool

Consider only observed azimuths. Defaults to True.

 True

get_azimuthal_gap 

get_azimuthal_gap(observed_only: bool = True) -> float

Get maximum azimuthal gap of the detection.

Parameters:

Name Type Description Default
observed_only bool

Consider only observed azimuths. Defaults to True.

 True

as_pyrocko_event 

as_pyrocko_event() -> Event

Get detection as Pyrocko event.

Returns:

Name Type Description
Event Event

Pyrocko event

get_csv_dict 

get_csv_dict() -> dict[str, Any]

Get detection as CSV line.

Returns:

Type Description
dict[str, Any]

dict[str, Any]: CSV line

csv_header classmethod 

csv_header() -> list[str]

Get CSV header for the detection.

Returns:

Type Description
list[str]

list[str]: CSV header

get_pyrocko_markers 

get_pyrocko_markers(
    modelled: bool = True, observed: bool = True
) -> list[EventMarker | PhaseMarker]

Get detections as Pyrocko markers.

Parameters:

Name Type Description Default
modelled bool

Include modelled arrivals. Defaults to True.

 True
observed bool

Include observed arrivals. Defaults to True.

 True

Returns:

Type Description
list[EventMarker | PhaseMarker]

list[marker.EventMarker | marker.PhaseMarker]: Pyrocko markers

export_pyrocko_markers 

export_pyrocko_markers(filename: Path) -> None

Save detection's Pyrocko markers to file.

Parameters:

Name Type Description Default
filename Path

path to marker file

 required

jitter_location 

jitter_location(meters: float) -> Self

Randomize detection location.

Parameters:

Name Type Description Default
meters float

maximum randomization in meters

 required

Returns:

Name Type Description
EventDetection Self

spatially jittered detection

snuffle 

snuffle(
    waveform_provider: WaveformProvider,
    stations: StationInventory | None = None,
    restituted: bool | MeasurementUnit = False,
) -> None

Open snuffler for detection.

Parameters:

Name Type Description Default
waveform_provider WaveformProvider

The waveform provider to use for retrieving waveforms.

 required
stations StationInventory

The station inventory to use for retrieving

 None
restituted bool

Restitude the data. Defaults to False.

 False

surface_distance_to 

surface_distance_to(other: Location) -> float

Compute surface distance [m] to other location object.

Parameters:

Name Type Description Default
other Location

The other location.

 required

Returns:

Name Type Description
float float

The surface distance in [m].

azimuth_to 

azimuth_to(other: Location) -> float

Compute azimuth [°] to other location object.

Parameters:

Name Type Description Default
other Location

The other location.

 required

Returns:

Name Type Description
float float

The azimuth in [°].

distance_to 

distance_to(other: Location) -> float

Compute 3-dimensional distance [m] to other location object.

Parameters:

Name Type Description Default
other Location

The other location.

 required

Returns:

Name Type Description
float float

The distance in [m].

offset_from 

offset_from(other: Location) -> tuple[float, float, float]

Return offset vector (east, north, depth) from other location in [m].

Parameters:

Name Type Description Default
other Location

The other location.

 required

Returns:

Type Description
tuple[float, float, float]

tuple[float, float, float]: The offset vector.

shifted_origin 

shifted_origin() -> Self

Shift the origin of the location to the effective lat/lon.

Returns:

Name Type Description
Self Self

The shifted location.

shift 

shift(east: float, north: float, elevation: float) -> Self

Shift the location by the given offsets.

Parameters:

Name Type Description Default
east float

East offset in [m].

 required
north float

North offset in [m].

 required
elevation float

Elevation offset in [m].

 required

Returns:

Name Type Description
Self Self

The shifted location.

origin 

origin() -> Location

Get the origin location.

Returns:

Name Type Description
Location Location

The origin location.

as_wkt 

as_wkt() -> str

Return the location as WKT string.