Matrix Containers

Note

Page role: Secondary API category

Stability: Stable

Multi-channel containers that group multiple TimeSeries, FrequencySeries, or Spectrogram objects and expose vectorized operations across all channels simultaneously.

Note

Learning path: Start here after the matrix-oriented tutorials if you want class members and exact method signatures.

See also

Time Series

Container-level time-series API that many matrix methods mirror.

Frequency Series

Frequency-domain container API used by FrequencySeriesMatrix.

Spectrogram

Time-frequency container API used by SpectrogramMatrix.

Signal Extraction: Weak Signal Recovery from Colored Noise

Multi-channel time-frequency workflow with matrix-style analysis.

Tutorials (Feature-Oriented Learning)

Tutorial hub for matrix-first learning paths before API lookup.

Reference Topics

Concept hub for conventions and advanced/theory notes tied to matrix workflows.

Time Series Matrix

TimeSeriesMatrix([data, times, dt, t0, ...])

A 2D matrix of TimeSeries objects sharing a common time axis.
class gwexpy.timeseries.TimeSeriesMatrix(data: ndarray | list | tuple | _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | TimeSeries | TimeSeriesMatrix | None = None, times: XIndex | Quantity | ndarray | None = None, dt: float | Quantity | None = None, t0: float | Quantity | None = None, sample_rate: float | Quantity | None = None, epoch: float | Quantity | None = None, **kwargs: Any)[source]

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

No

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

No

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

No

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

No

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.

Frequency Series Matrix

FrequencySeriesMatrix([data, frequencies, ...])

A 2D matrix of FrequencySeries objects sharing a common frequency axis.
class gwexpy.frequencyseries.FrequencySeriesMatrix(data: ndarray | list | tuple | _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | FrequencySeriesMatrix | None = None, frequencies: XIndex | Quantity | ndarray | None = None, df: float | Quantity | None = None, f0: float | Quantity | None = None, **kwargs: Any)[source]

Bases: FrequencySeriesMatrixCoreMixin, FrequencySeriesMatrixAnalysisMixin, SeriesMatrix

A 2D matrix of FrequencySeries objects sharing a common frequency axis.

FrequencySeriesMatrix represents a 2-dimensional array (rows x columns) where each element is a FrequencySeries. All elements in the matrix must share the same frequency synchronization (same f0, df, and number of frequency bins).

This class is typically used to represent multi-channel spectral data, such as Cross-Spectral Density (CSD) matrices, coherence matrices, or multi-channel Power Spectral Densities (PSDs).

Parameters:

  • data (array-like, optional) – The data values for the matrix. Should be of shape (rows, columns, frequencies).

  • frequencies (array-like, optional) – The frequency values corresponding to each bin. If provided, df and f0 are ignored.

  • df (float, ~astropy.units.Quantity, optional) – The frequency resolution.

  • f0 (float, ~astropy.units.Quantity, optional) – The start frequency.

  • **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

FrequencySeriesMatrix supports element-wise spectral operations (e.g., zpk, filter, smooth) and statistical aggregations.

Key methods:

plot(**kwargs)

Plot this object using gwexpy.plot.Plot.

smooth(width[, method, ignore_nan])

Smooth the frequency series matrix along the frequency axis.

to_dict()

Convert matrix to an appropriate collection dict (e.g. TimeSeriesDict).

Examples

>>> from gwexpy.frequencyseries import FrequencySeriesMatrix
>>> import numpy as np
>>> data = np.ones((2, 2, 100))
>>> fsm = FrequencySeriesMatrix(data, df=1, unit='V/Hz')
>>> fsm
<SeriesMatrix shape=(2, 2, 100) rows=('row0', 'row1') cols=('col0', 'col1')>
series_class

alias of FrequencySeries

dict_class

alias of FrequencySeriesDict

list_class

alias of FrequencySeriesList

series_type = 'freq'
default_xunit = 'Hz'
default_yunit = None

Spectrogram Matrix

SpectrogramMatrix(data[, times, ...])

Evaluation Matrix for Spectrograms (Time-Frequency maps).
class gwexpy.spectrogram.SpectrogramMatrix(data: ArrayLike | SpectrogramMatrix, times: IndexLike | None = None, frequencies: IndexLike | None = None, unit: UnitLike = None, name: str | None = None, rows: MetaDataCollectionType = None, cols: MetaDataCollectionType = None, meta: Any = None, **kwargs: Any)[source]

Bases: PhaseMethodsMixin, SpectrogramMatrixCoreMixin, SpectrogramMatrixAnalysisMixin, SeriesMatrix

Evaluation Matrix for Spectrograms (Time-Frequency maps).

SpectrogramMatrix represents a collection of Spectrograms, structured as a multivariate matrix with dimensions either:

  • 3D: (Batch, Time, Frequency)

  • 4D: (Row, Col, Time, Frequency)

It extends the core ~gwexpy.types.seriesmatrix.SeriesMatrix with spectrogram-specific axes (times and frequencies) and analysis methods.

Parameters:

  • data (array-like) – The data values for the matrix. Should be 3D or 4D.

  • times (array-like, optional) – The time values corresponding to each row.

  • frequencies (array-like, optional) – The frequency values corresponding to each column.

  • unit (str, ~astropy.units.Unit, optional) – Physical unit of the data.

  • **kwargs – Additional keyword arguments passed to the ~gwexpy.types.seriesmatrix.SeriesMatrix constructor.

Notes

Serialization is supported via HDF5 and Pickle. Metadata is preserved per-element in the meta attribute.

Key methods:

plot_summary(**kwargs)

Plot the matrix as side-by-side spectrograms and percentile summaries.

to_dict()

Convert to SpectrogramDict.

to_list()

Convert to SpectrogramList.

radian([unwrap])

Calculate the phase of the matrix in radians.

Examples

>>> from gwexpy.spectrogram import SpectrogramMatrix
>>> import numpy as np
>>> data = np.ones((1, 2, 2))
>>> sm = SpectrogramMatrix(data, times=[0, 1], frequencies=[10, 20])
>>> sm
<SeriesMatrix shape=(1, 2, 2) rows=('batch0',) cols=('col0',)>
series_class

alias of Spectrogram

dict_class

alias of SpectrogramDict

list_class

alias of SpectrogramList

row_keys()[source]

Return the row metadata keys.

col_keys()[source]

Return the column metadata keys.

is_compatible(other: Any) → bool[source]

Check compatibility with another SpectrogramMatrix/object.

Overrides SeriesMatrix.is_compatible to avoid loop range issues due to mismatch between data shape (Time axis) and metadata shape (Batch/Col).

row_index(key)[source]

Return the integer index for a row key.

col_index(key)[source]

Return the integer index for a column key.

to_series_2Dlist()[source]

Convert matrix to a 2D nested list of Spectrogram objects.

to_series_1Dlist()[source]

Convert matrix to a flat 1D list of Spectrogram objects.

to_list()[source]

Convert to SpectrogramList.

to_dict()[source]

Convert to SpectrogramDict.

property shape3D

Return the display-oriented 3D shape view.

plot_summary(**kwargs)[source]

Plot the matrix as side-by-side spectrograms and percentile summaries.