Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

gwexpy.frequencyseries.FrequencySeriesMatrix#

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`(args, *kwargs)	Return whether all raw values are truthy, as a plain NumPy value.
`angle`([unwrap, deg])	Return the element-wise complex phase angle of the matrix.
`any`(args, *kwargs)	Return whether any raw value is truthy, as a plain NumPy value.
`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 values while retaining independent public metadata.
`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])	Clip the values elementwise, preserving per-cell units.
`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`()	Return the conjugate with fully independent public metadata.
`conjugate`()	Return the elementwise complex conjugate, preserving per-cell units.
`copy`([order])	Copy values and every public metadata field independently.
`crop`([start, end, copy])	Crop the matrix to a specified range along the sample axis.
`cumprod`(args, *kwargs)	Return the cumulative product of the raw values as a plain NumPy array.
`cumsum`(args, *kwargs)	Return the cumulative sum of the raw values as a plain NumPy array.
`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])	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`(args, *kwargs)	Multiply the raw values together, returning a plain NumPy value.
`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 without sharing B0 public state with the source.
`resize`()	Change shape and size of array in-place.
`rms`([axis, keepdims, ignore_nan])	Compute the Root Mean Square (RMS) value.
`round`([decimals, out])	Round the values elementwise, preserving per-cell units.
`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, ...])
`step`([where])	Plot the matrix as a step function.
`submatrix`(row_keys, col_keys)	Extract a submatrix by selecting specific rows and columns.
`sum`(args, *kwargs)	Sum the raw values.
`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/columns with independent, correctly keyed metadata.
`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, ...])
`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`	Return the B0 row/column transpose.
`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`	Return the imaginary component without aliasing public metadata.
`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`	Return the real component without aliasing public metadata.
`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#

meta: MetaDataMatrix#

rows: MetaDataDict#

cols: MetaDataDict#

name: str | None#

epoch: float | int | None#

attrs: dict[str, Any] | None#

unit: u.Unit | None#