pycsamt.emtools.gradient_imaging

Gradient-based apparent resistivity pseudo-sections for CSAMT.

Implements the frequency-gradient, spatial-gradient, and joint frequency-spatial gradient apparent resistivity formulations proposed by:

zhang2021Zhang, Farquharson & Liu (2021), “Improved CSAMT apparent

resistivity pseudo sections based on the frequency and frequency-spatial gradients of electromagnetic fields”, Geophysical Prospecting, doi:10.1111/1365-2478.13059.

The three key gradient quantities are:

Transverse (along-line) gradient \(\Delta\rho_a^x\)

Finite difference of \(\rho_a\) between adjacent stations at each frequency.

Vertical (frequency) gradient \(\Delta\rho_a^z\)

Log-frequency finite difference of \(\rho_a\) at each station.

Joint vertical-transverse gradient \(\Delta\rho_a^{zx}\)

Frequency difference of the spatial gradient. This is the principal product of zhang2021: it suppresses background interference caused by the non-zero spatial gradient over homogeneous half-spaces and improves boundary delineation in pseudo-section images.

All three quantities are derived from the standard impedance-based \(\rho_a\), so no source moment or source–receiver geometry is required.

Functions

plot_gradient_section(sites[, quantity, ...])	Pseudo-section of a gradient apparent resistivity quantity.
rho_frequency_gradient(sites, *[, comp, ...])	Vertical (log-frequency) apparent resistivity gradient.
rho_joint_gradient(sites[, spacing_m, comp, ...])	Joint vertical-transverse apparent resistivity gradient.
rho_spatial_gradient(sites[, spacing_m, ...])	Transverse (along-line) apparent resistivity gradient.

pycsamt.emtools.gradient_imaging.rho_spatial_gradient(sites, spacing_m=200.0, *, comp='det', recursive=True, on_dup='replace', strict=False, verbose=0)

Transverse (along-line) apparent resistivity gradient.

Computes the first-order finite difference of \(\rho_a\) between adjacent stations at each frequency (eq. 11 of zhang2021):

\[\Delta\rho_a^x(j,\,f) \approx \rho_a(j,\,f) - \rho_a(j-1,\,f)\]

where station indices are ordered by their position along the survey line. The result is assigned to the spatial midpoint between the two stations.

Parameters:

• sites (Sites | list) – EDI-like objects or a Sites container.

• spacing_m (float, default 200) – Fall-back inter-station spacing [m] used when no coordinate metadata is available.

• comp ({"det", "xy", "yx"}, default "det") – Impedance component for \(\rho_a\). "det" uses the geometric-mean determinant.

• 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().

Returns:

One row per (station-pair, frequency). Columns:

station_a, station_b

Names of the left and right stations of each pair.

x_m

Midpoint position along the survey line [m].

dx_m

Spacing between the two stations [m].

freq_hz, period_s

Frequency [Hz] and period [s].

depth_m

Skin depth \(\delta = 503\,\sqrt{\rho_a/f}\) [m] at the midpoint \(\rho_a\) and the given frequency.

rho_a_ohmm

Mean \(\rho_a\) of the pair at that frequency [Ω·m].

delta_rho_x

\(\Delta\rho_a^x\) [Ω·m].

Return type:

pandas.DataFrame

References

Zhang et al. (2021), eq. (11).

pycsamt.emtools.gradient_imaging.rho_frequency_gradient(sites, *, comp='det', spacing_m=200.0, recursive=True, on_dup='replace', strict=False, verbose=0)

Vertical (log-frequency) apparent resistivity gradient.

Computes the first-order finite difference of \(\rho_a\) between adjacent frequencies at each station (eq. 12 of zhang2021):

\[\Delta\rho_a^z(j,\,f_k) \approx \rho_a(j,\,f_k) - \rho_a(j,\,f_{k-1})\]

where \(f_k > f_{k-1}\) (ascending frequency, ascending skin-depth index). Because different frequencies probe different depths, \(\Delta\rho_a^z\) is associated with vertical changes in the subsurface.

Parameters:

• sites (Sites | list) – EDI-like objects or a Sites container.

• comp ({"det", "xy", "yx"}, default "det") – Impedance component for \(\rho_a\).

• spacing_m (float, default 200) – Fall-back inter-station spacing [m].

• 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().

Returns:

One row per (station, adjacent-frequency pair). Columns:

station

Station name.

x_m

Station position along the survey line [m].

freq_hz, period_s

Higher frequency \(f_k\) of the pair [Hz] and its corresponding period [s].

depth_m

Skin depth at the mean \(\rho_a\) of the pair [m].

rho_a_ohmm

Mean \(\rho_a\) of the two adjacent frequencies [Ω·m].

delta_rho_z

\(\Delta\rho_a^z\) [Ω·m].

Return type:

pandas.DataFrame

References

Zhang et al. (2021), eq. (12).

pycsamt.emtools.gradient_imaging.rho_joint_gradient(sites, spacing_m=200.0, *, comp='det', recursive=True, on_dup='replace', strict=False, verbose=0)

Joint vertical-transverse apparent resistivity gradient.

Computes the frequency difference of the spatial gradient (eq. 13 of zhang2021), which simultaneously resolves lateral and vertical boundaries while suppressing the spurious background interference in the spatial gradient over homogeneous regions:

\[\Delta\rho_a^{zx}(j,\,f_k) = \Delta\rho_a^x(j,\,f_k) - \Delta\rho_a^x(j,\,f_{k-1})\]

Expanding in terms of \(\rho_a\):

\[\Delta\rho_a^{zx}(j,\,f_k) = \bigl[\rho_a(j,\,f_k) - \rho_a(j-1,\,f_k)\bigr] - \bigl[\rho_a(j,\,f_{k-1}) - \rho_a(j-1,\,f_{k-1})\bigr]\]

where station j is to the right of station j-1 along the survey line and \(f_k > f_{k-1}\).

The result is non-zero only where \(\rho_a\) changes in both the lateral and vertical directions simultaneously, making it a sensitive indicator of target boundaries.

Parameters:

• sites (Sites | list) – EDI-like objects or a Sites container.

• spacing_m (float, default 200) – Fall-back inter-station spacing [m].

• comp ({"det", "xy", "yx"}, default "det") – Impedance component for \(\rho_a\).

• 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().

Returns:

One row per (station-pair, adjacent-frequency pair). Columns:

station_a, station_b

Names of the left and right stations of each pair.

x_m

Midpoint position along the survey line [m].

dx_m

Spacing between the two stations [m].

freq_hz, period_s

Upper frequency \(f_k\) of the pair [Hz] and period [s].

depth_m

Skin depth [m] estimated from the median \(\rho_a\) of the four surrounding cells and the frequency \(f_k\).

delta_rho_zx

\(\Delta\rho_a^{zx}\) [Ω·m].

Return type:

pandas.DataFrame

References

Zhang et al. (2021), eqs. (1), (11), (13).

pycsamt.emtools.gradient_imaging.plot_gradient_section(sites, quantity='joint', spacing_m=200.0, *, comp='det', period_axis=True, log_y=True, figsize=(10.0, 5.0), cmap='RdBu_r', vlim=None, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)

Pseudo-section of a gradient apparent resistivity quantity.

Produces a colour-coded pseudo-section (position × period or frequency) for one of three gradient quantities from zhang2021:

• "spatial" (\(\Delta\rho_a^x\)) — lateral boundaries.

• "frequency" (\(\Delta\rho_a^z\)) — vertical boundaries.

• "joint" (\(\Delta\rho_a^{zx}\)) — combined; best boundary delineation and suppressed background interference (default).

A diverging colour-map centred at zero is used so that positive and negative gradient values (resistivity increase vs. decrease) can be distinguished at a glance.

Parameters:

• sites (Sites | list) – EDI-like objects or a Sites container.

• quantity ({"joint", "spatial", "frequency"}, default "joint") – Which gradient pseudo-section to plot.

• spacing_m (float, default 200) – Fall-back inter-station spacing [m].

• comp ({"det", "xy", "yx"}, default "det") – Impedance component for \(\rho_a\).

• period_axis (bool, default True) – Show period [s] on the y-axis when True; frequency [Hz] when False.

• log_y (bool, default True) – Use a logarithmic y-axis.

• figsize ((float, float), default (10, 5))

• cmap (str, default "RdBu_r") – Diverging Matplotlib colour-map.

• vlim ((vmin, vmax) or None) – Colour-scale limits [Ω·m]. If None, a symmetric range centred at zero is derived from the data.

• ax (matplotlib.axes.Axes or None) – Draw on existing axes; a new figure is created if None.

• 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().

Return type:

matplotlib.axes.Axes

References

Zhang et al. (2021), Geophysical Prospecting, doi:10.1111/1365-2478.13059.