tessl/pypi-gwpy
A python package for gravitational-wave astrophysics
—
Pending
timeseries.mddocs/
Time Series Analysis
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.
Capabilities
TimeSeries - Main Time Domain Data Class
The primary class for handling time-domain gravitational-wave data with built-in support for metadata, GPS timing, and domain-specific operations.
class TimeSeries(Series):
def __init__(self, data, times=None, t0=None, dt=None, sample_rate=None,
unit=None, name=None, channel=None, **kwargs):
"""
Create a new TimeSeries.
Parameters:
- data: array-like, time series data values
- times: array-like, time values for each sample
- t0: float, GPS start time
- dt: float, time between samples (seconds)
- sample_rate: float, samples per second (Hz)
- unit: str or Unit, physical unit of the data
- name: str, name for this series
- channel: str, source channel name
"""
@classmethod
def read(cls, source, channel=None, start=None, end=None, format=None, **kwargs):
"""
Read TimeSeries from various file formats.
Parameters:
- source: str, path to data file or NDS server
- channel: str, name of channel to read
- start: float, GPS start time
- end: float, GPS end time
- format: str, file format ('gwf', 'hdf5', 'txt', etc.)
Returns:
TimeSeries object
"""
@classmethod
def get(cls, channel, start, end, host=None, port=None, **kwargs):
"""
Fetch data from NDS server.
Parameters:
- channel: str, channel name
- start: float, GPS start time
- end: float, GPS end time
- host: str, NDS server hostname
- port: int, NDS server port
Returns:
TimeSeries object
"""
@classmethod
def fetch_open_data(cls, ifo, start, end, **kwargs):
"""
Fetch open gravitational-wave data from GWOSC.
Parameters:
- ifo: str, interferometer ('H1', 'L1', 'V1')
- start: float, GPS start time
- end: float, GPS end time
Returns:
TimeSeries object
"""
def filter(self, *filters, **kwargs):
"""
Apply digital filters to the time series.
Parameters:
- *filters: filter specifications (zpk, sos, ba tuples)
- filtfilt: bool, apply zero-phase filtering
Returns:
Filtered TimeSeries
"""
def resample(self, rate, **kwargs):
"""
Resample to a different sampling rate.
Parameters:
- rate: float, new sample rate in Hz
Returns:
Resampled TimeSeries
"""
def crop(self, start=None, end=None, copy=True):
"""
Crop to a specific time segment.
Parameters:
- start: float, start time
- end: float, end time
- copy: bool, return copy or view
Returns:
Cropped TimeSeries
"""
def psd(self, fftlength=None, overlap=None, window='hann', method='welch', **kwargs):
"""
Calculate power spectral density.
Parameters:
- fftlength: float, FFT length in seconds
- overlap: float, overlap between segments in seconds
- window: str, window function
- method: str, PSD estimation method
Returns:
FrequencySeries with PSD
"""
def asd(self, fftlength=None, overlap=None, **kwargs):
"""
Calculate amplitude spectral density (square root of PSD).
Returns:
FrequencySeries with ASD
"""
def spectrogram(self, stride, fftlength=None, overlap=None, **kwargs):
"""
Calculate time-frequency spectrogram.
Parameters:
- stride: float, time between spectrogram bins
- fftlength: float, FFT length for each bin
- overlap: float, overlap between FFTs
Returns:
Spectrogram object
"""
def q_transform(self, **kwargs):
"""
Calculate Q-transform for transient analysis.
Returns:
Spectrogram with Q-transform data
"""
def whiten(self, fftlength=None, overlap=None, method='welch', **kwargs):
"""
Whiten the data using its own PSD.
Returns:
Whitened TimeSeries
"""
def bandpass(self, flow, fhigh, **kwargs):
"""
Apply bandpass filter.
Parameters:
- flow: float, low frequency cutoff
- fhigh: float, high frequency cutoff
Returns:
Filtered TimeSeries
"""
def highpass(self, frequency, **kwargs):
"""
Apply highpass filter.
Parameters:
- frequency: float, cutoff frequency
Returns:
Filtered TimeSeries
"""
def lowpass(self, frequency, **kwargs):
"""
Apply lowpass filter.
Parameters:
- frequency: float, cutoff frequency
Returns:
Filtered TimeSeries
"""
def notch(self, frequency, type='iir', filtfilt=True, **kwargs):
"""
Notch out a frequency from the TimeSeries.
Parameters:
- frequency: float, frequency to notch (Hz)
- type: str, filter type ('iir' or 'fir')
- filtfilt: bool, apply zero-phase filtering
Returns:
Filtered TimeSeries
"""
def zpk(self, zeros, poles, gain, analog=True, **kwargs):
"""
Apply zero-pole-gain filter to the TimeSeries.
Parameters:
- zeros: array-like, filter zeros
- poles: array-like, filter poles
- gain: float, filter gain
- analog: bool, analog (True) or digital (False) filter
Returns:
Filtered TimeSeries
"""
def to_lal(self):
"""
Convert to LAL TimeSeries object.
Returns:
LAL TimeSeries
"""
def to_pycbc(self, copy=True):
"""
Convert to PyCBC TimeSeries object.
Parameters:
- copy: bool, copy data (default True)
Returns:
PyCBC TimeSeries
"""
@classmethod
def from_lal(cls, lalts, copy=True):
"""
Convert from LAL TimeSeries.
Parameters:
- lalts: LAL TimeSeries object
- copy: bool, copy data (default True)
Returns:
GWpy TimeSeries
"""
@classmethod
def from_pycbc(cls, pycbcseries, copy=True):
"""
Convert from PyCBC TimeSeries.
Parameters:
- pycbcseries: PyCBC TimeSeries object
- copy: bool, copy data (default True)
Returns:
GWpy TimeSeries
"""
def plot(self, **kwargs):
"""
Create a plot of the time series.
Returns:
Plot object
"""StateVector - Boolean Time Series for Detector States
Specialized TimeSeries for handling boolean state information and bit-packed data quality flags.
class StateVector(TimeSeries):
def __init__(self, data, bits=None, **kwargs):
"""
Create StateVector for boolean/bit data.
Parameters:
- data: array-like, boolean or integer bit data
- bits: list, bit definitions/names
"""
def to_dqflags(self, bits=None, **kwargs):
"""
Convert to DataQualityFlag objects.
Parameters:
- bits: list, specific bits to convert
Returns:
DataQualityDict with flags for each bit
"""
def get_bit_series(self, bits):
"""
Extract specific bits as separate time series.
Parameters:
- bits: int or list, bit indices to extract
Returns:
StateVector with selected bits
"""StateTimeSeries - Time Series of State Durations
Time series where each sample represents a state that persists for the sample duration.
class StateTimeSeries(StateVector):
def __init__(self, data, **kwargs):
"""
Time series of states with duration.
"""
def to_dqflag(self, **kwargs):
"""
Convert to DataQualityFlag.
Returns:
DataQualityFlag object
"""Collection Classes
Classes for handling multiple time series objects.
class TimeSeriesDict(dict):
def __init__(self, *args, **kwargs):
"""
Dictionary of TimeSeries objects.
"""
@classmethod
def read(cls, source, channels, **kwargs):
"""
Read multiple channels from data source.
Parameters:
- source: str, data source
- channels: list, channel names
Returns:
TimeSeriesDict with data for each channel
"""
@classmethod
def get(cls, channels, start, end, **kwargs):
"""
Fetch multiple channels from NDS.
Returns:
TimeSeriesDict with data for each channel
"""
def resample(self, rate, **kwargs):
"""
Resample all time series.
Returns:
Resampled TimeSeriesDict
"""
def plot(self, **kwargs):
"""
Plot all time series.
Returns:
Plot object
"""
class TimeSeriesList(list):
def __init__(self, *args, **kwargs):
"""
List of TimeSeries objects.
"""
def join(self, gap='raise', **kwargs):
"""
Join time series into single TimeSeries.
Parameters:
- gap: str, how to handle gaps ('raise', 'ignore', 'pad')
Returns:
Single joined TimeSeries
"""Usage Examples
Reading Gravitational-Wave Data
from gwpy.timeseries import TimeSeries
# Read from GWF file
strain = TimeSeries.read('H-H1_GWOSC_16KHZ_R1-1126259447-32.gwf',
'H1:GWOSC-16KHZ_R1_STRAIN')
# Fetch from NDS server
aux = TimeSeries.get('H1:LSC-DARM_ERR_DBL_DQ',
start=1126259446, end=1126259478)
# Get open data from GWOSC
strain = TimeSeries.fetch_open_data('H1', 1126259446, 1126259478,
sample_rate=4096)Signal Processing
# Apply bandpass filter for GW detection band
filtered = strain.bandpass(30, 400)
# Whiten the data
whitened = strain.whiten(fftlength=4, overlap=2)
# Calculate PSD for noise characterization
psd = strain.psd(fftlength=4, overlap=2)
# Resample to lower rate
downsampled = strain.resample(2048)Working with State Data
from gwpy.timeseries import StateVector
# Read bit-packed state vector
state = StateVector.read('H-H1_STATE-1126259446-32.gwf',
'H1:GDS-CALIB_STATE_VECTOR',
bits=['Locked', 'Science', 'Calibrated'])
# Convert to data quality flags
flags = state.to_dqflags()
# Check specific bits
locked_times = state.get_bit_series('Locked')Install with Tessl CLI
npx tessl i tessl/pypi-gwpy