pycsamt.emtools.spectra#

pycsamt.emtools.spectra#

Analysis and visualisation of MT cross-spectra stored in Spectra objects.

All plotting functions read visual defaults from the package-wide API singletons at call time, so a single configure_style() or use_style() call propagates here too.

Analysis#

coherence_matrix(sp)

Compute the inter-channel coherence matrix.

psd_table(sp_input, *[, normalize, api])

Power spectral density per channel as a tidy DataFrame.

coherence_table(sp_input, *[, pairs, api])

Inter-channel squared coherence as a tidy DataFrame.

snr_table(sp_input, *[, pairs, api])

Signal-to-noise ratio estimated from squared coherence.

band_select(sp, f_min, f_max)

Return a new Spectra restricted to the frequency band [f_min, f_max] Hz.

mask_low_coherence(sp, *[, pairs, ...])

Boolean mask of frequencies with sufficient coherence.

spectra_summary(sp, *[, api])

Compact per-frequency summary table.

Visualisation#

plot_psd(sp, *[, channels, log_psd, lw, ...])

Plot the power spectral density per channel.

plot_coherence(sp, *[, pairs, threshold, ...])

Plot squared coherence for selected channel pairs.

plot_spectra_matrix(sp, *[, freq_idx, ...])

Visualise the full cross-spectral density matrix at one frequency.

plot_z_from_spectra(sp, *[, e_labels, ...])

Plot apparent resistivity and phase recovered from spectra.

plot_tipper_from_spectra(sp, *[, h_labels, ...])

Plot the induction tipper magnitude and phase from spectra.

plot_psd_section(sp_input, *[, channel, ...])

Pseudo-section of PSD across stations (station × period).

plot_coherence_section(sp_input, *[, pair, ...])

Pseudo-section of coherence across stations (station × period).

Quick start#

from pycsamt.seg.spectra import Spectra
from pycsamt.emtools.spectra import (
    plot_psd, plot_coherence, plot_z_from_spectra,
    plot_tipper_from_spectra, coherence_table,
)

sp = Spectra.from_file("site.edi")

# power spectral density per channel
plot_psd(sp, title="HBH05-03 PSD")

# inter-channel coherence
plot_coherence(sp)

# apparent resistivity + phase recovered from spectra
plot_z_from_spectra(sp)

Functions

band_select(sp, f_min, f_max)

Return a new Spectra restricted to the frequency band [f_min, f_max] Hz.

coherence_matrix(sp)

Compute the inter-channel coherence matrix.

coherence_table(sp_input, *[, pairs, api])

Inter-channel squared coherence as a tidy DataFrame.

mask_low_coherence(sp, *[, pairs, ...])

Boolean mask of frequencies with sufficient coherence.

plot_coherence(sp, *[, pairs, threshold, ...])

Plot squared coherence for selected channel pairs.

plot_coherence_section(sp_input, *[, pair, ...])

Pseudo-section of coherence across stations (station × period).

plot_psd(sp, *[, channels, log_psd, lw, ...])

Plot the power spectral density per channel.

plot_psd_section(sp_input, *[, channel, ...])

Pseudo-section of PSD across stations (station × period).

plot_spectra_matrix(sp, *[, freq_idx, ...])

Visualise the full cross-spectral density matrix at one frequency.

plot_tipper_from_spectra(sp, *[, h_labels, ...])

Plot the induction tipper magnitude and phase from spectra.

plot_z_from_spectra(sp, *[, e_labels, ...])

Plot apparent resistivity and phase recovered from spectra.

psd_table(sp_input, *[, normalize, api])

Power spectral density per channel as a tidy DataFrame.

snr_table(sp_input, *[, pairs, api])

Signal-to-noise ratio estimated from squared coherence.

spectra_summary(sp, *[, api])

Compact per-frequency summary table.
pycsamt.emtools.spectra.coherence_matrix(sp)[source]#

Compute the inter-channel coherence matrix.

The squared coherence between channels i and j is:

\[\gamma^2_{ij}(f) = \frac{|S_{ij}(f)|^2}{S_{ii}(f)\,S_{jj}(f)}\]
Parameters:

sp (Spectra) – Cross-spectra container.

Returns:

coh – Real-valued coherence matrix per frequency, values in [0, 1].

Return type:

ndarray, shape (n_freq, n_chan, n_chan)

pycsamt.emtools.spectra.psd_table(sp_input, *, normalize=False, api=None)[source]#

Power spectral density per channel as a tidy DataFrame.

Parameters:

  • sp_input (Spectra or list/dict of Spectra) – One or more cross-spectra containers.

  • normalize (bool) – If True, normalise each channel’s PSD by its maximum value.

  • api (bool | None)

Returns:

Columns: station, freq, period, channel, psd.

Return type:

pd.DataFrame

pycsamt.emtools.spectra.coherence_table(sp_input, *, pairs=None, api=None)[source]#

Inter-channel squared coherence as a tidy DataFrame.

Parameters:

  • sp_input (Spectra or list/dict of Spectra)

  • pairs (list of (i, j), optional) – Channel index pairs. Default = all upper-triangle pairs.

  • api (bool | None)

Returns:

Columns: station, freq, period, ch_i, ch_j, pair, coherence.

Return type:

pd.DataFrame

pycsamt.emtools.spectra.snr_table(sp_input, *, pairs=None, api=None)[source]#

Signal-to-noise ratio estimated from squared coherence.

Uses the coherence-based estimator:

\[\text{SNR} = \frac{\gamma^2}{1 - \gamma^2}\]

with the dB version SNR_dB = 10 log₁₀(SNR).

Parameters:
Returns:

Columns: station, freq, period, pair, coherence, snr, snr_db.

Return type:

pd.DataFrame

pycsamt.emtools.spectra.band_select(sp, f_min, f_max)[source]#

Return a new Spectra restricted to the frequency band [f_min, f_max] Hz.

Parameters:

  • sp (Spectra)

  • f_min (float) – Frequency limits in Hz (inclusive).

  • f_max (float) – Frequency limits in Hz (inclusive).

Returns:

A shallow copy with arrays sliced to the band.

Return type:

Spectra

pycsamt.emtools.spectra.mask_low_coherence(sp, *, pairs=None, threshold=0.5, require_all=False)[source]#

Boolean mask of frequencies with sufficient coherence.

Parameters:

  • sp (Spectra)

  • pairs (list of (i, j), optional) – Pairs to evaluate. Default = all upper-triangle pairs.

  • threshold (float) – Minimum coherence required. Default 0.5.

  • require_all (bool) – If True, all requested pairs must exceed threshold. If False (default), at least one pair suffices.

Returns:

mask – True where coherence is acceptable.

Return type:

ndarray of bool, shape (n_freq,)

pycsamt.emtools.spectra.spectra_summary(sp, *, api=None)[source]#

Compact per-frequency summary table.

Columns: freq, period, bw, avgt, rotspec, plus the diagonal PSD and mean off-diagonal coherence for each channel.

Return type:

pd.DataFrame

Parameters:
pycsamt.emtools.spectra.plot_psd(sp, *, channels=None, log_psd=True, lw=<object object>, alpha=<object object>, title='', figsize=(9, 5), ax=None)[source]#

Plot the power spectral density per channel.

The x-axis follows PYCSAMT_CONTROL (log₁₀ period by default). Colours come from multiline.

Parameters:

  • sp (Spectra)

  • channels (sequence of int, optional) – Channel indices to plot. Default = all channels.

  • log_psd (bool) – Display log₁₀(PSD) when True.

  • lw (float) – Line width. Default: PYCSAMT_STYLE.multiline.lw.

  • alpha (float) – Line alpha. Default: PYCSAMT_STYLE.multiline.alpha.

  • title (str)

  • figsize ((float, float))

  • ax (Axes or None)

Returns:

ax

Return type:

Axes

pycsamt.emtools.spectra.plot_coherence(sp, *, pairs=None, threshold=0.5, show_threshold=True, lw=<object object>, alpha=<object object>, title='', axes=None, figsize=None)[source]#

Plot squared coherence for selected channel pairs.

Each pair gets its own sub-axis arranged in a grid. A dashed horizontal line marks threshold.

Parameters:

  • sp (Spectra)

  • pairs (list of (i, j), optional) – Default = all upper-triangle pairs.

  • threshold (float) – Quality threshold drawn as a dashed line. Default 0.5.

  • show_threshold (bool)

  • lw (float) – Style defaults from PYCSAMT_STYLE.multiline.

  • alpha (float) – Style defaults from PYCSAMT_STYLE.multiline.

  • title (str)

  • figsize ((float, float) or None) – Auto-computed from the number of pairs when None.

Returns:

axes

Return type:

ndarray of Axes, shape (n_pairs,)

pycsamt.emtools.spectra.plot_spectra_matrix(sp, *, freq_idx=0, quantity='abs', cmap=<object object>, log_scale=True, title='', ax=None, figsize=(7, 6))[source]#

Visualise the full cross-spectral density matrix at one frequency.

The matrix is drawn as a colour image. The diagonal shows auto- spectra (PSD); the upper and lower triangles show the magnitude (or real/imaginary part) of the cross-spectra.

Parameters:

  • sp (Spectra)

  • freq_idx (int) – Index into sp.freq for the frequency slice.

  • quantity ({'abs', 'real', 'imag', 'phase'}) – Quantity to colour.

  • cmap (str or _UNSET) – Colour map. Defaults to "viridis" (abs) or "RdBu_r" (real/imag/phase).

  • log_scale (bool) – Apply log₁₀ to the absolute value when quantity="abs".

  • title (str)

  • figsize ((float, float))

Returns:

fig

Return type:

Figure

pycsamt.emtools.spectra.plot_z_from_spectra(sp, *, e_labels=('EX', 'EY'), h_labels=('HX', 'HY'), ridge=None, estimate_error=False, show_error=True, title='', axes=None, figsize=(10, 5))[source]#

Plot apparent resistivity and phase recovered from spectra.

Calls to_Z() internally and renders the result with the standard MT component styling from PYCSAMT_STYLE.

Parameters:

  • sp (Spectra)

  • e_labels (tuple of str) – Channel type labels used for the E and H blocks in to_Z().

  • h_labels (tuple of str) – Channel type labels used for the E and H blocks in to_Z().

  • ridge (float or None) – Tikhonov regularization for S_HH inversion.

  • estimate_error (bool) – Estimate 1-σ errors in to_Z(). Default False (avoids DoF warnings when metadata is incomplete).

  • show_error (bool) – Shade error envelope when errors are available.

  • title (str)

  • figsize ((float, float))

Returns:

fig

Return type:

Figure

pycsamt.emtools.spectra.plot_tipper_from_spectra(sp, *, h_labels=('HX', 'HY'), ridge=None, estimate_error=False, show_error=True, title='', axes=None, figsize=(10, 5))[source]#

Plot the induction tipper magnitude and phase from spectra.

Displays the real and imaginary parts of T_x and T_y as well as their magnitudes on a two-panel figure (amplitude | phase).

Parameters:
Returns:

axes – [ax_amp, ax_phase]

Return type:

ndarray of Axes, shape (2,)

pycsamt.emtools.spectra.plot_psd_section(sp_input, *, channel=0, log_psd=True, cmap='viridis', vmin=None, vmax=None, section='pseudosection', title='', figsize=None, ax=None)[source]#

Pseudo-section of PSD across stations (station × period).

Interpolates all Spectra objects to a common log-spaced frequency grid before assembling the 2-D colour map.

Parameters:

  • sp_input (Spectra or list/dict of Spectra)

  • channel (int) – Channel index to display. Default 0.

  • log_psd (bool) – Colour log₁₀(PSD) when True.

  • cmap (str)

  • vmin (float or None)

  • vmax (float or None)

  • section (str or SectionStyle) – Layout preset from PYCSAMT_SECTION.

  • title (str)

  • figsize ((float, float) or None)

  • ax (Axes or None)

Returns:

ax

Return type:

Axes

pycsamt.emtools.spectra.plot_coherence_section(sp_input, *, pair=None, threshold=0.5, show_threshold=True, cmap='RdYlGn', section='pseudosection', title='', figsize=None, ax=None)[source]#

Pseudo-section of coherence across stations (station × period).

Parameters:

  • sp_input (Spectra or list/dict of Spectra)

  • pair ((int, int) or None) – Single channel pair (i, j) to display. When None the mean over all upper-triangle pairs is shown.

  • threshold (float) – Value shown by the shared colorbar. Default 0.5.

  • show_threshold (bool) – Add a contour at threshold when True.

  • cmap (str) – Default "RdYlGn" — red=low, green=high coherence.

  • section (str or SectionStyle)

  • title (str)

  • figsize ((float, float) or None)

  • ax (Axes or None)

Returns:

ax

Return type:

Axes