Getting Started

Installation

The installation is straight-forward using pip or pipx.

From GitHub

pip install git+https://github.com/pyrocko/qseek

or

Using pipx

pipx install git+https://github.com/pyrocko/qseek

Running Qseek

The 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

usage: qseek [-h] [--verbose] [--version]
             {config,search,continue,snuffler,feature-extraction,modules,serve,export,clear-cache,dump-schemas}
             ...

qseek - The wholesome earthquake detector 🚀

options:
  -h, --help            show this help message and exit
  --verbose, -v         increase verbosity of the log messages, repeat to
                        increase. Default level is INFO
  --version             show version and exit

commands:
  Available commands to run qseek. Get command help with `qseek <command>
  --help`.

  {config,search,continue,snuffler,feature-extraction,modules,serve,export,clear-cache,dump-schemas}
    config              print a new config
    search              start a search
    continue            continue an existing search
    snuffler            start the Pyrocko snuffler to inspect waveforms,
                        events and picks
    feature-extraction  extract features from an existing run
    modules             show available modules
    serve               start webserver and serve results from an existing run
    export              export detections to different output formats
    clear-cache         clear the cach directory
    dump-schemas        dump data models to json-schema (development)

Initializing a New Project

Once installed you can run the qseek executeable to initialize a new project.

Initialize new Project

qseek config > my-search.json

Check out the my-search.json config file and add your waveform data and velocity models.

Minimal Configuration Example

Here is a minimal JSON configuration for Qseek.

{
  "project_dir": ".",
  "stations": {
    "pyrocko_station_yamls": [],
    "station_xmls": [],
    "blacklist": [],
    "stations": [],
    "max_distance": null
  },
  "data_provider": {
    "provider": "PyrockoSquirrel",
    "environment": null,
    "persistent": null,
    "waveform_dirs": [
      "./data"
    ],
    "start_time": null,
    "end_time": null,
    "channel_selector": null,
    "n_threads": 8,
    "watch_waveforms": false
  },
  "pre_processing": [
    {
      "process": "downsample",
      "stations": [],
      "sampling_frequency": 100.0
    },
    {
      "process": "bandpass",
      "stations": [],
      "corners": 4,
      "bandpass": [
        0.5,
        30.0
      ],
      "demean": true
    }
  ],
  "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
    ]
  },
  "image_functions": [
    {
      "image": "SeisBench",
      "model": "PhaseNet",
      "pretrained": "original",
      "window_overlap_samples": 1500,
      "torch_use_cuda": true,
      "torch_cpu_threads": 4,
      "batch_size": 128,
      "stack_method": "avg",
      "rescale_input": 1.0,
      "phase_map": {
        "P": "cake:P",
        "S": "cake:S"
      },
      "weights": {
        "P": 1.0,
        "S": 1.0
      }
    }
  ],
  "ray_tracers": [
    {
      "tracer": "CakeTracer",
      "phases": {
        "cake:P": {
          "definition": "P,p"
        },
        "cake:S": {
          "definition": "S,s"
        }
      },
      "earthmodel": {
        "filename": "/home/runner/.cache/qseek/velocity_models/default.nd",
        "format": "nd",
        "crust2_profile": "",
        "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"
      },
      "trim_earth_model_depth": true,
      "lut_cache_size": 2147483648
    },
    {
      "tracer": "ConstantVelocityTracer",
      "phase": "constant:P",
      "velocity": 5000.0
    }
  ],
  "distance_weights": {
    "exponent": 3.0,
    "radius_meters": "mean_interstation",
    "waterlevel": 0.0,
    "lut_cache_size": 209715200
  },
  "station_corrections": null,
  "magnitudes": [],
  "features": [],
  "semblance_sampling_rate": 100,
  "detection_threshold": 0.2,
  "pick_confidence_threshold": 0.2,
  "min_stations": 3,
  "absorbing_boundary": false,
  "absorbing_boundary_width": "root_node_size",
  "node_peak_interpolation": true,
  "detection_blinding": "PT1S",
  "power_mean": 1.0,
  "window_length": "PT5M",
  "n_threads_parstack": "auto",
  "n_threads_argmax": "auto",
  "plot_octree_surface": false,
  "created": "2024-12-04T16:53:08.711418Z"
}

For more details and information about the component, head over to details of the modules.

Starting the Search

Once happy with the configuration, start the qseek CLI.

Start the earthquake detection and localization

qseek search my-search.json