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
```