scalert_mceqnotifier

Rich HTML earthquake email notifier for SeisComP scalert.

When an earthquake is detected, scalert calls this script with event parameters. The script fetches the full event XML from the SeisComP database, builds a detailed HTML email, and sends it via SMTP.

Features

• Rich HTML emails with PTWC-aligned color-coded alert levels (see table below)
• Tsunami alert banners — four-tier system aligned with PTWC (WARNING / ADVISORY / WATCH / INFORMATION)
• Epicenter map generated by scmapcut with station triangles (embedded inline in the email)
• Distance table to nearest cities and capitals (parsed from SeisComP cities.xml)
• Phase arrivals table with color-coded residuals
• Official bulletin via scbulletin (autoloc1 / autoloc3 / autoloc3extra / fdsnws)
• Travel-time curves (ObsPy TauPy, IASP91 model)
• Waveform plots (optional, requires local FDSNWS dataselect)
• KML attachment for Google Earth
• SeisComP XML attachment — optional, preferred origin with picks, magnitudes, and arrivals
• Google Maps link in the plain-text body
• Configurable magnitude threshold, arrival count, and new-event-only filtering
• Multiple region support — define geographic bounding boxes with per-region thresholds and recipients
• Event cooldown/deduplication — suppress rapid re-notifications as event parameters refine
• Event retraction — automatic cancellation emails when events are set to "not existing"
• Per-event log files — separate log per run (mceqnotifier_<eventID>_<timestamp>.log)
• Configurable log levels — debug / info / warning / error

Alert Levels (PTWC-aligned)

The email header color and subject line label are determined by magnitude and tsunami risk, whichever yields the higher alert level:

Level	Color	Magnitude	Tsunami (depth < 100 km)	Action
🔴 WARNING	Red	M ≥ 7.0	M ≥ 7.6	Dangerous coastal flooding — evacuate if ordered
🟠 ADVISORY	Orange	M ≥ 5.5	M 7.0–7.5	Strong currents — stay off beaches and harbors
🟡 WATCH	Yellow	M ≥ 4.0	M 6.5–6.9	Tsunami possible — be prepared to take action
🟢 INFORMATION	Green	M < 4.0	M < 6.5 or depth ≥ 100km	No tsunami threat — no action required

The tsunami banner (WARNING/ADVISORY/WATCH) only appears for shallow events (< 100 km) with M ≥ 6.5. Deep events receive INFORMATION level with no banner.

Event Retraction ("not existing")

When an analyst reviews a false or duplicate event in SeisComP and sets its type to not existing, the script automatically sends a retraction email to all applicable recipients. The retraction:

• Uses a distinct ⚫ CANCELLED subject line so it stands out in inboxes
• Includes a prominent red banner: "This event has been reviewed and marked as NOT EXISTING"
• Explains possible reasons (false detection, duplicate, analyst review)
• Sends to all matching region recipients (or global recipients)
• Suppresses new events that arrive already marked as not existing

Prerequisites

• SeisComP (>= 4.x) with the following modules available on $PATH:
  • scxmldump — fetches event XML from the database
  • scmapcut — generates the epicenter map image
  • scbulletin — produces the official bulletin text and KML
• Python 3 via the SeisComP Python environment (seiscomp-python)
• ObsPy — for travel-time curves (obspy.taup) and optional waveform retrieval
• matplotlib and NumPy — for generating plot images

Optional

• A running FDSNWS dataselect service (e.g., on localhost:8081) if you enable waveform plot attachments

Installation

1. Copy the files

Place scalert_mceqnotifier.py and your config file in a directory accessible by scalert. Recommended locations:

Option A — User-level SeisComP config directory (recommended):

This corresponds to @CONFIGDIR@ (~/.seiscomp):

DEST=~/.seiscomp
cp scalert_mceqnotifier.py "$DEST/"
cp scalert_mceqnotifier.cfg.example "$DEST/scalert_mceqnotifier.cfg"
chmod +x "$DEST/scalert_mceqnotifier.py"

Option B — System-wide SeisComP config directory:

This corresponds to @SYSTEMCONFIGDIR@ ($SEISCOMP_ROOT/etc):

DEST=$SEISCOMP_ROOT/etc
cp scalert_mceqnotifier.py "$DEST/"
cp scalert_mceqnotifier.cfg.example "$DEST/scalert_mceqnotifier.cfg"
chmod +x "$DEST/scalert_mceqnotifier.py"

SeisComP path variables reference:

Variable	Default path
@ROOTDIR@	/opt/seiscomp
@SYSTEMCONFIGDIR@	/opt/seiscomp/etc
@CONFIGDIR@	~/.seiscomp
@DATADIR@	/opt/seiscomp/share
@LOGDIR@	~/.seiscomp/log

2. Configure your settings

cd $DEST
cp scalert_mceqnotifier.cfg.example scalert_mceqnotifier.cfg
nano scalert_mceqnotifier.cfg

Edit at minimum:

Section	Key	What to set
[smtp]	user	Your SMTP username / email address
[smtp]	pw	Your SMTP password (use an App Password for Gmail)
[smtp]	from	Sender email address
[smtp]	to	Comma-separated list of recipient emails
[seiscomp]	database	Your SeisComP database connection string
[content]	footer	Custom footer text for your organization

Gmail users: You must use an App Password, not your regular Google password. Enable 2-Step Verification first, then generate an App Password.

3. Configure scalert

In scalert.cfg (or via scconfig), set the event script:

# scalert.cfg — if installed under ~/.seiscomp/ (Option A)
scripts.event = @CONFIGDIR@/scalert_mceqnotifier.py

# Or if installed under $SEISCOMP_ROOT/etc/ (Option B)
# scripts.event = @SYSTEMCONFIGDIR@/scalert_mceqnotifier.py

Then restart scalert:

seiscomp restart scalert

4. Test

You can test the script manually with a known event ID from your database:

seiscomp-python scalert_mceqnotifier.py "Test event" 1 gfz2024abcd 15 5.2

Arguments:

Position	Description
$1	Human-readable description string
$2	1 = new event, 0 = update
$3	SeisComP event public ID
$4	Number of arrivals
$5	Magnitude value (optional)

Configuration Reference

The config file scalert_mceqnotifier.cfg must be placed in the same directory as the Python script. All settings have sensible defaults.

[smtp] — Email delivery

Key	Default	Description
server	smtp.gmail.com	SMTP server hostname
port	587	SMTP port
ssl	false	Use SSL (implicit TLS on port 465)
tls	true	Use STARTTLS (explicit TLS on port 587)
user	(empty)	SMTP login username
pw	(empty)	SMTP login password
from	(same as user)	Sender address
to	(empty)	Comma-separated recipient list

[filter] — Event filtering

Key	Default	Description
min_magnitude	4.0	Ignore events below this magnitude
max_magnitude	(none)	Ignore events above this magnitude (testing)
min_arrivals	0	Minimum arrivals to trigger (0 = disabled)
new_events_only	false	If true, skip event updates

[seiscomp] — Database

Key	Default	Description
database	mysql://sysop:sysop@localhost/seiscomp	Database URI for scxmldump -d

[map] — Epicenter map

Key	Default	Description
width	512	Map image width in pixels
height	512	Map image height in pixels
radius_min	5	Minimum map radius in degrees
radius_max	40	Maximum map radius in degrees
auto_radius	true	Automatically adjust radius based on magnitude

[content] — Email content

Key	Default	Description
bulletin_format	autoloc3	scbulletin format
bulletin_enhanced	true	Use enhanced bulletin output
attach_kml	true	Attach KML file for Google Earth
attach_xml	false	Attach SeisComP XML (preferred origin, picks, arrivals)
include_maps_link	true	Include Google Maps link in plain-text body
footer	Automated Earthquake Notification	Footer text
generate_travel_curves	true	Attach travel-time curve plot (requires ObsPy)
generate_waveforms	false	Attach waveform plot (requires local FDSNWS)
fdsnws_url	http://localhost:8081	FDSNWS dataselect base URL
waveform_pre_secs	30	Seconds before origin for waveform window
waveform_post_secs	300	Seconds after origin for waveform window
waveform_max_stations	8	Maximum stations in waveform plot
max_arrivals_table	30	Maximum rows in phase arrivals table

[cities] — Distance table

Key	Default	Description
xml	(auto)	Path to cities.xml (auto-detects from $SEISCOMP_ROOT)
radius_km	1000	Search radius for nearby cities
max_count	10	Maximum cities to show
min_population	10000	Skip non-capitals below this population

[cooldown] — Event deduplication

Key	Default	Description
enabled	false	Enable cooldown to suppress rapid re-notifications
seconds	300	Suppress duplicate notifications within this window
state_dir	(tmp)	Directory for cooldown state files

[logging] — Log verbosity

Key	Default	Description
level	info	Log level: debug, info, warning, error
log_dir	(empty)	Directory for per-event log files (empty = disabled)

[region:NAME] — Region-based filtering (optional)

Define one or more [region:NAME] sections for geographic filtering. Each region supports a bounding box and per-region overrides. When regions are defined, events outside all regions are silently dropped. When no regions are defined, global filtering applies (backward-compatible).

Key	Default	Description
enabled	true	Enable/disable this region
lat_min	(required)	Southern latitude bound
lat_max	(required)	Northern latitude bound
lon_min	(required)	Western longitude bound
lon_max	(required)	Eastern longitude bound
min_magnitude	(global value)	Override minimum magnitude for this region
max_magnitude	(global value)	Override maximum magnitude for this region
min_arrivals	(global value)	Override minimum arrivals for this region
new_events_only	(global value)	Override new-events-only for this region
to	(global value)	Override recipients for this region

An event can match multiple regions — each matching region triggers its own notification (with its own recipients).

How It Works

scalert detects event
       │
       ▼
scalert_mceqnotifier.py called with CLI args
       │
       ├─ Global pre-filters: magnitude, arrivals, new_events_only
       │
       ├─ Fetch: scxmldump → full event XML from database
       │
       ├─ Parse: extract origin, magnitude, arrivals, region
       │
       ├─ Generate attachments:
       │    ├─ scmapcut → epicenter map (JPEG)
       │    ├─ TauPy → travel-time curves (PNG)
       │    ├─ FDSNWS → waveform plot (PNG, optional)
       │    └─ scbulletin --kml → KML file
       │
       ├─ Build: plain-text + rich HTML email
       │
       ├─ Dispatch:
       │    ├─ If regions defined → match epicenter to bounding boxes
       │    │    ├─ Per-region: check magnitude, arrivals, cooldown
       │    │    └─ Send to region-specific recipients
       │    └─ If no regions → global send (backward-compatible)
       │
       └─ Cooldown: record notification to prevent duplicates

Security Notes

• Never commit scalert_mceqnotifier.cfg to version control — it contains SMTP credentials
• The .gitignore in this repo excludes scalert_mceqnotifier.cfg by default
• Only scalert_mceqnotifier.cfg.example (with placeholder values) is tracked
• For Gmail, always use App Passwords — never your main account password

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-or-later).

Copyright (C) 2025 Mustafa Comoglu

If you use or modify this software, you must:

• Retain the original copyright notice and license
• Share any modifications under the same license
• Provide source access to users interacting with it over a network

Author

Mustafa Comoglu