0
# Time Series Analysis
1
2
Tools for analyzing time-domain gravitational-wave data including strain measurements, auxiliary channels, and detector state information. GWpy's TimeSeries class extends numpy arrays with gravitational-wave specific metadata and I/O capabilities.
3
4
## Capabilities
5
6
### TimeSeries - Main Time Domain Data Class
7
8
The primary class for handling time-domain gravitational-wave data with built-in support for metadata, GPS timing, and domain-specific operations.
9
10
```python { .api }
11
class TimeSeries(Series):
12
def __init__(self, data, times=None, t0=None, dt=None, sample_rate=None,
13
unit=None, name=None, channel=None, **kwargs):
14
"""
15
Create a new TimeSeries.
16
17
Parameters:
18
- data: array-like, time series data values
19
- times: array-like, time values for each sample
20
- t0: float, GPS start time
21
- dt: float, time between samples (seconds)
22
- sample_rate: float, samples per second (Hz)
23
- unit: str or Unit, physical unit of the data
24
- name: str, name for this series
25
- channel: str, source channel name
26
"""
27
28
@classmethod
29
def read(cls, source, channel=None, start=None, end=None, format=None, **kwargs):
30
"""
31
Read TimeSeries from various file formats.
32
33
Parameters:
34
- source: str, path to data file or NDS server
35
- channel: str, name of channel to read
36
- start: float, GPS start time
37
- end: float, GPS end time
38
- format: str, file format ('gwf', 'hdf5', 'txt', etc.)
39
40
Returns:
41
TimeSeries object
42
"""
43
44
@classmethod
45
def get(cls, channel, start, end, host=None, port=None, **kwargs):
46
"""
47
Fetch data from NDS server.
48
49
Parameters:
50
- channel: str, channel name
51
- start: float, GPS start time
52
- end: float, GPS end time
53
- host: str, NDS server hostname
54
- port: int, NDS server port
55
56
Returns:
57
TimeSeries object
58
"""
59
60
@classmethod
61
def fetch_open_data(cls, ifo, start, end, **kwargs):
62
"""
63
Fetch open gravitational-wave data from GWOSC.
64
65
Parameters:
66
- ifo: str, interferometer ('H1', 'L1', 'V1')
67
- start: float, GPS start time
68
- end: float, GPS end time
69
70
Returns:
71
TimeSeries object
72
"""
73
74
def filter(self, *filters, **kwargs):
75
"""
76
Apply digital filters to the time series.
77
78
Parameters:
79
- *filters: filter specifications (zpk, sos, ba tuples)
80
- filtfilt: bool, apply zero-phase filtering
81
82
Returns:
83
Filtered TimeSeries
84
"""
85
86
def resample(self, rate, **kwargs):
87
"""
88
Resample to a different sampling rate.
89
90
Parameters:
91
- rate: float, new sample rate in Hz
92
93
Returns:
94
Resampled TimeSeries
95
"""
96
97
def crop(self, start=None, end=None, copy=True):
98
"""
99
Crop to a specific time segment.
100
101
Parameters:
102
- start: float, start time
103
- end: float, end time
104
- copy: bool, return copy or view
105
106
Returns:
107
Cropped TimeSeries
108
"""
109
110
def psd(self, fftlength=None, overlap=None, window='hann', method='welch', **kwargs):
111
"""
112
Calculate power spectral density.
113
114
Parameters:
115
- fftlength: float, FFT length in seconds
116
- overlap: float, overlap between segments in seconds
117
- window: str, window function
118
- method: str, PSD estimation method
119
120
Returns:
121
FrequencySeries with PSD
122
"""
123
124
def asd(self, fftlength=None, overlap=None, **kwargs):
125
"""
126
Calculate amplitude spectral density (square root of PSD).
127
128
Returns:
129
FrequencySeries with ASD
130
"""
131
132
def spectrogram(self, stride, fftlength=None, overlap=None, **kwargs):
133
"""
134
Calculate time-frequency spectrogram.
135
136
Parameters:
137
- stride: float, time between spectrogram bins
138
- fftlength: float, FFT length for each bin
139
- overlap: float, overlap between FFTs
140
141
Returns:
142
Spectrogram object
143
"""
144
145
def q_transform(self, **kwargs):
146
"""
147
Calculate Q-transform for transient analysis.
148
149
Returns:
150
Spectrogram with Q-transform data
151
"""
152
153
def whiten(self, fftlength=None, overlap=None, method='welch', **kwargs):
154
"""
155
Whiten the data using its own PSD.
156
157
Returns:
158
Whitened TimeSeries
159
"""
160
161
def bandpass(self, flow, fhigh, **kwargs):
162
"""
163
Apply bandpass filter.
164
165
Parameters:
166
- flow: float, low frequency cutoff
167
- fhigh: float, high frequency cutoff
168
169
Returns:
170
Filtered TimeSeries
171
"""
172
173
def highpass(self, frequency, **kwargs):
174
"""
175
Apply highpass filter.
176
177
Parameters:
178
- frequency: float, cutoff frequency
179
180
Returns:
181
Filtered TimeSeries
182
"""
183
184
def lowpass(self, frequency, **kwargs):
185
"""
186
Apply lowpass filter.
187
188
Parameters:
189
- frequency: float, cutoff frequency
190
191
Returns:
192
Filtered TimeSeries
193
"""
194
195
def notch(self, frequency, type='iir', filtfilt=True, **kwargs):
196
"""
197
Notch out a frequency from the TimeSeries.
198
199
Parameters:
200
- frequency: float, frequency to notch (Hz)
201
- type: str, filter type ('iir' or 'fir')
202
- filtfilt: bool, apply zero-phase filtering
203
204
Returns:
205
Filtered TimeSeries
206
"""
207
208
def zpk(self, zeros, poles, gain, analog=True, **kwargs):
209
"""
210
Apply zero-pole-gain filter to the TimeSeries.
211
212
Parameters:
213
- zeros: array-like, filter zeros
214
- poles: array-like, filter poles
215
- gain: float, filter gain
216
- analog: bool, analog (True) or digital (False) filter
217
218
Returns:
219
Filtered TimeSeries
220
"""
221
222
def to_lal(self):
223
"""
224
Convert to LAL TimeSeries object.
225
226
Returns:
227
LAL TimeSeries
228
"""
229
230
def to_pycbc(self, copy=True):
231
"""
232
Convert to PyCBC TimeSeries object.
233
234
Parameters:
235
- copy: bool, copy data (default True)
236
237
Returns:
238
PyCBC TimeSeries
239
"""
240
241
@classmethod
242
def from_lal(cls, lalts, copy=True):
243
"""
244
Convert from LAL TimeSeries.
245
246
Parameters:
247
- lalts: LAL TimeSeries object
248
- copy: bool, copy data (default True)
249
250
Returns:
251
GWpy TimeSeries
252
"""
253
254
@classmethod
255
def from_pycbc(cls, pycbcseries, copy=True):
256
"""
257
Convert from PyCBC TimeSeries.
258
259
Parameters:
260
- pycbcseries: PyCBC TimeSeries object
261
- copy: bool, copy data (default True)
262
263
Returns:
264
GWpy TimeSeries
265
"""
266
267
def plot(self, **kwargs):
268
"""
269
Create a plot of the time series.
270
271
Returns:
272
Plot object
273
"""
274
```
275
276
### StateVector - Boolean Time Series for Detector States
277
278
Specialized TimeSeries for handling boolean state information and bit-packed data quality flags.
279
280
```python { .api }
281
class StateVector(TimeSeries):
282
def __init__(self, data, bits=None, **kwargs):
283
"""
284
Create StateVector for boolean/bit data.
285
286
Parameters:
287
- data: array-like, boolean or integer bit data
288
- bits: list, bit definitions/names
289
"""
290
291
def to_dqflags(self, bits=None, **kwargs):
292
"""
293
Convert to DataQualityFlag objects.
294
295
Parameters:
296
- bits: list, specific bits to convert
297
298
Returns:
299
DataQualityDict with flags for each bit
300
"""
301
302
def get_bit_series(self, bits):
303
"""
304
Extract specific bits as separate time series.
305
306
Parameters:
307
- bits: int or list, bit indices to extract
308
309
Returns:
310
StateVector with selected bits
311
"""
312
```
313
314
### StateTimeSeries - Time Series of State Durations
315
316
Time series where each sample represents a state that persists for the sample duration.
317
318
```python { .api }
319
class StateTimeSeries(StateVector):
320
def __init__(self, data, **kwargs):
321
"""
322
Time series of states with duration.
323
"""
324
325
def to_dqflag(self, **kwargs):
326
"""
327
Convert to DataQualityFlag.
328
329
Returns:
330
DataQualityFlag object
331
"""
332
```
333
334
### Collection Classes
335
336
Classes for handling multiple time series objects.
337
338
```python { .api }
339
class TimeSeriesDict(dict):
340
def __init__(self, *args, **kwargs):
341
"""
342
Dictionary of TimeSeries objects.
343
"""
344
345
@classmethod
346
def read(cls, source, channels, **kwargs):
347
"""
348
Read multiple channels from data source.
349
350
Parameters:
351
- source: str, data source
352
- channels: list, channel names
353
354
Returns:
355
TimeSeriesDict with data for each channel
356
"""
357
358
@classmethod
359
def get(cls, channels, start, end, **kwargs):
360
"""
361
Fetch multiple channels from NDS.
362
363
Returns:
364
TimeSeriesDict with data for each channel
365
"""
366
367
def resample(self, rate, **kwargs):
368
"""
369
Resample all time series.
370
371
Returns:
372
Resampled TimeSeriesDict
373
"""
374
375
def plot(self, **kwargs):
376
"""
377
Plot all time series.
378
379
Returns:
380
Plot object
381
"""
382
383
class TimeSeriesList(list):
384
def __init__(self, *args, **kwargs):
385
"""
386
List of TimeSeries objects.
387
"""
388
389
def join(self, gap='raise', **kwargs):
390
"""
391
Join time series into single TimeSeries.
392
393
Parameters:
394
- gap: str, how to handle gaps ('raise', 'ignore', 'pad')
395
396
Returns:
397
Single joined TimeSeries
398
"""
399
```
400
401
### Usage Examples
402
403
#### Reading Gravitational-Wave Data
404
405
```python
406
from gwpy.timeseries import TimeSeries
407
408
# Read from GWF file
409
strain = TimeSeries.read('H-H1_GWOSC_16KHZ_R1-1126259447-32.gwf',
410
'H1:GWOSC-16KHZ_R1_STRAIN')
411
412
# Fetch from NDS server
413
aux = TimeSeries.get('H1:LSC-DARM_ERR_DBL_DQ',
414
start=1126259446, end=1126259478)
415
416
# Get open data from GWOSC
417
strain = TimeSeries.fetch_open_data('H1', 1126259446, 1126259478,
418
sample_rate=4096)
419
```
420
421
#### Signal Processing
422
423
```python
424
# Apply bandpass filter for GW detection band
425
filtered = strain.bandpass(30, 400)
426
427
# Whiten the data
428
whitened = strain.whiten(fftlength=4, overlap=2)
429
430
# Calculate PSD for noise characterization
431
psd = strain.psd(fftlength=4, overlap=2)
432
433
# Resample to lower rate
434
downsampled = strain.resample(2048)
435
```
436
437
#### Working with State Data
438
439
```python
440
from gwpy.timeseries import StateVector
441
442
# Read bit-packed state vector
443
state = StateVector.read('H-H1_STATE-1126259446-32.gwf',
444
'H1:GDS-CALIB_STATE_VECTOR',
445
bits=['Locked', 'Science', 'Calibrated'])
446
447
# Convert to data quality flags
448
flags = state.to_dqflags()
449
450
# Check specific bits
451
locked_times = state.get_bit_series('Locked')
452
```