SpectrogramMatrix๏
Stability: Stable
What it is๏
Use SpectrogramMatrix for aligned multi-channel spectrogram analysis and summary statistics across a grid of spectrograms.
Representative Signatures๏
SpectrogramMatrix(data, times=None, frequencies=None, ...)
SpectrogramMatrix.to_dict()
Minimal Example๏
from gwexpy.spectrogram import SpectrogramMatrix
import numpy as np
mat = SpectrogramMatrix(np.ones((2, 8, 16)), times=np.arange(8), frequencies=np.arange(16))
out = mat.to_dict()
API Reference๏
The detailed generated API continues below on this page.
Inherits from: PhaseMethodsMixin, SpectrogramMatrixCoreMixin, SpectrogramMatrixAnalysisMixin, SeriesMatrix
Evaluation Matrix for Spectrograms (Time-Frequency maps).
This class represents a collection of Spectrograms, structured as either:
3D: (Batch, Time, Frequency)
4D: (Row, Col, Time, Frequency)
It inherits from SeriesMatrix, providing powerful indexing, metadata management, and analysis capabilities (slicing, interpolation, statistics).
Physical Context๏
Use SpectrogramMatrix when multiple time-frequency maps share one binning scheme and their relationships matter: detector arrays, parameter sweeps, before/after processing grids, or channel-by-channel summary studies.
matrix statistics are meaningful only when time and frequency axes are aligned
this container is for comparing structure across maps, not just storing many unrelated plots
Common Misreadings๏
treating any stack of spectrograms as comparable without matching transform settings
interpreting matrix summaries as physical averages when the input maps use different scales or normalization
forgetting that row/column structure is analytical metadata, not automatically spatial geometry
Where to go next๏
per-map interpretation: Spectrogram
container conversions: SpectrogramList, SpectrogramDict
aligned workflow: Spectrogram Matrix Tutorial
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).
angle๏
angle(self, unwrap: bool = False, deg: bool = False, **kwargs: Any) -> Any
Alias for phase(unwrap=unwrap, deg=deg).
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)
Get the integer index for a column key.
(Inherited from SeriesMatrix)
col_keys๏
col_keys(self)
Get the keys (labels) for all columns.
(Inherited from SeriesMatrix)
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.
degree๏
degree(self, unwrap: 'bool' = False) -> 'Any'
Calculate the phase of the matrix in degrees.
det๏
det(self)
Compute the determinant of the matrix at each sample point.
df๏
No documentation available.
diagonal๏
diagonal(self, output: 'str' = 'list')
Extract diagonal elements from the matrix.
dict_class๏
dict_class(dict=None, **kwargs)
Dictionary of Spectrogram objects.
Note
Spectrogram objects can be very large in memory.
Use inplace=True where possible to update container in-place.
diff๏
diff(self, n=1, axis=None)
Calculate the n-th discrete difference along the sample axis.
dt๏
Time spacing (dx).
duration๏
Duration covered by the samples.
dx๏
Step size between samples on the x-axis.
f0๏
No documentation available.
frequencies๏
Frequency array (yindex).
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'
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).
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.
list_class๏
list_class(initlist=None)
List of Spectrogram objects. Reference: similar to TimeSeriesList but for 2D Spectrograms.
Note
Spectrogram objects can be very large in memory.
Use inplace=True where possible to avoid deep copies.
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=
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=
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.
phase๏
phase(self, unwrap: bool = False, deg: bool = False, **kwargs: Any) -> Any
Calculate the phase of the data.
Parameters๏
unwrap : bool, optional
If True, unwrap the phase to remove discontinuities.
Default is False.
deg : bool, optional
If True, return the phase in degrees.
Default is False (radians).
**kwargs
Additional arguments passed to the underlying calculation.
Returns๏
Series or Matrix or Collection
The phase of the data.
plot๏
plot(self, **kwargs)
Plot the matrix data using gwexpy.plot.Plot.
plot_summary๏
plot_summary(self, **kwargs)
Plot Matrix as side-by-side Spectrograms and percentile summaries.
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.
radian๏
radian(self, unwrap: 'bool' = False) -> 'Any'
Calculate the phase of the matrix in radians.
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)
Get the integer index for a row key.
(Inherited from SeriesMatrix)
row_keys๏
row_keys(self)
Get the keys (labels) for all rows.
(Inherited from SeriesMatrix)
schur๏
schur(self, keep_rows, keep_cols=None, eliminate_rows=None, eliminate_cols=None)
Compute the Schur complement of a block matrix.
series_class๏
series_class(data, unit=None, t0=None, dt=None, f0=None, df=None, times=None, frequencies=None, name=None, channel=None, **kwargs)
Extends gwpy.spectrogram.Spectrogram with additional interop methods.
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.
(Inherited from SeriesMatrix)
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.
t0๏
Start time (x0).
times๏
Time array (xindex).
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)
Convert to SpectrogramDict.
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.
to_jax๏
to_jax(self) -> Any
Convert to JAX Array.
to_list๏
to_list(self)
Convert to SpectrogramList.
to_pandas๏
to_pandas(self, format='wide')
Convert matrix to a pandas DataFrame.
to_series_1Dlist๏
to_series_1Dlist(self)
Convert matrix to a flat 1D list of Spectrogram objects.
to_series_2Dlist๏
to_series_2Dlist(self)
Convert matrix to a 2D nested list of Spectrogram 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.
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.