gwexpy.timeseries.TimeSeriesMatrix

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')>
__init__()

Methods

__init__()

abs()

Return the absolute value of the matrix element-wise.

all([axis, out, keepdims, where])

Returns True if all elements evaluate to True.

angle([unwrap, deg])

Alias for phase(unwrap=unwrap, deg=deg).

any([axis, out, keepdims, where])

Returns True if any of the elements of a evaluate to True.

append(other[, inplace, pad, gap, resize])

Append another matrix along the sample axis.

append_exact(other[, inplace, pad, gap, tol])

Append another matrix with strict contiguity checking.

argmax([axis, out, keepdims])

Return indices of the maximum values along the given axis.

argmin([axis, out, keepdims])

Return indices of the minimum values along the given axis.

argpartition(kth[, axis, kind, order])

Returns the indices that would partition this array.

argsort([axis, kind, order, stable])

Returns the indices that would sort this array.

asd(**kwargs)

Compute the ASD of each element.

astype(dtype[, order, casting, subok, copy])

Cast matrix data to a specified type.

auto_coherence(*args, **kwargs)

Apply univariate spectral method TimeSeries.auto_coherence element-wise.

bandpass(*args, **kwargs)

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

byteswap([inplace])

Swap the bytes of the array elements

choose(choices[, out, mode])

Use an index array to construct a new array from a set of choices.

clip([min, max, out])

Return an array whose values are limited to [min, max].

coherence(other, *args, **kwargs)

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

coherence_ranking(target[, band, top_n, ...])

Compute pairwise Welch coherence between target and all other channels.

col_index(key)

Get the integer index for a column key.

col_keys()

Get the keys (labels) for all columns.

compress(condition[, axis, out])

Return selected slices of this array along given axis.

conj()

Complex conjugate of the matrix.

conjugate()

Return the complex conjugate, element-wise.

copy([order])

Create a deep copy of this matrix.

correlation([other, method])

Calculate correlation coefficients.

correlation_vector(target_timeseries[, ...])

Calculate correlation between a target series and all channels.

crop([start, end, copy])

Crop this matrix to the given GPS start and end times.

csd(other, *args, **kwargs)

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

cumprod([axis, dtype, out])

Return the cumulative product of the elements along the given axis.

cumsum([axis, dtype, out])

Return the cumulative sum of the elements along the given axis.

degree([unwrap])

Calculate the phase angle of the matrix in degrees.

det()

Compute the determinant of the matrix at each sample point.

detrend(*args, **kwargs)

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

diagonal([offset, axis1, axis2])

Extract diagonal elements from the matrix.

diff([n, axis])

Calculate the n-th discrete difference along the sample axis.

distance_correlation(other, **kwargs)

Calculate distance correlation.

dot(other, /[, out])

Refer to numpy.dot() for full documentation.

dump(file)

Dump a pickle of the array to the specified file.

dumps()

Returns the pickle of the array as a string.

fft(**kwargs)

Compute the FFT of each element.

fill(value)

Fill the array with a scalar value.

filter(*args, **kwargs)

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

flatten([order])

Return a copy of the array collapsed into one dimension.

from_neo(sig)

Create TimeSeriesMatrix from neo.AnalogSignal.

get_index(key_row, key_col)

Get the (row, col) integer indices for given keys.

getfield(dtype[, offset])

Returns a field of the given array as a certain type.

highpass(*args, **kwargs)

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

hilbert(**kwargs)

Compute the analytic signal via the Hilbert transform.

ica([return_model])

Fit and transform ICA.

ica_fit(**kwargs)

Fit ICA.

ica_inverse_transform(ica_res, sources)

Inverse transform ICA sources.

ica_transform(ica_res)

Transform using ICA.

impute(*[, method, limit, axis, max_gap])

Impute missing values in the matrix.

interpolate(xindex, **kwargs)

Interpolate the matrix to a new sample axis.

inv([swap_rowcol])

Compute the matrix inverse at each sample point.

is_compatible(other)

Compatibility check.

is_compatible_exact(other)

Check strict compatibility with another matrix.

is_contiguous(other[, tol])

Check if this matrix is contiguous with another.

is_contiguous_exact(other[, tol])

Check contiguity with strict shape matching.

item(*args)

Copy an element of an array to a standard Python scalar and return it.

keys()

Get both row and column keys.

ktau(other, **kwargs)

Calculate Kendall's rank correlation coefficient.

kurtosis([axis, fisher, nan_policy])

Compute the kurtosis of the matrix along the specified axis.

lock_in(**kwargs)

Apply lock-in amplification element-wise.

lowpass(*args, **kwargs)

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

max([axis, out, keepdims, initial, where])

Compute maximum along the specified axis.

mean([axis, dtype, out, keepdims, where])

Compute mean along the specified axis.

median([axis, out, overwrite_input, keepdims])

Compute the median.

mic(other, **kwargs)

Calculate the maximal information coefficient (MIC).

min([axis, out, keepdims, initial, where])

Compute minimum along the specified axis.

nonzero()

Return the indices of the elements that are non-zero.

notch(*args, **kwargs)

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

pad(pad_width, **kwargs)

Pad the matrix along the sample axis.

partial_correlation_matrix(*[, estimator, ...])

Compute a partial-correlation matrix across all channels.

partition(kth[, axis, kind, order])

Partially sorts the elements in the array in such a way that the value of the element in k-th position is in the position it would be in a sorted array.

pca([return_model])

Fit and transform PCA.

pca_fit(**kwargs)

Fit PCA.

pca_inverse_transform(pca_res, scores)

Inverse transform PCA scores.

pca_transform(pca_res, **kwargs)

Transform using PCA.

pcc(other, **kwargs)

Calculate the Pearson correlation coefficient.

phase([unwrap, deg])

Calculate the phase of the data.

plot(**kwargs)

Plot this object using gwexpy.plot.Plot.

prepend(other[, inplace, pad, gap, resize])

Prepend another matrix at the beginning along the sample axis.

prepend_exact(other[, inplace, pad, gap, tol])

Prepend another matrix with strict contiguity checking.

prod([axis, dtype, out, keepdims, initial, ...])

Return the product of the array elements over the given axis

psd(**kwargs)

Compute the PSD of each element.

put(indices, values[, mode])

Set a.flat[n] = values[n] for all n in indices.

q_transform(*args, **kwargs)

Compute the Q-transform of each element.

radian([unwrap])

Calculate the phase angle of the matrix in radians.

ravel([order])

Return a flattened array.

read(source, *args, **kwargs)

Read a TimeSeriesMatrix from a supported source.

repeat(repeats[, axis])

Repeat elements of an array.

resample(*args, **kwargs)

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

reshape(*shape[, order, copy])

Reshape the matrix dimensions.

resize()

Change shape and size of array in-place.

rms([axis, keepdims, ignore_nan])

Compute root-mean-square along the specified axis.

rolling_max(window, *[, center, min_count, ...])

Compute a rolling maximum along the time axis.

rolling_mean(window, *[, center, min_count, ...])

Compute a rolling mean along the time axis.

rolling_median(window, *[, center, ...])

Compute a rolling median along the time axis.

rolling_min(window, *[, center, min_count, ...])

Compute a rolling minimum along the time axis.

rolling_std(window, *[, center, min_count, ...])

Compute a rolling standard deviation along the time axis.

round([decimals, out])

Return a with each element rounded to the given number of decimals.

row_index(key)

Get the integer index for a row key.

row_keys()

Get the keys (labels) for all rows.

schur(keep_rows[, keep_cols, ...])

Compute the Schur complement of a block matrix.

searchsorted(v[, side, sorter])

Find indices where elements of v should be inserted in a to maintain order.

setfield(val, dtype[, offset])

Put a value into a specified place in a field defined by a data-type.

setflags([write, align, uic])

Set array flags WRITEABLE, ALIGNED, WRITEBACKIFCOPY, respectively.

shift(delta)

Shift the sample axis by a constant offset.

skewness([axis, nan_policy])

Compute the skewness of the matrix along the specified axis.

sort([axis, kind, order, stable])

Sort an array in-place.

spectrogram(*args, **kwargs)

Compute a spectrogram of each element.

spectrogram2(*args, **kwargs)

Compute spectrogram2 for each element.

squeeze([axis])

Remove axes of length one from a.

standardize(*[, axis, method, ddof])

Standardize the matrix.

std([axis, dtype, out, ddof, keepdims, where])

Compute standard deviation along the specified axis.

step([where])

Plot the matrix as a step function.

submatrix(row_keys, col_keys)

Extract a submatrix by selecting specific rows and columns.

sum([axis, dtype, out, keepdims, initial, where])

Return the sum of the array elements over the given axis.

swapaxes(axis1, axis2, /)

Return a view of the array with axis1 and axis2 interchanged.

take(indices[, axis, out, mode])

Return an array formed from the elements of a at the given indices.

taper(*args, **kwargs)

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

to_cupy([dtype])

Convert to CuPy Array.

to_dask([chunks])

Convert to Dask Array.

to_device(device, /, *[, stream])

For Array API compatibility.

to_dict()

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

to_dict_flat()

Convert matrix to a flat dictionary mapping name to Series.

to_hdf5(filepath, **kwargs)

Write matrix to HDF5 file.

to_jax()

Convert to JAX Array.

to_list()

Convert matrix to an appropriate collection list (e.g. TimeSeriesList).

to_mne([info])

Convert to mne.io.RawArray.

to_neo([units])

Convert to neo.AnalogSignal.

to_pandas([format])

Convert the matrix to a pandas DataFrame.

to_series_1Dlist()

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

to_series_2Dlist()

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

to_tensorflow([dtype])

Convert to tensorflow.Tensor.

to_torch([device, dtype, requires_grad, copy])

Convert to torch.Tensor.

to_zarr(store[, path])

Save to Zarr storage.

tobytes([order])

Construct Python bytes containing the raw data bytes in the array.

tofile(fid, /[, sep, format])

Write array to a file as text or binary (default).

tolist()

Return the array as an a.ndim-levels deep nested list of Python scalars.

trace([offset, axis1, axis2, dtype, out])

Compute the trace of the matrix (sum of diagonal elements).

transfer_function(other, *args, **kwargs)

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

transpose(*axes)

Transpose rows and columns, preserving sample axis as 2.

update(other[, inplace, pad, gap])

Update matrix by appending without resizing (rolling buffer style).

value_at(x)

Get the matrix values at a specific x-axis location.

var([axis, dtype, out, ddof, keepdims, where])

view([dtype][, type])

New view of array with the same data.

whiten(*args, **kwargs)

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

whiten_channels(*[, method, eps, ...])

Whiten the matrix across channels or components.

write(target[, format])

Write the matrix to a file.

Attributes

MetaDataMatrix

Metadata matrix containing per-element metadata.

N_samples

Number of samples along the x-axis.

T

Transpose of the matrix (rows and columns swapped).

base

Base object if memory is from some other object.

channel_names

Flattened list of all element names.

channels

2D array of channel identifiers for each matrix element.

ctypes

An object to simplify the interaction of the array with the ctypes module.

data

Python buffer object pointing to the start of the array's data.

default_xunit

default_yunit

device

dt

Time spacing (dx).

dtype

Data-type of the array's elements.

duration

Duration covered by the samples.

dx

Step size between samples on the x-axis.

flags

Information about the memory layout of the array.

flat

A 1-D iterator over the array.

imag

Imaginary part of the matrix.

is_regular

Return True if this series has a regular grid (constant spacing).

itemsize

Length of one array element in bytes.

loc

Label-based indexer for direct value access.

mT

View of the matrix transposed array.

names

2D array of names for each matrix element.

nbytes

Total bytes consumed by the elements of the array.

ndim

Number of array dimensions.

real

Real part of the matrix.

sample_rate

Sampling rate (1/dt).

series_type

shape

Tuple of array dimensions.

shape3D

Shape of the matrix as a 3-tuple (n_rows, n_cols, n_samples).

size

Number of elements in the array.

span

Time span (xspan).

strides

Tuple of bytes to step in each dimension when traversing an array.

t0

Start time (x0).

times

Time array (xindex).

units

2D array of units for each matrix element.

value

Underlying numpy array of data values.

x0

Starting value of the sample axis.

xarray

Return the sample axis values.

xindex

Sample axis index array.

xspan

Full extent of the sample axis as a tuple (start, end).

xunit

Unit of the sample axis.
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.