Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

Matrix Containers#

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.

Time Series Matrix#

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

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

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): Read a TimeSeriesMatrix from a supported source.

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.

meta: MetaDataMatrix

rows: MetaDataDict

cols: MetaDataDict

name: str | None

epoch: float | int | None

attrs: dict[str, Any] | None

unit: u.Unit | None

Frequency Series Matrix#

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

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

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

meta: MetaDataMatrix

rows: MetaDataDict

cols: MetaDataDict

name: str | None

epoch: float | int | None

attrs: dict[str, Any] | None

unit: u.Unit | None

Spectrogram Matrix#

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

Evaluation Matrix for Spectrograms (Time-Frequency maps).

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

copy(order='C')

Create a deep copy of this matrix, including the frequency axis.

The inherited ~gwexpy.types.series_matrix_structure.SeriesMatrixStructureMixin.copy only knows about the row/col/xindex metadata shared by every ~gwexpy.types.seriesmatrix.SeriesMatrix; it does not resupply frequencies – a SpectrogramMatrix-specific axis – so a bare call silently dropped frequencies/f0/df (and anything derived from them, such as clip/round, which rebuild via copy).

astype(dtype, order='K', casting='unsafe', subok=True, copy=True)

Cast matrix data to dtype, including the frequency axis.

_rebuild_with_values (used by clip/round) falls back to astype instead of copy whenever the operation changes dtype – e.g. clipping an integer-valued matrix against float or Quantity bounds. The inherited ~gwexpy.types.series_matrix_structure.SeriesMatrixStructureMixin.astype does not resupply frequencies either, so that path silently dropped it the same way the un-overridden copy used to.

property real: SpectrogramMatrix: Return a fully independent real component with both axes intact.

property imag: SpectrogramMatrix: Return a fully independent imaginary component with both axes intact.

conj() → SpectrogramMatrix: Return a conjugate with axes and public metadata independent.

row_keys(): Return the row metadata keys.

col_keys(): Return the column metadata keys.

is_compatible(other: Any) → bool

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): Return the integer index for a row key.

col_index(key): Return the integer index for a column key.

to_series_2Dlist(): Convert matrix to a 2D nested list of Spectrogram objects.

to_series_1Dlist(): Convert matrix to a flat 1D list of Spectrogram objects.

to_list(): Convert to SpectrogramList.

to_dict(): Convert to SpectrogramDict.

property shape3D: Return the display-oriented 3D shape view.

plot_summary(**kwargs): Plot the matrix as side-by-side spectrograms and percentile summaries.

meta: MetaDataMatrix

rows: MetaDataDict

cols: MetaDataDict

name: str | None

epoch: float | int | None

attrs: dict[str, Any] | None

unit: Unit | None