pycsamt.emtools.fieldzone#

Functions

classify_field_zones(sites[, source_offset, ...])

Classify CSAMT measurement zones per station per frequency.

near_field_factor(sites[, source_offset, ...])

Near-field correction factor for apparent resistivity (equatorial HED).

plot_field_zones(sites[, source_offset, ...])

Pseudosection of CSAMT field zones across stations and frequencies.
pycsamt.emtools.fieldzone.classify_field_zones(sites, source_offset=None, *, far_threshold=3.0, near_threshold=0.3, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Classify CSAMT measurement zones per station per frequency.

For each (station, frequency) pair the dimensionless field-zone parameter is computed as:

|k·r| = r / δ_B where δ_B = 356 √(ρ_a / f) (metres)

and the zone is assigned as:

Parameters:

  • sites (path, EDI-like, Sites, or iterable) – Any input accepted by ensure_sites().

  • source_offset (float, dict {station: float}, or None) – Source–receiver separation r in metres. If a dict is given, missing stations are skipped (or read from ed.offset / ed.source_offset).

  • far_threshold (float, default=3.0) – |k·r| threshold for the far-field (plane-wave) zone.

  • near_threshold (float, default=0.3) – |k·r| threshold below which the near-field zone is declared.

  • 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:

Tidy table, one row per (station, frequency):

station, freq_hz, period_s, offset_m, rho_a_ohmm, delta_bostick_m, kr, zone

Return type:

pandas.DataFrame

References

Chen & Yan (2005), J. Geophysics and Engineering 2, 105–120. Yan & Fu (2004), analytical shadow/overprint estimation.

pycsamt.emtools.fieldzone.near_field_factor(sites, source_offset=None, *, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Near-field correction factor for apparent resistivity (equatorial HED).

For the equatorial E_y component from a horizontal electric dipole over a homogeneous half-space, the ratio of the measured E_y to the plane-wave (far-field) E_y is:

F(p) = 1 − 3/p² + 3/p³ p = k·r (complex)

so the apparent resistivity is biased by factor |F(p)|². When |F(p)| ≈ 1 the data are in the plane-wave zone; strong departures indicate near-field contamination.

Parameters:

  • sites (path, EDI-like, Sites, or iterable)

  • source_offset (float, dict {station: float}, or None) – Source–receiver separation r in metres.

  • 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:

Columns: station, freq_hz, period_s, offset_m, rho_a_ohmm, kr, nf_factor.

  • nf_factor = |F(p)|; close to 1.0 → far-field (safe).

  • nf_factor far from 1.0 → near-field bias present.

Return type:

pandas.DataFrame

References

Chen & Yan (2005), eqs. (8)–(10).

pycsamt.emtools.fieldzone.plot_field_zones(sites, source_offset=None, *, far_threshold=3.0, near_threshold=0.3, contour_kr=True, kr_levels=(0.1, 0.3, 1.0, 3.0, 10.0), sort_by='name', period_axis=True, log_y=True, figsize=(10.0, 5.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Pseudosection of CSAMT field zones across stations and frequencies.

Each cell (station × period/frequency) is filled by zone colour:

  • green → far field (|k·r| ≥ far_threshold)

  • orange → transition

  • red → near field (|k·r| < near_threshold)

Dashed white contours of constant |k·r| can be overlaid.

Parameters:

  • sites (path, EDI-like, Sites, or iterable)

  • source_offset (float, dict {station: float}, or None) – Source–receiver separation r in metres.

  • far_threshold (float) – Zone boundaries in |k·r|.

  • near_threshold (float) – Zone boundaries in |k·r|.

  • contour_kr (bool, default=True) – Draw |k·r| contours.

  • kr_levels (tuple of float) – |k·r| values to contour.

  • sort_by ({"name", "lon", "lat"}) – Station ordering along the x-axis.

  • period_axis (bool, default=True) – If True y-axis shows period (s), else frequency (Hz).

  • log_y (bool, default=True) – Use a quasi-log y-axis (log-spaced tick labels).

  • figsize ((float, float), default=(10, 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:

matplotlib.axes.Axes