ObsPy is a Python toolbox for seismology providing parsers for seismological data formats, clients for data centers, and signal processing routines for seismological time series analysis.
npx @tessl/cli install tessl/pypi-obspy@1.4.0A comprehensive Python framework for seismological data processing and analysis. ObsPy provides parsers for common seismological file formats, clients to access seismological data centers, and a complete toolkit for seismological signal processing including filtering, triggering, instrument response correction, travel time calculations, and beamforming.
pip install obspyimport obspyMost common pattern for accessing core functionality:
from obspy import UTCDateTime, Trace, Stream, read, read_events, read_inventory, InventorySpecific module imports:
from obspy.core import Stream, Trace, UTCDateTime
from obspy.clients.fdsn import Client
from obspy.signal.trigger import classic_sta_lta
import obspy.signal.filter as signal_filterimport obspy
from obspy import UTCDateTime
from obspy.clients.fdsn import Client
# Read local seismic data files
st = obspy.read('path/to/seismic/data.mseed')
print(st) # Stream containing traces
# Access individual traces
trace = st[0] # First trace
print(f"Station: {trace.stats.station}")
print(f"Start time: {trace.stats.starttime}")
print(f"Sample rate: {trace.stats.sampling_rate} Hz")
# Basic signal processing
st.detrend('linear')
st.filter('bandpass', freqmin=1, freqmax=5)
st.plot() # Visualize the data
# Access seismological data centers
client = Client("IRIS")
starttime = UTCDateTime("2023-01-01")
endtime = UTCDateTime("2023-01-02")
# Download waveform data
st = client.get_waveforms("IU", "ANMO", "00", "BHZ", starttime, endtime)
# Download earthquake catalog
catalog = client.get_events(starttime=starttime, endtime=endtime, minmagnitude=6.0)
print(f"Found {len(catalog)} events")
# Download station metadata
inventory = client.get_stations(network="IU", station="ANMO")ObsPy is organized around fundamental seismological data structures and processing workflows:
This design enables rapid development of seismological applications by providing a unified interface to the global seismological data ecosystem while maintaining the flexibility to handle specialized seismological workflows.
Fundamental data objects for seismological time series, event catalogs, and station metadata. These objects provide the foundation for all ObsPy functionality with automatic format detection and seamless integration.
class UTCDateTime:
def __init__(self, *args, **kwargs): ...
def strftime(self, fmt: str) -> str: ...
class Trace:
def __init__(self, data=None, header=None): ...
def plot(self, **kwargs): ...
def filter(self, type: str, **options): ...
def trim(self, starttime=None, endtime=None): ...
class Stream:
def __init__(self, traces=None): ...
def append(self, trace: Trace): ...
def select(self, **kwargs) -> 'Stream': ...
def merge(self, method=0, fill_value=None, interpolation_samples=0, **kwargs): ...
def read(pathname_or_url, format=None, **kwargs) -> Stream: ...
def read_events(pathname_or_url, format=None, **kwargs): ...
def read_inventory(pathname_or_url, format=None, **kwargs): ...Comprehensive signal processing toolkit including digital filters, triggering algorithms, spectral analysis, array processing, and coordinate transformations specifically designed for seismological data analysis.
# Filter functions (obspy.signal.filter)
def bandpass(data, freqmin: float, freqmax: float, df: float, **kwargs): ...
def lowpass(data, freq: float, df: float, **kwargs): ...
def highpass(data, freq: float, df: float, **kwargs): ...
# Trigger functions (obspy.signal.trigger)
def classic_sta_lta(a, nsta: int, nlta: int): ...
def recursive_sta_lta(a, nsta: int, nlta: int): ...
def trigger_onset(charfct, thres1: float, thres2: float): ...
# Probabilistic Power Spectral Density
class PPSD:
def __init__(self, stats, paz_or_resp, **kwargs): ...
def add(self, stream): ...
def plot(self, **kwargs): ...Standardized clients for accessing 67+ global seismological data centers including IRIS, GEOFON, NCEDC, SCEDC, and others through FDSN web services with unified interfaces for waveforms, events, and station metadata.
class Client:
def __init__(self, base_url: str = "IRIS", **kwargs): ...
def get_waveforms(self, network: str, station: str, location: str,
channel: str, starttime, endtime, **kwargs) -> Stream: ...
def get_events(self, starttime=None, endtime=None, **kwargs): ...
def get_stations(self, network=None, station=None, **kwargs): ...
def get_waveforms_bulk(self, bulk, **kwargs) -> Stream: ...
class RoutingClient:
def __init__(self, routing_type: str = "eida-routing", **kwargs): ...Support for 67+ seismological file formats with automatic format detection, unified read/write interfaces, and format-specific optimizations for waveforms, events, and station metadata.
# Format support accessed through unified read functions
def read(pathname_or_url, format=None, **kwargs) -> Stream: ...
def read_events(pathname_or_url, format=None, **kwargs): ...
def read_inventory(pathname_or_url, format=None, **kwargs): ...
# Stream/Catalog/Inventory write methods
Stream.write(self, filename: str, format: str, **kwargs): ...
Catalog.write(self, filename: str, format: str, **kwargs): ...
Inventory.write(self, filename: str, format: str, **kwargs): ...Supported Waveform Formats: MiniSEED, SAC, GSE2, SEG-Y, WIN, CSS, SEISAN, AH, WAV, GCF, RefTek, and 15+ others
Supported Event Formats: QuakeML, NDK, CMTSOLUTION, Nordic, NonLinLoc, ZMAP, JSON, KML, and 10+ others
Supported Inventory Formats: StationXML, SEED/XSEED, SACPZ, CSS, RESP, and 4+ others
Seismic ray theory calculations using multiple Earth models for travel times, ray paths, and pierce points. Essential for earthquake location, phase identification, and tomographic studies.
class TauPyModel:
def __init__(self, model: str = "iasp91", **kwargs): ...
def get_travel_times(self, source_depth_in_km: float,
distance_in_degree: float, **kwargs): ...
def get_ray_paths(self, source_depth_in_km: float,
distance_in_degree: float, **kwargs): ...
def get_pierce_points(self, source_depth_in_km: float,
distance_in_degree: float, **kwargs): ...
def plot_travel_times(source_depth: float, **kwargs): ...
def plot_ray_paths(source_depth: float, distance: float, **kwargs): ...Available Earth Models: ak135, iasp91, prem, 1066a, 1066b, herrin, jb, pwdk, sp6
Geographic and coordinate system calculations for seismological applications including distance, azimuth, and coordinate transformations using spherical and ellipsoidal Earth models.
def gps2dist_azimuth(lat1: float, lon1: float, lat2: float, lon2: float): ...
def calc_vincenty_inverse(lat1: float, lon1: float, lat2: float, lon2: float): ...
def degrees2kilometers(degrees: float, radius: float = 6371.0): ...
def kilometers2degrees(kilometers: float, radius: float = 6371.0): ...
def locations2degrees(lat1: float, lon1: float, lat2: float, lon2: float): ...
class FlinnEngdahl:
def __init__(self): ...
def get_region(self, longitude: float, latitude: float) -> str: ...Seismological visualization capabilities including waveform plotting, spectrograms, focal mechanism beachballs, and array processing visualizations integrated with matplotlib.
# Integrated plotting methods
Trace.plot(self, **kwargs): ...
Stream.plot(self, **kwargs): ...
Trace.spectrogram(self, **kwargs): ...
Stream.spectrogram(self, **kwargs): ...
# Beachball plotting (obspy.imaging.beachball)
def beachball(fm, **kwargs): ...
def beach(fm, **kwargs): ...
# PPSD plotting
PPSD.plot(self, **kwargs): ...Real-time Processing (obspy.realtime): Specialized classes (RtTrace, RtMemory) for real-time seismological data processing and streaming workflows.
Scripts and CLI Tools (obspy.scripts): Command-line utilities for batch processing, format conversion, and automated seismological workflows.
Performance Libraries (obspy.lib): Low-level C/Fortran libraries providing optimized implementations for computationally intensive seismological operations.
# Core exceptions
class ObsPyException(Exception): ...
class ObsPyReadingError(ObsPyException): ...
class ZeroSamplingRate(ObsPyException): ...
# Utility types
class AttribDict(dict):
def __init__(self, *args, **kwargs): ...
def __getattr__(self, name): ...
def __setattr__(self, name, value): ...