Octree

A 3D space is searched for sources of seismic energy. Qseek created an octree structure which is iteratively refined when energy is detected, to focus on the source' location. This speeds up the search and improves the resolution of the localisations.

Surface projection of the refined octree focusing on the seismic source region. In this example four levels of refinement are can be seen, refining the 3D octree from the initial 4000 nodes to 8823 nodes.

Octree Module

Config OctreeJSON

location

The geographical center of the octree.

root_node_size: 1000.0

Size of the root node at the initial level (level 0) in meters.

n_levels: 5

Number of levels in the octree, defining the final resolution of the detection. Default is 5.

east_bounds

East bounds of the octree in meters.

north_bounds

North bounds of the octree in meters.

depth_bounds

Depth bounds of the octree in meters.

JSON for Octree

{
  "location": {
    "lat": 0.0,
    "lon": 0.0,
    "east_shift": 0.0,
    "north_shift": 0.0,
    "elevation": 0.0,
    "depth": 0.0
  },
  "root_node_size": 1000.0,
  "n_levels": 5,
  "east_bounds": [
    -10000.0,
    10000.0
  ],
  "north_bounds": [
    -10000.0,
    10000.0
  ],
  "depth_bounds": [
    0.0,
    20000.0
  ]
}

qseek.octree.Octree pydantic-model

Bases: BaseModel, Iterator[Node]

Config:

• ignored_types: (cached_property)

Fields:

• location (Location)
• root_node_size (PositiveFloat)
• n_levels (int)
• east_bounds (Range)
• north_bounds (Range)
• depth_bounds (Range)
• _root_nodes (list[Node])
• _semblance (ndarray | None)
• _cached_coordinates (dict[CoordSystem, ndarray])
• _nodes (list[Node])
• n_nodes (int)
• n_leaf_nodes (int)
• nodes (list[Node])
• volume (float)
• leaf_nodes (list[Node])
• semblance (ndarray)

Validators:

• check_reference → location
• check_limits

depth_bounds pydantic-field

depth_bounds: Range = Range(0 * KM, 20 * KM)

Depth bounds of the octree in meters.

east_bounds pydantic-field

east_bounds: Range = Range(-10 * KM, 10 * KM)

East bounds of the octree in meters.

leaf_nodes pydantic-field

leaf_nodes: list[Node]

Get all leaf nodes of the octree.

Returns:

Type	Description
list[Node]	list[Node]: List of leaf nodes.

location pydantic-field

location: Location = Location(lat=0.0, lon=0.0)

The geographical center of the octree.

n_leaf_nodes pydantic-field

n_leaf_nodes: int

Number of nodes in the octree.

n_levels pydantic-field

n_levels: int = 5

Number of levels in the octree, defining the final resolution of the detection. Default is 5.

n_nodes pydantic-field

n_nodes: int

Number of nodes in the octree.

nodes pydantic-field

nodes: list[Node]

List of nodes in the octree.

north_bounds pydantic-field

north_bounds: Range = Range(-10 * KM, 10 * KM)

North bounds of the octree in meters.

root_node_size pydantic-field

root_node_size: PositiveFloat = 1 * KM

Size of the root node at the initial level (level 0) in meters.

semblance pydantic-field

semblance: ndarray

Returns the semblance values of all nodes.

volume pydantic-field

volume: float

Volume of the octree in cubic meters.

cached_bottom

cached_bottom() -> Self

Returns a copy of the octree refined to the cached bottom nodes.

Raises:

Type	Description
EnvironmentError	If the octree has never been split.

Returns:

Name	Type	Description
Self	Self	Copy of the octree with cached bottom nodes.

check_limits pydantic-validator

check_limits() -> Octree

Check that the size limits are valid.

clear

clear() -> None

Clear the octree's cached data.

distances_stations

distances_stations(stations: Stations) -> ndarray

Returns the 3D distances from all nodes to all stations.

Parameters:

Name	Type	Description	Default
stations	Stations	Stations to calculate distance to.	required

Returns:

Type	Description
ndarray	np.ndarray: Of shape (n-nodes, n-stations).

distances_stations_surface

distances_stations_surface(stations: Stations) -> ndarray

Returns the surface distance from all nodes to all stations.

Parameters:

Name	Type	Description	Default
stations	Stations	Stations to calculate distance to.	required

Returns:

Type	Description
ndarray	np.ndarray: Distances in shape (n-nodes, n-stations).

extent

extent() -> tuple[float, float, float]

Returns the extent of the octree.

Returns:

Type	Description
tuple[float, float, float]	tuple[float, float, float]: EW, NS and depth extent of the octree in meters.

get_corners

get_corners() -> list[Location]

Get the corners of the octree.

Returns:

Type	Description
list[Location]	list[Location]: List of locations.

get_nodes

get_nodes(indices: Iterable[int]) -> list[Node]

Retrieves a list of nodes from the octree based on the given indices.

Parameters:

Name	Type	Description	Default
indices	Iterable[int]	The indices of the nodes to retrieve.	required

Returns:

Type	Description
list[Node]	list[Node]: A list of nodes corresponding to the given indices.

get_nodes_by_threshold

get_nodes_by_threshold(semblance_threshold: float = 0.0) -> list[Node]

Get all nodes with a semblance above a threshold.

Parameters:

Name	Type	Description	Default
semblance_threshold	float	Semblance threshold. Default is 0.0.	0.0

Returns:

Type	Description
list[Node]	list[Node]: List of nodes.

get_nodes_level

get_nodes_level(level: int = 0) -> list[Node]

Get all nodes at a specific level.

Parameters:

Name	Type	Description	Default
level	int	Level to get nodes from.	0

Returns:

Type	Description
list[Node]	list[Node]: List of nodes.

interpolate_max_semblance async

interpolate_max_semblance(peak_node: Node) -> Location

Interpolate the location of the maximum semblance value.

This method calculates the location of the maximum semblance value by performing interpolation using surrounding nodes. It uses the scipy Rbf (Radial basis function) interpolation method to fit a smooth function to the given data points. The function is then minimized to find the location of the maximum value.

Returns:

Name	Type	Description
Location	Location	Location of the maximum semblance value.

Raises:

Type	Description
AttributeError	If no semblance values are set.

map_semblance

map_semblance(semblance: ndarray, leaf_only: bool = True) -> None

Maps semblance values to nodes.

Parameters:

Name	Type	Description	Default
semblance	ndarray	Of shape (n-nodes,).	required
leaf_only	bool	If True, only leaf nodes are mapped. Defaults to True.	True

model_post_init

model_post_init(__context: Any) -> None

Initialize octree. This method is called by the pydantic model.

reduce_axis

reduce_axis(surface: Literal['NE', 'ED', 'ND'] = 'NE', max_level: int = -1, accumulator: Callable[ndarray] = max) -> ndarray

Reduce the octree's nodes to the surface.

Parameters:

Name	Type	Description	Default
surface	Literal['NE', 'ED', 'ND']	Surface to reduce to. Defaults to "NE".	'NE'
max_level	int	Maximum level to reduce to. Defaults to -1.	-1
accumulator	Callable	Accumulator function. Defaults to np.max.	max

Returns:

Type	Description
ndarray	np.ndarray: Of shape (n-nodes, 4) with columns (east, north, depth, value).

reset

reset() -> Self

Reset the octree to its initial state and return it.

save_pickle

save_pickle(filename: Path) -> None

Save the octree to a pickle file.

Parameters:

Name	Type	Description	Default
filename	Path	Filename to save to.	required

set_level

set_level(level: int) -> None

Set the octree to a specific level.

Parameters:

Name	Type	Description	Default
level	int	Level to set the octree to.	required

smallest_node_size

smallest_node_size() -> float

Returns the smallest possible node size.

Returns:

Name	Type	Description
float	float	Smallest possible node size.

total_number_nodes

total_number_nodes() -> int

Returns the total number of nodes of all levels.

Returns:

Name	Type	Description
int	int	Total number of nodes.