Qseek is an earthquake detection and localisation framework. It combines modern machine learning phase detection and robust migration and stacking techniques.
The detector is leveraging Pyrocko and SeisBench, it is highly-performant and can search massive data sets for seismic activity efficiently.
Citation
Marius Paul Isken, Peter Niemz, Jannes M\u00fcnchmeyer, Sebastian Heimann, Simone Cesca, Torsten Dahm, Qseek: A data-driven Framework for Machine-Learning Earthquake Detection, Localization and Characterization, Seismica, 2024, submitted
Seismic swarm activity at Iceland, Reykjanes Peninsula during a 2020 unrest. 15,000+ earthquakes detected, outlining a dike intrusion, preceeding the 2021 Fagradasfjall eruption. Visualized in Pyrocko Sparrow.
"},{"location":"#features","title":"Features","text":"Get Started!
"},{"location":"#build-with","title":"Build with","text":""},{"location":"benchmark/","title":"Benchmark","text":""},{"location":"benchmark/#computation-performance","title":"Computation Performance","text":"Qseek is built for searching in large-N data sets. The implementation is leveraging Python asyncio heavily to implement threading and keeping the CPU busy. It is built on top of highly performant Pyrocko functions implemented in C language. The inference is using PyTorch which enables GPU computation of the seismic imaging functions.
This enables high throughput of seismic data in different scenarios.
Number Stations Throughput in MB Throughput in Waveform data 300+ 50 MB/sec 12 hours/sec 50 200 MB/sec 6 hours/secScanning a 600 GB (~700 years of waveforms) data set costs ~2 days on a 64 cores machine equipped with an Nvidia A100 GPU.
Note
The performance depends heavily on the octree resolution and the number of events detected in the data set.
"},{"location":"benchmark/#related-projects","title":"Related Projects","text":"A list of other projects using stacking and migration approach to back-project seismic energy sources in 3D space:
"},{"location":"benchmark/#lassie-v1","title":"Lassie-v1","text":"Lassie - The friendly Earthquake detector in version 1. Qseek utilizes the same optimized heavy-duty functions for stacking and migration as Lassie v1.
Lassie-v1 on Pyrocko Git
"},{"location":"benchmark/#quakemigrate","title":"QuakeMigrate","text":"QuakeMigrate uses a waveform migration and stacking algorithm to search for coherent seismic phase arrivals across a network of instruments. It produces\u2014from raw data\u2014catalogues of earthquakes with locations, origin times, phase arrival picks, and local magnitude estimates, as well as rigorous estimates of the associated uncertainties.
QuakeMigrate on GitHub
"},{"location":"benchmark/#bpmf","title":"BPMF","text":"Complete framework for earthquake detection and location: Backprojection and matched-filtering (BPMF), with methods for automatic picking, relocation and efficient waveform stacking.
BPMF on GitHub
"},{"location":"benchmark/#loki","title":"Loki","text":"LOKI (LOcation of seismic events through traveltime staKIng) is a code that performs earthquake detection and location using waveform coherence analysis (waveform stacking).
Loki on GitHub
"},{"location":"benchmark/#malmi","title":"MALMI","text":"MALMI (MAchine Learning aided earthquake MIgration location), variant of Loki for detecting and locating earthquakes using ML image functions provided by SeisBench.
MALMI on GitHub
"},{"location":"getting_started/","title":"Getting Started","text":""},{"location":"getting_started/#installation","title":"Installation","text":"The installation is straight-forward using pip or pipx.
From GitHubpip install git+https://github.com/pyrocko/qseek\nor
Using pipxpipx install git+https://github.com/pyrocko/qseek\nThe main entry point in the executeable is the qseek command. The provided command line interface (CLI) and a JSON config file is all what is needed to run the program.
qseek --help\nusage: qseek [-h] [--verbose] [--version]\n {config,search,continue,snuffler,feature-extraction,modules,serve,export,clear-cache,dump-schemas}\n ...\n\nqseek - The wholesome earthquake detector \ud83d\ude80\n\noptions:\n -h, --help show this help message and exit\n --verbose, -v increase verbosity of the log messages, repeat to\n increase. Default level is INFO\n --version show version and exit\n\ncommands:\n Available commands to run qseek. Get command help with `qseek <command>\n --help`.\n\n {config,search,continue,snuffler,feature-extraction,modules,serve,export,clear-cache,dump-schemas}\n config print a new config\n search start a search\n continue continue an existing search\n snuffler start the Pyrocko snuffler to inspect waveforms,\n events and picks\n feature-extraction extract features from an existing run\n modules show available modules\n serve start webserver and serve results from an existing run\n export export detections to different output formats\n clear-cache clear the cach directory\n dump-schemas dump data models to json-schema (development)\nOnce installed you can run the qseek executeable to initialize a new project.
qseek config > my-search.json\nCheck out the my-search.json config file and add your waveform data and velocity models.
Here is a minimal JSON configuration for Qseek.
{\n \"project_dir\": \".\",\n \"stations\": {\n \"pyrocko_station_yamls\": [],\n \"station_xmls\": [],\n \"blacklist\": [],\n \"stations\": [],\n \"max_distance\": null\n },\n \"data_provider\": {\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": null,\n \"persistent\": null,\n \"waveform_dirs\": [\n \"./data\"\n ],\n \"start_time\": null,\n \"end_time\": null,\n \"channel_selector\": null,\n \"n_threads\": 8,\n \"watch_waveforms\": false\n },\n \"pre_processing\": [\n {\n \"process\": \"downsample\",\n \"stations\": [],\n \"sampling_frequency\": 100.0\n },\n {\n \"process\": \"bandpass\",\n \"stations\": [],\n \"corners\": 4,\n \"bandpass\": [\n 0.5,\n 30.0\n ],\n \"demean\": true\n }\n ],\n \"octree\": {\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 1000.0,\n \"n_levels\": 5,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ]\n },\n \"image_functions\": [\n {\n \"image\": \"SeisBench\",\n \"model\": \"PhaseNet\",\n \"pretrained\": \"original\",\n \"window_overlap_samples\": 1500,\n \"torch_use_cuda\": true,\n \"torch_cpu_threads\": 4,\n \"batch_size\": 128,\n \"stack_method\": \"avg\",\n \"rescale_input\": 1.0,\n \"phase_map\": {\n \"P\": \"cake:P\",\n \"S\": \"cake:S\"\n },\n \"weights\": {\n \"P\": 1.0,\n \"S\": 1.0\n }\n }\n ],\n \"ray_tracers\": [\n {\n \"tracer\": \"FastMarchingRayTracer\",\n \"phase\": \"fm:P\",\n \"interpolation_method\": \"cubic\",\n \"nthreads\": 0,\n \"lut_cache_size\": 2147483648,\n \"velocity_model\": {\n \"model\": \"Constant3DVelocityModel\",\n \"grid_spacing\": \"octree\",\n \"velocity\": 5000.0\n },\n \"implementation\": \"scikit-fmm\"\n },\n {\n \"tracer\": \"CakeTracer\",\n \"phases\": {\n \"cake:P\": {\n \"definition\": \"P,p\"\n },\n \"cake:S\": {\n \"definition\": \"S,s\"\n }\n },\n \"earthmodel\": {\n \"filename\": \"/home/marius/.cache/qseek/velocity_models/default.nd\",\n \"format\": \"nd\",\n \"crust2_profile\": \"\",\n \"raw_file_data\": \"\\n-1.00 5.50 3.59 2.7\\n 0.00 5.50 3.59 2.7\\n 1.00 5.50 3.59 2.7\\n 1.00 6.00 3.92 2.7\\n 4.00 6.00 3.92 2.7\\n 4.00 6.20 4.05 2.7\\n 8.00 6.20 4.05 2.7\\n 8.00 6.30 4.12 2.7\\n13.00 6.30 4.12 2.7\\n13.00 6.40 4.18 2.7\\n17.00 6.40 4.18 2.7\\n17.00 6.50 4.25 2.7\\n22.00 6.50 4.25 2.7\\n22.00 6.60 4.31 2.7\\n26.00 6.60 4.31 2.7\\n26.00 6.80 4.44 2.7\\n30.00 6.80 4.44 2.7\\n30.00 8.10 5.29 2.7\\n45.00 8.10 5.29 2.7\\n\"\n },\n \"trim_earth_model_depth\": true,\n \"lut_cache_size\": 2147483648\n },\n {\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n }\n ],\n \"distance_weights\": {\n \"exponent\": 3.0,\n \"radius_meters\": \"mean_interstation\",\n \"waterlevel\": 0.0,\n \"lut_cache_size\": 209715200\n },\n \"station_corrections\": null,\n \"magnitudes\": [],\n \"features\": [],\n \"semblance_sampling_rate\": 100,\n \"detection_threshold\": 0.2,\n \"pick_confidence_threshold\": 0.2,\n \"min_stations\": 3,\n \"absorbing_boundary\": false,\n \"absorbing_boundary_width\": \"root_node_size\",\n \"node_peak_interpolation\": true,\n \"detection_blinding\": \"PT1S\",\n \"power_mean\": 1.0,\n \"window_length\": \"PT5M\",\n \"n_threads_parstack\": \"auto\",\n \"n_threads_argmax\": \"auto\",\n \"plot_octree_surface\": false,\n \"created\": \"2024-11-29T18:13:33.959755Z\"\n}\nFor more details and information about the component, head over to details of the modules.
"},{"location":"getting_started/#starting-the-search","title":"Starting the Search","text":"Once happy with the configuration, start the qseek CLI.
qseek search my-search.json\nThe event detections are exported in Qseek-native JSON, Pyrocko YAML format and as CSV files.
"},{"location":"visualizing_results/#pyrocko-sparrow","title":"Pyrocko Sparrow","text":"For large data sets use the Pyrocko Sparrow to visualise seismic event detections in 3D. Also seismic stations and many other features from the Pyrocko ecosystem can be integrated into the view.
"},{"location":"visualizing_results/#qgis","title":"QGIS","text":"QGIS can be used to import .csv and explore the data in an interactive fashion. Detections can be rendered by e.g. the detection semblance or the calculated magnitude.
At center is a JSON configuration file which is parsed by Pydantic. The following pages will detail how to setup this JSON file for the search.
See the getting started guide for a brief introduction into the CLI.
General configuration conventions are outlines in this guide as well.
Create a new config file.
Using the CLIqseek config\nThe search configuration. This is the entrypoint for the EQ detection and localisation. More information on the submodules (e.g. Octree, Data Provider and other) can be found on subpages in the navigation.
"},{"location":"components/configuration/#exec-3--search-module","title":"Search Module","text":"Config SearchJSONstations Station inventory from StationXML or Pyrocko Station YAML.
data_provider Data provider for waveform data.
pre_processing Pre-processing steps for waveform data.
octree Octree volume for the search.
image_functions Image functions for waveform processing and phase on-set detection.
ray_tracers List of ray tracers for travel time calculation.
distance_weights Spatial weights for distance weighting.
station_corrections Apply station corrections extracted from a previous run.
magnitudes Magnitude calculators to use.
features Event features to extract.
semblance_sampling_rate: 10 | 20 | 25 | 50 | 100 | 200 | 400 Sampling rate for the semblance image function. Choose from 10, 20, 25, 50, 100, 200 or 400 Hz.
detection_threshold: 0.2 Detection threshold for semblance.
pick_confidence_threshold: 0.2 Confidence threshold for picking.
min_stations: 3 Minimum number of stations required for detection and localization.
absorbing_boundary: False | with_surface | without_surface Ignore events that are inside the first root node layer of the octree. If with_surface, all events inside the boundaries of the volume are absorbed. If without_surface, events at the surface are not absorbed.
absorbing_boundary_width Width of the absorbing boundary around the octree volume. If 'octree' the width is set to the root node size of the octree.
node_peak_interpolation: True Interpolate intranode locations for detected events using radial basis functions. If False, the node center location is used for the event hypocentre.
detection_blinding Blinding time in seconds before and after the detection peak. This is used to avoid detecting the same event multiple times. Default is 2 seconds.
power_mean: 1.0 Power mean exponent for stacking and combining the image functions for stacking. A value of 1.0 is the arithmetic mean, 2.0 is the quadratic mean. A higher value will result in sharper detections and low values smooth the stacking function.
window_length Window length for processing. Smaller window size will be less RAM consuming. Default is 5 minutes.
n_threads_parstack Number of threads for stacking and migration. 'auto' will use the maximum number of cores and leaves resources for I/O and other work. 0 uses all available cores.
n_threads_argmax Number of threads for argmax. 'auto' will use the maximum number of cores and leaves resources for I/O and other work. 0 uses all available cores.
{\n \"project_dir\": \".\",\n \"stations\": {\n \"pyrocko_station_yamls\": [],\n \"station_xmls\": [],\n \"blacklist\": [],\n \"stations\": [],\n \"max_distance\": null\n },\n \"data_provider\": {\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": null,\n \"persistent\": null,\n \"waveform_dirs\": [\n \"./data\"\n ],\n \"start_time\": null,\n \"end_time\": null,\n \"channel_selector\": null,\n \"n_threads\": 8,\n \"watch_waveforms\": false\n },\n \"pre_processing\": [\n {\n \"process\": \"downsample\",\n \"stations\": [],\n \"sampling_frequency\": 100.0\n },\n {\n \"process\": \"bandpass\",\n \"stations\": [],\n \"corners\": 4,\n \"bandpass\": [\n 0.5,\n 30.0\n ],\n \"demean\": true\n }\n ],\n \"octree\": {\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 1000.0,\n \"n_levels\": 5,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ]\n },\n \"image_functions\": [\n {\n \"image\": \"SeisBench\",\n \"model\": \"PhaseNet\",\n \"pretrained\": \"original\",\n \"window_overlap_samples\": 1500,\n \"torch_use_cuda\": true,\n \"torch_cpu_threads\": 4,\n \"batch_size\": 128,\n \"stack_method\": \"avg\",\n \"rescale_input\": 1.0,\n \"phase_map\": {\n \"P\": \"cake:P\",\n \"S\": \"cake:S\"\n },\n \"weights\": {\n \"P\": 1.0,\n \"S\": 1.0\n }\n }\n ],\n \"ray_tracers\": [\n {\n \"tracer\": \"CakeTracer\",\n \"phases\": {\n \"cake:P\": {\n \"definition\": \"P,p\"\n },\n \"cake:S\": {\n \"definition\": \"S,s\"\n }\n },\n \"earthmodel\": {\n \"filename\": \"/home/marius/.cache/qseek/velocity_models/default.nd\",\n \"format\": \"nd\",\n \"crust2_profile\": \"\",\n \"raw_file_data\": \"\\n-1.00 5.50 3.59 2.7\\n 0.00 5.50 3.59 2.7\\n 1.00 5.50 3.59 2.7\\n 1.00 6.00 3.92 2.7\\n 4.00 6.00 3.92 2.7\\n 4.00 6.20 4.05 2.7\\n 8.00 6.20 4.05 2.7\\n 8.00 6.30 4.12 2.7\\n13.00 6.30 4.12 2.7\\n13.00 6.40 4.18 2.7\\n17.00 6.40 4.18 2.7\\n17.00 6.50 4.25 2.7\\n22.00 6.50 4.25 2.7\\n22.00 6.60 4.31 2.7\\n26.00 6.60 4.31 2.7\\n26.00 6.80 4.44 2.7\\n30.00 6.80 4.44 2.7\\n30.00 8.10 5.29 2.7\\n45.00 8.10 5.29 2.7\\n\"\n },\n \"trim_earth_model_depth\": true,\n \"lut_cache_size\": 2147483648\n },\n {\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n }\n ],\n \"distance_weights\": {\n \"exponent\": 3.0,\n \"radius_meters\": \"mean_interstation\",\n \"waterlevel\": 0.0,\n \"lut_cache_size\": 209715200\n },\n \"station_corrections\": null,\n \"magnitudes\": [],\n \"features\": [],\n \"semblance_sampling_rate\": 100,\n \"detection_threshold\": 0.2,\n \"pick_confidence_threshold\": 0.2,\n \"min_stations\": 3,\n \"absorbing_boundary\": false,\n \"absorbing_boundary_width\": \"root_node_size\",\n \"node_peak_interpolation\": true,\n \"detection_blinding\": \"PT1S\",\n \"power_mean\": 1.0,\n \"window_length\": \"PT5M\",\n \"n_threads_parstack\": \"auto\",\n \"n_threads_argmax\": \"auto\",\n \"plot_octree_surface\": false,\n \"created\": \"2024-11-29T18:13:34.707783Z\"\n}\nThis is a minimal config which can used to start a Qseek search.
Minimal Qseek Config{\n \"project_dir\": \".\",\n \"stations\": {\n \"station_xmls\": [],\n \"pyrocko_station_yamls\": [\"search/pyrocko-stations.yaml\"],\n },\n \"data_provider\": {\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": \".\",\n \"waveform_dirs\": [\"data/\"],\n },\n \"octree\": {\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 2000.0,\n \"n_levels\": 3,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ],\n \"absorbing_boundary\": 1000.0\n },\n \"image_functions\": [\n {\n \"image\": \"PhaseNet\",\n \"model\": \"ethz\",\n \"torch_use_cuda\": false,\n \"phase_map\": {\n \"P\": \"constant:P\",\n \"S\": \"constant:S\"\n },\n }\n ],\n \"ray_tracers\": [\n {\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n }\n ],\n \"station_corrections\": {},\n \"event_features\": [],\n \"sampling_rate\": 100,\n \"detection_threshold\": 0.05,\n \"detection_blinding\": \"PT2S\",\n \"node_split_threshold\": 0.9,\n \"window_length\": \"PT300S\",\n \"n_threads_parstack\": 0,\n \"n_threads_argmax\": 4,\n}\nStructure of the search and optimisation of the octree, which is focusing in on seismic energy.
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontSize': '14pt'}}}%%\nflowchart LR\n subgraph Seismic Data\n waveforms([\"fa:fa-water Seismic\\nWaveforms\"])\n image{{\"fa:fa-bolt Waveform Image Function\\nPhaseNet / EQTransformer / ...\"}}\n waveforms --> image\n end\n subgraph Travel Time Model\n travelTimes([\"fa:fa-layer-group Seismic\\nTravel Time Model\"])\n stationCorrections{{\"fab:fa-arrows-to-dot Station Corrections\\nSST / SSST\"}}\n travelTimes -->|add| stationCorrections\n end\n subgraph Stacking and Migration\n octree[\"fa:fa-cubes\\nOctree Grid\"]\n detection[\"fa:fa-bullseye Detection\\nand Localisation\"]\n end\n featureExtraction(\"fa:fa-info Extract Event Features\\nMagnitudes, Ground Motion, ...\")\n correctionExtraction(\"fa:fa-stopwatch Extract\\nStation Corrections\")\n\n image --> octree\n stationCorrections --> octree\n detection -.->|\"fa:fa-cube\\nRefine\"| octree\n octree --> detection\n detection --> featureExtraction & correctionExtraction\nBuilding blocks of the specific stacking and migration method for earthquake detection, localisation and characterisation.
"},{"location":"components/general/","title":"General Settings","text":""},{"location":"components/general/#paths","title":"Paths","text":"Paths can be relative to the location of the config file or absolute. File paths and directory paths are checked whether they exist.
"},{"location":"components/general/#date-and-time","title":"Date and Time","text":"Serialisation of time, dates and date times and durations follow ISO8601 format with timezone information. E.g. 2023-10-28T01:21:21.003Z.
Duration are serialized like PT600S, this example shows a duration of 600 seconds, 10 minutes.
!!!+ note Timezone Info All datetimes are timezone aware! For UTC this is the Z or +00:00 suffix. Also other offsets can be defined according to ISO8601.
{\n \"start_time\": \"2023-10-28T01:21:21.003+00:00\",\n \"end_time\": \"2023-10-28T01:21:21.003+00:00\",\n \"duration\": \"PT600S\"\n}\nGeographic locations have a geographic reference and a relative shift in meters. The octree or velocity models are referenced using Location objects.
All distances, depths and elevations are given in meters.
"},{"location":"components/general/#exec-4--location-module","title":"Location Module","text":"Config LocationJSONlat: PydanticUndefined Latitude in degrees.
lon: PydanticUndefined Longitude in degrees.
east_shift: 0.0 East shift towards geographical reference in meters.
north_shift: 0.0 North shift towards geographical reference in meters.
elevation: 0.0 Elevation in meters.
depth: 0.0 Depth in meters, positive is down.
JSON for Location{\n \"lat\": 52.3825,\n \"lon\": 13.0644,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n}\nFor image functions this version of Qseek relies heavily on machine learning pickers delivered by SeisBench.
"},{"location":"components/image_function/#seisbench-image-function","title":"SeisBench Image Function","text":"SeisBench offers access to a variety of machine learning phase pickers pre-trained on various data sets.
Citation PhaseNet
Zhu, Weiqiang, and Gregory C. Beroza. \"PhaseNet: A Deep-Neural-Network-Based Seismic Arrival Time Picking Method.\" arXiv preprint arXiv:1803.03211 (2018).
"},{"location":"components/image_function/#exec-5--seisbench-module","title":"SeisBench Module","text":"PhaseNet image function. For more details see SeisBench documentation.
Config SeisBenchJSONmodel: PhaseNet | EQTransformer | OBSTransformer | LFEDetect The model to use for the image function. Currently supported models are PhaseNet, EQTransformer, GPD, OBSTransformer, LFEDetect.
pretrained: cascadia | cms | diting | dummy | ethz | geofon | instance | iquique | jcms | jcs | jms | lendb | mexico | nankai | neic | obs | obst2024 | original | original_nonconservative | san_andreas | scedc | stead | volpick SeisBench pre-trained model to use. Choose from ethz, geofon, instance, iquique, lendb, neic, obs, original, scedc, stead. For more details see SeisBench documentation
window_overlap_samples: 1500 Window overlap in samples.
torch_use_cuda Use CUDA for inference. If True use default device, if int use the specified device.
torch_cpu_threads: 4 Number of CPU threads to use if only CPU is used.
batch_size: 128 Batch size for inference, larger values can improve performance.
stack_method: avg | max Method to stack the overlaping blocks internally. Choose from avg and max.
rescale_input: 1.0 Upscale input by factor. This augments the input data from e.g. 100 Hz to 50 Hz (factor: 2). Can be useful for high-frequency microseismic events.
phase_map Phase mapping from SeisBench PhaseNet to Lassie phases.
weights Weights for each phase.
JSON for SeisBench{\n \"image\": \"SeisBench\",\n \"model\": \"PhaseNet\",\n \"pretrained\": \"original\",\n \"window_overlap_samples\": 1500,\n \"torch_use_cuda\": true,\n \"torch_cpu_threads\": 4,\n \"batch_size\": 128,\n \"stack_method\": \"avg\",\n \"rescale_input\": 1.0,\n \"phase_map\": {\n \"P\": \"cake:P\",\n \"S\": \"cake:S\"\n },\n \"weights\": {\n \"P\": 1.0,\n \"S\": 1.0\n }\n}\nA 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.
"},{"location":"components/octree/#exec-6--octree-module","title":"Octree Module","text":"Config OctreeJSONlocation 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{\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 1000.0,\n \"n_levels\": 5,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ]\n}\npydantic-model","text":" 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 \u2192 location check_limits pydantic-field","text":"depth_bounds: Range = Range(0 * KM, 20 * KM)\nDepth bounds of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.east_bounds","title":"east_boundspydantic-field","text":"east_bounds: Range = Range(-10 * KM, 10 * KM)\nEast bounds of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.leaf_nodes","title":"leaf_nodespydantic-field","text":"leaf_nodes: list[Node]\nGet all leaf nodes of the octree.
Returns:
Type Descriptionlist[Node] list[Node]: List of leaf nodes.
"},{"location":"components/octree/#qseek.octree.Octree.location","title":"locationpydantic-field","text":"location: Location = Location(lat=0.0, lon=0.0)\nThe geographical center of the octree.
"},{"location":"components/octree/#qseek.octree.Octree.n_leaf_nodes","title":"n_leaf_nodespydantic-field","text":"n_leaf_nodes: int\nNumber of nodes in the octree.
"},{"location":"components/octree/#qseek.octree.Octree.n_levels","title":"n_levelspydantic-field","text":"n_levels: int = 5\nNumber of levels in the octree, defining the final resolution of the detection. Default is 5.
"},{"location":"components/octree/#qseek.octree.Octree.n_nodes","title":"n_nodespydantic-field","text":"n_nodes: int\nNumber of nodes in the octree.
"},{"location":"components/octree/#qseek.octree.Octree.nodes","title":"nodespydantic-field","text":"nodes: list[Node]\nList of nodes in the octree.
"},{"location":"components/octree/#qseek.octree.Octree.north_bounds","title":"north_boundspydantic-field","text":"north_bounds: Range = Range(-10 * KM, 10 * KM)\nNorth bounds of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.root_node_size","title":"root_node_sizepydantic-field","text":"root_node_size: PositiveFloat = 1 * KM\nSize of the root node at the initial level (level 0) in meters.
"},{"location":"components/octree/#qseek.octree.Octree.semblance","title":"semblancepydantic-field","text":"semblance: ndarray\nReturns the semblance values of all nodes.
"},{"location":"components/octree/#qseek.octree.Octree.volume","title":"volumepydantic-field","text":"volume: float\nVolume of the octree in cubic meters.
"},{"location":"components/octree/#qseek.octree.Octree.cached_bottom","title":"cached_bottom","text":"cached_bottom() -> Self\nReturns a copy of the octree refined to the cached bottom nodes.
Raises:
Type DescriptionEnvironmentError If the octree has never been split.
Returns:
Name Type DescriptionSelf Self Copy of the octree with cached bottom nodes.
"},{"location":"components/octree/#qseek.octree.Octree.check_limits","title":"check_limitspydantic-validator","text":"check_limits() -> Octree\nCheck that the size limits are valid.
"},{"location":"components/octree/#qseek.octree.Octree.clear","title":"clear","text":"clear() -> None\nClear the octree's cached data.
"},{"location":"components/octree/#qseek.octree.Octree.distances_stations","title":"distances_stations","text":"distances_stations(stations: Stations) -> ndarray\nReturns the 3D distances from all nodes to all stations.
Parameters:
Name Type Description Defaultstations Stations Stations to calculate distance to.
requiredReturns:
Type Descriptionndarray np.ndarray: Of shape (n-nodes, n-stations).
"},{"location":"components/octree/#qseek.octree.Octree.distances_stations_surface","title":"distances_stations_surface","text":"distances_stations_surface(stations: Stations) -> ndarray\nReturns the surface distance from all nodes to all stations.
Parameters:
Name Type Description Defaultstations Stations Stations to calculate distance to.
requiredReturns:
Type Descriptionndarray np.ndarray: Distances in shape (n-nodes, n-stations).
"},{"location":"components/octree/#qseek.octree.Octree.extent","title":"extent","text":"extent() -> tuple[float, float, float]\nReturns the extent of the octree.
Returns:
Type Descriptiontuple[float, float, float] tuple[float, float, float]: EW, NS and depth extent of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.get_corners","title":"get_corners","text":"get_corners() -> list[Location]\nGet the corners of the octree.
Returns:
Type Descriptionlist[Location] list[Location]: List of locations.
"},{"location":"components/octree/#qseek.octree.Octree.get_nodes","title":"get_nodes","text":"get_nodes(indices: Iterable[int]) -> list[Node]\nRetrieves a list of nodes from the octree based on the given indices.
Parameters:
Name Type Description Defaultindices Iterable[int] The indices of the nodes to retrieve.
requiredReturns:
Type Descriptionlist[Node] list[Node]: A list of nodes corresponding to the given indices.
"},{"location":"components/octree/#qseek.octree.Octree.get_nodes_by_threshold","title":"get_nodes_by_threshold","text":"get_nodes_by_threshold(\n semblance_threshold: float = 0.0,\n) -> list[Node]\nGet all nodes with a semblance above a threshold.
Parameters:
Name Type Description Defaultsemblance_threshold float Semblance threshold. Default is 0.0.
0.0 Returns:
Type Descriptionlist[Node] list[Node]: List of nodes.
"},{"location":"components/octree/#qseek.octree.Octree.get_nodes_level","title":"get_nodes_level","text":"get_nodes_level(level: int = 0) -> list[Node]\nGet all nodes at a specific level.
Parameters:
Name Type Description Defaultlevel int Level to get nodes from.
0 Returns:
Type Descriptionlist[Node] list[Node]: List of nodes.
"},{"location":"components/octree/#qseek.octree.Octree.interpolate_max_semblance","title":"interpolate_max_semblanceasync","text":"interpolate_max_semblance(peak_node: Node) -> Location\nInterpolate 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 DescriptionLocation Location Location of the maximum semblance value.
Raises:
Type DescriptionAttributeError If no semblance values are set.
"},{"location":"components/octree/#qseek.octree.Octree.map_semblance","title":"map_semblance","text":"map_semblance(\n semblance: ndarray, leaf_only: bool = True\n) -> None\nMaps semblance values to nodes.
Parameters:
Name Type Description Defaultsemblance ndarray Of shape (n-nodes,).
requiredleaf_only bool If True, only leaf nodes are mapped. Defaults to True.
True"},{"location":"components/octree/#qseek.octree.Octree.model_post_init","title":"model_post_init","text":"model_post_init(__context: Any) -> None\nInitialize octree. This method is called by the pydantic model.
"},{"location":"components/octree/#qseek.octree.Octree.reduce_axis","title":"reduce_axis","text":"reduce_axis(\n surface: Literal[\"NE\", \"ED\", \"ND\"] = \"NE\",\n max_level: int = -1,\n accumulator: Callable[ndarray] = max,\n) -> ndarray\nReduce the octree's nodes to the surface.
Parameters:
Name Type Description Defaultsurface 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 Descriptionndarray np.ndarray: Of shape (n-nodes, 4) with columns (east, north, depth, value).
"},{"location":"components/octree/#qseek.octree.Octree.reset","title":"reset","text":"reset() -> Self\nReset the octree to its initial state and return it.
"},{"location":"components/octree/#qseek.octree.Octree.save_pickle","title":"save_pickle","text":"save_pickle(filename: Path) -> None\nSave the octree to a pickle file.
Parameters:
Name Type Description Defaultfilename Path Filename to save to.
required"},{"location":"components/octree/#qseek.octree.Octree.set_level","title":"set_level","text":"set_level(level: int) -> None\nSet the octree to a specific level.
Parameters:
Name Type Description Defaultlevel int Level to set the octree to.
required"},{"location":"components/octree/#qseek.octree.Octree.smallest_node_size","title":"smallest_node_size","text":"smallest_node_size() -> float\nReturns the smallest possible node size.
Returns:
Name Type Descriptionfloat float Smallest possible node size.
"},{"location":"components/octree/#qseek.octree.Octree.total_number_nodes","title":"total_number_nodes","text":"total_number_nodes() -> int\nReturns the total number of nodes of all levels.
Returns:
Name Type Descriptionint int Total number of nodes.
"},{"location":"components/ray_tracer/","title":"Ray Tracers","text":"The calculation of seismic travel times is a cornerstone for the migration and stacking approach. Qseek supports different ray tracers for travel time calculation, which can be adapted for different geological settings.
"},{"location":"components/ray_tracer/#constant-velocity","title":"Constant Velocity","text":"The constant velocity models is trivial and follows:
\\[ t_{P} = \\frac{d}{v_P} \\]This module is used for simple use cases and cross-referencing testing.
"},{"location":"components/ray_tracer/#exec-7--constantvelocitytracer-module","title":"ConstantVelocityTracer Module","text":"Travel time tracer with a constant velocity.
Config ConstantVelocityTracerJSONphase: constant:P Name of the phase.
velocity: 5000.0 Constant velocity of the phase in m/s.
JSON for ConstantVelocityTracer{\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n}\nCalculation of travel times in 1D layered media is based on the Pyrocko Cake ray tracer.
Pyrocko Cake 1D ray tracer for travel time calculation in 1D layered media
"},{"location":"components/ray_tracer/#exec-8--caketracer-module","title":"CakeTracer Module","text":"Travel time ray tracer for 1D layered earth models.
Config CakeTracerJSONphases Dictionary of phases and timings to calculate.
earthmodel Earth model to calculate travel times for.
trim_earth_model_depth: True Trim earth model to max depth of the octree.
lut_cache_size Size of the LUT cache. Default is 2G.
{\n \"tracer\": \"CakeTracer\",\n \"phases\": {\n \"cake:P\": {\n \"definition\": \"P,p\"\n },\n \"cake:S\": {\n \"definition\": \"S,s\"\n }\n },\n \"earthmodel\": {\n \"filename\": \"/home/marius/.cache/qseek/velocity_models/default.nd\",\n \"format\": \"nd\",\n \"crust2_profile\": \"\"\n },\n \"trim_earth_model_depth\": true,\n \"lut_cache_size\": 2147483648\n}\nWe implement the fast marching method for calculating first arrivals of waves in 3D volumes. Currently three different 3D velocity models are supported:
Conceptual 2D visualisation for seismic traveltimes calculation in heterogenous media using the fast-marching method for the Eikonal solution is presented. Traveltimes from the receiving station at the surface (indicated by a yellow triangle) towards the subsurface grid are calculated, resulting in station-specifig traveltimes for all potential source locations simultaneously.
"},{"location":"components/ray_tracer/#exec-9--fastmarchingtracer-module","title":"FastMarchingTracer Module","text":"Travel time ray tracer using the Fast Marching Method for 3D earth models.
Config FastMarchingTracerJSONinterpolation_method: nearest | linear | cubic Interpolation method for travel times in the volume. Choose from nearest, linear or cubic.
nthreads: 0 Number of threads to use for travel time. If set to 0, cpu_count*2 will be used.
lut_cache_size Size of the LUT cache. Default is 2G.
velocity_model Velocity model for the ray tracer.
implementation: pyrocko | scikit-fmm Implementation of the Fast Marching Method. Pyrocko only supports first-order FMM for now.
JSON for FastMarchingTracer{\n \"tracer\": \"FastMarchingRayTracer\",\n \"phase\": \"fm:P\",\n \"interpolation_method\": \"cubic\",\n \"nthreads\": 0,\n \"lut_cache_size\": 2147483648,\n \"velocity_model\": {\n \"model\": \"Constant3DVelocityModel\",\n \"grid_spacing\": \"octree\",\n \"velocity\": 5000.0\n },\n \"implementation\": \"scikit-fmm\"\n}\nFor quality check, all 3D velocity models are exported to vtk/ folder as .vti files. Use ParaView to inspect and explore the velocity models.
Seismic velocity model of the Utah FORGE testbed site, visualized in ParaView.
"},{"location":"components/station_corrections/","title":"Station Corrections","text":"Station corrections can be extract from previous runs to refine the localisation accuracy. The corrections can also help to improve the semblance find more events in a dataset.
"},{"location":"components/station_corrections/#station-specific-corrections","title":"Station Specific Corrections","text":"Statistics of station delay times.
"},{"location":"components/station_corrections/#exec-10--stationcorrections-module","title":"StationCorrections Module","text":"Config StationCorrectionsJSONimport_rundir Path to rundir, to extract the station corrections from.
plot_corrections: False Plot the station corrections statistics.
statistic: median | average Arithmetic measure for the traveltime delays. Choose from median and average.
weighting: none | confidence | semblance | add-confidence-semblance | mul-confidence-semblance Weighting of the traveltime delays. Choose from none, confidence, semblance, add-confidence-semblance and mul-confidence-semblance.
min_num_picks: 50 Minimum number of picks at a station required to calculate station corrections.
min_distance_border: 500.0 Minimum event distance from the border of the octree grid.
JSON for StationCorrections{\n \"corrections\": \"StationCorrections\",\n \"import_rundir\": \".\",\n \"plot_corrections\": false,\n \"statistic\": \"median\",\n \"weighting\": \"mul-confidence-semblance\",\n \"min_num_picks\": 50,\n \"min_distance_border\": 500.0\n}\nDelay volume for a selected stations.
"},{"location":"components/station_corrections/#exec-11--sourcespecificstationcorrections-module","title":"SourceSpecificStationCorrections Module","text":"Source specific station travel time corrections.
Config SourceSpecificStationCorrectionsJSONimport_rundir Path to rundir, to extract the station corrections from.
weighting: none | confidence | semblance | add-confidence-semblance | mul-confidence-semblance Weighting of the traveltime delays. Choose from none, confidence, semblance, add-confidence-semblance and mul-confidence-semblance.
min_confidence: 5.0 Minimum cumulative pick confidence within the sphere surrouding the node. If the cumulative pick confidence inside the sphere is below this value, the sphere radius is increased until enough picks are inside the sphere.
min_distance_border: 500.0 Minimum event distance from the border of the octree grid.
spatial_weighting_exponent: 3.0 The exponent of the spatial weighting function around the sphere.
octree_level: 0 The octree level (resolution) to use for the station corrections. This is the SSST grid spacing.
delay_interpolation_method: nearest | linear | cubic The interpolation method to use for interpolating delays between nodes.
lut_cache_size Size of the LUT cache. Default is 2G.
{\n \"corrections\": \"SourceSpecificStationCorrections\",\n \"import_rundir\": \".\",\n \"weighting\": \"mul-confidence-semblance\",\n \"min_confidence\": 5.0,\n \"min_distance_border\": 500.0,\n \"spatial_weighting_exponent\": 3.0,\n \"octree_level\": 0,\n \"delay_interpolation_method\": \"linear\",\n \"lut_cache_size\": 2147483648\n}\nMeta data is required primarily for station locations and codes.
Supported data formats are:
Metadata does not need to include response information for pure detection and localisation. If local magnitudes ML are extracted, response information is required.
"},{"location":"components/station_metadata/#exec-12--stations-module","title":"Stations Module","text":"Config StationsJSONpyrocko_station_yamls List of Pyrocko station YAML files.
station_xmls List of StationXML files or directories containing StationXML (.xml) files.
blacklist Blacklist stations and exclude from detecion. Format is ['NET.STA.LOC', ...].
max_distance Maximum distance in meters from the centroid location to include stations for detection. If None, all stations are included.
JSON for Stations{\n \"pyrocko_station_yamls\": [],\n \"station_xmls\": [],\n \"blacklist\": [],\n \"stations\": [],\n \"max_distance\": null\n}\nThe seismic can be delivered in MiniSeed or any other format compatible with Pyrocko. Qseek utilizes the Pyrocko Squirrel for fast and asynchronous data access.
To prepare your data for EQ detection and localisation, organize it in a MiniSeed file or an SDS structure.
"},{"location":"components/waveform_data/#exec-13--pyrockosquirrel-module","title":"PyrockoSquirrel Module","text":"Waveform provider using Pyrocko's Squirrel.
Config PyrockoSquirrelJSONenvironment Path to a Pyrocko Squirrel environment.
persistent Name of the Squirrel's persistent collection for faster loading of large data sets.
waveform_dirs List of directories holding the waveform files.
start_time Start time for the search in ISO8601 including timezone. E.g. 2024-12-30T00:00:00Z.
end_time End time for the search in ISO8601 including timezone. E.g. 2024-12-31T00:00:00Z.
channel_selector Channel selector for waveforms, e.g. ['HH', 'EN'].
n_threads: 8 Number of threads for loading waveforms, important for large data sets.
watch_waveforms Watch the waveform directories for changes. If True it will check every ten minutes. If a timedelta is provided it will check every specified time. Default is False.
{\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": null,\n \"persistent\": \"docs\",\n \"waveform_dirs\": [\n \"./data\"\n ],\n \"start_time\": null,\n \"end_time\": null,\n \"channel_selector\": null,\n \"n_threads\": 8,\n \"watch_waveforms\": false\n}\nQseek is an earthquake detection and localisation framework. It combines modern machine learning phase detection and robust migration and stacking techniques.
The detector is leveraging Pyrocko and SeisBench, it is highly-performant and can search massive data sets for seismic activity efficiently.
Citation
Marius Paul Isken, Peter Niemz, Jannes M\u00fcnchmeyer, Sebastian Heimann, Simone Cesca, Torsten Dahm, Qseek: A data-driven Framework for Machine-Learning Earthquake Detection, Localization and Characterization, Seismica, 2024, submitted
Seismic swarm activity at Iceland, Reykjanes Peninsula during a 2020 unrest. 15,000+ earthquakes detected, outlining a dike intrusion, preceeding the 2021 Fagradasfjall eruption. Visualized in Pyrocko Sparrow.
"},{"location":"#features","title":"Features","text":"Get Started!
"},{"location":"#build-with","title":"Build with","text":""},{"location":"benchmark/","title":"Benchmark","text":""},{"location":"benchmark/#computation-performance","title":"Computation Performance","text":"Qseek is built for searching in large-N data sets. The implementation is leveraging Python asyncio heavily to implement threading and keeping the CPU busy. It is built on top of highly performant Pyrocko functions implemented in C language. The inference is using PyTorch which enables GPU computation of the seismic imaging functions.
This enables high throughput of seismic data in different scenarios.
Number Stations Throughput in MB Throughput in Waveform data 300+ 50 MB/sec 12 hours/sec 50 200 MB/sec 6 hours/secScanning a 600 GB (~700 years of waveforms) data set costs ~2 days on a 64 cores machine equipped with an Nvidia A100 GPU.
Note
The performance depends heavily on the octree resolution and the number of events detected in the data set.
"},{"location":"benchmark/#related-projects","title":"Related Projects","text":"A list of other projects using stacking and migration approach to back-project seismic energy sources in 3D space:
"},{"location":"benchmark/#lassie-v1","title":"Lassie-v1","text":"Lassie - The friendly Earthquake detector in version 1. Qseek utilizes the same optimized heavy-duty functions for stacking and migration as Lassie v1.
Lassie-v1 on Pyrocko Git
"},{"location":"benchmark/#quakemigrate","title":"QuakeMigrate","text":"QuakeMigrate uses a waveform migration and stacking algorithm to search for coherent seismic phase arrivals across a network of instruments. It produces\u2014from raw data\u2014catalogues of earthquakes with locations, origin times, phase arrival picks, and local magnitude estimates, as well as rigorous estimates of the associated uncertainties.
QuakeMigrate on GitHub
"},{"location":"benchmark/#bpmf","title":"BPMF","text":"Complete framework for earthquake detection and location: Backprojection and matched-filtering (BPMF), with methods for automatic picking, relocation and efficient waveform stacking.
BPMF on GitHub
"},{"location":"benchmark/#loki","title":"Loki","text":"LOKI (LOcation of seismic events through traveltime staKIng) is a code that performs earthquake detection and location using waveform coherence analysis (waveform stacking).
Loki on GitHub
"},{"location":"benchmark/#malmi","title":"MALMI","text":"MALMI (MAchine Learning aided earthquake MIgration location), variant of Loki for detecting and locating earthquakes using ML image functions provided by SeisBench.
MALMI on GitHub
"},{"location":"getting_started/","title":"Getting Started","text":""},{"location":"getting_started/#installation","title":"Installation","text":"The installation is straight-forward using pip or pipx.
From GitHubpip install git+https://github.com/pyrocko/qseek\nor
Using pipxpipx install git+https://github.com/pyrocko/qseek\nThe main entry point in the executeable is the qseek command. The provided command line interface (CLI) and a JSON config file is all what is needed to run the program.
qseek --help\nusage: qseek [-h] [--verbose] [--version]\n {config,search,continue,snuffler,feature-extraction,modules,serve,export,clear-cache,dump-schemas}\n ...\n\nqseek - The wholesome earthquake detector \ud83d\ude80\n\noptions:\n -h, --help show this help message and exit\n --verbose, -v increase verbosity of the log messages, repeat to\n increase. Default level is INFO\n --version show version and exit\n\ncommands:\n Available commands to run qseek. Get command help with `qseek <command>\n --help`.\n\n {config,search,continue,snuffler,feature-extraction,modules,serve,export,clear-cache,dump-schemas}\n config print a new config\n search start a search\n continue continue an existing search\n snuffler start the Pyrocko snuffler to inspect waveforms,\n events and picks\n feature-extraction extract features from an existing run\n modules show available modules\n serve start webserver and serve results from an existing run\n export export detections to different output formats\n clear-cache clear the cach directory\n dump-schemas dump data models to json-schema (development)\nOnce installed you can run the qseek executeable to initialize a new project.
qseek config > my-search.json\nCheck out the my-search.json config file and add your waveform data and velocity models.
Here is a minimal JSON configuration for Qseek.
{\n \"project_dir\": \".\",\n \"stations\": {\n \"pyrocko_station_yamls\": [],\n \"station_xmls\": [],\n \"blacklist\": [],\n \"stations\": [],\n \"max_distance\": null\n },\n \"data_provider\": {\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": null,\n \"persistent\": null,\n \"waveform_dirs\": [\n \"./data\"\n ],\n \"start_time\": null,\n \"end_time\": null,\n \"channel_selector\": null,\n \"n_threads\": 8,\n \"watch_waveforms\": false\n },\n \"pre_processing\": [\n {\n \"process\": \"downsample\",\n \"stations\": [],\n \"sampling_frequency\": 100.0\n },\n {\n \"process\": \"bandpass\",\n \"stations\": [],\n \"corners\": 4,\n \"bandpass\": [\n 0.5,\n 30.0\n ],\n \"demean\": true\n }\n ],\n \"octree\": {\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 1000.0,\n \"n_levels\": 5,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ]\n },\n \"image_functions\": [\n {\n \"image\": \"SeisBench\",\n \"model\": \"PhaseNet\",\n \"pretrained\": \"original\",\n \"window_overlap_samples\": 1500,\n \"torch_use_cuda\": true,\n \"torch_cpu_threads\": 4,\n \"batch_size\": 128,\n \"stack_method\": \"avg\",\n \"rescale_input\": 1.0,\n \"phase_map\": {\n \"P\": \"cake:P\",\n \"S\": \"cake:S\"\n },\n \"weights\": {\n \"P\": 1.0,\n \"S\": 1.0\n }\n }\n ],\n \"ray_tracers\": [\n {\n \"tracer\": \"FastMarchingRayTracer\",\n \"phase\": \"fm:P\",\n \"interpolation_method\": \"cubic\",\n \"nthreads\": 0,\n \"lut_cache_size\": 2147483648,\n \"velocity_model\": {\n \"model\": \"Constant3DVelocityModel\",\n \"grid_spacing\": \"octree\",\n \"velocity\": 5000.0\n },\n \"implementation\": \"scikit-fmm\"\n },\n {\n \"tracer\": \"CakeTracer\",\n \"phases\": {\n \"cake:P\": {\n \"definition\": \"P,p\"\n },\n \"cake:S\": {\n \"definition\": \"S,s\"\n }\n },\n \"earthmodel\": {\n \"filename\": \"/home/marius/.cache/qseek/velocity_models/default.nd\",\n \"format\": \"nd\",\n \"crust2_profile\": \"\",\n \"raw_file_data\": \"\\n-1.00 5.50 3.59 2.7\\n 0.00 5.50 3.59 2.7\\n 1.00 5.50 3.59 2.7\\n 1.00 6.00 3.92 2.7\\n 4.00 6.00 3.92 2.7\\n 4.00 6.20 4.05 2.7\\n 8.00 6.20 4.05 2.7\\n 8.00 6.30 4.12 2.7\\n13.00 6.30 4.12 2.7\\n13.00 6.40 4.18 2.7\\n17.00 6.40 4.18 2.7\\n17.00 6.50 4.25 2.7\\n22.00 6.50 4.25 2.7\\n22.00 6.60 4.31 2.7\\n26.00 6.60 4.31 2.7\\n26.00 6.80 4.44 2.7\\n30.00 6.80 4.44 2.7\\n30.00 8.10 5.29 2.7\\n45.00 8.10 5.29 2.7\\n\"\n },\n \"trim_earth_model_depth\": true,\n \"lut_cache_size\": 2147483648\n },\n {\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n }\n ],\n \"distance_weights\": {\n \"exponent\": 3.0,\n \"radius_meters\": \"mean_interstation\",\n \"waterlevel\": 0.0,\n \"lut_cache_size\": 209715200\n },\n \"station_corrections\": null,\n \"magnitudes\": [],\n \"features\": [],\n \"semblance_sampling_rate\": 100,\n \"detection_threshold\": 0.2,\n \"pick_confidence_threshold\": 0.2,\n \"min_stations\": 3,\n \"absorbing_boundary\": false,\n \"absorbing_boundary_width\": \"root_node_size\",\n \"node_peak_interpolation\": true,\n \"detection_blinding\": \"PT1S\",\n \"power_mean\": 1.0,\n \"window_length\": \"PT5M\",\n \"n_threads_parstack\": \"auto\",\n \"n_threads_argmax\": \"auto\",\n \"plot_octree_surface\": false,\n \"created\": \"2024-11-29T18:14:02.141680Z\"\n}\nFor more details and information about the component, head over to details of the modules.
"},{"location":"getting_started/#starting-the-search","title":"Starting the Search","text":"Once happy with the configuration, start the qseek CLI.
qseek search my-search.json\nThe event detections are exported in Qseek-native JSON, Pyrocko YAML format and as CSV files.
"},{"location":"visualizing_results/#pyrocko-sparrow","title":"Pyrocko Sparrow","text":"For large data sets use the Pyrocko Sparrow to visualise seismic event detections in 3D. Also seismic stations and many other features from the Pyrocko ecosystem can be integrated into the view.
"},{"location":"visualizing_results/#qgis","title":"QGIS","text":"QGIS can be used to import .csv and explore the data in an interactive fashion. Detections can be rendered by e.g. the detection semblance or the calculated magnitude.
At center is a JSON configuration file which is parsed by Pydantic. The following pages will detail how to setup this JSON file for the search.
See the getting started guide for a brief introduction into the CLI.
General configuration conventions are outlines in this guide as well.
Create a new config file.
Using the CLIqseek config\nThe search configuration. This is the entrypoint for the EQ detection and localisation. More information on the submodules (e.g. Octree, Data Provider and other) can be found on subpages in the navigation.
"},{"location":"components/configuration/#exec-3--search-module","title":"Search Module","text":"Config SearchJSONstations Station inventory from StationXML or Pyrocko Station YAML.
data_provider Data provider for waveform data.
pre_processing Pre-processing steps for waveform data.
octree Octree volume for the search.
image_functions Image functions for waveform processing and phase on-set detection.
ray_tracers List of ray tracers for travel time calculation.
distance_weights Spatial weights for distance weighting.
station_corrections Apply station corrections extracted from a previous run.
magnitudes Magnitude calculators to use.
features Event features to extract.
semblance_sampling_rate: 10 | 20 | 25 | 50 | 100 | 200 | 400 Sampling rate for the semblance image function. Choose from 10, 20, 25, 50, 100, 200 or 400 Hz.
detection_threshold: 0.2 Detection threshold for semblance.
pick_confidence_threshold: 0.2 Confidence threshold for picking.
min_stations: 3 Minimum number of stations required for detection and localization.
absorbing_boundary: False | with_surface | without_surface Ignore events that are inside the first root node layer of the octree. If with_surface, all events inside the boundaries of the volume are absorbed. If without_surface, events at the surface are not absorbed.
absorbing_boundary_width Width of the absorbing boundary around the octree volume. If 'octree' the width is set to the root node size of the octree.
node_peak_interpolation: True Interpolate intranode locations for detected events using radial basis functions. If False, the node center location is used for the event hypocentre.
detection_blinding Blinding time in seconds before and after the detection peak. This is used to avoid detecting the same event multiple times. Default is 2 seconds.
power_mean: 1.0 Power mean exponent for stacking and combining the image functions for stacking. A value of 1.0 is the arithmetic mean, 2.0 is the quadratic mean. A higher value will result in sharper detections and low values smooth the stacking function.
window_length Window length for processing. Smaller window size will be less RAM consuming. Default is 5 minutes.
n_threads_parstack Number of threads for stacking and migration. 'auto' will use the maximum number of cores and leaves resources for I/O and other work. 0 uses all available cores.
n_threads_argmax Number of threads for argmax. 'auto' will use the maximum number of cores and leaves resources for I/O and other work. 0 uses all available cores.
{\n \"project_dir\": \".\",\n \"stations\": {\n \"pyrocko_station_yamls\": [],\n \"station_xmls\": [],\n \"blacklist\": [],\n \"stations\": [],\n \"max_distance\": null\n },\n \"data_provider\": {\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": null,\n \"persistent\": null,\n \"waveform_dirs\": [\n \"./data\"\n ],\n \"start_time\": null,\n \"end_time\": null,\n \"channel_selector\": null,\n \"n_threads\": 8,\n \"watch_waveforms\": false\n },\n \"pre_processing\": [\n {\n \"process\": \"downsample\",\n \"stations\": [],\n \"sampling_frequency\": 100.0\n },\n {\n \"process\": \"bandpass\",\n \"stations\": [],\n \"corners\": 4,\n \"bandpass\": [\n 0.5,\n 30.0\n ],\n \"demean\": true\n }\n ],\n \"octree\": {\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 1000.0,\n \"n_levels\": 5,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ]\n },\n \"image_functions\": [\n {\n \"image\": \"SeisBench\",\n \"model\": \"PhaseNet\",\n \"pretrained\": \"original\",\n \"window_overlap_samples\": 1500,\n \"torch_use_cuda\": true,\n \"torch_cpu_threads\": 4,\n \"batch_size\": 128,\n \"stack_method\": \"avg\",\n \"rescale_input\": 1.0,\n \"phase_map\": {\n \"P\": \"cake:P\",\n \"S\": \"cake:S\"\n },\n \"weights\": {\n \"P\": 1.0,\n \"S\": 1.0\n }\n }\n ],\n \"ray_tracers\": [\n {\n \"tracer\": \"CakeTracer\",\n \"phases\": {\n \"cake:P\": {\n \"definition\": \"P,p\"\n },\n \"cake:S\": {\n \"definition\": \"S,s\"\n }\n },\n \"earthmodel\": {\n \"filename\": \"/home/marius/.cache/qseek/velocity_models/default.nd\",\n \"format\": \"nd\",\n \"crust2_profile\": \"\",\n \"raw_file_data\": \"\\n-1.00 5.50 3.59 2.7\\n 0.00 5.50 3.59 2.7\\n 1.00 5.50 3.59 2.7\\n 1.00 6.00 3.92 2.7\\n 4.00 6.00 3.92 2.7\\n 4.00 6.20 4.05 2.7\\n 8.00 6.20 4.05 2.7\\n 8.00 6.30 4.12 2.7\\n13.00 6.30 4.12 2.7\\n13.00 6.40 4.18 2.7\\n17.00 6.40 4.18 2.7\\n17.00 6.50 4.25 2.7\\n22.00 6.50 4.25 2.7\\n22.00 6.60 4.31 2.7\\n26.00 6.60 4.31 2.7\\n26.00 6.80 4.44 2.7\\n30.00 6.80 4.44 2.7\\n30.00 8.10 5.29 2.7\\n45.00 8.10 5.29 2.7\\n\"\n },\n \"trim_earth_model_depth\": true,\n \"lut_cache_size\": 2147483648\n },\n {\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n }\n ],\n \"distance_weights\": {\n \"exponent\": 3.0,\n \"radius_meters\": \"mean_interstation\",\n \"waterlevel\": 0.0,\n \"lut_cache_size\": 209715200\n },\n \"station_corrections\": null,\n \"magnitudes\": [],\n \"features\": [],\n \"semblance_sampling_rate\": 100,\n \"detection_threshold\": 0.2,\n \"pick_confidence_threshold\": 0.2,\n \"min_stations\": 3,\n \"absorbing_boundary\": false,\n \"absorbing_boundary_width\": \"root_node_size\",\n \"node_peak_interpolation\": true,\n \"detection_blinding\": \"PT1S\",\n \"power_mean\": 1.0,\n \"window_length\": \"PT5M\",\n \"n_threads_parstack\": \"auto\",\n \"n_threads_argmax\": \"auto\",\n \"plot_octree_surface\": false,\n \"created\": \"2024-11-29T18:14:02.874868Z\"\n}\nThis is a minimal config which can used to start a Qseek search.
Minimal Qseek Config{\n \"project_dir\": \".\",\n \"stations\": {\n \"station_xmls\": [],\n \"pyrocko_station_yamls\": [\"search/pyrocko-stations.yaml\"],\n },\n \"data_provider\": {\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": \".\",\n \"waveform_dirs\": [\"data/\"],\n },\n \"octree\": {\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 2000.0,\n \"n_levels\": 3,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ],\n \"absorbing_boundary\": 1000.0\n },\n \"image_functions\": [\n {\n \"image\": \"PhaseNet\",\n \"model\": \"ethz\",\n \"torch_use_cuda\": false,\n \"phase_map\": {\n \"P\": \"constant:P\",\n \"S\": \"constant:S\"\n },\n }\n ],\n \"ray_tracers\": [\n {\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n }\n ],\n \"station_corrections\": {},\n \"event_features\": [],\n \"sampling_rate\": 100,\n \"detection_threshold\": 0.05,\n \"detection_blinding\": \"PT2S\",\n \"node_split_threshold\": 0.9,\n \"window_length\": \"PT300S\",\n \"n_threads_parstack\": 0,\n \"n_threads_argmax\": 4,\n}\nStructure of the search and optimisation of the octree, which is focusing in on seismic energy.
%%{init: {'theme': 'neutral', 'themeVariables': { 'fontSize': '14pt'}}}%%\nflowchart LR\n subgraph Seismic Data\n waveforms([\"fa:fa-water Seismic\\nWaveforms\"])\n image{{\"fa:fa-bolt Waveform Image Function\\nPhaseNet / EQTransformer / ...\"}}\n waveforms --> image\n end\n subgraph Travel Time Model\n travelTimes([\"fa:fa-layer-group Seismic\\nTravel Time Model\"])\n stationCorrections{{\"fab:fa-arrows-to-dot Station Corrections\\nSST / SSST\"}}\n travelTimes -->|add| stationCorrections\n end\n subgraph Stacking and Migration\n octree[\"fa:fa-cubes\\nOctree Grid\"]\n detection[\"fa:fa-bullseye Detection\\nand Localisation\"]\n end\n featureExtraction(\"fa:fa-info Extract Event Features\\nMagnitudes, Ground Motion, ...\")\n correctionExtraction(\"fa:fa-stopwatch Extract\\nStation Corrections\")\n\n image --> octree\n stationCorrections --> octree\n detection -.->|\"fa:fa-cube\\nRefine\"| octree\n octree --> detection\n detection --> featureExtraction & correctionExtraction\nBuilding blocks of the specific stacking and migration method for earthquake detection, localisation and characterisation.
"},{"location":"components/general/","title":"General Settings","text":""},{"location":"components/general/#paths","title":"Paths","text":"Paths can be relative to the location of the config file or absolute. File paths and directory paths are checked whether they exist.
"},{"location":"components/general/#date-and-time","title":"Date and Time","text":"Serialisation of time, dates and date times and durations follow ISO8601 format with timezone information. E.g. 2023-10-28T01:21:21.003Z.
Duration are serialized like PT600S, this example shows a duration of 600 seconds, 10 minutes.
!!!+ note Timezone Info All datetimes are timezone aware! For UTC this is the Z or +00:00 suffix. Also other offsets can be defined according to ISO8601.
{\n \"start_time\": \"2023-10-28T01:21:21.003+00:00\",\n \"end_time\": \"2023-10-28T01:21:21.003+00:00\",\n \"duration\": \"PT600S\"\n}\nGeographic locations have a geographic reference and a relative shift in meters. The octree or velocity models are referenced using Location objects.
All distances, depths and elevations are given in meters.
"},{"location":"components/general/#exec-4--location-module","title":"Location Module","text":"Config LocationJSONlat: PydanticUndefined Latitude in degrees.
lon: PydanticUndefined Longitude in degrees.
east_shift: 0.0 East shift towards geographical reference in meters.
north_shift: 0.0 North shift towards geographical reference in meters.
elevation: 0.0 Elevation in meters.
depth: 0.0 Depth in meters, positive is down.
JSON for Location{\n \"lat\": 52.3825,\n \"lon\": 13.0644,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n}\nFor image functions this version of Qseek relies heavily on machine learning pickers delivered by SeisBench.
"},{"location":"components/image_function/#seisbench-image-function","title":"SeisBench Image Function","text":"SeisBench offers access to a variety of machine learning phase pickers pre-trained on various data sets.
Citation PhaseNet
Zhu, Weiqiang, and Gregory C. Beroza. \"PhaseNet: A Deep-Neural-Network-Based Seismic Arrival Time Picking Method.\" arXiv preprint arXiv:1803.03211 (2018).
"},{"location":"components/image_function/#exec-5--seisbench-module","title":"SeisBench Module","text":"PhaseNet image function. For more details see SeisBench documentation.
Config SeisBenchJSONmodel: PhaseNet | EQTransformer | OBSTransformer | LFEDetect The model to use for the image function. Currently supported models are PhaseNet, EQTransformer, GPD, OBSTransformer, LFEDetect.
pretrained: cascadia | cms | diting | dummy | ethz | geofon | instance | iquique | jcms | jcs | jms | lendb | mexico | nankai | neic | obs | obst2024 | original | original_nonconservative | san_andreas | scedc | stead | volpick SeisBench pre-trained model to use. Choose from ethz, geofon, instance, iquique, lendb, neic, obs, original, scedc, stead. For more details see SeisBench documentation
window_overlap_samples: 1500 Window overlap in samples.
torch_use_cuda Use CUDA for inference. If True use default device, if int use the specified device.
torch_cpu_threads: 4 Number of CPU threads to use if only CPU is used.
batch_size: 128 Batch size for inference, larger values can improve performance.
stack_method: avg | max Method to stack the overlaping blocks internally. Choose from avg and max.
rescale_input: 1.0 Upscale input by factor. This augments the input data from e.g. 100 Hz to 50 Hz (factor: 2). Can be useful for high-frequency microseismic events.
phase_map Phase mapping from SeisBench PhaseNet to Lassie phases.
weights Weights for each phase.
JSON for SeisBench{\n \"image\": \"SeisBench\",\n \"model\": \"PhaseNet\",\n \"pretrained\": \"original\",\n \"window_overlap_samples\": 1500,\n \"torch_use_cuda\": true,\n \"torch_cpu_threads\": 4,\n \"batch_size\": 128,\n \"stack_method\": \"avg\",\n \"rescale_input\": 1.0,\n \"phase_map\": {\n \"P\": \"cake:P\",\n \"S\": \"cake:S\"\n },\n \"weights\": {\n \"P\": 1.0,\n \"S\": 1.0\n }\n}\nA 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.
"},{"location":"components/octree/#exec-6--octree-module","title":"Octree Module","text":"Config OctreeJSONlocation 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{\n \"location\": {\n \"lat\": 0.0,\n \"lon\": 0.0,\n \"east_shift\": 0.0,\n \"north_shift\": 0.0,\n \"elevation\": 0.0,\n \"depth\": 0.0\n },\n \"root_node_size\": 1000.0,\n \"n_levels\": 5,\n \"east_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"north_bounds\": [\n -10000.0,\n 10000.0\n ],\n \"depth_bounds\": [\n 0.0,\n 20000.0\n ]\n}\npydantic-model","text":" 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 \u2192 location check_limits pydantic-field","text":"depth_bounds: Range = Range(0 * KM, 20 * KM)\nDepth bounds of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.east_bounds","title":"east_boundspydantic-field","text":"east_bounds: Range = Range(-10 * KM, 10 * KM)\nEast bounds of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.leaf_nodes","title":"leaf_nodespydantic-field","text":"leaf_nodes: list[Node]\nGet all leaf nodes of the octree.
Returns:
Type Descriptionlist[Node] list[Node]: List of leaf nodes.
"},{"location":"components/octree/#qseek.octree.Octree.location","title":"locationpydantic-field","text":"location: Location = Location(lat=0.0, lon=0.0)\nThe geographical center of the octree.
"},{"location":"components/octree/#qseek.octree.Octree.n_leaf_nodes","title":"n_leaf_nodespydantic-field","text":"n_leaf_nodes: int\nNumber of nodes in the octree.
"},{"location":"components/octree/#qseek.octree.Octree.n_levels","title":"n_levelspydantic-field","text":"n_levels: int = 5\nNumber of levels in the octree, defining the final resolution of the detection. Default is 5.
"},{"location":"components/octree/#qseek.octree.Octree.n_nodes","title":"n_nodespydantic-field","text":"n_nodes: int\nNumber of nodes in the octree.
"},{"location":"components/octree/#qseek.octree.Octree.nodes","title":"nodespydantic-field","text":"nodes: list[Node]\nList of nodes in the octree.
"},{"location":"components/octree/#qseek.octree.Octree.north_bounds","title":"north_boundspydantic-field","text":"north_bounds: Range = Range(-10 * KM, 10 * KM)\nNorth bounds of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.root_node_size","title":"root_node_sizepydantic-field","text":"root_node_size: PositiveFloat = 1 * KM\nSize of the root node at the initial level (level 0) in meters.
"},{"location":"components/octree/#qseek.octree.Octree.semblance","title":"semblancepydantic-field","text":"semblance: ndarray\nReturns the semblance values of all nodes.
"},{"location":"components/octree/#qseek.octree.Octree.volume","title":"volumepydantic-field","text":"volume: float\nVolume of the octree in cubic meters.
"},{"location":"components/octree/#qseek.octree.Octree.cached_bottom","title":"cached_bottom","text":"cached_bottom() -> Self\nReturns a copy of the octree refined to the cached bottom nodes.
Raises:
Type DescriptionEnvironmentError If the octree has never been split.
Returns:
Name Type DescriptionSelf Self Copy of the octree with cached bottom nodes.
"},{"location":"components/octree/#qseek.octree.Octree.check_limits","title":"check_limitspydantic-validator","text":"check_limits() -> Octree\nCheck that the size limits are valid.
"},{"location":"components/octree/#qseek.octree.Octree.clear","title":"clear","text":"clear() -> None\nClear the octree's cached data.
"},{"location":"components/octree/#qseek.octree.Octree.distances_stations","title":"distances_stations","text":"distances_stations(stations: Stations) -> ndarray\nReturns the 3D distances from all nodes to all stations.
Parameters:
Name Type Description Defaultstations Stations Stations to calculate distance to.
requiredReturns:
Type Descriptionndarray np.ndarray: Of shape (n-nodes, n-stations).
"},{"location":"components/octree/#qseek.octree.Octree.distances_stations_surface","title":"distances_stations_surface","text":"distances_stations_surface(stations: Stations) -> ndarray\nReturns the surface distance from all nodes to all stations.
Parameters:
Name Type Description Defaultstations Stations Stations to calculate distance to.
requiredReturns:
Type Descriptionndarray np.ndarray: Distances in shape (n-nodes, n-stations).
"},{"location":"components/octree/#qseek.octree.Octree.extent","title":"extent","text":"extent() -> tuple[float, float, float]\nReturns the extent of the octree.
Returns:
Type Descriptiontuple[float, float, float] tuple[float, float, float]: EW, NS and depth extent of the octree in meters.
"},{"location":"components/octree/#qseek.octree.Octree.get_corners","title":"get_corners","text":"get_corners() -> list[Location]\nGet the corners of the octree.
Returns:
Type Descriptionlist[Location] list[Location]: List of locations.
"},{"location":"components/octree/#qseek.octree.Octree.get_nodes","title":"get_nodes","text":"get_nodes(indices: Iterable[int]) -> list[Node]\nRetrieves a list of nodes from the octree based on the given indices.
Parameters:
Name Type Description Defaultindices Iterable[int] The indices of the nodes to retrieve.
requiredReturns:
Type Descriptionlist[Node] list[Node]: A list of nodes corresponding to the given indices.
"},{"location":"components/octree/#qseek.octree.Octree.get_nodes_by_threshold","title":"get_nodes_by_threshold","text":"get_nodes_by_threshold(\n semblance_threshold: float = 0.0,\n) -> list[Node]\nGet all nodes with a semblance above a threshold.
Parameters:
Name Type Description Defaultsemblance_threshold float Semblance threshold. Default is 0.0.
0.0 Returns:
Type Descriptionlist[Node] list[Node]: List of nodes.
"},{"location":"components/octree/#qseek.octree.Octree.get_nodes_level","title":"get_nodes_level","text":"get_nodes_level(level: int = 0) -> list[Node]\nGet all nodes at a specific level.
Parameters:
Name Type Description Defaultlevel int Level to get nodes from.
0 Returns:
Type Descriptionlist[Node] list[Node]: List of nodes.
"},{"location":"components/octree/#qseek.octree.Octree.interpolate_max_semblance","title":"interpolate_max_semblanceasync","text":"interpolate_max_semblance(peak_node: Node) -> Location\nInterpolate 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 DescriptionLocation Location Location of the maximum semblance value.
Raises:
Type DescriptionAttributeError If no semblance values are set.
"},{"location":"components/octree/#qseek.octree.Octree.map_semblance","title":"map_semblance","text":"map_semblance(\n semblance: ndarray, leaf_only: bool = True\n) -> None\nMaps semblance values to nodes.
Parameters:
Name Type Description Defaultsemblance ndarray Of shape (n-nodes,).
requiredleaf_only bool If True, only leaf nodes are mapped. Defaults to True.
True"},{"location":"components/octree/#qseek.octree.Octree.model_post_init","title":"model_post_init","text":"model_post_init(__context: Any) -> None\nInitialize octree. This method is called by the pydantic model.
"},{"location":"components/octree/#qseek.octree.Octree.reduce_axis","title":"reduce_axis","text":"reduce_axis(\n surface: Literal[\"NE\", \"ED\", \"ND\"] = \"NE\",\n max_level: int = -1,\n accumulator: Callable[ndarray] = max,\n) -> ndarray\nReduce the octree's nodes to the surface.
Parameters:
Name Type Description Defaultsurface 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 Descriptionndarray np.ndarray: Of shape (n-nodes, 4) with columns (east, north, depth, value).
"},{"location":"components/octree/#qseek.octree.Octree.reset","title":"reset","text":"reset() -> Self\nReset the octree to its initial state and return it.
"},{"location":"components/octree/#qseek.octree.Octree.save_pickle","title":"save_pickle","text":"save_pickle(filename: Path) -> None\nSave the octree to a pickle file.
Parameters:
Name Type Description Defaultfilename Path Filename to save to.
required"},{"location":"components/octree/#qseek.octree.Octree.set_level","title":"set_level","text":"set_level(level: int) -> None\nSet the octree to a specific level.
Parameters:
Name Type Description Defaultlevel int Level to set the octree to.
required"},{"location":"components/octree/#qseek.octree.Octree.smallest_node_size","title":"smallest_node_size","text":"smallest_node_size() -> float\nReturns the smallest possible node size.
Returns:
Name Type Descriptionfloat float Smallest possible node size.
"},{"location":"components/octree/#qseek.octree.Octree.total_number_nodes","title":"total_number_nodes","text":"total_number_nodes() -> int\nReturns the total number of nodes of all levels.
Returns:
Name Type Descriptionint int Total number of nodes.
"},{"location":"components/ray_tracer/","title":"Ray Tracers","text":"The calculation of seismic travel times is a cornerstone for the migration and stacking approach. Qseek supports different ray tracers for travel time calculation, which can be adapted for different geological settings.
"},{"location":"components/ray_tracer/#constant-velocity","title":"Constant Velocity","text":"The constant velocity models is trivial and follows:
\\[ t_{P} = \\frac{d}{v_P} \\]This module is used for simple use cases and cross-referencing testing.
"},{"location":"components/ray_tracer/#exec-7--constantvelocitytracer-module","title":"ConstantVelocityTracer Module","text":"Travel time tracer with a constant velocity.
Config ConstantVelocityTracerJSONphase: constant:P Name of the phase.
velocity: 5000.0 Constant velocity of the phase in m/s.
JSON for ConstantVelocityTracer{\n \"tracer\": \"ConstantVelocityTracer\",\n \"phase\": \"constant:P\",\n \"velocity\": 5000.0\n}\nCalculation of travel times in 1D layered media is based on the Pyrocko Cake ray tracer.
Pyrocko Cake 1D ray tracer for travel time calculation in 1D layered media
"},{"location":"components/ray_tracer/#exec-8--caketracer-module","title":"CakeTracer Module","text":"Travel time ray tracer for 1D layered earth models.
Config CakeTracerJSONphases Dictionary of phases and timings to calculate.
earthmodel Earth model to calculate travel times for.
trim_earth_model_depth: True Trim earth model to max depth of the octree.
lut_cache_size Size of the LUT cache. Default is 2G.
{\n \"tracer\": \"CakeTracer\",\n \"phases\": {\n \"cake:P\": {\n \"definition\": \"P,p\"\n },\n \"cake:S\": {\n \"definition\": \"S,s\"\n }\n },\n \"earthmodel\": {\n \"filename\": \"/home/marius/.cache/qseek/velocity_models/default.nd\",\n \"format\": \"nd\",\n \"crust2_profile\": \"\"\n },\n \"trim_earth_model_depth\": true,\n \"lut_cache_size\": 2147483648\n}\nWe implement the fast marching method for calculating first arrivals of waves in 3D volumes. Currently three different 3D velocity models are supported:
Conceptual 2D visualisation for seismic traveltimes calculation in heterogenous media using the fast-marching method for the Eikonal solution is presented. Traveltimes from the receiving station at the surface (indicated by a yellow triangle) towards the subsurface grid are calculated, resulting in station-specifig traveltimes for all potential source locations simultaneously.
"},{"location":"components/ray_tracer/#exec-9--fastmarchingtracer-module","title":"FastMarchingTracer Module","text":"Travel time ray tracer using the Fast Marching Method for 3D earth models.
Config FastMarchingTracerJSONinterpolation_method: nearest | linear | cubic Interpolation method for travel times in the volume. Choose from nearest, linear or cubic.
nthreads: 0 Number of threads to use for travel time. If set to 0, cpu_count*2 will be used.
lut_cache_size Size of the LUT cache. Default is 2G.
velocity_model Velocity model for the ray tracer.
implementation: pyrocko | scikit-fmm Implementation of the Fast Marching Method. Pyrocko only supports first-order FMM for now.
JSON for FastMarchingTracer{\n \"tracer\": \"FastMarchingRayTracer\",\n \"phase\": \"fm:P\",\n \"interpolation_method\": \"cubic\",\n \"nthreads\": 0,\n \"lut_cache_size\": 2147483648,\n \"velocity_model\": {\n \"model\": \"Constant3DVelocityModel\",\n \"grid_spacing\": \"octree\",\n \"velocity\": 5000.0\n },\n \"implementation\": \"scikit-fmm\"\n}\nFor quality check, all 3D velocity models are exported to vtk/ folder as .vti files. Use ParaView to inspect and explore the velocity models.
Seismic velocity model of the Utah FORGE testbed site, visualized in ParaView.
"},{"location":"components/station_corrections/","title":"Station Corrections","text":"Station corrections can be extract from previous runs to refine the localisation accuracy. The corrections can also help to improve the semblance find more events in a dataset.
"},{"location":"components/station_corrections/#station-specific-corrections","title":"Station Specific Corrections","text":"Statistics of station delay times.
"},{"location":"components/station_corrections/#exec-10--stationcorrections-module","title":"StationCorrections Module","text":"Config StationCorrectionsJSONimport_rundir Path to rundir, to extract the station corrections from.
plot_corrections: False Plot the station corrections statistics.
statistic: median | average Arithmetic measure for the traveltime delays. Choose from median and average.
weighting: none | confidence | semblance | add-confidence-semblance | mul-confidence-semblance Weighting of the traveltime delays. Choose from none, confidence, semblance, add-confidence-semblance and mul-confidence-semblance.
min_num_picks: 50 Minimum number of picks at a station required to calculate station corrections.
min_distance_border: 500.0 Minimum event distance from the border of the octree grid.
JSON for StationCorrections{\n \"corrections\": \"StationCorrections\",\n \"import_rundir\": \".\",\n \"plot_corrections\": false,\n \"statistic\": \"median\",\n \"weighting\": \"mul-confidence-semblance\",\n \"min_num_picks\": 50,\n \"min_distance_border\": 500.0\n}\nDelay volume for a selected stations.
"},{"location":"components/station_corrections/#exec-11--sourcespecificstationcorrections-module","title":"SourceSpecificStationCorrections Module","text":"Source specific station travel time corrections.
Config SourceSpecificStationCorrectionsJSONimport_rundir Path to rundir, to extract the station corrections from.
weighting: none | confidence | semblance | add-confidence-semblance | mul-confidence-semblance Weighting of the traveltime delays. Choose from none, confidence, semblance, add-confidence-semblance and mul-confidence-semblance.
min_confidence: 5.0 Minimum cumulative pick confidence within the sphere surrouding the node. If the cumulative pick confidence inside the sphere is below this value, the sphere radius is increased until enough picks are inside the sphere.
min_distance_border: 500.0 Minimum event distance from the border of the octree grid.
spatial_weighting_exponent: 3.0 The exponent of the spatial weighting function around the sphere.
octree_level: 0 The octree level (resolution) to use for the station corrections. This is the SSST grid spacing.
delay_interpolation_method: nearest | linear | cubic The interpolation method to use for interpolating delays between nodes.
lut_cache_size Size of the LUT cache. Default is 2G.
{\n \"corrections\": \"SourceSpecificStationCorrections\",\n \"import_rundir\": \".\",\n \"weighting\": \"mul-confidence-semblance\",\n \"min_confidence\": 5.0,\n \"min_distance_border\": 500.0,\n \"spatial_weighting_exponent\": 3.0,\n \"octree_level\": 0,\n \"delay_interpolation_method\": \"linear\",\n \"lut_cache_size\": 2147483648\n}\nMeta data is required primarily for station locations and codes.
Supported data formats are:
Metadata does not need to include response information for pure detection and localisation. If local magnitudes ML are extracted, response information is required.
"},{"location":"components/station_metadata/#exec-12--stations-module","title":"Stations Module","text":"Config StationsJSONpyrocko_station_yamls List of Pyrocko station YAML files.
station_xmls List of StationXML files or directories containing StationXML (.xml) files.
blacklist Blacklist stations and exclude from detecion. Format is ['NET.STA.LOC', ...].
max_distance Maximum distance in meters from the centroid location to include stations for detection. If None, all stations are included.
JSON for Stations{\n \"pyrocko_station_yamls\": [],\n \"station_xmls\": [],\n \"blacklist\": [],\n \"stations\": [],\n \"max_distance\": null\n}\nThe seismic can be delivered in MiniSeed or any other format compatible with Pyrocko. Qseek utilizes the Pyrocko Squirrel for fast and asynchronous data access.
To prepare your data for EQ detection and localisation, organize it in a MiniSeed file or an SDS structure.
"},{"location":"components/waveform_data/#exec-13--pyrockosquirrel-module","title":"PyrockoSquirrel Module","text":"Waveform provider using Pyrocko's Squirrel.
Config PyrockoSquirrelJSONenvironment Path to a Pyrocko Squirrel environment.
persistent Name of the Squirrel's persistent collection for faster loading of large data sets.
waveform_dirs List of directories holding the waveform files.
start_time Start time for the search in ISO8601 including timezone. E.g. 2024-12-30T00:00:00Z.
end_time End time for the search in ISO8601 including timezone. E.g. 2024-12-31T00:00:00Z.
channel_selector Channel selector for waveforms, e.g. ['HH', 'EN'].
n_threads: 8 Number of threads for loading waveforms, important for large data sets.
watch_waveforms Watch the waveform directories for changes. If True it will check every ten minutes. If a timedelta is provided it will check every specified time. Default is False.
{\n \"provider\": \"PyrockoSquirrel\",\n \"environment\": null,\n \"persistent\": \"docs\",\n \"waveform_dirs\": [\n \"./data\"\n ],\n \"start_time\": null,\n \"end_time\": null,\n \"channel_selector\": null,\n \"n_threads\": 8,\n \"watch_waveforms\": false\n}\n