Models

qseek.models.location.Location pydantic-model

Bases: BaseModel

Fields:

• lat (float)
• lon (float)
• east_shift (float)
• north_shift (float)
• elevation (float)
• depth (float)
• _cached_lat_lon (tuple[float, float] | None)
• _cached_origin (Location | None)

depth pydantic-field

depth: float = 0.0

Depth in meters, positive is down.

east_shift pydantic-field

east_shift: float = 0.0

East shift towards geographical reference in meters.

effective_lat_lon property

effective_lat_lon: tuple[float, float]

Shift-corrected lat/lon pair of the location.

elevation pydantic-field

elevation: float = 0.0

Elevation in meters.

lat pydantic-field

lat: float

Latitude in degrees.

lon pydantic-field

lon: float

Longitude in degrees.

north_shift pydantic-field

north_shift: float = 0.0

North shift towards geographical reference in meters.

as_wkt

as_wkt() -> str

Return the location as WKT string.

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.

origin

origin() -> Location

Get the origin location.

Returns:

Name	Type	Description
Location	Location	The origin 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.

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.

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].

qseek.models.detection.EventDetection pydantic-model

Bases: Location

Fields:

• lat (float)
• lon (float)
• east_shift (float)
• north_shift (float)
• elevation (float)
• depth (float)
• _cached_lat_lon (tuple[float, float] | None)
• _cached_origin (Location | None)
• uid (UUID)
• time (AwareDatetime)
• semblance (PositiveFloat)
• n_stations (int)
• distance_border (PositiveFloat)
• in_bounds (bool)
• uncertainty (DetectionUncertainty | None)
• magnitudes (list[EventMagnitudeType])
• features (list[EventFeaturesType])
• _receivers (EventReceivers | None)
• _detection_idx (int | None)
• _receiver_cache (ReceiverCache | None)

Validators:

• migrate_features → features

depth pydantic-field

depth: float = 0.0

Depth in meters, positive is down.

distance_border pydantic-field

distance_border: PositiveFloat

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

east_shift pydantic-field

east_shift: float = 0.0

East shift towards geographical reference in meters.

effective_lat_lon property

effective_lat_lon: tuple[float, float]

Shift-corrected lat/lon pair of the location.

elevation pydantic-field

elevation: float = 0.0

Elevation in meters.

features pydantic-field

features: list[EventFeaturesType] = []

Event features.

in_bounds pydantic-field

in_bounds: bool = True

Is detection in bounds, and inside the configured border.

lat pydantic-field

lat: float

Latitude in degrees.

lon pydantic-field

lon: float

Longitude in degrees.

magnitude property

magnitude: EventMagnitude | None

Returns the magnitude of the event.

If there are no magnitudes available, returns None.

magnitudes pydantic-field

magnitudes: list[EventMagnitudeType] = []

Event magnitudes.

n_picks property

n_picks: int

Number of phase picks in the detection.

n_stations pydantic-field

n_stations: int = 0

Number of stations in the detection.

north_shift pydantic-field

north_shift: float = 0.0

North shift towards geographical reference in meters.

receivers property

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.

semblance pydantic-field

semblance: PositiveFloat

Detection semblance

time pydantic-field

time: AwareDatetime

Detection time

uncertainty pydantic-field

uncertainty: DetectionUncertainty | None = None

Detection uncertainty.

add_feature

add_feature(feature: EventFeature) -> None

Add feature to the feature set.

Parameters:

Name	Type	Description	Default
feature	EventFeature	Feature to add	required

add_magnitude

add_magnitude(magnitude: EventMagnitude) -> None

Add magnitude to detection.

Parameters:

Name	Type	Description	Default
magnitude	EventMagnitudeType	magnitude	required

as_pyrocko_event

as_pyrocko_event() -> Event

Get detection as Pyrocko event.

Returns:

Name	Type	Description
Event	Event	Pyrocko event

as_wkt

as_wkt() -> str

Return the location as WKT string.

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].

export_csv_line

export_csv_line(file: Path, 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
jitter_location	float	The amount of spatial jitter to apply. Defaults to 0.0.	0.0

export_pyrocko_event

export_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

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

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

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

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

get_receiver_azimuths

get_receiver_azimuths(observed_only: bool = True)

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]: Receiver azimuths

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

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.

origin

origin() -> Location

Get the origin location.

Returns:

Name	Type	Description
Location	Location	The origin location.

save async

save(rundir: Path, update: bool = False, jitter_location: float = 0.0) -> None

Dump the detection data to a 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
rundir	Path	The path to the rundir.	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.

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_receiver_cache

set_receiver_cache(rundir: Path) -> None

Set the rundir for the detection model.

Parameters:

Name	Type	Description	Default
rundir	Path	The path to the rundir.	required

set_uncertainty

set_uncertainty(uncertainty: DetectionUncertainty) -> None

Set detection uncertainty.

Parameters:

Name	Type	Description	Default
uncertainty	DetectionUncertainty	detection uncertainty	required

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.

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.

snuffle

snuffle(squirrel: Squirrel, restituted: bool | MeasurementUnit = False) -> None

Open snuffler for detection.

Parameters:

Name	Type	Description	Default
squirrel	Squirrel	The squirrel, holding the data	required
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].

update async

update(rundir: Path) -> None

Update detection in database.

Doing this often requires a lot of I/O.