gwexpy.frequencyseries.FrequencySeriesMatrix

class gwexpy.frequencyseries.FrequencySeriesMatrix(data: ndarray | list | tuple | _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | FrequencySeriesMatrix | None = None, frequencies: XIndex | Quantity | ndarray | None = None, df: float | Quantity | None = None, f0: float | Quantity | None = None, **kwargs: Any)

Bases: FrequencySeriesMatrixCoreMixin, FrequencySeriesMatrixAnalysisMixin, SeriesMatrix

A 2D matrix of FrequencySeries objects sharing a common frequency axis.

FrequencySeriesMatrix represents a 2-dimensional array (rows x columns) where each element is a FrequencySeries. All elements in the matrix must share the same frequency synchronization (same f0, df, and number of frequency bins).

This class is typically used to represent multi-channel spectral data, such as Cross-Spectral Density (CSD) matrices, coherence matrices, or multi-channel Power Spectral Densities (PSDs).

Parameters:

• data (array-like, optional) – The data values for the matrix. Should be of shape (rows, columns, frequencies).

• frequencies (array-like, optional) – The frequency values corresponding to each bin. If provided, df and f0 are ignored.

• df (float, ~astropy.units.Quantity, optional) – The frequency resolution.

• f0 (float, ~astropy.units.Quantity, optional) – The start frequency.

• **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

FrequencySeriesMatrix supports element-wise spectral operations (e.g., zpk, filter, smooth) and statistical aggregations.

Key methods:

plot(**kwargs)	Plot this object using gwexpy.plot.Plot.
smooth(width[, method, ignore_nan])	Smooth the frequency series matrix along the frequency axis.
to_dict()	Convert matrix to an appropriate collection dict (e.g. TimeSeriesDict).

Examples

>>> from gwexpy.frequencyseries import FrequencySeriesMatrix
>>> import numpy as np
>>> data = np.ones((2, 2, 100))
>>> fsm = FrequencySeriesMatrix(data, df=1, unit='V/Hz')
>>> fsm
<SeriesMatrix shape=(2, 2, 100) 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])	Return the element-wise complex phase angle of the matrix.
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.
apply_response(response[, inplace])	Apply a complex frequency response to the matrix.
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)	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.
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.
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.
filter(*filt, **kwargs)	Apply a filter to the FrequencySeriesMatrix.
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.
ifft()	Compute the inverse FFT of this frequency-domain 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.
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.
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
put(indices, values[, mode])	Set a.flat[n] = values[n] for all n in indices.
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)	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 data.
smooth(width[, method, ignore_nan])	Smooth the frequency series matrix along the frequency axis.
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 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_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).
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.
default_xunit
default_yunit
device
df	Frequency 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	Starting frequency (x0).
flags	Information about the memory layout of the array.
flat	A 1-D iterator over the array.
frequencies	Frequency array (xindex).
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.
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.
strides	Tuple of bytes to step in each dimension when traversing an array.
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	The physical unit of the frequency axis.

series_class

alias of FrequencySeries

dict_class

alias of FrequencySeriesDict

list_class

alias of FrequencySeriesList

series_type = 'freq'

default_xunit = 'Hz'

default_yunit = None