0
# ObsPy
1

2
A 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.
3

4
## Package Information
5

6
- **Package Name**: obspy
7
- **Language**: Python (3.8+)
8
- **Installation**: `pip install obspy`
9
- **License**: LGPL-3.0
10
- **Documentation**: https://docs.obspy.org/
11

12
## Core Imports
13

14
```python
15
import obspy
16
```
17

18
Most common pattern for accessing core functionality:
19

20
```python
21
from obspy import UTCDateTime, Trace, Stream, read, read_events, read_inventory, Inventory
22
```
23

24
Specific module imports:
25

26
```python
27
from obspy.core import Stream, Trace, UTCDateTime
28
from obspy.clients.fdsn import Client
29
from obspy.signal.trigger import classic_sta_lta
30
import obspy.signal.filter as signal_filter
31
```
32

33
## Basic Usage
34

35
```python
36
import obspy
37
from obspy import UTCDateTime
38
from obspy.clients.fdsn import Client
39

40
# Read local seismic data files
41
st = obspy.read('path/to/seismic/data.mseed')
42
print(st)  # Stream containing traces
43

44
# Access individual traces
45
trace = st[0]  # First trace
46
print(f"Station: {trace.stats.station}")
47
print(f"Start time: {trace.stats.starttime}")
48
print(f"Sample rate: {trace.stats.sampling_rate} Hz")
49

50
# Basic signal processing
51
st.detrend('linear')
52
st.filter('bandpass', freqmin=1, freqmax=5)
53
st.plot()  # Visualize the data
54

55
# Access seismological data centers
56
client = Client("IRIS")
57
starttime = UTCDateTime("2023-01-01")
58
endtime = UTCDateTime("2023-01-02")
59

60
# Download waveform data
61
st = client.get_waveforms("IU", "ANMO", "00", "BHZ", starttime, endtime)
62

63
# Download earthquake catalog
64
catalog = client.get_events(starttime=starttime, endtime=endtime, minmagnitude=6.0)
65
print(f"Found {len(catalog)} events")
66

67
# Download station metadata
68
inventory = client.get_stations(network="IU", station="ANMO")
69
```
70

71
## Architecture
72

73
ObsPy is organized around fundamental seismological data structures and processing workflows:
74

75
- **Core Data Objects**: UTCDateTime, Trace, Stream, Event, Inventory provide the foundation for all seismological data handling
76
- **Universal I/O System**: Automatic format detection and unified read/write interface for 67+ seismological file formats
77
- **Client Framework**: Standardized access to 67+ global seismological data centers through web services
78
- **Signal Processing Toolkit**: Comprehensive suite of seismological signal processing algorithms
79
- **Visualization System**: Integrated plotting capabilities for waveforms, spectrograms, and seismological visualizations
80

81
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.
82

83
## Capabilities
84

85
### Core Data Structures
86

87
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.
88

89
```python { .api }
90
class UTCDateTime:
91
    def __init__(self, *args, **kwargs): ...
92
    def strftime(self, fmt: str) -> str: ...
93

94
class Trace:
95
    def __init__(self, data=None, header=None): ...
96
    def plot(self, **kwargs): ...
97
    def filter(self, type: str, **options): ...
98
    def trim(self, starttime=None, endtime=None): ...
99

100
class Stream:
101
    def __init__(self, traces=None): ...
102
    def append(self, trace: Trace): ...
103
    def select(self, **kwargs) -> 'Stream': ...
104
    def merge(self, method=0, fill_value=None, interpolation_samples=0, **kwargs): ...
105

106
def read(pathname_or_url, format=None, **kwargs) -> Stream: ...
107
def read_events(pathname_or_url, format=None, **kwargs): ...
108
def read_inventory(pathname_or_url, format=None, **kwargs): ...
109
```
110

111
[Core Data Structures](./core-data-structures.md)
112

113
### Signal Processing
114

115
Comprehensive signal processing toolkit including digital filters, triggering algorithms, spectral analysis, array processing, and coordinate transformations specifically designed for seismological data analysis.
116

117
```python { .api }
118
# Filter functions (obspy.signal.filter)
119
def bandpass(data, freqmin: float, freqmax: float, df: float, **kwargs): ...
120
def lowpass(data, freq: float, df: float, **kwargs): ...
121
def highpass(data, freq: float, df: float, **kwargs): ...
122

123
# Trigger functions (obspy.signal.trigger)  
124
def classic_sta_lta(a, nsta: int, nlta: int): ...
125
def recursive_sta_lta(a, nsta: int, nlta: int): ...
126
def trigger_onset(charfct, thres1: float, thres2: float): ...
127

128
# Probabilistic Power Spectral Density
129
class PPSD:
130
    def __init__(self, stats, paz_or_resp, **kwargs): ...
131
    def add(self, stream): ...
132
    def plot(self, **kwargs): ...
133
```
134

135
[Signal Processing](./signal-processing.md)
136

137
### Data Center Clients
138

139
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.
140

141
```python { .api }
142
class Client:
143
    def __init__(self, base_url: str = "IRIS", **kwargs): ...
144
    def get_waveforms(self, network: str, station: str, location: str, 
145
                     channel: str, starttime, endtime, **kwargs) -> Stream: ...
146
    def get_events(self, starttime=None, endtime=None, **kwargs): ...
147
    def get_stations(self, network=None, station=None, **kwargs): ...
148
    def get_waveforms_bulk(self, bulk, **kwargs) -> Stream: ...
149

150
class RoutingClient:
151
    def __init__(self, routing_type: str = "eida-routing", **kwargs): ...
152
```
153

154
[Data Center Clients](./data-center-clients.md)
155

156
### File Format I/O
157

158
Support for 67+ seismological file formats with automatic format detection, unified read/write interfaces, and format-specific optimizations for waveforms, events, and station metadata.
159

160
```python { .api }
161
# Format support accessed through unified read functions
162
def read(pathname_or_url, format=None, **kwargs) -> Stream: ...
163
def read_events(pathname_or_url, format=None, **kwargs): ...  
164
def read_inventory(pathname_or_url, format=None, **kwargs): ...
165

166
# Stream/Catalog/Inventory write methods
167
Stream.write(self, filename: str, format: str, **kwargs): ...
168
Catalog.write(self, filename: str, format: str, **kwargs): ...
169
Inventory.write(self, filename: str, format: str, **kwargs): ...
170
```
171

172
**Supported Waveform Formats**: MiniSEED, SAC, GSE2, SEG-Y, WIN, CSS, SEISAN, AH, WAV, GCF, RefTek, and 15+ others
173

174
**Supported Event Formats**: QuakeML, NDK, CMTSOLUTION, Nordic, NonLinLoc, ZMAP, JSON, KML, and 10+ others
175

176
**Supported Inventory Formats**: StationXML, SEED/XSEED, SACPZ, CSS, RESP, and 4+ others
177

178
[File Format I/O](./file-format-io.md)
179

180
### Travel Time Calculations
181

182
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.
183

184
```python { .api }
185
class TauPyModel:
186
    def __init__(self, model: str = "iasp91", **kwargs): ...
187
    def get_travel_times(self, source_depth_in_km: float, 
188
                        distance_in_degree: float, **kwargs): ...
189
    def get_ray_paths(self, source_depth_in_km: float,
190
                     distance_in_degree: float, **kwargs): ...
191
    def get_pierce_points(self, source_depth_in_km: float,
192
                         distance_in_degree: float, **kwargs): ...
193

194
def plot_travel_times(source_depth: float, **kwargs): ...
195
def plot_ray_paths(source_depth: float, distance: float, **kwargs): ...
196
```
197

198
**Available Earth Models**: ak135, iasp91, prem, 1066a, 1066b, herrin, jb, pwdk, sp6
199

200
[Travel Time Calculations](./travel-time-calculations.md)
201

202
### Geodetic Calculations  
203

204
Geographic and coordinate system calculations for seismological applications including distance, azimuth, and coordinate transformations using spherical and ellipsoidal Earth models.
205

206
```python { .api }
207
def gps2dist_azimuth(lat1: float, lon1: float, lat2: float, lon2: float): ...
208
def calc_vincenty_inverse(lat1: float, lon1: float, lat2: float, lon2: float): ...
209
def degrees2kilometers(degrees: float, radius: float = 6371.0): ...
210
def kilometers2degrees(kilometers: float, radius: float = 6371.0): ...
211
def locations2degrees(lat1: float, lon1: float, lat2: float, lon2: float): ...
212

213
class FlinnEngdahl:
214
    def __init__(self): ...
215
    def get_region(self, longitude: float, latitude: float) -> str: ...
216
```
217

218
[Geodetic Calculations](./geodetic-calculations.md)
219

220
### Visualization and Imaging
221

222
Seismological visualization capabilities including waveform plotting, spectrograms, focal mechanism beachballs, and array processing visualizations integrated with matplotlib.
223

224
```python { .api }
225
# Integrated plotting methods
226
Trace.plot(self, **kwargs): ...
227
Stream.plot(self, **kwargs): ...
228
Trace.spectrogram(self, **kwargs): ...
229
Stream.spectrogram(self, **kwargs): ...
230

231
# Beachball plotting (obspy.imaging.beachball)
232
def beachball(fm, **kwargs): ...
233
def beach(fm, **kwargs): ...
234

235
# PPSD plotting
236
PPSD.plot(self, **kwargs): ...
237
```
238

239
[Visualization and Imaging](./visualization-imaging.md)
240

241
### Additional Modules
242

243
**Real-time Processing** (`obspy.realtime`): Specialized classes (`RtTrace`, `RtMemory`) for real-time seismological data processing and streaming workflows.
244

245
**Scripts and CLI Tools** (`obspy.scripts`): Command-line utilities for batch processing, format conversion, and automated seismological workflows.
246

247
**Performance Libraries** (`obspy.lib`): Low-level C/Fortran libraries providing optimized implementations for computationally intensive seismological operations.
248

249
## Types
250

251
```python { .api }
252
# Core exceptions
253
class ObsPyException(Exception): ...
254
class ObsPyReadingError(ObsPyException): ...
255
class ZeroSamplingRate(ObsPyException): ...
256

257
# Utility types
258
class AttribDict(dict):
259
    def __init__(self, *args, **kwargs): ...
260
    def __getattr__(self, name): ...
261
    def __setattr__(self, name, value): ...
262
```