FrequencySeriesMatrix

Stability: Stable

What it is

Use FrequencySeriesMatrix for aligned multi-channel spectra that should be processed together as one matrix.

Representative Signatures

FrequencySeriesMatrix(data, frequencies=None, df=None, f0=None, ...)
FrequencySeriesMatrix.to_dict()

Minimal Example

from gwexpy.frequencyseries import FrequencySeriesMatrix
import numpy as np

mat = FrequencySeriesMatrix(np.ones((2, 2, 64)), df=1.0)
out = mat.to_dict()

API Reference

The detailed generated API continues below on this page.

Inherits from: FrequencySeriesMatrixCoreMixin, FrequencySeriesMatrixAnalysisMixin, SeriesMatrix

Matrix container for multiple FrequencySeries objects.

Inherits from SeriesMatrix and returns FrequencySeries instances when indexed.

Physical Context

Use FrequencySeriesMatrix when multiple spectra are already aligned on one frequency axis and should be processed as one object: sensor arrays, response matrices, coherence-like channel grids, or repeated spectra arranged by configuration.

  • matrix operations assume shared sampling on the frequency axis

  • this is the right container when relationships between channels matter as much as the spectra themselves

Common Misreadings

  1. treating an unaligned stack of spectra as a valid matrix input

  2. forgetting that matrix-level filtering or inversion is only meaningful when the entries share a common physical frequency grid

  3. interpreting linear-algebra outputs without checking conditioning and units

Where to go next

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.

apply_response

apply_response(self, response: 'Any', inplace: 'bool' = False) -> 'Any'

Apply a complex frequency response to the matrix.

Extension method (not in GWpy) to support complex filtering/calibration.

Parameters

response : array-like or Quantity Complex frequency response array aligned with self.frequencies. inplace : bool, optional If True, modify in-place.

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.

df

Frequency spacing (dx).

diagonal

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

Extract diagonal elements from the matrix.

dict_class

dict_class(*args: 'Any', **kwargs: 'Any')

Ordered mapping of FrequencySeries objects keyed by label.

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.

f0

Starting frequency (x0).

filter

filter(self, *filt: 'Any', **kwargs: 'Any') -> 'Any'

Apply a filter to the FrequencySeriesMatrix.

Matches GWpy FrequencySeries.filter behavior (magnitude-only response) by delegating to gwpy.frequencyseries._fdcommon.fdfilter. Use apply_response() for complex response application.

Parameters

*filt : filter arguments Filter definition. inplace : bool, optional If True, modify in-place. Default False. **kwargs : Additional arguments passed to fdfilter (e.g. analog=True).

Returns

FrequencySeriesMatrix Filtered matrix.

frequencies

Frequency array (xindex).

get_index

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

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

ifft

ifft(self) -> 'Any'

Compute the inverse FFT of this frequency-domain matrix.

Matches GWpy FrequencySeries.ifft normalization.

Returns

TimeSeriesMatrix The time-domain matrix resulting from the inverse FFT.

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.

list_class

list_class(*items: 'Union[_FS, Iterable[_FS]]')

List of FrequencySeries objects.

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

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.

series_class

series_class(data, unit=None, f0=None, df=None, frequencies=None, name=None, epoch=None, channel=None, **kwargs)

Light wrapper of gwpy’s FrequencySeries for compatibility and future extension.

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.

smooth

smooth(self, width: 'int', method: 'str' = 'amplitude', ignore_nan: 'bool' = True) -> 'Any'

Smooth the frequency series matrix along the frequency axis.

Parameters

width : int Full width of the smoothing window in samples. method : str, optional Smoothing method: β€˜amplitude’, β€˜power’, β€˜complex’, β€˜db’. Default is β€˜amplitude’. ignore_nan : bool, optional If True, ignore NaNs during smoothing. Default is True.

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.

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 to a pandas DataFrame.

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.

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.