Skip to content

Callbacks

Callbacks run your code at defined points of a search, its hooks, e.g. to send an alert for every new detection during real-time monitoring. callbacks is a list of callbacks; Qseek calls each of them:

Hook When
on_start the search starts
on_batch_start, on_batch_end before and after each window of waveforms
on_new_detection for every new detection, after its magnitudes and features
on_stop the search ends

Telegram alerts

Sends detection alerts to a Telegram chat. Set the bot token with the QSEEK_TELEGRAM_BOT_TOKEN environment variable: it is not stored in the run's search.json. Set the chat with chat_id in the configuration or with the QSEEK_TELEGRAM_CHAT_ID environment variable. The real-time monitoring guide shows the setup.

TelegramAlert
{
  "callback": "TelegramAlert",
  "magnitude_alert": 2.0,
  "rate_alert_magnitude": 1.0,
  "rate_alert_count": 10,
  "rate_alert_window": "P1D"
}

TelegramAlert pydantic-model

Bases: Callback

Sends detection alerts to a Telegram chat.

bot_token is excluded from search.json so it never ends up on disk; set it (and optionally chat_id) through the QSEEK_TELEGRAM_BOT_TOKEN / QSEEK_TELEGRAM_CHAT_ID environment variables instead.

Fields:

Validators:

  • _credentials_from_env

bot_token pydantic-field 

bot_token: SecretStr

The bot's token, as provided by BotFather.

chat_id pydantic-field 

chat_id: str

The chat ID to send messages to.

magnitude_alert pydantic-field 

magnitude_alert: float | None = 2.0

Only notify for detections at or above this magnitude. Detections without a computed magnitude are not notified.

rate_alert_magnitude pydantic-field 

rate_alert_magnitude: float = 1.0

Magnitude threshold considered for the rate alert.

rate_alert_count pydantic-field 

rate_alert_count: int = 10

Number of events at or above rate_alert_magnitude within rate_alert_window that triggers a swarm alert.

rate_alert_window pydantic-field 

rate_alert_window: timedelta = timedelta(hours=24)

Rolling time window for the rate alert.

on_batch_start async 

on_batch_start(batch: WaveformBatch) -> None

Called before a waveform batch is processed.

on_batch_end async 

on_batch_end(batch: WaveformBatch) -> None

Called after a waveform batch has been processed.

get_subclasses classmethod 

get_subclasses() -> tuple[type[Callback], ...]

Get the subclasses of this class.

Returns:

Type Description
tuple[type[Callback], ...]

tuple[type[Callback], ...]: The subclasses of this class.

Custom callbacks

Write your own callback in a single Python file and list it in callback_scripts. The file subclasses Callback, implements the hooks it needs, and defines a top-level load() function that returns an instance.

my_callback.py
from qseek.plugins import Callback


class PrintDetections(Callback):
    async def on_new_detection(self, detection):
        print(f"new event at {detection.time}, semblance {detection.semblance:.2f}")


def load() -> Callback:
    return PrintDetections()