pycsamt.emtools.ss<a class="headerlink" href="#module-pycsamt.emtools.ss" title="Link to this heading">#

See also

correct_ss_ama: estimate + apply in one call.
apply_ss_factors: apply a pre-built table.

Examples

from pycsamt.api import read_edis
from pycsamt.emtools.ss import (
    estimate_ss_ama,
)
survey = read_edis("L22PLT/")
sites  = survey.collection
tbl = estimate_ss_ama(
    sites,
    half_window=3,
    sort_by="lon",
)
print(
    tbl[[
        "station",
        "delta_log10_rho",
        "fac_z",
    ]]
)

pycsamt.emtools.ss.apply_ss_factors(sites, factors, *, key='fac_z', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Apply pre-computed static-shift correction factors to sites.

Scales each site’s impedance tensor Z by a per-station correction factor from a table (e.g. from estimate_ss_ama(), estimate_ss_loess(), etc.) or dictionary.

Parameters:

sites (any) – EDI data source accepted by ensure_sites().
factors (dict or pandas.DataFrame) – If DataFrame, must contain 'station' and key columns. If dict, maps station names to correction factors.
key (str, default 'fac_z') – Column name or dict key holding the impedance scaling factors. Common choices are 'fac_z' (impedance) or 'fac_rho' (resistivity).
inplace (bool, default False) – Modify the input Sites object. When False, a corrected copy is returned.
recursive (bool, default True) – Recursive EDI directory search.
on_dup (str, default 'replace') – Duplicate-station resolution.
strict (bool, default False) – Raise on EDI parse errors.
verbose (int, default 0) – Verbosity level.

Returns:

Corrected Sites object (same type as input). When inplace is True the original is modified and returned.

Return type:

Sites

See also

estimate_ss_ama: Estimate factors via AMA.
estimate_ss_loess: Estimate factors via LOESS.

pycsamt.emtools.ss.correct_ss_ama(sites, *, sort_by='lon', half_window=3, weights='tri', pband=None, max_skew=6.0, robust_freq='median', robust_overall='median', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Correct static shift by the AMA method.

Estimates per-station log10-resistivity shift factors with estimate_ss_ama(), then scales each site’s impedance tensor Z by the corresponding fac_z column.

Parameters:

sites (Sites, str, Path, list, EDICollection) – EDI data source.
sort_by (str, default 'lon') – Along-line order axis for AMA estimation.
half_window (int, default 3) – Neighbours on each side of the target.
weights (str, default 'tri') – Spatial weight scheme ('tri', 'gauss', or 'uniform').
pband (tuple of float or None) – Period band (p_min_s, p_max_s) in seconds.
max_skew (float or None, default 6.0) – Phase-tensor skew exclusion threshold.
robust_freq (str, default 'median') – Neighbour aggregation per frequency.
robust_overall (str, default 'median') – Reduce per-frequency deltas to a scalar.
inplace (bool, default False) – Modify the input Sites object in place. When False, returns a corrected copy.
recursive (bool, default True) – Recursive EDI directory search.
on_dup (str, default 'replace') – Duplicate-station resolution.
strict (bool, default False) – Raise on EDI parse errors.
verbose (int, default 0) – Verbosity level.

Returns:

Corrected Sites object (same type as input). When inplace is True the original object is modified and returned.

Return type:

Sites

See also

estimate_ss_ama: inspect factors before apply.
apply_ss_factors: apply a custom factor table.

Examples

from pycsamt.api import read_edis
from pycsamt.emtools.ss import (
    correct_ss_ama,
)
survey     = read_edis("L22PLT/")
sites      = survey.collection
sites_corr = correct_ss_ama(
    sites,
    half_window=3,
    sort_by="lon",
)

pycsamt.emtools.ss.estimate_ss_loess(sites, *, half_window=3, poly=1, it=2, pband=None, max_skew=6.0, summary='median', recursive=True, on_dup='replace', strict=False, verbose=0, api=None)[source]#

Estimate static-shift factors via locally-weighted regression (LOESS).

Fits a local polynomial trend across neighbouring stations in the along-line direction, then returns the per-station deviation from that trend as correction factors.

Parameters:

sites (Sites, str, Path, list, EDICollection) – EDI data source accepted by ensure_sites().
half_window (int, default 3) – Neighbours on each side of the target.
poly (int, default 1) – Polynomial degree (0=constant, 1=linear).
it (int, default 2) – Robust iteration count.
pband (tuple of float or None) – Period band $(p_{min}, p_{max})$ in seconds. None uses all periods.
max_skew (float or None, default 6.0) – Phase-tensor skew threshold. Points where :math:`|\\beta| > ` max_skew are excluded.
summary (str, default 'median') – Per-station aggregation: 'median' or 'mean'.
recursive (bool, default True) – Recursive EDI directory search.
on_dup (str, default 'replace') – Duplicate-station resolution.
strict (bool, default False) – Raise on EDI parse errors.
verbose (int, default 0) – Verbosity level.
api (bool or None) – Return an APIFrame when True.

Returns:

One row per station with columns: station, delta_log10_rho, fac_rho, fac_z, n_used.

Return type:

See also

estimate_ss_ama: AMA (moving average) method.
estimate_ss_bilateral: Bilateral filtering method.

pycsamt.emtools.ss.estimate_ss_bilateral(sites, *, half_window=4, sig_dist=None, sig_val=None, pband=None, max_skew=6.0, summary='median', recursive=True, on_dup='replace', strict=False, verbose=0, api=None)[source]#

Estimate static-shift factors via bilateral filtering.

Applies a combined spatial and range-based Gaussian filter (bilateral filter) to compute a local trend, then returns per-station deviations as correction factors.

Parameters:

sites (Sites, str, Path, list, EDICollection) – EDI data source accepted by ensure_sites().
half_window (int, default 4) – Spatial window (neighbours each side).
sig_dist (float or None) – Spatial Gaussian width (in index units). When None, defaults to $0.5 \\times \\texttt{half\\_window}$.
sig_val (float or None) – Range (value) Gaussian width. When None, estimated from data.
pband (tuple of float or None) – Period band $(p_{min}, p_{max})$ in seconds.
max_skew (float or None, default 6.0) – Phase-tensor skew threshold.
summary (str, default 'median') – Aggregation: 'median' or 'mean'.
recursive (bool) – Forwarded to ensure_sites().
on_dup (str) – Forwarded to ensure_sites().
strict (bool) – Forwarded to ensure_sites().
verbose (int) – Forwarded to ensure_sites().
api (bool or None) – Return an APIFrame when True.

Returns:

One row per station with columns: station, delta_log10_rho, fac_rho, fac_z, n_used.

Return type:

See also

estimate_ss_ama: Moving-average method.
estimate_ss_loess: Local polynomial method.

pycsamt.emtools.ss.estimate_ss_refmedian(sites, *, pband=None, max_skew=6.0, smooth_sites=0, summary='median', recursive=True, on_dup='replace', strict=False, verbose=0, api=None)[source]#

Estimate static-shift factors via reference-median method.

Computes a global frequency-wise median resistivity across all stations, then estimates per-station shifts as deviations from this reference curve.

Parameters:

sites (Sites, str, Path, list, EDICollection) – EDI data source.
pband (tuple of float or None) – Period band $(p_{min}, p_{max})$ in seconds.
max_skew (float or None, default 6.0) – Phase-tensor skew threshold.
smooth_sites (int, default 0) – Optional smoothing window (reserved for future use).
summary (str, default 'median') – Aggregation: 'median' or 'mean'.
recursive (bool) – Forwarded to ensure_sites().
on_dup (str) – Forwarded to ensure_sites().
strict (bool) – Forwarded to ensure_sites().
verbose (int) – Forwarded to ensure_sites().
api (bool or None) – Return an APIFrame when True.

Returns:

One row per station with columns: station, delta_log10_rho, fac_rho, fac_z, n_used.

Return type:

See also

estimate_ss_ama: Moving-average method.
estimate_ss_loess: Local polynomial method.

pycsamt.emtools.ss.plot_ss_delta_psection(before, after, *, axis_y='logperiod', vlim=None, pband=None, figsize=(9.0, 4.8), verbose=0, ax=None)[source]#

Plot pseudosection of static-shift change (corrected minus original).

Displays a heatmap showing the pointwise difference $\Delta\log_{10}\rho = \rho_{after} - \rho_{before}$ across all stations and frequencies on a log-period y-axis.

Parameters:

before (any) – EDI data source (uncorrected sites).
after (any) – EDI data source (corrected sites).
axis_y (str, default 'logperiod') – Y-axis scale: 'logperiod' or 'period'.
vlim (float or None) – Symmetric colour range $\pm \texttt{vlim}$. When None, auto-scales from data.
pband (tuple of float or None) – Period band $(p_{min}, p_{max})$ in seconds.
figsize ((float, float), default (9, 4.8)) – Figure size.
verbose (int, default 0) – Verbosity level.
ax (matplotlib.axes.Axes or None) – Draw on existing axes.

Return type:

pycsamt.emtools.ss.plot_ss_station_curves(before, after, *, station=None, pband=None, figsize=(7.8, 4.2), verbose=0, ax=None)[source]#

Plot before-and-after apparent-resistivity curves for a single station.

Overlays two 1-D sounding curves (before correction and after correction) on a period x-axis to visualize the magnitude and frequency-dependence of the correction at one location.

Parameters:

before (any) – Uncorrected EDI data.
after (any) – Corrected EDI data.
station (str or None) – Station identifier. When None, the first common station is used.
pband (tuple of float or None) – Period band $(p_{min}, p_{max})$ in seconds.
figsize ((float, float), default (7.8, 4.2)) – Figure size.
verbose (int, default 0) – Verbosity level.
ax (matplotlib.axes.Axes or None) – Draw on existing axes.

Return type:

pycsamt.emtools.ss.plot_ss_delta_profile(before, after, *, pband=None, robust='median', figsize=(8.6, 3.6), verbose=0, ax=None)[source]#

Plot per-station static-shift correction amplitudes as a bar chart.

Shows the median (or mean) of the frequency-dependent correction $\Delta\log_{10}\rho$ at each station, making it easy to identify spatial patterns in the applied corrections.

Parameters:

before (any) – Uncorrected EDI data.
after (any) – Corrected EDI data.
pband (tuple of float or None) – Period band $(p_{min}, p_{max})$ in seconds.
robust (str, default 'median') – Aggregation method: 'median' or 'mean'.
figsize ((float, float), default (8.6, 3.6)) – Figure size.
verbose (int, default 0) – Verbosity level.
ax (matplotlib.axes.Axes or None) – Draw on existing axes.

Return type:

pycsamt.emtools.ss.plot_ss_comparison_psection(logRho_before, logRho_after, *, freqs, station_labels=None, show_delta=True, cmap='RdYlBu_r', delta_cmap='RdBu_r', clim=None, clim_pct=(2.0, 98.0), delta_vlim=None, delta_vlim_pct=95.0, period_up=True, title_before='(a) Before static-shift correction', title_after='(b) After static-shift correction', title_delta='(c) Correction amplitude $\\Delta\\log_{10}\\rho$', suptitle='', xlabel='Station', ylabel='Period (s)', n_yticks=7, colorbar_label='$\\log_{10}\\,\\rho_a$ (Ω·m)', delta_colorbar_label='$\\Delta\\log_{10}\\rho$', tick_label_rotation=45.0, tick_fontsize=7, figsize=None, axes=None)[source]#

Two- or three-panel pseudo-section comparison for static-shift correction.

The before and after panels share a colour scale so that the station-dependent vertical offsets are directly visible. The optional third panel shows the pointwise difference Δ log₁₀ ρ = after − before on a diverging scale, making the spatial pattern of the correction explicit.

Parameters:

logRho_before (ndarray, shape (n_st, n_f)) – Log₁₀ apparent resistivity before static-shift correction (Ω·m).
logRho_after (ndarray, shape (n_st, n_f)) – Log₁₀ apparent resistivity after static-shift correction (Ω·m).
freqs (ndarray, shape (n_f,)) – Frequency array in Hz. Need not be sorted.
station_labels (list of str or None) – X-axis tick labels. Defaults to "0", "1", ….
show_delta (bool, default True) – Append a third panel showing Δ log₁₀ ρ.
cmap (str, default "RdYlBu_r") – Colormap for the before/after panels.
delta_cmap (str, default "RdBu_r") – Diverging colormap for the Δ panel.
clim ((vmin, vmax) or None) – Explicit colour limits (log₁₀ Ω·m) shared by the before/after panels.
clim_pct ((lo, hi), default (2.0, 98.0)) – Percentile bounds for automatic clim.
delta_vlim (float or None) – Symmetric limit (−δ, +δ) for the Δ panel. When None, derived from delta_vlim_pct of |Δ|.
delta_vlim_pct (float, default 95.0)
period_up (bool, default True) – Long period at the top of each panel (MT convention).
title_before (str) – Per-panel titles. Pass "" to suppress.
title_after (str) – Per-panel titles. Pass "" to suppress.
title_delta (str) – Per-panel titles. Pass "" to suppress.
suptitle (str) – Figure-level title.
xlabel (str) – Axis labels.
ylabel (str) – Axis labels.
n_yticks (int, default 7) – Number of log-period y-ticks.
colorbar_label (str)
delta_colorbar_label (str)
tick_label_rotation (float, default 45.0) – Station tick rotation (degrees).
tick_fontsize (int, default 7)
figsize ((w, h) or None) – Override automatic size.
axes (sequence of Axes or None) – Pre-created axes (length 2 without delta, 3 with).

Returns:

fig

Return type:

pycsamt.emtools.ss.plot_ss_1d_curves(logRho_before, logRho_after, *, freqs, stations=None, station_labels=None, n_cols=4, max_stations=16, color_before=<object object>, color_after=<object object>, ls_before=<object object>, ls_after=<object object>, marker_before=<object object>, marker_after=<object object>, marker_size=<object object>, lw=<object object>, log_period=True, show_shift_annotation=True, annotation_fontsize=7, ylabel='$\\log_{10}\\, \\rho_a$ (Ω·m)', xlabel='Period (s)', axes=None, figsize=None, title='', legend_loc='best', show_grid=True)[source]#

Per-station 1-D apparent-resistivity curves: before and after correction.

Lays out a grid of subplots (one per selected station) each showing the before/after sounding curves on a period x-axis. A small annotation reports the mean correction amplitude Δ per station, making it easy to spot outliers.

Parameters:

logRho_before (ndarray, shape (n_st, n_f))
logRho_after (ndarray, shape (n_st, n_f))
freqs (ndarray, shape (n_f,) Hz.)
stations (list of int, list of str, or None) – Stations to display. Integers are row indices into logRho_before. Strings are matched against station_labels. None → all stations, capped at max_stations.
station_labels (list of str or None) – Label for each row. Defaults to "0", "1", ….
n_cols (int, default 4) – Subplot grid columns.
max_stations (int, default 16) – Cap when stations is None.
color_before (str, default "#2c7bb6" (blue))
color_after (str, default "#d7191c" (red))
ls_before (str, default "--")
ls_after (str, default "-")
marker_before (str)
marker_after (str)
marker_size (float, default 3.0)
lw (float, default 1.2)
log_period (bool, default True) – Log-scale period x-axis.
show_shift_annotation (bool, default True) – Print mean Δ log₁₀ ρ in the lower-right corner of each subplot.
annotation_fontsize (int, default 7)
ylabel (str)
xlabel (str)
figsize ((w, h) or None)
title (str) – Figure-level title.
legend_loc (str, default "best") – Legend location (first subplot only).
show_grid (bool, default True)

Returns:

fig

Return type:

pycsamt.emtools.ss.plot_ss_summary(logRho_before, logRho_after, *, freqs, station_labels=None, cmap='RdYlBu_r', delta_cmap='RdBu_r', clim=None, clim_pct=(2.0, 98.0), delta_vlim=None, delta_vlim_pct=95.0, period_up=True, n_yticks=7, tick_label_rotation=45.0, tick_fontsize=7, colorbar_label='$\\log_{10}\\,\\rho_a$ (Ω·m)', shift_bar_color='#4c72b0', shift_bar_neg_color='#c44e52', shift_robust='median', suptitle='', axes=None, figsize=None)[source]#

Four-panel summary figure for static-shift correction.

Layout:

┌──────────────┬──────────────┐
│  (a) Before  │  (b) After   │  shared y-axis · shared colorbar
├──────────────┴──────────────┤
│  (c) Δ log₁₀ ρ section     │  diverging colorbar
├──────────────────────────── ┤
│  (d) Per-station shift bar  │  positive/negative coloured bars
└─────────────────────────────┘

Parameters:

logRho_before (ndarray, shape (n_st, n_f))
logRho_after (ndarray, shape (n_st, n_f))
freqs (ndarray, shape (n_f,) Hz.)
station_labels (list of str or None) – X-axis tick labels for all panels.
cmap (str, default "RdYlBu_r")
delta_cmap (str, default "RdBu_r")
clim (see plot_ss_comparison_psection().)
clim_pct (see plot_ss_comparison_psection().)
delta_vlim (see plot_ss_comparison_psection().)
delta_vlim_pct (see plot_ss_comparison_psection().)
period_up (bool, default True)
n_yticks (int, default 7)
tick_label_rotation (float, default 45.0)
tick_fontsize (int, default 7)
colorbar_label (str)
shift_bar_color (str) – Bar colour for positive per-station shifts (default blue).
shift_bar_neg_color (str) – Bar colour for negative shifts (default red).
shift_robust ("median" | "mean") – Aggregation used to reduce per-frequency shifts to a scalar per station for panel (d).
suptitle (str) – Figure-level title.
figsize ((w, h) or None)

Returns:

fig

Return type:

pycsamt.emtools.ss.ss_qc_psection(sites, *, method='ama', return_sites=False, axis_y='logperiod', vlim=None, pband=None, figsize=(9.0, 4.8), verbose=0, ax=None, **corr)[source]#

Estimate static-shift correction and plot delta pseudosection.

Combines automatic static-shift estimation with a heatmap visualization in one call. A convenience wrapper around a correction estimator and plot_ss_delta_psection().

Parameters:

sites (any) – EDI paths or Sites.
method (str, default 'ama') – Correction method: 'ama', 'loess', 'bilateral', or 'refmedian'.
return_sites (bool, default False) – When True, return (ax, corrected_sites).
axis_y (str) – Forwarded to plot_ss_delta_psection().
vlim (float | None) – Forwarded to plot_ss_delta_psection().
pband (tuple[float, float] | None) – Forwarded to plot_ss_delta_psection().
figsize (tuple[float, float]) – Forwarded to plot_ss_delta_psection().
verbose (int, default 0) – Verbosity level.
ax (matplotlib.axes.Axes or None) – Draw on existing axes.
**corr – Forwarded to the correction estimator.

Return type:

matplotlib.axes.Axes or (Axes, Sites)

pycsamt.emtools.ss.ss_qc_station_curves(sites, *, method='ama', station=None, return_sites=False, pband=None, figsize=(7.8, 4.2), verbose=0, ax=None, **corr)[source]#

Estimate correction and plot before/after curves for one station.

A convenience wrapper combining automatic static-shift estimation with 1-D curve visualization.

Parameters:

sites (any) – EDI paths or Sites object.
method (str, default 'ama') – Correction method.
station (str or None) – Station identifier. When None, uses the first.
return_sites (bool, default False) – When True, return (ax, corrected_sites).
pband (tuple[float, float] | None) – Forwarded to plot_ss_station_curves().
figsize (tuple[float, float]) – Forwarded to plot_ss_station_curves().
verbose (int) – Forwarded to plot_ss_station_curves().
ax (Axes | None) – Forwarded to plot_ss_station_curves().
**corr (Any) – Forwarded to the correction estimator.

Return type:

matplotlib.axes.Axes or (Axes, Sites)

pycsamt.emtools.ss.ss_qc_profile(sites, *, method='ama', return_sites=False, pband=None, robust='median', figsize=(8.6, 3.6), verbose=0, ax=None, **corr)[source]#

Estimate correction and plot per-station shift profile.

A convenience wrapper for automatic static-shift estimation with bar-chart visualization of the per-station amplitudes.

Parameters:

sites (any) – EDI paths or Sites object.
method (str, default 'ama') – Correction method.
return_sites (bool, default False) – When True, return (ax, corrected_sites).
pband (tuple[float, float] | None) – Forwarded to plot_ss_delta_profile().
robust (str) – Forwarded to plot_ss_delta_profile().
figsize (tuple[float, float]) – Forwarded to plot_ss_delta_profile().
verbose (int) – Forwarded to plot_ss_delta_profile().
ax (Axes | None) – Forwarded to plot_ss_delta_profile().
**corr (Any) – Forwarded to the correction estimator.

Return type:

matplotlib.axes.Axes or (Axes, Sites)

pycsamt.emtools.ss.ss_comparison_psection(sites, *, method='ama', return_sites=False, station_labels=None, show_delta=True, cmap='RdYlBu_r', delta_cmap='RdBu_r', clim=None, clim_pct=(2.0, 98.0), delta_vlim=None, delta_vlim_pct=95.0, period_up=True, suptitle='', tick_label_rotation=45.0, tick_fontsize=7, figsize=None, verbose=0, **corr)[source]#

Correct sites for static shift and plot a comparison pseudo-section.

A convenience wrapper that combines correct_ss_ama() (or the chosen method) with plot_ss_comparison_psection().

Parameters:

sites (any) – EDI paths, glob pattern, or Sites accepted by ensure_sites().
method ("ama" | "loess" | "bilateral" | "refmedian") – Static-shift estimator.
return_sites (bool, default False) – When True, return (fig, corrected_sites) instead of fig.
**corr (Any) – Forwarded to the correction estimator.
station_labels (list[str] | None)
show_delta (bool)
cmap (str)
delta_cmap (str)
clim (tuple[float, float] | None)
clim_pct (tuple[float, float])
delta_vlim (float | None)
delta_vlim_pct (float)
period_up (bool)
suptitle (str)
tick_label_rotation (float)
tick_fontsize (int)
figsize (tuple[float, float] | None)
verbose (int)
**corr

Returns:

fig – Or (fig, corrected_sites) when return_sites is True.

Return type:

See also

plot_ss_comparison_psection: Lower-level function that accepts pre-built arrays directly.

pycsamt.emtools.ss.plot_ss_radar(sites, *, station=None, pband=None, rotate='pt', rotate_stat='median', rotate_deg=0.0, radial='log10rho', theta_axis='logperiod', fill_between=False, colors=<object object>, marker=<object object>, ms=<object object>, lw=<object object>, ls=<object object>, figsize=(4.8, 4.8), recursive=True, on_dup='replace', strict=False, verbose=0, eps=1e-24, ax=None)[source]#

Plot apparent resistivity against period on a polar grid.

Displays the off-diagonal impedance components (xy and yx) as radial curves on a polar coordinate system, where the azimuthal angle encodes frequency (or period) and the radius encodes resistivity magnitude. Useful for detecting anisotropy and strike angles across the full frequency spectrum.

Parameters:

sites (any) – EDI data source.
station (str or None) – Station identifier. When None, uses the first.
pband (tuple of float or None) – Period band $(p_{min}, p_{max})$ in seconds.
rotate (str, default 'pt') – Rotation mode: 'pt' (phase-tensor strike), 'deg' (fixed angle), or 'none' (no rotation).
rotate_stat (str, default 'median') – Per-frequency aggregation for phase-tensor rotation.
rotate_deg (float, default 0.0) – Fixed rotation angle (degrees) when rotate=’deg’.
radial (str, default 'log10rho') – Radial scale: 'log10rho' (log base 10 of apparent resistivity) or 'rho' (linear resistivity).
theta_axis (str, default 'logperiod') – Angular axis: 'logperiod', 'period', or 'freq' (Hz).
fill_between (bool, default False) – Shade the region between xy and yx curves.
colors (tuple or _UNSET) – (color_xy, color_yx). Defaults from style.
marker (_UNSET or values) – Line and marker style. Defaults from style.
ms (_UNSET or values) – Line and marker style. Defaults from style.
lw (_UNSET or values) – Line and marker style. Defaults from style.
ls (_UNSET or values) – Line and marker style. Defaults from style.
figsize ((float, float), default (4.8, 4.8)) – Figure size.
recursive (bool) – Forwarded to ensure_sites().
on_dup (str) – Forwarded to ensure_sites().
strict (bool) – Forwarded to ensure_sites().
verbose (int) – Forwarded to ensure_sites().
eps (float, default 1e-24) – Numerical floor to avoid division by zero.
ax (matplotlib.axes.Axes or None) – Draw on existing axes (auto-creates polar if needed).

Returns:

Polar axes object.

Return type:

pycsamt.emtools.ss.detect_near_surface(sites, *, f_split=1.0, pband=None, ns_threshold=2.0, ss_threshold=0.1, sort_by='lon', half_window=3, weights='tri', max_skew=6.0, recursive=True, on_dup='replace', strict=False, verbose=0, api=None)[source]#

Detect and classify near-surface distortion in CSAMT/MT apparent resistivity curves.

Distinguishes between two types of distortion:

Static effect — frequency-independent multiplicative shift of the whole ρ_a curve. Addressable by AMA/LOESS static-shift correction.
Near-surface effect — frequency-dependent distortion concentrated at high frequencies (f ≥ f_split), caused by shallow inhomogeneities. Not correctable by conventional static-shift methods; 2-D inversion is recommended.

Three per-station diagnostics are computed from the residuals of the ρ_a curve relative to an AMA spatial trend:

NS index η = σ_HF / σ_LF — spread ratio between the high-frequency (f ≥ f_split) and low-frequency bands. η >> 1 is the hallmark of near-surface contamination.
Gradient delta Δγ = |slope_HF − slope_LF| — absolute difference of the log-log slope d(log ρ_a)/d(log f) between the two bands.
Static shift δ = median(log10 ρ_a − AMA trend) — classic AMA shift estimate over the full frequency range.

Classification:

`"clean"`	η ≤ ns_threshold, \|δ\| ≤ ss_threshold
`"static"`	η ≤ ns_threshold, \|δ\| > ss_threshold
`"near_surface"`	η > ns_threshold, \|δ\| ≤ ss_threshold
`"mixed"`	η > ns_threshold, \|δ\| > ss_threshold

Parameters:

sites (path, EDI-like, Sites, or iterable) – Any input accepted by ensure_sites().
f_split (float, default=1.0) – Frequency boundary in Hz separating the HF (f ≥ f_split) from the LF (f < f_split) band.
pband ((float, float) or None) – Period band (lo_s, hi_s) pre-filter applied before all computations.
ns_threshold (float, default=2.0) – η > this → near-surface flag.
ss_threshold (float, default=0.1) – |δ| > this (log10 units) → static-shift flag.
sort_by ({"lon", "lat", "name"}, default="lon") – Station ordering for the AMA spatial trend.
half_window (int, default=3) – Number of neighbouring stations each side in the AMA trend.
weights ({"tri", "gauss", "uniform"}, default="tri") – Spatial weighting for the AMA trend.
max_skew (float or None, default=6.0) – Phase-tensor skew ceiling; data above this are excluded.
recursive (bool) – Forwarded to ensure_sites().
on_dup (str) – Forwarded to ensure_sites().
strict (bool) – Forwarded to ensure_sites().
verbose (int) – Forwarded to ensure_sites().
api (bool | None)

Returns:

One row per station with columns: station, n_hf, n_lf, sigma_hf, sigma_lf, ns_index, slope_hf, slope_lf, gradient_delta, ss_delta_log10, ns_flag, ss_flag, distortion_type.

Return type:

References

Lei et al. (2017), “The non-static effect of near-surface inhomogeneity on CSAMT data”, Geophysics.

pycsamt.emtools.ss.plot_ns_detection(sites, *, f_split=1.0, pband=None, ns_threshold=2.0, ss_threshold=0.1, sort_by='lon', half_window=3, weights='tri', max_skew=6.0, show_ss=True, figsize=(9.0, 4.5), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Bar chart of the NS index per station, colored by distortion type.

Each bar height is η = σ_HF / σ_LF. A dashed line marks ns_threshold. An optional secondary y-axis shows the static-shift estimate δ (log10 units) as a stem plot.

Parameters:

sites (path, EDI-like, Sites, or iterable)
f_split (float, default=1.0) – HF/LF split frequency in Hz.
pband ((float, float) or None)
ns_threshold (float)
ss_threshold (float)
sort_by ({"lon", "lat", "name"})
half_window (int) – Forwarded to detect_near_surface().
weights (str) – Forwarded to detect_near_surface().
max_skew (float | None) – Forwarded to detect_near_surface().
show_ss (bool, default=True) – If True and ax has room, overlay static-shift δ as a grey stem plot on a secondary y-axis.
figsize ((float, float), default=(9, 4.5))
recursive (bool) – Forwarded to ensure_sites().
on_dup (str) – Forwarded to ensure_sites().
strict (bool) – Forwarded to ensure_sites().
verbose (int) – Forwarded to ensure_sites().
ax (matplotlib.axes.Axes, optional) – Draw on existing axes.

Return type: