Configuration¶

You configure a search in one JSON file. It names your stations, the waveform data, the velocity models and the search volume, and selects the modules for every step of the search. Qseek validates the file when the search starts and reports every invalid or missing field.

Create a configuration with all defaults:

Create a configuration file

qseek config > my-search.json

Minimal configuration¶

This configuration reads waveforms from an SDS archive, annotates phases with PhaseNet and calculates travel times for a constant velocity. Replace the paths, the location and the bounds with your own.

my-search.json

{
  "project_dir": ".",
  "stations": {
    "station_xmls": ["meta/stations.xml"]
  },
  "data_provider": {
    "provider": "SDSArchive",
    "archive": "data/sds"
  },
  "octree": {
    "location": {
      "lat": 52.38,
      "lon": 13.06
    },
    "root_node_size": 2000.0,
    "n_levels": 3,
    "east_bounds": [-10000.0, 10000.0],
    "north_bounds": [-10000.0, 10000.0],
    "depth_bounds": [0.0, 20000.0]
  },
  "image_function": {
    "image": "SeisBench",
    "model": "PhaseNet",
    "pretrained": "original",
    "phase_map": {
      "P": "constant:P",
      "S": "constant:S"
    }
  },
  "ray_tracers": [
    {
      "tracer": "ConstantVelocityTracer",
      "phase": "constant:P",
      "velocity": 5000.0
    },
    {
      "tracer": "ConstantVelocityTracer",
      "phase": "constant:S",
      "velocity": 2900.0
    }
  ],
  "detection_threshold": "MAD",
  "window_length": "PT5M"
}

Durations such as the window_length are ISO 8601 durations: "PT5M" is 5 minutes. The conventions explain these formats.

Modules¶

Every top-level field of the configuration configures one module of the search. How Qseek works explains how they work together.

Field	Module	Configures
`stations`	Stations	Station metadata and excluded stations
`data_provider`	Waveforms	SDS archive, Pyrocko Squirrel or SeedLink streams
`pre_processing`	Pre-processing	Resampling, filters and denoising
`image_function`	Image functions	Phase annotation and picking
`ray_tracers`	Ray tracers	Travel times for every phase
`octree`	Search volume	Location, size and resolution of the search volume
`distance_weights`	Distance weighting	Weights of the stations for every node
`station_corrections`	Station corrections	Travel time delays per station
`magnitudes`	Magnitudes	Local and moment magnitudes
`features`	Event features	Ground motions
`callbacks`	Callbacks	Alerts and custom actions for new detections

The conventions explain the formats of paths, times, durations, station codes and locations.

The search¶

The remaining fields of the search set the detection and the processing.

Search

{
  "project_dir": ".",
  "stations": {
    "pyrocko_station_yamls": [],
    "station_xmls": [],
    "blacklist": [],
    "stations": [],
    "max_distance": null
  },
  "data_provider": {
    "provider": "SDSArchive",
    "channel_selector": null,
    "archive": "./sds-archive",
    "start_time": null,
    "end_time": null,
    "channel_orientations": "ENZ0123",
    "n_threads": 4,
    "queue_size": 16
  },
  "pre_processing": [
    {
      "process": "resample",
      "stations": [],
      "sampling_frequency": 100.0,
      "n_threads": 8
    },
    {
      "process": "bandpass",
      "stations": [],
      "corners": 4,
      "bandpass": [
        0.5,
        30.0
      ],
      "demean": true,
      "zero_phase": 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_function": {
    "image": "SeisBench",
    "picker": {
      "threshold_p": 0.1,
      "threshold_s": 0.1,
      "search_window_seconds": 5.0,
      "peak_separation_seconds": 0.1
    },
    "model": "PhaseNet",
    "pretrained": "original",
    "window_overlap_samples": 2000,
    "torch_use_cuda": true,
    "torch_cpu_threads": 4,
    "batch_size": 128,
    "stack_method": "avg",
    "sampling_rate": 100.0,
    "phase_map": {
      "P": "cake:P",
      "S": "cake:S"
    },
    "weights": {
      "P": 1.0,
      "S": 1.0
    }
  },
  "ray_tracers": [
    {
      "tracer": "FastMarching3D",
      "phase": "fm3d:P",
      "interpolation_method": "cubic",
      "nthreads": 0,
      "velocity_model": {
        "model": "Constant3DVelocityModel",
        "grid_spacing": "octree",
        "velocity": 5000.0
      },
      "implementation": "eikonalfm"
    },
    {
      "tracer": "CakeTracer",
      "phases": {
        "cake:P": {
          "definition": "P,p"
        },
        "cake:S": {
          "definition": "S,s"
        }
      },
      "earthmodel": {
        "filename": "~/.cache/qseek/velocity_models/default.nd",
        "format": "nd",
        "crust2_profile": "",
        "raw_file_data": null
      }
    },
    {
      "tracer": "ConstantVelocityTracer",
      "phase": "constant:P",
      "velocity": 5000.0
    },
    {
      "tracer": "FastMarching",
      "velocity_model": {
        "filename": "~/.cache/qseek/velocity_models/default.nd",
        "format": "nd",
        "crust2_profile": "",
        "raw_file_data": null
      },
      "interpolation_method": "linear",
      "nthreads": 0,
      "implementation": "eikonalfm",
      "phases": [
        "fm:P",
        "fm:S"
      ]
    }
  ],
  "distance_weights": {
    "distance_taper": "mean_interstation",
    "required_closest_stations": 4,
    "waterlevel": 0.0
  },
  "station_corrections": null,
  "magnitudes": [],
  "features": [],
  "webserver": {
    "host": "0.0.0.0",
    "port": "auto"
  },
  "callbacks": [],
  "callback_scripts": [],
  "detection_threshold": "MAD",
  "min_stations": 3,
  "ignore_boundary": "without_surface",
  "ignore_boundary_width": "root_node_size",
  "node_interpolation": true,
  "detection_blinding": "PT1S",
  "window_length": "PT5M",
  "n_threads": 28,
  "save_images": false,
  "created": "2026-10-01T21:10:49.218380Z"
}

Search `pydantic-model` ¶

Bases: Model

The search: configuration of the earthquake detection and localization.

This is the root of the JSON configuration file. Every field configures one part of the search, from the stations and waveform data to the image function, the travel times and the extracted event features.

Fields:

project_dir (Path)
stations (StationInventory)
data_provider (WaveformProviderType)
pre_processing (PreProcessing)
octree (Octree)
image_function (ImageFunctionType)
ray_tracers (RayTracers)
distance_weights (DistanceWeights | None)
station_corrections (StationCorrectionType | None)
magnitudes (list[EventMagnitudeCalculatorType])
features (list[FeatureExtractorType])
webserver (WebServer | None)
callbacks (list[CallbackType])
callback_scripts (list[Path])
detection_threshold (Literal['MAD'] | PositiveFloat)
min_stations (int)
ignore_boundary (IgnoreBoundary)
ignore_boundary_width (float | Literal['root_node_size'])
node_interpolation (bool)
detection_blinding (timedelta)
window_length (timedelta)
n_threads (CpuCount)
save_images (bool)
created (datetime)
_last_detection_export (int)

Validators:

load_path → station_corrections

project_dir `pydantic-field` ¶

project_dir: Path = Path('.')

Directory in which the run directory is created, relative to the configuration file.

stations `pydantic-field` ¶

stations: StationInventory

Station inventory from StationXML or Pyrocko Station YAML.

data_provider `pydantic-field` ¶

data_provider: WaveformProviderType

Data provider for waveform data.

pre_processing `pydantic-field` ¶

pre_processing: PreProcessing

Pre-processing steps for waveform data.

octree `pydantic-field` ¶

octree: Octree

Octree volume for the search.

image_function `pydantic-field` ¶

image_function: ImageFunctionType

Image function for waveform processing and phase on-set detection.

ray_tracers `pydantic-field` ¶

ray_tracers: RayTracers

List of ray tracers for travel time calculation.

distance_weights `pydantic-field` ¶

distance_weights: DistanceWeights | None

Spatial weights for distance weighting.

station_corrections `pydantic-field` ¶

station_corrections: StationCorrectionType | None = None

Apply station corrections extracted from a previous run or a path to a directory with station correction files.

magnitudes `pydantic-field` ¶

magnitudes: list[EventMagnitudeCalculatorType]

Magnitude calculators to use.

features `pydantic-field` ¶

features: list[FeatureExtractorType]

Event features to extract.

webserver `pydantic-field` ¶

webserver: WebServer | None

Web server for serving search results and monitoring.

callbacks `pydantic-field` ¶

callbacks: list[CallbackType]

Callback plugins notified of search lifecycle events.

callback_scripts `pydantic-field` ¶

callback_scripts: list[Path]

Paths to single-file callback plugins. Each file is loaded relative to the current working directory and must define a top-level load() function returning a Callback instance.

detection_threshold `pydantic-field` ¶

detection_threshold: Literal['MAD'] | PositiveFloat = 'MAD'

Minimum semblance of a detection. "MAD" sets the threshold to 10 times the median absolute deviation of the maximum semblance in each processed window.

min_stations `pydantic-field` ¶

min_stations: int = 3

Minimum number of stations required for detection and localization.

ignore_boundary `pydantic-field` ¶

ignore_boundary: IgnoreBoundary = '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.

ignore_boundary_width `pydantic-field` ¶

ignore_boundary_width: float | Literal["root_node_size"] = (
    "root_node_size"
)

Width of the absorbing boundary around the search volume in meters. "root_node_size" uses the root node size of the octree.

node_interpolation `pydantic-field` ¶

node_interpolation: bool = True

Interpolate the location of a detection within its node using radial basis functions. If false, the node center is the hypocenter.

detection_blinding `pydantic-field` ¶

detection_blinding: timedelta = timedelta(seconds=1.0)

Blinding time before and after a detection in which no other detection is made. Prevents detecting the same event twice.

window_length `pydantic-field` ¶

window_length: timedelta = timedelta(minutes=5)

Length of the waveform windows processed at once. Shorter windows need less memory.

n_threads `pydantic-field` ¶

n_threads: CpuCount = 'auto'

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.

save_images `pydantic-field` ¶

save_images: bool = False

Save annotation images to disk for debugging and analysis.

created `pydantic-field` ¶

created: datetime

Creation time of the search, set by Qseek.

get_window_padding `async` ¶

get_window_padding() -> timedelta

Get window padding length based on maximum travel time shifts.

This is a calculation based on the maximum travel time shifts from the ray tracers, the image function blinding, and the detection blinding.

Returns:

Name	Type	Description
`timedelta`	`timedelta`	Window padding length.

prepare `async` ¶

prepare() -> None

Prepares the search by initializing necessary components and data.

This method prepares the search by performing the following steps: 1. Prepares the data provider with the given stations. 2. Prepares the ray tracers with the octree, stations, phases, and rundir. 3. Prepares each magnitude with the octree and stations. 4. Prepares the station corrections with the stations, octree, and phases. 5. Initializes the boundaries.

Note: This method is asynchronous.

Returns:

Type	Description
`None`	None

new_detections `async` ¶

new_detections(detections: list[EventDetection]) -> None

Process new detections.

Parameters:

Name	Type	Description	Default
`detections`	`list[EventDetection]`	List of new event detections.	required

add_magnitude_and_features `async` ¶

add_magnitude_and_features(
    event: EventDetection, recalculate: bool = True
) -> EventDetection

Adds magnitude and features to the given event.

Parameters:

Name	Type	Description	Default
`event`	`EventDetection`	The event to add magnitude and features to.	required
`recalculate`	`bool`	Whether to overwrite existing magnitudes and features. Defaults to True.	`True`

load_rundir `classmethod` ¶

load_rundir(
    rundir: Path, search_file: Path | None = None
) -> Self

Loads a search from a rundir.

Parameters:

Name	Type	Description	Default
`rundir`	`Path`	Path to the rundir to load the search from.	required
`search_file`	`Path \| None`	Path to the search file, if different from the default `rundir/search.json`. Defaults to None.	`None`

Returns:

Name	Type	Description
`Self`	`Self`	The loaded search object.

Configuration¶

Minimal configuration¶

Modules¶

The search¶

Search pydantic-model ¶

project_dir pydantic-field ¶

stations pydantic-field ¶

data_provider pydantic-field ¶

pre_processing pydantic-field ¶

octree pydantic-field ¶

image_function pydantic-field ¶

ray_tracers pydantic-field ¶

distance_weights pydantic-field ¶

station_corrections pydantic-field ¶

magnitudes pydantic-field ¶

features pydantic-field ¶

webserver pydantic-field ¶

callbacks pydantic-field ¶

callback_scripts pydantic-field ¶

detection_threshold pydantic-field ¶

min_stations pydantic-field ¶

ignore_boundary pydantic-field ¶

ignore_boundary_width pydantic-field ¶

node_interpolation pydantic-field ¶

detection_blinding pydantic-field ¶

window_length pydantic-field ¶

n_threads pydantic-field ¶

save_images pydantic-field ¶

created pydantic-field ¶

get_window_padding async ¶

prepare async ¶

new_detections async ¶

add_magnitude_and_features async ¶

load_rundir classmethod ¶

Search `pydantic-model` ¶

project_dir `pydantic-field` ¶

stations `pydantic-field` ¶

data_provider `pydantic-field` ¶

pre_processing `pydantic-field` ¶

octree `pydantic-field` ¶

image_function `pydantic-field` ¶

ray_tracers `pydantic-field` ¶

distance_weights `pydantic-field` ¶

station_corrections `pydantic-field` ¶

magnitudes `pydantic-field` ¶

features `pydantic-field` ¶

webserver `pydantic-field` ¶

callbacks `pydantic-field` ¶

callback_scripts `pydantic-field` ¶

detection_threshold `pydantic-field` ¶

min_stations `pydantic-field` ¶

ignore_boundary `pydantic-field` ¶

ignore_boundary_width `pydantic-field` ¶

node_interpolation `pydantic-field` ¶

detection_blinding `pydantic-field` ¶

window_length `pydantic-field` ¶

n_threads `pydantic-field` ¶

save_images `pydantic-field` ¶

created `pydantic-field` ¶

get_window_padding `async` ¶

prepare `async` ¶

new_detections `async` ¶

add_magnitude_and_features `async` ¶

load_rundir `classmethod` ¶