gwexpy.spectrogram.SpectrogramMatrix

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)

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',)>

__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.
astype(dtype[, order, casting, subok, copy])	Cast matrix data to a specified type.
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].
col_index(key)	Return the integer index for a column key.
col_keys()	Return the column metadata keys.
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.
crop([start, end, copy])	Crop the matrix to a specified range along the sample axis.
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 of the matrix in degrees.
det()	Compute the determinant of the matrix at each sample point.
diagonal([offset, axis1, axis2])	Extract diagonal elements from the matrix.
diff([n, axis])	Calculate the n-th discrete difference along the sample axis.
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.
fill(value)	Fill the array with a scalar value.
flatten([order])	Return a copy of the array collapsed into one dimension.
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.
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)	Check compatibility with another SpectrogramMatrix/object.
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.
kurtosis([axis, fisher, nan_policy])	Compute the kurtosis (Fisher or Pearson) of the data.
max([axis, out, keepdims, initial, where])
mean([axis, dtype, out, keepdims, where])
median([axis, out, overwrite_input, keepdims])	Compute the median.
min([axis, out, keepdims, initial, where])
nonzero()	Return the indices of the elements that are non-zero.
pad(pad_width, **kwargs)	Pad the matrix along the sample axis.
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.
phase([unwrap, deg])	Calculate the phase of the data.
plot(**kwargs)	Plot this object using gwexpy.plot.Plot.
plot_summary(**kwargs)	Plot the matrix as side-by-side spectrograms and percentile summaries.
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
put(indices, values[, mode])	Set a.flat[n] = values[n] for all n in indices.
radian([unwrap])	Calculate the phase of the matrix in radians.
ravel([order])	Return a flattened array.
read(source[, format])	Read a SeriesMatrix from file.
repeat(repeats[, axis])	Repeat elements of an array.
reshape(*shape[, order, copy])	Reshape the matrix dimensions.
resize()	Change shape and size of array in-place.
rms([axis, keepdims, ignore_nan])	Compute the Root Mean Square (RMS) value.
round([decimals, out])	Return a with each element rounded to the given number of decimals.
row_index(key)	Return the integer index for a row key.
row_keys()	Return the row metadata keys.
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 data.
sort([axis, kind, order, stable])	Sort an array in-place.
squeeze([axis])	Remove axes of length one from a.
std([axis, dtype, out, ddof, keepdims, where])
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.
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 to SpectrogramDict.
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 to SpectrogramList.
to_pandas([format])	Convert the matrix to a pandas DataFrame.
to_series_1Dlist()	Convert matrix to a flat 1D list of Spectrogram objects.
to_series_2Dlist()	Convert matrix to a 2D nested list of Spectrogram 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).
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.
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.
device
df	Return the frequency spacing.
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.
f0	Return the starting frequency.
flags	Information about the memory layout of the array.
flat	A 1-D iterator over the array.
frequencies	Frequency array (yindex).
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.
shape	Tuple of array dimensions.
shape3D	Return the display-oriented 3D shape view.
size	Number of elements in the array.
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 Spectrogram

dict_class

alias of SpectrogramDict

list_class

alias of SpectrogramList

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.