---

name: obspy description: "Guides seismological data workflows with ObsPy, including waveform processing, format conversion, event and station metadata, FDSN or local archive access, signal analysis, travel times, geodesy, and headless imaging." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

ObsPy operating skill

Use this skill when a task names ObsPy or asks to read, process, convert, retrieve, analyze, or visualize seismological waveforms, events, station metadata, or travel times. It is a reusable package guide: first inspect the installed ObsPy version and the task's local/network boundaries, then load only the focused route below.

Install and inspect

Install the public package in an isolated supported Python environment:

python -m pip install obspy
python -c "import obspy; print(obspy.__version__)"

The base runtime uses NumPy, SciPy, Matplotlib, lxml, SQLAlchemy, requests, and decorator. Add only needed extras: obspy[tests] for focused test tooling, obspy[geo] for geographiclib, obspy[imaging] for Cartopy map plots, and obspy[io.shapefile] for shapefile support. Do not install all by default. ObsPy includes native extensions for several IO and signal/TauP paths; if an import fails, read cross-cutting troubleshooting before changing package versions.

For a minimal read-only smoke check, run scripts/check_environment.py. It verifies public imports, native extension handles, a TauP calculation, headless plotting, and CLI help without contacting a service or writing into the current directory.

Route by the user's deliverable

User request or artifact	Read next	Primary entry points
Read/write, inspect, trim, merge, filter, resample, or plot local waveforms	waveform-processing	read, Trace, Stream, UTCDateTime
Convert MiniSEED/SAC/ASCII, QuakeML, StationXML, RESP/SEED/XSEED; preserve metadata	formats-and-metadata	read, read_events, read_inventory, Catalog, Inventory
Query FDSN waveforms/stations/events, route providers, use SDS/TSIndex/SeedLink	data-access	Client, RoutingClient, filesystem clients
Filter/detect/trigger/correlate, remove or simulate responses, PPSD, arrays, realtime	signal-analysis	obspy.signal, Trace/Stream methods, obspy.realtime
Compute arrivals/ray paths, geodesy, beachballs, spectra, or scientific figures	travel-times-and-imaging	TauPyModel, geodetics, imaging, Matplotlib

A task can load multiple routes. For example, retrieve with data-access, serialize with formats-and-metadata, then process with waveform-processing or signal-analysis.

Shared operating rules

1. Make the data boundary explicit: local file, synthetic fixture, local archive, or live network service. Do not turn an offline task into a network request implicitly.
2. Preserve raw inputs and write fresh outputs by default. ObsPy processing methods commonly mutate Trace/Stream; copy before destructive transforms.
3. Record UTC bounds, NSLC identifiers, sample rate, units/response status, format, parameters, output path, and validation checks.
4. Prefer explicit format names and bounded query windows. Check returned object counts, gaps/overlaps, metadata, and output re-openability rather than accepting a successful call at face value.
5. Use MPLBACKEND=Agg, show=False, and explicit output files for headless plotting. Treat Cartopy, shapefile, credentials, and live service access as optional prerequisites, not silent fallbacks.

Public boundaries and refresh

This graph covers user-facing package workflows, public CLIs, and representative CPU/offline behavior. It does not cover maintainer release automation, docs deployment, large benchmark/training operations, or every legacy file format. Read provenance when working from a checkout or deciding whether this graph is stale; refresh it when the package version, public entry points, or major source evidence differ.