0
# GWpy - Gravitational-Wave Astrophysics
1
2
GWpy is a collaboration-driven Python package providing comprehensive tools for studying data from ground-based gravitational-wave detectors like LIGO and Virgo. It offers a user-friendly, intuitive interface to common time-domain and frequency-domain data produced by gravitational-wave observatories, enabling researchers to perform complex astrophysical analyses with easy-to-follow workflows.
3
4
## Package Information
5
6
- **Package Name**: gwpy
7
- **Language**: Python
8
- **Installation**: `conda install -c conda-forge gwpy` or `pip install gwpy`
9
- **Documentation**: https://gwpy.github.io/docs/
10
- **License**: GPL-3.0-or-later
11
12
## Core Imports
13
14
```python
15
import gwpy
16
```
17
18
Common imports for working with gravitational-wave data:
19
20
```python
21
from gwpy.timeseries import TimeSeries
22
from gwpy.frequencyseries import FrequencySeries
23
from gwpy.spectrogram import Spectrogram
24
from gwpy.segments import DataQualityFlag, Segment
25
from gwpy.table import EventTable
26
from gwpy.plot import Plot
27
```
28
29
## Basic Usage
30
31
```python
32
from gwpy.timeseries import TimeSeries
33
from gwpy.segments import DataQualityFlag
34
35
# Read gravitational-wave strain data
36
strain = TimeSeries.read('H-H1_STRAIN-1126259446-32.gwf',
37
'H1:DCS-CALIB_STRAIN_C02',
38
start=1126259446, end=1126259478)
39
40
# Calculate power spectral density
41
psd = strain.psd(fftlength=4, overlap=2)
42
43
# Create a time-frequency spectrogram
44
spec = strain.spectrogram(stride=1, fftlength=4, overlap=2)
45
46
# Read data quality information
47
dqflag = DataQualityFlag.query('H1:DMT-ANALYSIS_READY:1',
48
start=1126259446, end=1126259478)
49
50
# Create a plot
51
plot = strain.plot()
52
plot.show()
53
```
54
55
## Architecture
56
57
GWpy is built around core data types that extend standard scientific Python libraries:
58
59
- **Data Types**: TimeSeries, FrequencySeries, Spectrogram extend numpy arrays with metadata
60
- **Collections**: Dict and List variants provide multi-channel data handling
61
- **I/O System**: Unified interface for reading/writing gravitational-wave data formats
62
- **Plotting**: Enhanced matplotlib integration with domain-specific visualizations
63
- **Signal Processing**: Specialized algorithms for gravitational-wave data analysis
64
65
The package integrates seamlessly with the broader scientific Python ecosystem (NumPy, SciPy, Astropy, Matplotlib) while providing gravitational-wave specific functionality and metadata handling.
66
67
## Capabilities
68
69
### Time Series Analysis
70
71
Tools for analyzing time-domain gravitational-wave data including strain measurements, auxiliary channels, and detector state information. Supports reading from various data formats and provides filtering, resampling, and statistical analysis.
72
73
```python { .api }
74
class TimeSeries(Series):
75
def __init__(self, data, times=None, **kwargs): ...
76
def read(source, channel, start=None, end=None, **kwargs): ...
77
def get(channel, start, end, **kwargs): ...
78
def filter(*filters, **kwargs): ...
79
def resample(rate, **kwargs): ...
80
def psd(fftlength=None, overlap=None, **kwargs): ...
81
def asd(fftlength=None, overlap=None, **kwargs): ...
82
83
class StateVector(TimeSeries):
84
def __init__(self, data, bits=None, **kwargs): ...
85
def to_dqflags(self): ...
86
```
87
88
[Time Series Analysis](./timeseries.md)
89
90
### Frequency Domain Analysis
91
92
Spectral analysis tools for power spectral densities, amplitude spectral densities, and frequency-domain filtering. Includes methods for noise characterization and detector sensitivity analysis.
93
94
```python { .api }
95
class FrequencySeries(Series):
96
def __init__(self, data, frequencies=None, **kwargs): ...
97
def read(source, **kwargs): ...
98
def plot(**kwargs): ...
99
def zpk(zeros, poles, gain, **kwargs): ...
100
101
class SpectralVariance(Array2D):
102
def __init__(self, data, **kwargs): ...
103
```
104
105
[Frequency Domain Analysis](./frequencyseries.md)
106
107
### Time-Frequency Analysis
108
109
Time-frequency representation tools including spectrograms and Q-transforms for transient gravitational-wave event analysis and glitch characterization.
110
111
```python { .api }
112
class Spectrogram(Array2D):
113
def __init__(self, data, times=None, frequencies=None, **kwargs): ...
114
def read(source, **kwargs): ...
115
def ratio(method='median'): ...
116
def q_transform(**kwargs): ...
117
```
118
119
[Time-Frequency Analysis](./spectrogram.md)
120
121
### Segments and Data Quality
122
123
Data quality flag handling and time segment management for identifying valid analysis periods and detector operational states.
124
125
```python { .api }
126
class Segment:
127
def __init__(self, start, end): ...
128
def __contains__(self, other): ...
129
def protract(self, x): ...
130
def contract(self, x): ...
131
132
class DataQualityFlag:
133
def __init__(self, name=None, **kwargs): ...
134
def query(flag, start, end, **kwargs): ...
135
def read(source, **kwargs): ...
136
def write(target, **kwargs): ...
137
```
138
139
[Segments and Data Quality](./segments.md)
140
141
### Signal Processing
142
143
Advanced signal processing algorithms including digital filtering, window functions, Q-transforms, and spectral estimation methods optimized for gravitational-wave data.
144
145
```python { .api }
146
# Filter design functions
147
def lowpass(frequency, sample_rate, **kwargs): ...
148
def highpass(frequency, sample_rate, **kwargs): ...
149
def bandpass(flow, fhigh, sample_rate, **kwargs): ...
150
def notch(frequency, sample_rate, **kwargs): ...
151
152
# Spectral analysis functions
153
def welch(data, **kwargs): ...
154
def bartlett(data, **kwargs): ...
155
def median(data, **kwargs): ...
156
def coherence(x, y, **kwargs): ...
157
```
158
159
[Signal Processing](./signal-processing.md)
160
161
### Plotting and Visualization
162
163
Enhanced matplotlib integration with gravitational-wave specific plot types, GPS time handling, and publication-quality figure generation.
164
165
```python { .api }
166
class Plot:
167
def __init__(self, *data, **kwargs): ...
168
def add_timeseries(self, ts, **kwargs): ...
169
def add_spectrogram(self, spec, **kwargs): ...
170
def show(self, **kwargs): ...
171
def save(self, filename, **kwargs): ...
172
173
class BodePlot(Plot):
174
def __init__(self, **kwargs): ...
175
```
176
177
[Plotting and Visualization](./plotting.md)
178
179
### Detector Utilities
180
181
Detector-specific utilities for channel management, timezone handling, and interferometer-specific configurations.
182
183
```python { .api }
184
class Channel:
185
def __init__(self, name, **kwargs): ...
186
def query(self, **kwargs): ...
187
188
def get_timezone(ifo): ...
189
def get_timezone_offset(ifo, dt=None): ...
190
```
191
192
[Detector Utilities](./detector.md)
193
194
### Astrophysics Calculations
195
196
Sensitivity and detection range calculations for gravitational-wave sources including binary inspirals and burst sources.
197
198
```python { .api }
199
def inspiral_range(psd, **kwargs): ...
200
def burst_range(spectrum, **kwargs): ...
201
def sensemon_range(psd, **kwargs): ...
202
def range_timeseries(timeseries, **kwargs): ...
203
```
204
205
[Astrophysics Calculations](./astrophysics.md)
206
207
## Types
208
209
```python { .api }
210
# Core data types from gwpy.types
211
from gwpy.types import Array, Series, Array2D
212
213
class Array:
214
def __init__(self, data, **kwargs): ...
215
def copy(self): ...
216
def __getitem__(self, item): ...
217
def value_at(self, x): ...
218
def shift(self, delta): ...
219
220
class Series(Array):
221
def __init__(self, data, index=None, **kwargs): ...
222
def plot(**kwargs): ...
223
def write(target, **kwargs): ...
224
def crop(self, start=None, end=None, copy=False): ...
225
def append(self, other, inplace=True, **kwargs): ...
226
def prepend(self, other, inplace=True, **kwargs): ...
227
228
class Array2D(Array):
229
def __init__(self, data, **kwargs): ...
230
def transpose(self): ...
231
232
# Collection types
233
from gwpy.timeseries import TimeSeriesDict, TimeSeriesList
234
from gwpy.frequencyseries import FrequencySeriesDict, FrequencySeriesList
235
from gwpy.segments import SegmentList, DataQualityDict
236
237
# Time types
238
from gwpy.time import Time, LIGOTimeGPS
239
from astropy.time import Time
240
241
# Event types
242
from gwpy.table import EventTable
243
244
# I/O and utility types
245
from astropy.units import Unit, Quantity
246
import numpy as np
247
```