pycsamt.zonge.tensor#

TensorBase – generic 2×2 impedance-like tensor adapter.

This mixin-like base sits on top of AVGComponentBase. It provides helpers to move between tidy per-component tables and 3D/4D tensor blocks suitable for numerical work:

(freq, 2, 2) – single-station view (station, freq, 2, 2) – multi-station view

Supported component labels:

  • MT style: Zxx, Zxy, Zyx, Zyy

  • CSAMT style: ExHx, ExHy, EyHx, EyHy

Classes

TensorBase([data, meta, name, verbose])

Adds impedance-like tensor helpers to a component.
class pycsamt.zonge.tensor.TensorBase(data=None, meta=None, *, name=None, verbose=0)[source]#

Bases: AVGComponentBase

Adds impedance-like tensor helpers to a component.

This class acts as a mixin, providing methods to transform data between a tidy DataFrame format (one measurement per row) and a dense, multi-dimensional tensor format suitable for numerical computations.

It is agnostic to the actual physical quantity being reshaped; the var parameter in its methods specifies which column from the internal DataFrame to use for the tensor’s values.

Notes

Subclasses must provide a tidy _frame attribute containing at least the columns ['freq', 'comp'] and optionally 'station'.

The tensor axes are consistently ordered: - 3D (single station): (frequency, E-field, H-field) - 4D (multi-station): (station, frequency, E, H)

The E-field and H-field axes are of size 2, corresponding to the x and y components.

Parameters:
to_tensor(var, station=None, ...)[source]#

Converts a data column into a NumPy ndarray with a shape of (..., 2, 2).

Parameters:
Return type:

tuple[ndarray, ndarray, ndarray]

from_tensor(tensor, freqs, var, stations=None, ...)[source]#

Reconstructs a tidy DataFrame from a NumPy tensor.

Parameters:
Return type:

DataFrame

to_xarray_tensor(var, station=None, ...)[source]#

Converts a data column into a labeled xarray.DataArray.

Parameters:

See also

Z

A key subclass that uses these tensor operations.

Resistivity

Another subclass that benefits from this mixin.

Phase

A third subclass that uses this mixin.

to_tensor(*, var, station=None, agg='mean', fill_value=nan, sort_freq=True, align='union')[source]#

Convert per-component values into a 2×2 tensor per frequency.

Returns:

  • tensor (np.ndarray) – If station is provided → shape (n_freq, 2, 2). Else (multi-station) → shape (n_station, n_freq, 2, 2).

  • freqs (np.ndarray) – Sorted unique frequencies used in the tensor grid.

  • stations (np.ndarray) – Stations used (size 0 for single-station request).

Parameters:
Return type:

tuple[ndarray, ndarray, ndarray]

static from_tensor(tensor, freqs, *, var, stations=None, comp_style='mt')[source]#

Reconstruct a tidy frame from a (…×2×2) tensor.

Parameters:

  • tensor (ndarray) – Either (n_freq, 2, 2) or (n_station, n_freq, 2, 2).

  • freqs (Sequence[float]) – Frequencies corresponding to axis 0 (or 1).

  • var (str) – Column name to emit for the tensor values.

  • stations (Sequence[int | float | str] | None) – If provided and tensor is 4-D, labels for station axis.

  • comp_style (str) – ‘mt’ → Zxx/Zxy/Zyx/Zyy ; ‘csamt’ → ExHx/ExHy/EyHx/EyHy

Return type:

DataFrame

to_xarray_tensor(*, var, station=None, agg='mean', fill_value=nan, attrs=None)[source]#
Return a 3-D or 4-D xarray.DataArray with dims:

single-station → (freq, e, h) multi-station → (station, freq, e, h)

Parameters:
read(source, meta=None, **kws)[source]#

Parse source and mutate component state.

Implementations should:

  1. validate required columns using _require(...)

  2. copy/select needed columns into self._frame

  3. set/merge metadata into self._meta

Parameters:
Return type:

None

write()[source]#

Serialise the component to text lines. Implementations may delegate to _write_csv_block for a consistent block format (header + CSV). The base does not write to disk.

Return type:

Sequence[str]