Time Series

Stability: Stable

Overview

TimeSeries Class

Bases: PlotMixin, TimeSeriesInteropMixin, TimeSeriesAnalysisMixin, TimeSeriesResamplingMixin, TimeSeriesSignalMixin, SignalAnalysisMixin, TimeSeriesSpectralMixin, StatisticsMixin, FittingMixin, PhaseMethodsMixin, TimeSeriesCore

A data array holding some metadata to represent a time-series.

TimeSeries is the primary object used to represent time-domain data in gwexpy. It extends the standard gwpy.timeseries.TimeSeries by incorporating additional mixins for plotting, signal analysis, regularity checks, numerical fitting, statistical methods, and enhanced interoperability.

Parameters:

data (array-like) – Input data array.
unit (~astropy.units.Unit, optional) – Physical unit of these data.
t0 (~gwpy.time.LIGOTimeGPS, float, str, optional, default: 0) – GPS epoch associated with these data, any input parsable by ~gwpy.time.to_gps is fine.
dt (float, ~astropy.units.Quantity, optional, default: 1) – Time resolution for these data.
sample_rate (float, ~astropy.units.Quantity, optional, default: 1) – Sample rate for these data.
times (array-like) – The complete array of times indexing the data. This argument takes precedence over t0 and dt so should be given in place of these if relevant, not alongside.
name (str, optional) – Descriptive title for this array.
channel (~gwpy.detector.Channel, str, optional) – Source data stream for these data.
dtype (~numpy.dtype, optional) – Input data type.
copy (bool, optional, default: False) – Choose to copy the input data to new memory.
subok (bool, optional, default: True) – Allow passing of sub-classes by the array generator.

Notes

In addition to the standard GWpy functionality, this class provides advanced features such as time-domain differentiation/integration, rolling statistics, and seamless interoperability with PyTorch, Xarray, and Polars.

Key methods:

`plot`(**kwargs)	Plot this object using `gwexpy.plot.Plot`.
`resample`(rate, *args[, ignore_nan])	Resample the TimeSeries.
`filter`(filt, *[, analog, unit, ...])	Filter this TimeSeries with an IIR or FIR filter.
`fft`([nfft, mode, pad_mode, pad_left, ...])	Compute the Discrete Fourier Transform (DFT).
`psd`(args, *kwargs)
`spectrogram`(args, *kwargs)	Compute the average power spectrogram.

Examples

>>> from gwexpy.timeseries import TimeSeries
>>> import numpy as np
>>> data = np.array([0.1, -1.2, 0.5])
>>> ts = TimeSeries(data, sample_rate=1000, unit='V')
>>> ts
<TimeSeries([ 0.1, -1.2,  0.5],
            unit=Unit("V"),
            t0=<Quantity 0. s>,
            dt=<Quantity 0.001 s>,
            name=None,
            channel=None)>

Methods

`fft`([nfft, mode, pad_mode, pad_left, ...])	Compute the Discrete Fourier Transform (DFT).
`rfft`(args, *kwargs)	Real-valued Fast Fourier Transform.
`psd`(args, *kwargs)
`asd`(args, *kwargs)
`csd`(other, args, *kwargs)
`spectrogram`(args, *kwargs)	Compute the average power spectrogram.
`coherence`(args, *kwargs)
`filter`(filt, *[, analog, unit, ...])	Filter this TimeSeries with an IIR or FIR filter.
`resample`(rate, *args[, ignore_nan])	Resample the TimeSeries.
`detrend`([detrend])	Remove the trend from this TimeSeries.
`cepstrum`([kind, window, detrend, eps, fft_mode])	Compute the cepstrum of the time series.
`cwt`([wavelet, widths, frequencies, window, ...])	Compute the Continuous Wavelet Transform (CWT).
`dct`([type, norm, window, detrend])	Compute the Discrete Cosine Transform (DCT).
`emd`(*[, method, max_imf, sift_max_iter, ...])	Decompose the TimeSeries using Empirical Mode Decomposition (EMD).
`hht`(*[, emd_method, emd_kwargs, ...])	Perform Hilbert-Huang Transform (HHT) on the TimeSeries.
`hilbert_analysis`(*[, unwrap_phase, ...])	Perform Hilbert analysis to extract instantaneous amplitude, phase, and frequency.

classmethod read(source, *args, **kwargs)[source]

Read a TimeSeries from a supported source.

This override adds explicit CSV and .gwf handling for deterministic behavior when .read() is called through the public API.

The available built-in formats are:

Format	Read	Write	Auto-identify
ats	Yes	No	Yes
ats.mth5	Yes	No	No
csv	Yes	No	Yes
dttxml	Yes	No	No
flac	Yes	Yes	Yes
frame	Yes	Yes	No
framecpp	Yes	Yes	No
framel	Yes	Yes	No
gbd	Yes	No	Yes
gse2	Yes	Yes	Yes
hdf.ndscope	Yes	Yes	Yes
knet	Yes	No	Yes
lalframe	Yes	No	No
li	Yes	No	No
lsf	Yes	No	No
m4a	Yes	Yes	Yes
mem	Yes	No	No
miniseed	Yes	Yes	No
mp3	Yes	Yes	Yes
mseed	Yes	Yes	Yes
nc	Yes	Yes	Yes
ndscope-hdf5	Yes	Yes	No
ndscope_hdf5	Yes	Yes	No
ndscopehdf5	Yes	Yes	No
netcdf4	Yes	Yes	No
ogg	Yes	Yes	Yes
orf	Yes	No	No
sac	Yes	Yes	Yes
sdb	Yes	No	Yes
sqlite	Yes	No	Yes
sqlite3	Yes	No	Yes
taffmat	Yes	No	No
tdms	Yes	No	Yes
wav	Yes	No	Yes
wdf	Yes	No	No
win	Yes	No	Yes
win32	Yes	No	Yes
wvf	Yes	No	No
xml.diaggui	Yes	No	Yes
zarr	Yes	Yes	Yes

write(target, *args, **kwargs)[source]

Write a TimeSeries to a supported target.

This override preserves minimal metadata for direct CSV round-trips.

The available built-in formats are:

Format	Read	Write	Auto-identify
flac	Yes	Yes	Yes
frame	Yes	Yes	No
framecpp	Yes	Yes	No
framel	Yes	Yes	No
gse2	Yes	Yes	Yes
hdf.ndscope	Yes	Yes	Yes
lalframe	Yes	Yes	No
m4a	Yes	Yes	Yes
miniseed	Yes	Yes	No
mp3	Yes	Yes	Yes
mseed	Yes	Yes	Yes
nc	Yes	Yes	Yes
ndscope-hdf5	Yes	Yes	No
ndscope_hdf5	Yes	Yes	No
ndscopehdf5	Yes	Yes	No
netcdf4	Yes	Yes	No
ogg	Yes	Yes	Yes
sac	Yes	Yes	Yes
zarr	Yes	Yes	Yes

Convert to SimPEG Data object.

Parameters:

location (array_like, optional) – Rx location (x, y, z). Default is [0, 0, 0].
rx_type (str, optional) – Receiver class name. Default “PointElectricField”.
orientation (str, optional) – Receiver orientation (‘x’, ‘y’, ‘z’). Default ‘x’.
**kwargs (Any) – Additional arguments passed to SimPEG converter.

Return type:

simpeg.data.Data

classmethod from_simpeg(data_obj: Any, **kwargs: Any) → TimeSeries[source]

Create TimeSeries from SimPEG Data object.

Parameters:

data_obj (simpeg.data.Data) – Input SimPEG Data.
**kwargs (Any) – Additional arguments passed to constructor.

Return type:

TimeSeries

classmethod from_control(response: Any, **kwargs: Any) → TimeSeries | TimeSeriesDict[source]

Create TimeSeries from python-control TimeResponseData.

Parameters:

response (control.TimeResponseData) – The simulation result from python-control.
**kwargs (dict) – Additional arguments passed to the constructor.

Returns:

The converted time-domain data.

Return type:

TimeSeries or TimeSeriesDict

arima(order: tuple[int, int, int] = (1, 0, 0), *, seasonal_order: tuple[int, int, int, int] | None = None, auto: bool = False, **kwargs: Any) → Any[source]

Fit an ARIMA or SARIMAX model to this TimeSeries.

This method wraps statsmodels.tsa.arima.model.ARIMA (or SARIMAX). If auto=True, it uses pmdarima to automatically find the best parameters.

Parameters:

order (tuple, default=(1, 0, 0)) – The (p,d,q) order of the model.
seasonal_order (tuple, optional) – The (P,D,Q,s) seasonal order.
auto (bool, default=False) – If True, perform Auto-ARIMA search (requires pmdarima).
**kwargs – Additional arguments passed to fit_arima.

Returns:

Object containing the fitted model, with methods .predict(), .forecast(), .plot().

Return type:

ArimaResult

ar(p: int = 1, **kwargs: Any) → Any[source]

Fit an AutoRegressive AR(p) model.

Shortcut for .arima(order=(p, 0, 0)).

ma(q: int = 1, **kwargs: Any) → Any[source]

Fit a Moving Average MA(q) model.

Shortcut for .arima(order=(0, 0, q)).

arma(p: int = 1, q: int = 1, **kwargs: Any) → Any[source]

Fit an ARMA(p, q) model.

Shortcut for .arima(order=(p, 0, q)).

Module Contents

gwexpy.timeseries - Time series data containers and operations.

class gwexpy.timeseries.TimeSeriesDict[source]

Bases: PlotMixin, DictMapMixin, PhaseMethodsMixin, TimeSeriesDict

A dictionary of TimeSeries, indexed by name.

TimeSeriesDict is a specialized dictionary designed to hold and manipulate multiple TimeSeries objects simultaneously. It provides batch processing methods (e.g., resample, filter, fft) that operate on all entries at once, and supports advanced I/O for multi-channel data (HDF5, Zarr, CSV).

Parameters:

*args – A mapping or iterable of (key, TimeSeries) pairs.
**kwargs – Additional keyword arguments for the dictionary.

Notes

This class is highly interoperable, supporting conversions to and from Pandas DataFrames, Polars DataFrames, and MNE Raw objects. It also supports matrix conversion via to_matrix().

Key methods:

`read`(source, args, *kwargs)	Read a TimeSeriesDict from a supported source.
`write`(target, args, *kwargs)	Write the collection to a supported target.
`plot`(**kwargs)	Plot this object using `gwexpy.plot.Plot`.
`resample`(rate, **kwargs)	Resample items in the TimeSeriesDict.
`fft`(args, *kwargs)	Apply FFT to each TimeSeries.
`psd`(args, *kwargs)	Compute PSD for each TimeSeries.

Examples

>>> from gwexpy.timeseries import TimeSeries, TimeSeriesDict
>>> tsd = TimeSeriesDict()
>>> tsd['H1'] = TimeSeries([1, 2], sample_rate=1)
>>> tsd
{'H1': <TimeSeries([1, 2],
            unit=Unit(dimensionless),
            t0=<Quantity 0. s>,
            dt=<Quantity 1. s>,
            name=None,
            channel=None)>}

classmethod read(source, *args: Any, **kwargs: Any)[source]

Read a TimeSeriesDict from a supported source.

Registry-generated format documentation follows. The available built-in formats are:

Format	Read	Write	Auto-identify
ats	Yes	No	Yes
csv	Yes	No	Yes
dttxml	Yes	No	No
flac	Yes	Yes	Yes
frame	Yes	Yes	No
framecpp	Yes	Yes	No
framel	Yes	Yes	No
gbd	Yes	No	Yes
gse2	Yes	Yes	Yes
hdf.ndscope	Yes	Yes	Yes
knet	Yes	No	Yes
lalframe	Yes	No	No
li	Yes	No	No
lsf	Yes	No	No
m4a	Yes	Yes	Yes
mem	Yes	No	No
miniseed	Yes	Yes	No
mp3	Yes	Yes	Yes
mseed	Yes	Yes	Yes
nc	Yes	Yes	Yes
ndscope-hdf5	Yes	Yes	No
ndscope_hdf5	Yes	Yes	No
ndscopehdf5	Yes	Yes	No
netcdf4	Yes	Yes	No
ogg	Yes	Yes	Yes
orf	Yes	No	No
sac	Yes	Yes	Yes
sdb	Yes	No	Yes
sqlite	Yes	No	Yes
sqlite3	Yes	No	Yes
taffmat	Yes	No	No
tdms	Yes	No	Yes
wav	Yes	No	Yes
wdf	Yes	No	No
win	Yes	No	Yes
win32	Yes	No	Yes
wvf	Yes	No	No
xml.diaggui	Yes	No	Yes
zarr	Yes	Yes	Yes

asfreq(*args, **kwargs): Apply asfreq to each TimeSeries in the dict.

resample(rate, **kwargs)[source]

Resample items in the TimeSeriesDict.

In-place operation (updates the dict contents).

If rate is time-like, performs time-bin resampling. Otherwise performs signal processing resampling (gwpy’s native behavior).

hilbert(*args, **kwargs): Apply Hilbert transform to each item.

envelope(*args, **kwargs): Apply envelope to each item.

instantaneous_phase(*args, **kwargs): Apply instantaneous_phase to each item.

to_mne(info=None, picks=None)[source]: Convert to mne.io.RawArray.

classmethod from_mne(raw, *, unit_map=None)[source]: Create from mne.io.Raw.

classmethod from_control(response: Any, **kwargs) → TimeSeriesDict[source]

Create TimeSeriesDict from python-control TimeResponseData.

Parameters:

response (control.TimeResponseData) – The simulation result from python-control.
**kwargs (dict) – Additional arguments passed to the TimeSeries constructor.

Returns:

The converted time-domain data.

Return type:

TimeSeriesDict

radian(*args, **kwargs): Compute instantaneous phase (in radians) of each item.

degree(*args, **kwargs): Compute instantaneous phase (in degrees) of each item.

unwrap_phase(*args, **kwargs): Apply unwrap_phase to each item.

instantaneous_frequency(*args, **kwargs): Apply instantaneous_frequency to each item.

mix_down(*args, **kwargs): Apply mix_down to each item.

baseband(*args, **kwargs): Apply baseband to each item.

heterodyne(*args, **kwargs): Apply heterodyne to each item.

lock_in(*args, **kwargs)[source]

Apply lock_in to each item.

Returns TimeSeriesDict (if output=’complex’) or tuple of TimeSeriesDicts.

csd_matrix(other=None, *args, fftlength=None, overlap=None, window='hann', hermitian=True, include_diagonal=True, **kwargs)[source]

Compute Cross-Spectral Density matrix for all pairs.

Parameters:

other (TimeSeriesDict or TimeSeriesList, optional) – Another collection for cross-CSD. If None, compute self-CSD matrix.
*args – Positional arguments forwarded to TimeSeries.csd.
fftlength (float, optional) – FFT length in seconds.
overlap (float, optional) – Overlap between segments in seconds.
window (str, optional) – Window function name (default ‘hann’).
hermitian (bool, optional) – If True, exploit Hermitian symmetry (default True).
include_diagonal (bool, optional) – Must be True for CSD matrices; False raises ValueError because the diagonal is always the PSD.
**kwargs – Additional keyword arguments forwarded to TimeSeries.csd.

Returns:

The CSD matrix.

Return type:

FrequencySeriesMatrix

Notes

The diagonal of a self-CSD matrix is always computed as the PSD. Any uncomputed elements are represented as complex NaN. The frequency axis is taken from the first computed element without alignment/truncation; dt and fftlength consistency is enforced before computation.

coherence_matrix(other=None, *args, fftlength=None, overlap=None, window='hann', symmetric=True, include_diagonal=True, diagonal_value=1.0, **kwargs)[source]

Compute coherence matrix for all pairs.

Parameters:

other (TimeSeriesDict or TimeSeriesList, optional) – Another collection for cross-coherence.
*args – Positional arguments forwarded to TimeSeries.coherence.
fftlength (float, optional) – FFT length in seconds.
overlap (float, optional) – Overlap between segments in seconds.
window (str, optional) – Window function name (default ‘hann’).
symmetric (bool, optional) – If True, exploit symmetry (default True).
include_diagonal (bool, optional) – Whether to include diagonal elements (default True).
diagonal_value (float, optional) – Value for diagonal elements (default 1.0).
**kwargs – Additional keyword arguments forwarded to TimeSeries.coherence.

Returns:

The coherence matrix.

Return type:

FrequencySeriesMatrix

Notes

If include_diagonal is True and diagonal_value is not None, the diagonal is filled with that value without computation. If diagonal_value is None, the diagonal coherence is computed. Uncomputed elements are represented as NaN. The frequency axis is taken from the first computed element without alignment/truncation; dt and fftlength consistency is enforced before computation.

csd(other=None, *args, fftlength=None, overlap=None, window='hann', hermitian=True, include_diagonal=True, **kwargs)[source]: Compute CSD for each element or as a matrix depending on other.

coherence(other=None, *args, fftlength=None, overlap=None, window='hann', symmetric=True, include_diagonal=True, diagonal_value=1.0, **kwargs)[source]: Compute coherence for each element or as a matrix depending on other.

psd(*args, **kwargs): Compute PSD for each TimeSeries. Returns a FrequencySeriesDict.

asd(*args, **kwargs): Compute ASD for each TimeSeries. Returns a FrequencySeriesDict.

spectrogram(*args, **kwargs): Compute spectrogram for each TimeSeries. Returns a SpectrogramDict.

spectrogram2(*args, **kwargs): Compute spectrogram2 for each TimeSeries. Returns a SpectrogramDict.

q_transform(*args, **kwargs): Compute Q-transform for each TimeSeries. Returns a SpectrogramDict.

histogram(*args, **kwargs): Compute Histogram for each TimeSeries. Returns a HistogramDict.

to_pandas(index='datetime', *, copy=False)[source]: Convert to pandas.DataFrame.

classmethod from_pandas(df, *, unit_map=None, t0=None, dt=None)[source]: Create TimeSeriesDict from pandas.DataFrame.

to_polars(time_column='time', time_unit='datetime')[source]: Convert to polars.DataFrame.

classmethod from_polars(df, *, time_column='time', unit_map=None)[source]: Create TimeSeriesDict from polars.DataFrame.

to_tmultigraph(name: str | None = None) → Any[source]: Convert to ROOT TMultiGraph.

write(target: str, *args: Any, **kwargs: Any) → Any[source]

Write the collection to a supported target.

Registry-generated format documentation follows. The available built-in formats are:

Format	Read	Write	Auto-identify
flac	Yes	Yes	Yes
frame	Yes	Yes	No
framecpp	Yes	Yes	No
framel	Yes	Yes	No
gse2	Yes	Yes	Yes
hdf.ndscope	Yes	Yes	Yes
lalframe	Yes	Yes	No
m4a	Yes	Yes	Yes
miniseed	Yes	Yes	No
mp3	Yes	Yes	Yes
mseed	Yes	Yes	Yes
nc	Yes	Yes	Yes
ndscope-hdf5	Yes	Yes	No
ndscope_hdf5	Yes	Yes	No
ndscopehdf5	Yes	Yes	No
netcdf4	Yes	Yes	No
ogg	Yes	Yes	Yes
sac	Yes	Yes	Yes
zarr	Yes	Yes	Yes

plot_all(*args: Any, **kwargs: Any)[source]: Alias for plot(). Plots all series.

impute(*args, **kwargs): Apply impute to each item.

rolling_mean(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling mean to each item.

rolling_std(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ddof=0, ignore_nan=None)[source]: Apply rolling std to each item.

rolling_median(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling median to each item.

rolling_min(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling min to each item.

rolling_max(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling max to each item.

to_matrix(*, align='intersection', **kwargs)[source]: Convert the dictionary to a TimeSeriesMatrix with alignment.

crop(start=None, end=None, copy=False) → TimeSeriesDict[source]

Crop each TimeSeries in the dict.

Accepts any time format supported by gwexpy.time.to_gps (str, datetime, pandas, obspy, etc). Returns a new TimeSeriesDict.

append(other, copy=True, **kwargs) → TimeSeriesDict[source]: Append another mapping of TimeSeries or a single TimeSeries to each item.

prepend(*args, **kwargs) → TimeSeriesDict[source]

Prepend to each TimeSeries in the dict (in-place).

Returns self.

shift(*args, **kwargs): Shift each TimeSeries in the dict.

gate(*args, **kwargs): Gate each TimeSeries in the dict.

mask(*args, **kwargs): Mask each TimeSeries in the dict.

decimate(*args, **kwargs): Decimate each TimeSeries in the dict.

filter(*args, **kwargs): Filter each TimeSeries in the dict.

whiten(*args, **kwargs): Whiten each TimeSeries in the dict.

notch(*args, **kwargs): Notch filter each TimeSeries in the dict.

zpk(*args, **kwargs): Apply ZPK filter to each TimeSeries in the dict.

detrend(*args, **kwargs): Detrend each TimeSeries in the dict.

taper(*args, **kwargs): Taper each TimeSeries in the dict.

fft(*args, **kwargs): Apply FFT to each TimeSeries. Returns a FrequencySeriesDict.

average_fft(*args, **kwargs): Apply average_fft to each TimeSeries. Returns a FrequencySeriesDict.

value_at(*args, **kwargs)[source]: Get value at a specific time for each TimeSeries.

is_contiguous(*args, **kwargs)[source]: Check contiguity with another object for each TimeSeries.

skewness(**kwargs)[source]: Compute skewness. Vectorized via TimeSeriesMatrix.

kurtosis(**kwargs)[source]: Compute kurtosis. Vectorized via TimeSeriesMatrix.

mean(**kwargs)[source]: Compute mean. Vectorized via TimeSeriesMatrix.

std(**kwargs)[source]: Compute standard deviation. Vectorized via TimeSeriesMatrix.

rms(**kwargs)[source]: Compute root-mean-square. Vectorized via TimeSeriesMatrix.

min(**kwargs)[source]: Compute minimum. Vectorized via TimeSeriesMatrix.

max(**kwargs)[source]: Compute maximum. Vectorized via TimeSeriesMatrix.

correlation(other=None, **kwargs)[source]: Compute correlation. Vectorized via TimeSeriesMatrix.

mic(other, **kwargs)[source]: Compute MIC. Vectorized via TimeSeriesMatrix.

distance_correlation(other, **kwargs)[source]: Compute distance correlation. Vectorized via TimeSeriesMatrix.

pcc(other, **kwargs)[source]: Compute Pearson correlation. Vectorized via TimeSeriesMatrix.

ktau(other, **kwargs)[source]: Compute Kendall’s tau. Vectorized via TimeSeriesMatrix.

state_segments(*args, **kwargs)[source]: Run state_segments on each item (returns Series of SegmentLists).

pca(*args, **kwargs)[source]: Perform PCA decomposition across channels.

ica(*args, **kwargs)[source]: Perform ICA decomposition across channels.

class gwexpy.timeseries.TimeSeriesList(*items: _T)[source]

Bases: PlotMixin, ListMapMixin, PhaseMethodsMixin, TimeSeriesList

A list of TimeSeries objects.

TimeSeriesList is a specialized list designed to hold and manipulate multiple TimeSeries objects. It provides batch processing methods that operate on all entries at once.

Parameters:: *args – An iterable of TimeSeries objects.

Notes

Key methods:

`plot`(**kwargs)	Plot this object using `gwexpy.plot.Plot`.
`append`(item)	Append object to the end of the list.
`extend`(item)	Extend list by appending elements from the iterable.
`csd_matrix`([other, fftlength, overlap, ...])	Compute Cross Spectral Density Matrix.
`coherence_matrix`([other, fftlength, ...])	Compute Coherence Matrix.

Examples

>>> from gwexpy.timeseries import TimeSeries, TimeSeriesList
>>> tsl = TimeSeriesList([TimeSeries([1, 2], sample_rate=1)])
>>> tsl
[<TimeSeries([1, 2],
            unit=Unit(dimensionless),
            t0=<Quantity 0. s>,
            dt=<Quantity 1. s>,
            name=None,
            channel=None)>]

csd_matrix(other=None, *args, fftlength=None, overlap=None, window='hann', hermitian=True, include_diagonal=True, **kwargs)[source]

Compute Cross Spectral Density Matrix.

Parameters:

other (TimeSeriesDict or TimeSeriesList, optional) – Other collection for cross-CSD.
*args – Positional arguments forwarded to TimeSeries.csd.
fftlength – See TimeSeries.csd() arguments.
overlap – See TimeSeries.csd() arguments.
window – See TimeSeries.csd() arguments.
hermitian (bool, default=True) – If True and other is None, compute only upper triangle and conjugate fill lower.
include_diagonal (bool, default=True) – Must be True for CSD matrices; False raises ValueError because the diagonal is always the PSD.
**kwargs – Additional keyword arguments forwarded to TimeSeries.csd.

Return type:

FrequencySeriesMatrix

Notes

The diagonal of a self-CSD matrix is always computed as the PSD. Any uncomputed elements are represented as complex NaN. The frequency axis is taken from the first computed element without alignment/truncation; dt and fftlength consistency is enforced before computation.

coherence_matrix(other=None, *args, fftlength=None, overlap=None, window='hann', symmetric=True, include_diagonal=True, diagonal_value=1.0, **kwargs)[source]

Compute Coherence Matrix.

Parameters:

other (TimeSeriesDict or TimeSeriesList, optional) – Other collection.
*args – Positional arguments forwarded to TimeSeries.coherence.
fftlength – See TimeSeries.coherence().
overlap – See TimeSeries.coherence().
window – See TimeSeries.coherence().
symmetric (bool, default=True) – If True and other is None, compute only upper triangle and copy to lower.
include_diagonal (bool, default=True) – Include diagonal.
diagonal_value (float or None, default=1.0) – Value to fill diagonal if include_diagonal is True. If None, compute diagonal coherence.
**kwargs – Additional keyword arguments forwarded to TimeSeries.coherence.

Return type:

FrequencySeriesMatrix

Notes

If include_diagonal is True and diagonal_value is not None, the diagonal is filled with that value without computation. If diagonal_value is None, the diagonal coherence is computed. Uncomputed elements are represented as NaN. The frequency axis is taken from the first computed element without alignment/truncation; dt and fftlength consistency is enforced before computation.

csd(other=None, *args, fftlength=None, overlap=None, window='hann', hermitian=True, include_diagonal=True, **kwargs)[source]: Compute CSD for each element or as a matrix depending on other.

coherence(other=None, *args, fftlength=None, overlap=None, window='hann', symmetric=True, include_diagonal=True, diagonal_value=1.0, **kwargs)[source]: Compute coherence for each element or as a matrix depending on other.

impute(*, method='interpolate', limit=None, axis='time', max_gap=None, **kwargs)[source]

Impute missing data (NaNs) in each TimeSeries.

Parameters:

method (str, optional) – Imputation method (‘interpolate’, ‘fill’, etc.).
limit (int, optional) – Maximum number of consecutive NaNs to fill.
axis (str, optional) – Axis to impute along.
max_gap (float, optional) – Maximum gap size to fill (in seconds).
**kwargs – Passed to TimeSeries.impute().

Return type:

TimeSeriesList

rolling_mean(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling mean to each element.

rolling_std(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ddof=0, ignore_nan=None)[source]: Apply rolling std to each element.

rolling_median(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling median to each element.

rolling_min(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling min to each element.

rolling_max(window, *, center=False, min_count=1, nan_policy='omit', backend='auto', ignore_nan=None)[source]: Apply rolling max to each element.

to_matrix(*, align='intersection', **kwargs)[source]

Convert list to TimeSeriesMatrix with alignment.

Parameters:

align (str, optional) – Alignment strategy (‘intersection’, ‘union’, etc.). Default ‘intersection’.
**kwargs – Additional arguments passed to alignment function.

Returns:

Matrix with all series aligned to common time axis.

Return type:

TimeSeriesMatrix

crop(start=None, end=None, copy=False) → TimeSeriesList[source]

Crop each TimeSeries in the list.

Accepts any time format supported by gwexpy.time.to_gps (str, datetime, pandas, obspy, etc). Returns a new TimeSeriesList.

shift(*args, **kwargs): Shift each TimeSeries in the list.

gate(*args, **kwargs): Gate each TimeSeries in the list.

mask(*args, **kwargs): Mask each TimeSeries in the list.

resample(*args, **kwargs): Resample each TimeSeries in the list.

decimate(*args, **kwargs): Decimate each TimeSeries in the list.

filter(*args, **kwargs): Filter each TimeSeries in the list.

whiten(*args, **kwargs): Whiten each TimeSeries in the list.

notch(*args, **kwargs): Notch filter each TimeSeries in the list.

zpk(*args, **kwargs): ZPK filter each TimeSeries in the list.

detrend(*args, **kwargs): Detrend each TimeSeries in the list.

taper(*args, **kwargs): Taper each TimeSeries in the list.

hilbert(*args, **kwargs): Apply Hilbert transform to each item.

envelope(*args, **kwargs): Apply envelope to each item.

instantaneous_phase(*args, **kwargs): Apply instantaneous_phase to each item.

unwrap_phase(*args, **kwargs): Apply unwrap_phase to each item.

instantaneous_frequency(*args, **kwargs): Apply instantaneous_frequency to each item.

mix_down(*args, **kwargs): Apply mix_down to each item.

baseband(*args, **kwargs): Apply baseband to each item.

heterodyne(*args, **kwargs): Apply heterodyne to each item.

lock_in(*args, **kwargs)[source]: Apply lock_in to each item.

fft(*args, **kwargs): Apply FFT to each TimeSeries. Returns a FrequencySeriesList.

average_fft(*args, **kwargs): Apply average_fft to each TimeSeries. Returns a FrequencySeriesList.

psd(*args, **kwargs): Compute PSD for each TimeSeries. Returns a FrequencySeriesList.

asd(*args, **kwargs): Compute ASD for each TimeSeries. Returns a FrequencySeriesList.

spectrogram(*args, **kwargs): Compute spectrogram for each TimeSeries. Returns a SpectrogramList.

spectrogram2(*args, **kwargs): Compute spectrogram2 for each TimeSeries. Returns a SpectrogramList.

q_transform(*args, **kwargs): Compute Q-transform for each TimeSeries. Returns a SpectrogramList.

value_at(*args, **kwargs)[source]: Get value at a specific time for each TimeSeries.

is_contiguous(*args, **kwargs)[source]: Check contiguity with another object for each TimeSeries.

skewness(**kwargs)[source]: Compute skewness. Vectorized via TimeSeriesMatrix.

kurtosis(**kwargs)[source]: Compute kurtosis. Vectorized via TimeSeriesMatrix.

mean(**kwargs)[source]: Compute mean. Vectorized via TimeSeriesMatrix.

std(**kwargs)[source]: Compute standard deviation. Vectorized via TimeSeriesMatrix.

rms(**kwargs)[source]: Compute root-mean-square. Vectorized via TimeSeriesMatrix.

min(**kwargs)[source]: Compute minimum. Vectorized via TimeSeriesMatrix.

max(**kwargs)[source]: Compute maximum. Vectorized via TimeSeriesMatrix.

correlation(other=None, **kwargs)[source]: Compute correlation. Vectorized via TimeSeriesMatrix.

mic(other, **kwargs)[source]: Compute MIC. Vectorized via TimeSeriesMatrix.

to_pandas(**kwargs)[source]

Convert a TimeSeriesList to a pandas DataFrame.

Each element becomes a column. ASSUMES common time axis.

to_tmultigraph(name: str | None = None) → Any[source]: Convert to ROOT TMultiGraph.

classmethod read(source, *args: Any, **kwargs: Any)[source]: Read a TimeSeriesList from a supported source.

write(target: str, *args: Any, **kwargs: Any) → Any[source]: Write TimeSeriesList to file (HDF5, ROOT, etc.).

pca(*args, **kwargs)[source]: Perform PCA decomposition across channels.

ica(*args, **kwargs)[source]: Perform ICA decomposition across channels.

plot_all(*args: Any, **kwargs: Any)[source]: Alias for plot(). Plots all series.

histogram(*args, **kwargs): Compute Histogram for each TimeSeries. Returns a HistogramList.

radian(*args, **kwargs): Compute instantaneous phase (in radians) of each item.

degree(*args, **kwargs): Compute instantaneous phase (in degrees) of each item.

Bases: PhaseMethodsMixin, TimeSeriesMatrixCoreMixin, TimeSeriesMatrixAnalysisMixin, TimeSeriesMatrixSpectralMixin, TimeSeriesMatrixInteropMixin, SeriesMatrix

A 2D matrix of TimeSeries objects sharing a common time axis.

TimeSeriesMatrix represents a 2-dimensional array (rows x columns) where each element is a TimeSeries. All elements in the matrix must share the same time synchronization (same t0, dt, and number of samples).

This class is ideal for representing multi-channel data from a detector sub-system or a set of sensors where the spatial or logical relationship is best represented as a grid.

Parameters:

data (array-like) – The data values for the matrix. Should be of shape (rows, columns, samples).
times (array-like, optional) – The time values corresponding to each sample. If provided, dt and t0 are ignored.
dt (float, ~astropy.units.Quantity, optional) – The time step between samples.
t0 (float, ~astropy.units.Quantity, optional) – The start time of the data.
sample_rate (float, ~astropy.units.Quantity, optional) – The sample rate of the data (1/dt).
epoch (float, ~astropy.units.Quantity, optional) – The epoch of the data.
**kwargs – Additional keyword arguments: - channel_names: list of strings for channel labels. - unit: physical unit of the data. - name: descriptive title for the matrix.

Notes

TimeSeriesMatrix supports element-wise signal processing (e.g., detrend, filter, resample) and bivariate spectral methods (e.g., csd, coherence) between matrices.

Key methods:

`plot`(**kwargs)	Plot this object using `gwexpy.plot.Plot`.
`fft`(**kwargs)	Compute the FFT of each element.
`psd`(**kwargs)	Compute the PSD of each element.
`csd`(other, args, *kwargs)	Apply TimeSeries.csd element-wise with another TimeSeries object.
`coherence`(other, args, *kwargs)	Apply TimeSeries.coherence element-wise with another TimeSeries object.
`to_dict`()	Convert matrix to an appropriate collection dict (e.g. TimeSeriesDict).

Examples

>>> from gwexpy.timeseries import TimeSeriesMatrix
>>> import numpy as np
>>> data = np.ones((2, 2, 3))
>>> tsm = TimeSeriesMatrix(data, sample_rate=1, unit='m')
>>> tsm
<SeriesMatrix shape=(2, 2, 3) rows=('row0', 'row1') cols=('col0', 'col1')>

series_class: alias of TimeSeries

dict_class: alias of TimeSeriesDict

list_class: alias of TimeSeriesList

series_type = 'time'

default_xunit = 's'

default_yunit: str | u.Unit | None = None

classmethod read(source, *args: Any, **kwargs: Any)[source]

Read a TimeSeriesMatrix from a supported source.

Registry-generated format documentation follows. The available built-in formats are:

Format	Read	Write	Auto-identify
ats	Yes	No	Yes
csv	Yes	No	Yes
dttxml	Yes	No	No
flac	Yes	Yes	Yes
frame	Yes	No	No
framecpp	Yes	No	No
framel	Yes	No	No
gbd	Yes	No	Yes
gse2	Yes	No	Yes
gwf	Yes	No	No
gwf.framecpp	Yes	No	No
gwf.framel	Yes	No	No
gwf.lalframe	Yes	No	No
hdf.ndscope	Yes	Yes	Yes
knet	Yes	No	Yes
lalframe	Yes	No	No
li	Yes	No	No
lsf	Yes	No	No
m4a	Yes	Yes	Yes
mem	Yes	No	No
miniseed	Yes	No	No
mp3	Yes	Yes	Yes
mseed	Yes	No	Yes
nc	Yes	Yes	Yes
ndscope-hdf5	Yes	Yes	No
ndscope_hdf5	Yes	Yes	No
ndscopehdf5	Yes	Yes	No
netcdf4	Yes	Yes	No
ogg	Yes	Yes	Yes
orf	Yes	No	No
sac	Yes	No	Yes
sdb	Yes	No	Yes
sqlite	Yes	No	Yes
sqlite3	Yes	No	Yes
taffmat	Yes	No	No
tdms	Yes	No	Yes
wav	Yes	No	Yes
wdf	Yes	No	No
win	Yes	No	Yes
win32	Yes	No	Yes
wvf	Yes	No	No
xml.diaggui	Yes	No	No
zarr	Yes	Yes	Yes

auto_coherence(*args, **kwargs)

Apply univariate spectral method TimeSeries.auto_coherence element-wise.

Computes the auto_coherence for each entry in the matrix, returning a FrequencySeriesMatrix containing the results.

bandpass(*args, **kwargs)

Apply TimeSeries.bandpass element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

coherence(other, *args, **kwargs)

Apply TimeSeries.coherence element-wise with another TimeSeries object.

This method delegates the bivariate call to each TimeSeries in the matrix, using the provided other object as the second operand.

csd(other, *args, **kwargs)

Apply TimeSeries.csd element-wise with another TimeSeries object.

This method delegates the bivariate call to each TimeSeries in the matrix, using the provided other object as the second operand.

detrend(*args, **kwargs)

Apply TimeSeries.detrend element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

filter(*args, **kwargs)

Apply TimeSeries.filter element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

highpass(*args, **kwargs)

Apply TimeSeries.highpass element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

lowpass(*args, **kwargs)

Apply TimeSeries.lowpass element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

notch(*args, **kwargs)

Apply TimeSeries.notch element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

resample(*args, **kwargs)

Apply TimeSeries.resample element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

taper(*args, **kwargs)

Apply TimeSeries.taper element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

transfer_function(other, *args, **kwargs)

Apply TimeSeries.transfer_function element-wise with another TimeSeries object.

This method delegates the bivariate call to each TimeSeries in the matrix, using the provided other object as the second operand.

whiten(*args, **kwargs)

Apply TimeSeries.whiten element-wise to all entries in the matrix.

This method delegates the call to the underlying TimeSeries objects, preserving the matrix structure and per-element metadata while updating the data values and time axis according to the operation.

class gwexpy.timeseries.Transform[source]

Bases: object

Base interface for reusable preprocessing transforms.

Subclasses implement transform() and optionally fit() and inverse_transform(). The interface accepts individual TimeSeries objects as well as GWexpy collections such as TimeSeriesMatrix, TimeSeriesDict, and TimeSeriesList.

Examples

>>> transform = ImputeTransform(method="interpolate")
>>> filled = transform.fit_transform(ts)
>>> filled.shape == ts.shape
True

supports_inverse = False

fit(x)[source]: Fit the transform to the input data and return self.

transform(x)[source]

Apply the transform to input data.

Subclasses must override this method.

fit_transform(x)[source]: Fit the transform and immediately apply it to x.

inverse_transform(y)[source]: Reverse the transform when supported by the subclass.

class gwexpy.timeseries.Pipeline(steps: Sequence[tuple[str, Transform]])[source]

Bases: object

Compose multiple transforms into a deterministic preprocessing chain.

The pipeline applies each step in order during fit() and transform(), mirroring common ML preprocessing workflows while preserving GWexpy metadata and collection types.

Parameters:: steps (sequence of (str, Transform)) – Ordered (name, transform) pairs to execute.

Examples

>>> pipeline = Pipeline(
...     [
...         ("impute", ImputeTransform(method="interpolate")),
...         ("standardize", StandardizeTransform()),
...     ]
... )
>>> standardized = pipeline.fit_transform(ts_matrix)
>>> standardized.shape == ts_matrix.shape
True

steps: list[tuple[str, Transform]]

fit(x)[source]: Fit each step in order using the output of the previous step.

transform(x)[source]: Apply every fitted transform in sequence.

fit_transform(x)[source]: Fit the pipeline and return the transformed output.

inverse_transform(y, *, strict: bool = True)[source]

Apply supported inverse transforms in reverse order.

Parameters:

y (data) – Transformed data.
strict (bool, optional) – If True, raise error if any step doesn’t support inverse.

class gwexpy.timeseries.ImputeTransform(method: str = 'interpolate', **kwargs)[source]

Bases: Transform

Impute missing values using existing lower-level helpers.

transform(x)[source]: Apply imputation to TimeSeries, Matrix, or Collections.

class gwexpy.timeseries.StandardizeTransform(method: str = 'zscore', ddof: int = 0, robust: bool = False, axis: str = 'time', *, multivariate: bool = False, align: str = 'intersection')[source]

Bases: Transform

Standardize TimeSeries or matrix objects with optional robust scaling.

supports_inverse = True

params: dict[str, Any] | None

fit(x)[source]: Fit standardization parameters (center, scale) for the input data.

transform(x)[source]: Apply standardization using fitted parameters.

inverse_transform(y)[source]: Reverse standardization transformation.

class gwexpy.timeseries.WhitenTransform(method: Literal['pca', 'zca'] = 'pca', eps: float = 1e-12, n_components: int | None = None, *, multivariate: bool = True, align: str = 'intersection')[source]

Bases: Transform

Whiten TimeSeriesMatrix-like data with PCA or ZCA.

supports_inverse = True

model: WhiteningModel | None

fit(x)[source]: Fit whitening parameters for the input data.

transform(x)[source]: Apply whitening transform.

inverse_transform(y)[source]: Reverse whitening transformation.

class gwexpy.timeseries.PCATransform(n_components: int | None = None, *, multivariate: bool = True, align: str = 'intersection', **kwargs)[source]

Bases: Transform

Wrap PCA using existing decomposition helpers.

supports_inverse = True

fit(x)[source]: Fit PCA model for the input data.

transform(x)[source]: Apply PCA transformation (project to scores).

inverse_transform(y)[source]: Reverse PCA transformation (reconstruct from scores).

class gwexpy.timeseries.ICATransform(n_components: int | None = None, *, multivariate: bool = True, align: str = 'intersection', **kwargs)[source]

Bases: Transform

Wrap ICA using existing decomposition helpers.

supports_inverse = True

fit(x)[source]: Fit ICA model for the input data.

transform(x)[source]: Apply ICA transformation (project to sources).

inverse_transform(y)[source]: Reverse ICA transformation (reconstruct from sources).