pycsamt.seg.ops#

Functions

`amp_or_psd`(x, fs, *[, mode])	Return (f, y) where y is amplitude or PSD.
`coherence_ms`(Sxy, Sxx, Syy)	Magnitude-squared coherency γ^2.
`compute_errors_from_S`(S, e_idx, h_idx[, ...])	Estimate 1-sigma uncertainties for the impedance tensor and, optionally, the tipper at a single frequency.
`effective_dof_from_meta`(*[, segnum, avgt, ...])	Estimate effective DoF (independent averages) from per-frequency metadata.
`pack_hermitian`(C)	Pack Hermitian NxN into upper-triangular vector.
`rho_phi_to_z`(rho, phi_deg, freq, *[, mu0])	Build Z from ρ, φ, and freq (per component).
`rotate_impedance`(z, theta_deg)	Rotate 2x2 impedance per freq: Z' = R Z R^T.
`rotate_spectra`(C, theta_deg)	Rotate cross-power matrix: C' = R C Rᵀ (per freq).
`rotate_tipper`(t, theta_deg)	Rotate tipper horizontal vector(s): t' = R t.
`synthesize_spectra_from_z`(Z, *[, S_HH, ...])	Synthesize a full Hermitian cross–spectral tensor from an impedance tensor `Z(f)` and optional tipper.
`time_vector`(npts, dt)	Evenly spaced time vector [s] from N and Δt.
`tipper_error_from_blocks`(S_ZH, S_ZZ, S_HH, *, M)	Diagonal σ estimate for tipper components.
`unpack_hermitian`(v, n)	Unpack upper-triangular vector into Hermitian matrix.
`z_error_from_blocks`(S_EE, S_EH, S_HH, *, M)	Diagonal σ estimate for Z components from spectral blocks.
`z_to_rho_phi`(z, freq, *[, mu0])	Component-wise apparent resistivity and phase from Z.

pycsamt.seg.ops.rotate_impedance(z, theta_deg)[source]#

Rotate 2x2 impedance per freq: Z’ = R Z R^T.

Shapes supported:

z: (nfreq, 2, 2) or (2, 2)
theta: scalar or (nfreq,)

Parameters:

z (ndarray)
theta_deg (float | ndarray)

Return type:

ndarray

pycsamt.seg.ops.rotate_tipper(t, theta_deg)[source]#

Rotate tipper horizontal vector(s): t’ = R t.

Accepts:

t: (nfreq, 2) or (nfreq, 1, 2) or (2,)
theta: scalar or (nfreq,)

Parameters:

t (ndarray)
theta_deg (float | ndarray)

Return type:

ndarray

pycsamt.seg.ops.z_to_rho_phi(z, freq, *, mu0=1.2566370614359173e-06)[source]#

Component-wise apparent resistivity and phase from Z.

ρ = |Z|^2 / (μ0 ω) ; φ = atan2(Im(Z), Re(Z)) [deg]

Parameters:

z (ndarray)
freq (ndarray | Iterable[float])
mu0 (float)

Return type:

tuple[ndarray, ndarray]

pycsamt.seg.ops.rho_phi_to_z(rho, phi_deg, freq, *, mu0=1.2566370614359173e-06)[source]#

Build Z from ρ, φ, and freq (per component).

Parameters:

rho (ndarray)
phi_deg (ndarray)
freq (ndarray | Iterable[float])
mu0 (float)

Return type:

ndarray

pycsamt.seg.ops.time_vector(npts, dt)[source]#

Evenly spaced time vector [s] from N and Δt.

Parameters:

npts (int)
dt (float)

Return type:

ndarray

pycsamt.seg.ops.coherence_ms(Sxy, Sxx, Syy)[source]#

Magnitude-squared coherency γ^2.

Parameters:

Sxy (ndarray)
Sxx (ndarray)
Syy (ndarray)

Return type:

ndarray

pycsamt.seg.ops.pack_hermitian(C)[source]#

Pack Hermitian NxN into upper-triangular vector.

Output length = N*(N+1)/2, complex dtype preserved.

Parameters:: C (ndarray)
Return type:: ndarray

pycsamt.seg.ops.unpack_hermitian(v, n)[source]#

Unpack upper-triangular vector into Hermitian matrix.

Parameters:

v (ndarray)
n (int)

Return type:

ndarray

pycsamt.seg.ops.rotate_spectra(C, theta_deg)[source]#

Rotate cross-power matrix: C’ = R C Rᵀ (per freq).

Parameters:

C (ndarray)
theta_deg (float)

Return type:

ndarray

pycsamt.seg.ops.amp_or_psd(x, fs, *, mode='amp')[source]#

Return (f, y) where y is amplitude or PSD.

mode=”amp”: |X(f)| / N mode=”psd”: (|X(f)|^2) / (fs * N)

Parameters:

x (ndarray)
fs (float)
mode (str)

Return type:

tuple[ndarray, ndarray]

pycsamt.seg.ops.synthesize_spectra_from_z(Z, *, S_HH=None, H_psd=None, tipper=None, include_hz=False, chan_order=('HX', 'HY', 'EX', 'EY'), e_noise=None, h_noise=None)[source]#

Synthesize a full Hermitian cross–spectral tensor from an impedance tensor Z(f) and optional tipper.

Given electric–magnetic relation E = Z H, blocks are:

S_EH = Z S_HH
S_EE = Z S_HH Z^H

If a horizontal tipper T (TX, TY) is supplied and HZ is requested, additional blocks are:

S_ZH = T S_HH, S_ZZ = T S_HH T^H
S_EZ = Z S_HH T^H

If magnetic spectra are not provided, a unit–power model is used (S_HH = I). The result is explicitly symmetrized to be Hermitian.

Parameters:

Z (ndarray) – Impedance per frequency. Shape (n, 2, 2) or (2, 2). If 2–D, it is broadcast to one frequency.
S_HH (ndarray, optional) – Magnetic spectra per frequency, shape (n, 2, 2). Must be Hermitian. Overrides H_psd if both are given.
H_psd (tuple of ndarray, optional) – (Pxx, Pyy, Pxy) where Pxx, Pyy are real (n,) and Pxy is optional complex (n,). Used to assemble S_HH when it is not supplied.
tipper (ndarray, optional) – Horizontal tipper as (n, 1, 2) or (n, 2). Required when include_hz is True or when "HZ" is in chan_order.
include_hz (bool, default False) – If True, add HZ and its cross–terms. Requires tipper.
chan_order (tuple of str, optional) – Channel order of the output spectra. Defaults to ("HX","HY","EX","EY"). Include "HZ" to place the vertical magnetic channel.
e_noise (float or ndarray, optional) – Diagonal noise power added to the electric block S_EE. Scalar or length n.
h_noise (float or ndarray, optional) – Diagonal noise power added to the magnetic block S_HH. Scalar or length n.

Returns:

Sfull (ndarray) – Cross–spectral tensor, shape (n, m, m), complex, Hermitian. m = len(chan_order).
chan_ids (list of str) – Channel names in the order used for Sfull.

Raises:

ValueError – If shapes are incompatible, the tipper is missing when HZ is requested, or dimensions do not match.

Return type:

tuple[ndarray, list[str]]

Notes

Absolute scaling of spectra depends on S_HH. If neither S_HH nor H_psd is provided, the unit– power model is used. This is convenient for tests and structure checks, but does not preserve physical power.

The function enforces Hermitian symmetry by conjugating off–diagonal blocks and real–ifying the diagonal.

Examples

Minimal, unit–power synthesis:

>>> S, order = synthesize_spectra_from_z(Z_arr)

With magnetic PSDs and tipper, including HZ:

>>> Pxx = np.full(n, 1e-2)
>>> Pyy = np.full(n, 1e-2)
>>> S, order = synthesize_spectra_from_z(
...     Z_arr,
...     H_psd=(Pxx, Pyy, None),
...     tipper=T_arr,       # (n,1,2) or (n,2)
...     include_hz=True,
...     chan_order=("HX","HY","HZ","EX","EY"),
... )