SeriesMatrix

Stability: Stable

What it is

Use SeriesMatrix as the common matrix abstraction behind time-series, frequency-series, and spectrogram matrix containers.

Representative Signatures

SeriesMatrix(data, xindex=None, x0=None, dx=None, names=None, ...)
SeriesMatrix.to_dict()

Minimal Example

from gwexpy.types import SeriesMatrix
import numpy as np

mat = SeriesMatrix(np.ones((2, 2, 32)), x0=0, dx=1.0)
out = mat.to_dict()

API Reference

The detailed generated API continues below on this page.

Round-Trip Metadata Contract

Use copy(), Python pickle, or to_hdf5() / read(..., format="hdf5") when a SeriesMatrix-family object must preserve matrix values, the sample axis, per-element units/names/channels, row and column metadata, name, epoch, and JSON-serializable attrs.

to_pandas() and write(..., format="csv") / write(..., format="parquet") are value exports. They preserve the numeric values, sample index values, and row/column keys flattened into tabular labels, but they do not preserve per-element metadata, row/column metadata payloads, attrs, epoch, or the sample-axis unit as reconstructable object metadata. Prefer HDF5 for metadata-preserving interchange.

Inherits from: RegularityMixin, InteropMixin, SeriesMatrixCoreMixin, SeriesMatrixIndexingMixin, SeriesMatrixIOMixin, SeriesMatrixMathMixin, SeriesMatrixAnalysisMixin, SeriesMatrixStructureMixin, SeriesMatrixVisualizationMixin, SeriesMatrixValidationMixin, StatisticalMethodsMixin, ndarray

Methods

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).

append

append(self, other, inplace=True, pad=None, gap=None, resize=True)

Append another matrix along the sample axis.

append_exact

append_exact(self, other, inplace=False, pad=None, gap=None, tol=3.814697265625e-06)

Append another matrix with strict contiguity checking.

astype

astype(self, dtype, copy=True)

Cast matrix data to a specified type.

channel_names

Flattened list of all element names.

channels

2D array of channel identifiers for each matrix element.

col_index

col_index(self, key: 'Any') -> 'int'

Get the integer index for a column key.

col_keys

col_keys(self) -> 'tuple[Any, ...]'

Get the keys (labels) for all columns.

conj

conj(self)

Complex conjugate of the matrix.

copy

copy(self, order='C')

Create a deep copy of this matrix.

crop

crop(self, start=None, end=None, copy=False)

Crop the matrix to a specified range along the sample axis.

det

det(self)

Compute the determinant of the matrix at each sample point.

diagonal

diagonal(self, output: 'str' = 'list')

Extract diagonal elements from the matrix.

diff

diff(self, n=1, axis=None)

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

duration

Duration covered by the samples.

dx

Step size between samples on the x-axis.

get_index

get_index(self, key_row: 'Any', key_col: 'Any') -> 'tuple[int, int]'

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

imag

imag(self)

Imaginary part of the matrix.

interpolate

interpolate(self, xindex, **kwargs)

Interpolate the matrix to a new sample axis.

inv

inv(self, swap_rowcol: 'bool' = True)

Compute the matrix inverse at each sample point.

is_compatible

is_compatible(self, other: 'Any') -> 'bool'

Compatibility check.

is_compatible_exact

is_compatible_exact(self, other: 'Any') -> 'bool'

Check strict compatibility with another matrix.

is_contiguous

is_contiguous(self, other: 'Any', tol: 'float' = 3.814697265625e-06) -> 'int'

Check if this matrix is contiguous with another.

is_contiguous_exact

is_contiguous_exact(self, other: 'Any', tol: 'float' = 3.814697265625e-06) -> 'int'

Check contiguity with strict shape matching.

is_regular

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

keys

keys(self) -> 'tuple[tuple[Any, ...], tuple[Any, ...]]'

Get both row and column keys.

loc

Label-based indexer for direct value access.

max

max(self, axis=None, out=None, keepdims=False, initial=None, where=True, ignore_nan=True)

a.max(axis=None, out=None, keepdims=False, initial=, where=True)

Return the maximum along a given axis.

Refer to numpy.amax for full documentation.

See Also

numpy.amax : equivalent function

(Inherited from ndarray)

mean

mean(self, axis=None, dtype=None, out=None, keepdims=False, *, where=True, ignore_nan=True)

a.mean(axis=None, dtype=None, out=None, keepdims=False, *, where=True)

Returns the average of the array elements along given axis.

Refer to numpy.mean for full documentation.

See Also

numpy.mean : equivalent function

(Inherited from ndarray)

median

median(self, axis=None, out=None, overwrite_input=False, keepdims=False, ignore_nan=True)

No documentation available.

min

min(self, axis=None, out=None, keepdims=False, initial=None, where=True, ignore_nan=True)

a.min(axis=None, out=None, keepdims=False, initial=, where=True)

Return the minimum along a given axis.

Refer to numpy.amin for full documentation.

See Also

numpy.amin : equivalent function

(Inherited from ndarray)

names

2D array of names for each matrix element. Alias for channel_names if 1D.

pad

pad(self, pad_width, **kwargs)

Pad the matrix along the sample axis.

plot

plot(self, **kwargs: 'Any') -> 'Any'

Plot this SeriesMatrix using gwexpy.plot.Plot.

prepend

prepend(self, other, inplace=True, pad=None, gap=None, resize=True)

Prepend another matrix at the beginning along the sample axis.

prepend_exact

prepend_exact(self, other, inplace=False, pad=None, gap=None, tol=3.814697265625e-06)

Prepend another matrix with strict contiguity checking.

read

read(source, format=None, **kwargs)

Read a SeriesMatrix from file.

Parameters

source : str or path-like Path to file to read. format : str, optional File format. If None, inferred from extension. **kwargs Additional arguments passed to the reader.

Returns

SeriesMatrix The loaded matrix.

The available built-in formats are:

======== ==== ===== ============= Format Read Write Auto-identify ======== ==== ===== ============= ats Yes No No dttxml Yes No No gbd Yes No No gse2 Yes No No knet Yes No No li Yes No No lsf Yes No No mem Yes No No miniseed Yes No No orf Yes No No sac Yes No No sdb Yes No No sqlite Yes No No sqlite3 Yes No No taffmat Yes No No tdms Yes No No wav Yes No No wdf Yes No No win Yes No No win32 Yes No No wvf Yes No No ======== ==== ===== =============

real

real(self)

Real part of the matrix.

reshape

reshape(self, shape, order='C')

Reshape the matrix dimensions.

rms

rms(self, axis=None, keepdims=False, ignore_nan=True)

No documentation available.

row_index

row_index(self, key: 'Any') -> 'int'

Get the integer index for a row key.

row_keys

row_keys(self) -> 'tuple[Any, ...]'

Get the keys (labels) for all rows.

schur

schur(self, keep_rows, keep_cols=None, eliminate_rows=None, eliminate_cols=None)

Compute the Schur complement of a block matrix.

shape3D

Shape of the matrix as a 3-tuple (n_rows, n_cols, n_samples). For 4D matrices (spectrograms), the last dimension is likely frequency, so n_samples is determined by _x_axis_index.

shift

shift(self, delta)

Shift the sample axis by a constant offset.

std

std(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True, ignore_nan=True)

a.std(axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True)

Returns the standard deviation of the array elements along given axis.

Refer to numpy.std for full documentation.

See Also

numpy.std : equivalent function

(Inherited from ndarray)

step

step(self, where: 'str' = 'post', **kwargs: 'Any') -> 'Any'

Plot the matrix as a step function.

submatrix

submatrix(self, row_keys, col_keys)

Extract a submatrix by selecting specific rows and columns.

to_cupy

to_cupy(self, dtype=None) -> Any

Convert to CuPy Array.

to_dask

to_dask(self, chunks='auto') -> Any

Convert to Dask Array.

to_dict

to_dict(self) -> 'Any'

Convert matrix to an appropriate collection dict (e.g. TimeSeriesDict). Follows the matrix structure (row, col) unless it’s a 1-column matrix.

to_dict_flat

to_dict_flat(self) -> 'dict[str, Series]'

Convert matrix to a flat dictionary mapping name to Series.

to_hdf5

to_hdf5(self, filepath, **kwargs)

Write matrix to HDF5 file.

This is the preferred metadata-preserving file path for SeriesMatrix objects: values, sample-axis values and unit, element metadata, row/column metadata, name, epoch, and JSON-serializable attrs are part of the round-trip contract.

to_jax

to_jax(self) -> Any

Convert to JAX Array.

to_list

to_list(self) -> 'Any'

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

to_pandas

to_pandas(self, format='wide')

Convert matrix values to a pandas DataFrame.

This is a value export, not an object metadata round-trip. The DataFrame keeps numeric values, sample index values, and row/column keys in wide or long form, but drops element metadata, row/column metadata payloads, attrs, epoch, and reconstructable sample-axis unit metadata.

to_series_1Dlist

to_series_1Dlist(self) -> 'list[Series]'

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

to_series_2Dlist

to_series_2Dlist(self) -> 'list[list[Series]]'

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

to_tensorflow

to_tensorflow(self, dtype: Any = None) -> Any

Convert to tensorflow.Tensor.

to_torch

to_torch(self, device: Optional[str] = None, dtype: Any = None, requires_grad: bool = False, copy: bool = False) -> Any

Convert to torch.Tensor.

to_zarr

to_zarr(self, store, path=None, **kwargs) -> Any

Save to Zarr storage.

trace

trace(self)

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

transpose

transpose(self, *axes)

Transpose rows and columns, preserving sample axis as 2.

units

2D array of units for each matrix element.

update

update(self, other, inplace=True, pad=None, gap=None)

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

value

Underlying numpy array of data values.

value_at

value_at(self, x)

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

var

var(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True, ignore_nan=True)

a.var(axis=None, dtype=None, out=None, ddof=0, keepdims=False, *, where=True)

Returns the variance of the array elements, along given axis.

Refer to numpy.var for full documentation.

See Also

numpy.var : equivalent function

(Inherited from ndarray)

write

write(self, target, format=None, **kwargs)

Write matrix to file.

format="hdf5" preserves the object metadata contract described above. CSV and parquet writes use to_pandas(format="wide") and should be treated as value-only exports.

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

No documentation available.