pycsamt.emtools.tf#

Functions

`plot_induction_arrows`(sites, *[, periods, ...])
`plot_induction_convention`(sites, *[, ...])	2×2 panel: Parkinson/Wiese × Real/Imaginary conventions.
`plot_induction_map`(sites, *[, period, ...])	Map-view induction arrows at one period.
`plot_induction_map_from_spectra`(sp_input, *)	Map-view induction arrows from `Spectra`.
`plot_induction_multiperiod_map`(sites, *[, ...])	Stacked multi-period induction vector map.
`plot_induction_rose`(sites, *[, component, ...])	Rose diagram of induction arrow azimuths (all stations & periods).
`plot_induction_rose_from_spectra`(sp_input, *)	Rose diagram of induction arrow directions from Spectra objects.
`plot_induction_section`(sites, *[, ...])	Period × station pseudo-section coloured by \|T\| magnitude.
`plot_tipper_hodograms`(sites, *[, station, ...])
`plot_tipper_polar`(sites, *[, station, ...])	Polar view: tipper azimuth (angle) and magnitude (radius) vs period.
`plot_tipper_polar_from_spectra`(sp, *[, ...])	Polar tipper from a `Spectra` object.

pycsamt.emtools.tf.plot_tipper_hodograms(sites, *, station=None, bands=None, n_bands=3, normalize=False, colors=None, marker='o', ms=3.0, lw=1.0, ls='-', unit_circle=True, axes=None, figsize=(6.4, 3.2), recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Parameters:

sites (Any)
station (str | None)
bands (Sequence[tuple[float, float]] | None)
n_bands (int)
normalize (bool)
colors (Sequence[str] | None)
marker (str)
ms (float)
lw (float)
ls (str)
unit_circle (bool)
figsize (tuple[float, float])
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

pycsamt.emtools.tf.plot_induction_arrows(sites, *, periods=(1.0,), convention='park', scale=1.0, normalize=True, strike_ticks=True, tick_len=0.25, figsize=(7.2, 3.4), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Parameters:

sites (Any)
periods (Sequence[float])
convention (str)
scale (float)
normalize (bool)
strike_ticks (bool)
tick_len (float)
figsize (tuple[float, float])
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)
ax (Axes | None)

pycsamt.emtools.tf.plot_induction_map(sites, *, period=1.0, convention='park', show_real=True, show_imag=True, scale=<object object>, cmap='plasma', clim=None, show_colorbar=True, reference_arrow=0.1, station_labels=True, title='', figsize=(8, 7), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Map-view induction arrows at one period.

Real (solid) and imaginary (dashed) Parkinson arrows at every station, coloured by |T| magnitude.

Parameters:

sites (Sites-like)
period (float) – Target period in seconds.
convention ({'park', 'wiese', 'real', 'imag'})
show_real (bool)
show_imag (bool)
scale (float or _UNSET) – Arrow scale factor (auto from station spacing).
cmap (str)
clim ((vmin, vmax) or None)
show_colorbar (bool)
reference_arrow (float) – Length of the scale-bar reference arrow.
station_labels (bool)
title (str)
figsize (standard)
ax (standard)
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

Returns:

ax

Return type:

Axes

pycsamt.emtools.tf.plot_induction_section(sites, *, component='abs', n_periods=20, cmap='RdBu_r', clim=None, section='pseudosection', title='', figsize=None, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Period × station pseudo-section coloured by |T| magnitude.

Parameters:

sites (Sites-like)
component ({'real', 'imag', 'abs'})
n_periods (int)
cmap (str)
clim ((vmin, vmax) or None)
section (str or SectionStyle)
title (standard)
figsize (standard)
ax (standard)
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

Returns:

ax

Return type:

Axes

pycsamt.emtools.tf.plot_induction_convention(sites, *, period=1.0, scale=<object object>, station_labels=True, title='', axes=None, figsize=(11, 10), recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

2×2 panel: Parkinson/Wiese × Real/Imaginary conventions.

Parkinson — Real	Parkinson — Imaginary
Wiese — Real	Wiese — Imaginary

Parameters:

sites (Sites-like)
period (float)
scale (standard)
station_labels (standard)
title (standard)
figsize (standard)
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

Returns:

axes

Return type:

ndarray of Axes, shape (2, 2)

pycsamt.emtools.tf.plot_tipper_polar(sites, *, station=None, component='real', cmap=<object object>, lw=<object object>, alpha=<object object>, title='', figsize=(5.5, 5.5), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Polar view: tipper azimuth (angle) and magnitude (radius) vs period.

Each frequency is one scatter point; colour encodes log₁₀(period). North (0°) = up, clockwise positive, following geomagnetic convention.

Parameters:

sites (Sites-like)
station (str or None)
component ({'real', 'imag', 'abs'})
cmap (str or _UNSET)
lw (float or _UNSET)
alpha (float or _UNSET)
title (standard)
figsize (standard)
ax (standard)
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

Returns:

ax

Return type:

polar Axes

pycsamt.emtools.tf.plot_induction_rose(sites, *, component='real', pband=None, nbins=36, style=<object object>, title='', figsize=(5, 5), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Rose diagram of induction arrow azimuths (all stations & periods).

Parameters:

sites (Sites-like)
component ({'real', 'imag', 'abs'})
pband ((T_min, T_max) or None)
nbins (int (default 36 → 10° bins))
style (RoseStyle or str or _UNSET)
title (standard)
figsize (standard)
ax (standard)
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

Returns:

ax

Return type:

polar Axes

pycsamt.emtools.tf.plot_induction_map_from_spectra(sp_input, *, period=1.0, coords=None, show_real=True, show_imag=True, scale=<object object>, cmap='plasma', station_labels=True, title='', figsize=(8, 5), ax=None)[source]#

Map-view induction arrows from Spectra.

Parameters:

sp_input (Spectra, list, or dict[str, Spectra])
period (float)
coords (dict[name → (x, y)] or None) – Station positions. Equidistant line when None.
show_real (bool)
show_imag (bool)
scale (standard)
cmap (standard)
station_labels (standard)
title (standard)
figsize (standard)
ax (standard)

Returns:

ax

Return type:

Axes

pycsamt.emtools.tf.plot_tipper_polar_from_spectra(sp, *, component='real', cmap='viridis', title='', ax=None, figsize=(5.5, 5.5))[source]#

Polar tipper from a Spectra object.

Parameters:

sp (Spectra)
component ({'real', 'imag', 'abs'})
cmap (standard)
title (standard)
figsize (standard)

Returns:

ax

Return type:

polar Axes

pycsamt.emtools.tf.plot_induction_rose_from_spectra(sp_input, *, component='real', pband=None, nbins=36, style=<object object>, title='', figsize=(5, 5), ax=None)[source]#

Rose diagram of induction arrow directions from Spectra objects.

Parameters:

sp_input (Spectra, list, or dict[str, Spectra])
component ({'real', 'imag', 'abs'})
pband ((T_min, T_max) or None)
nbins (int)
style (RoseStyle or str or _UNSET)
title (standard)
figsize (standard)
ax (standard)

Returns:

ax

Return type:

polar Axes

pycsamt.emtools.tf.plot_induction_multiperiod_map(sites, *, periods=(1.0, 10.0, 100.0, 1000.0), tipper_data=None, convention='park', panel_labels=None, background=None, background_extent=None, background_cmap='terrain', background_alpha=0.75, background_clim=None, bg_colorbar_label='Elevation (m)', bg_colorbar_side='right', show_background_cbar=True, arrow_color='black', arrow_scale=<object object>, arrow_lw=1.6, reference_arrow=0.1, reference_panel=0, reference_label=<object object>, show_stations=True, station_labels=False, annotations=None, annotation_color='navy', annotation_fontsize=8.0, title='', axes=None, figsize=<object object>, panel_height=3.0, panel_width=8.5, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Stacked multi-period induction vector map.

Produces one panel per period (stacked vertically), each showing the real Parkinson induction vectors on a background colour map (elevation, resistivity, or any 2-D raster). The layout mimics the style of Boukhalfa et al. (2020, GJI) Fig. 7 and the paper figure described in the session above.

Visual conventions#

Arrows: black solid vectors using the Parkinson (1962) convention (real component pointing toward the conductor).
Background: smooth terrain coloured with background_cmap; a synthetic gradient is auto-generated when background is None.
Reference vector: drawn in the first (or reference_panel) sub-plot; labelled with its normalised length.
Shared colorbar: placed on the right edge of the figure, spanning all panels.
Panel labels: "(A) 1 s", "(B) 10 s", … placed in the lower-left corner of each panel.
Geological / site annotations: optional blue text labels supplied via annotations.

param sites:

EDI collection accepted by ensure_sites(). When the EDIs carry no tipper (Tipper.tipper all-zero), pass synthetic tipper via tipper_data.

type sites:

Sites-like

param periods:

Target periods in seconds, one panel each.

type periods:

sequence of float

param tipper_data:

Explicit tipper override. Keys must match periods (nearest match is used). Column 0 = T_x, column 1 = T_y. When absent, the tipper is read from the EDIs.

type tipper_data:

dict {period → (n_sites, 2) complex array}, optional

param convention:

Arrow convention. "park" (Parkinson real) is the only one used in published induction-vector maps; "wiese" is supported.

type convention:

str

param panel_labels:

Panel corner labels (e.g. ["(A) 1 s", "(B) 10 s", ...]). Auto-generated when None.

type panel_labels:

sequence of str, optional

param background:

Pre-computed background raster. A smooth synthetic terrain is generated when None.

type background:

ndarray (ny, nx), optional

param background_extent:

Geographic extent for the background raster. Auto-inferred from station positions when None.

type background_extent:

(x_left, x_right, y_bottom, y_top), optional

param background_cmap:

Colormap for the background. Default "terrain" (green→brown elevation appearance).

type background_cmap:

str

param background_alpha:

Background opacity (0–1).

type background_alpha:

float

param background_clim:

type background_clim:

(vmin, vmax) or None

param bg_colorbar_label:

Label for the shared colorbar.

type bg_colorbar_label:

str

param bg_colorbar_side:

Side of the figure where the shared background colorbar is placed. Right-side placement is the package default because it keeps section axes and station labels visually grouped.

type bg_colorbar_side:

{‘right’, ‘left’, ‘top’, ‘bottom’}, default ‘right’

param show_background_cbar:

type show_background_cbar:

bool

param arrow_color:

Single colour for all induction vectors. Default "black".

type arrow_color:

str

param arrow_scale:

Multiplier for arrow length in data units. Auto-computed from the typical station spacing when _UNSET.

type arrow_scale:

float or _UNSET

param arrow_lw:

Arrow shaft line width in points.

type arrow_lw:

float

param reference_arrow:

Normalised length of the scale-reference arrow drawn in the reference_panel sub-plot. Default 0.1.

type reference_arrow:

float

param reference_panel:

Sub-plot index (0-based) where the reference arrow appears.

type reference_panel:

int

param reference_label:

Text for the reference arrow. Defaults to "Vector length {reference_arrow}".

type reference_label:

str or _UNSET

param show_stations:

Draw a small marker (▼) at each station position.

type show_stations:

bool

param station_labels:

Annotate station names next to markers.

type station_labels:

bool

param annotations:

Geological or site annotations drawn in annotation_color on every panel.

type annotations:

dict {label: (x, y)} or {label: (x, y, {fontsize, color, …})}, optional

param annotation_color:

Default colour for annotations.

type annotation_color:

str

param annotation_fontsize:

type annotation_fontsize:

float

param title:

Figure suptitle.

type title:

str

param figsize:

Auto-computed from panel_height, panel_width, and number of panels when omitted.

type figsize:

(float, float) or _UNSET

param panel_height:

Per-panel size in inches used for auto figsize.

type panel_height:

float

param panel_width:

Per-panel size in inches used for auto figsize.

type panel_width:

float

param recursive:

type recursive:

standard ensure_sites kwargs.

param on_dup:

type on_dup:

standard ensure_sites kwargs.

param strict:

type strict:

standard ensure_sites kwargs.

param verbose:

type verbose:

standard ensure_sites kwargs.

returns:

fig (Figure)
axes (ndarray of Axes, shape (n_periods,))

Examples

Real data with tipper:

fig, axs = plot_induction_multiperiod_map(
    "site.edi",
    periods=[1, 10, 100, 1000],
)

Synthetic tipper supplied explicitly:

tipper = {1.0:   st_tips_1s,
          10.0:  st_tips_10s,
          100.0: st_tips_100s}
fig, axs = plot_induction_multiperiod_map(
    "profile/*.edi",
    periods=[1, 10, 100],
    tipper_data=tipper,
)

Parameters:

sites (Any)
periods (Sequence[float])
tipper_data (dict[str, ndarray] | None)
convention (str)
panel_labels (Sequence[str] | None)
background (ndarray | None)
background_extent (tuple[float, float, float, float] | None)
background_cmap (str)
background_alpha (float)
background_clim (tuple[float, float] | None)
bg_colorbar_label (str)
bg_colorbar_side (str)
show_background_cbar (bool)
arrow_color (str)
arrow_scale (float)
arrow_lw (float)
reference_arrow (float)
reference_panel (int)
reference_label (str)
show_stations (bool)
station_labels (bool)
annotations (dict[str, Any] | None)
annotation_color (str)
annotation_fontsize (float)
title (str)
figsize (Any)
panel_height (float)
panel_width (float)
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

Return type:

tuple[Figure, ndarray]