pycsamt.emtools.tensor#

Functions

antisymmetrize(sites, *[, how, inplace, ...])

balance_offdiag(sites, *[, mode, inplace, ...])

build_phase_tensor_table(sites, *[, ...])

invert(sites, *[, inplace, recursive, ...])

orient_from_sensors(sites, ex, ey, bx, by, *)

phase_tensor_legend(*[, size, figsize, ax])

plot_dimensionality_grid(sites, *[, ...])

plot_dimensionality_psection(sites, *[, ...])

plot_ellipticity_psection(sites, *[, ...])

plot_phase_tensor_map(sites, *[, period, ...])

Publication-quality phase-tensor map at a single period.

plot_phase_tensor_psection(sites, *[, ...])

Phase-tensor ellipse pseudo-section (Caldwell et al. 2004 style).

plot_phase_tensor_rose(sites, *[, style, ...])

Publication-quality phase-tensor θ rose diagram.

plot_phase_tensor_skewmap(sites, *[, ...])

plot_phase_tensor_strip(sites, *[, station, ...])

Single-station phase-tensor ellipse strip vs period.

plot_phase_tensor_strip_grid(sites, profiles, *)

Phase-tensor ellipse strips for several stations, grouped by profile.

plot_phase_tensor_summary(sites, *[, ...])

Three-panel phase-tensor summary figure.

plot_skew_ellipt_density(sites, *[, band, ...])

plot_strike_director_field(sites, *[, ...])

Geoelectric-strike director field over station and period.

plot_theta_rose_grid(sites, *[, n_bands, ...])

Phase-tensor θ rose grid — one pycsamt-styled rose per frequency decade.

plot_theta_stability_stripe(sites, *[, win, ...])

plot_theta_vs_period(sites, *[, figsize, ...])

rotate(sites, angle, *[, inplace, ...])

rotate_by_map(sites, angle_by_station, *[, ...])

rotate_to_strike(sites, *[, method, ...])

sigma_clip_z(sites, *[, sigma, inplace, ...])

pycsamt.emtools.tensor.rotate_to_strike(sites, *, method='swift', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.rotate(sites, angle, *, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.rotate_by_map(sites, angle_by_station, *, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.antisymmetrize(sites, *, how='rms', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.invert(sites, *, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.orient_from_sensors(sites, ex, ey, bx, by, *, degrees=True, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.sigma_clip_z(sites, *, sigma=3.0, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.balance_offdiag(sites, *, mode='avgabs', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

Sites

pycsamt.emtools.tensor.build_phase_tensor_table(sites, *, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

DataFrame

pycsamt.emtools.tensor.plot_phase_tensor_psection(sites, *, stations=None, period_range=None, axis_y='logperiod', period_up=True, scale=<object object>, normalise_by=<object object>, s1_ref=None, min_aspect=<object object>, c_by=<object object>, cmap=<object object>, clim=None, clim_pct=<object object>, symmetric_clim=<object object>, edgecolor=<object object>, linewidth=<object object>, alpha=<object object>, skew_threshold=<object object>, mark_3d=<object object>, ref_ellipse=<object object>, legend_fontsize=8.0, title='', xlabel='', ylabel='', tick_label_rotation=45.0, figsize=(10.0, 5.5), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Phase-tensor ellipse pseudo-section (Caldwell et al. 2004 style).

Each cell (station × period) is drawn as an ellipse whose shape, orientation, and fill colour encode phase-tensor invariants:

  • major axis ∝ φ_max (s1 eigenvalue — mean phase level)

  • minor axis ∝ φ_min (s2 eigenvalue — minimum phase)

  • aspect ratio = φ_min / φ_max (1 = isotropic / 1-D)

  • rotation = θ (geoelectric strike, CCW from E)

  • fill colour controlled by c_by (default: skew angle β)

Parameters:

  • sites (any) – EDI paths, glob pattern, Sites, or any input accepted by ensure_sites().

  • stations (list of str or None) – Restrict to a subset of station names.

  • period_range ((T_min, T_max) in seconds or None) – Restrict the period range plotted.

  • axis_y ("logperiod" | "logfreq") – Y-axis quantity. "logperiod" is the MT convention.

  • period_up (bool, default True) – When True (MT convention) long period (low frequency) is at the top of the figure; False flips the y-axis.

  • scale (float, default 0.85) – Fraction of each cell occupied by the reference ellipse (the one with s1 = s1_ref). Values above 1 cause overlap.

  • normalise_by ("cell" | "unity" | "abs") –

    Sizing strategy:

    "cell"

    Sizes are normalised so the 90th-percentile s1 fills scale of its cell. Preserves relative size information.

    "unity"

    s1_ref = 1.0 (tan 45° = 1-D half-space reference). A 45° phase tensor is drawn as a circle filling scale of its cell.

    "abs"

    Raw: width = scale × s1, height = scale × s2 in data units (legacy behaviour).

  • s1_ref (float or None) – Override the reference s1 for "cell" and "unity" modes.

  • min_aspect (float, default 0.18) – Minimum height/width ratio enforced on every ellipse so that near-degenerate (φ_min ≈ 0) cells stay visible as ovals instead of collapsing into an invisible hairline. Set to 0 to plot raw ellipticity.

  • c_by (str, default "skew") – Column name or derived quantity to map to fill colour. Supported values: "skew", "beta", "alpha", "theta", "ellipt", "s1", "s2", "|skew|", "|beta|", "|theta|", "phi_mean", "phi_max", "phi_min".

  • cmap (str, default "RdBu_r") – Matplotlib colormap name.

  • clim ((vmin, vmax) or None) – Explicit colour limits. When None, derived from clim_pct.

  • clim_pct ((lo, hi), default (5.0, 95.0)) – Percentile limits used when clim is None.

  • symmetric_clim (bool, default True) – Enforce vmin = −vmax for skew-like quantities.

  • edgecolor (str, default "k") – Ellipse border colour. Set to "none" to suppress borders.

  • linewidth (float, default 0.2) – Ellipse border width (pts). 3-D cells receive 3 × this width when mark_3d is True.

  • alpha (float, default 0.92) – Ellipse fill opacity.

  • skew_threshold (float or None, default 3.0) – |β| threshold (degrees) separating 1-D/2-D from 3-D structure. Used to cap clim symmetrically when clim is None, and to highlight 3-D cells with a thicker border when mark_3d is True.

  • mark_3d (bool, default True) – Draw a thicker border on ellipses where |β| > skew_threshold.

  • ref_ellipse (bool, default True) – Draw a labelled reference circle (φ_max = φ_min = s1_ref, β = 0°) in a reserved legend strip above the data, as a scale indicator.

  • legend_fontsize (float, default 8.0) – Font size for the reference-circle label and the 1-D/2-D vs 3-D annotation shown when ref_ellipse / skew_threshold are active.

  • title (str) – Axes title and axis labels. Sensible defaults are used when empty.

  • xlabel (str) – Axes title and axis labels. Sensible defaults are used when empty.

  • ylabel (str) – Axes title and axis labels. Sensible defaults are used when empty.

  • tick_label_rotation (float, default 45.0) – Station-name tick rotation in degrees.

  • figsize ((width, height), default (10.0, 5.5)) – Figure size (ignored when ax is provided).

  • recursive (see ensure_sites().)

  • on_dup (see ensure_sites().)

  • strict (see ensure_sites().)

  • verbose (see ensure_sites().)

  • ax (Axes or None) – If provided, draw into this axes and return it; otherwise create a new figure.

Returns:

ax

Return type:

Axes

See also

build_phase_tensor_table

Underlying data computation.

plot_phase_tensor_summary

3-panel figure combining ellipses, dimensionality, and skew distribution.

plot_phase_tensor_map

Geographic map view.

pycsamt.emtools.tensor.plot_phase_tensor_skewmap(sites, *, axis_y='logperiod', agg='median', figsize=(9.0, 4.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_theta_vs_period(sites, *, figsize=(8.0, 4.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_strike_director_field(sites, *, color_by='skew', length_by='ellipt', streamlines=True, skew_max=6.0, cmap=None, period_subsample=None, bar_scale=26.0, show_legend=True, title=None, figsize=(12.0, 5.2), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Geoelectric-strike director field over station and period.

A supplement to plot_theta_vs_period(). Because the phase-tensor strike theta is an axial angle (defined mod 180 deg), the correct glyph is not a point on a linear axis but a head-less bar pointing along the strike. This draws one director per (station, period) cell on a station x log-period grid, encoding three more channels at once:

  • orientation – the strike theta;

  • length – length_by (default ellipticity), the 2-D strength: near-1-D cells get a short bar because there strike is ill-defined;

  • colour – color_by (default |skew|), the departure from 2-D: green = low-skew / reliable, red = high-skew / 3-D or galvanic distortion where the strike should not be trusted.

An optional smoothed streamline overlay (streamlines=True) integrates the director field into a strike “flow”, so lateral and vertical coherence read at a glance.

Interpretation#

  • long, aligned, green bars flowing in a laminar bundle -> robust, depth-consistent 2-D strike; read the azimuth with confidence;

  • bars rotating smoothly with depth -> strike varies with depth (dipping structure or layered anisotropy);

  • short and/or red, swirling bars -> 1-D, 3-D, or noise: do not over-interpret the direction there.

param sites:

Anything accepted by build_phase_tensor_table().

type sites:

path, EDI object, APISurvey, Sites, or iterable of sites

param color_by:

Table column mapped to bar colour (its absolute value is used).

type color_by:

{‘skew’, ‘ellipt’, ‘s1’, ‘s2’, …}, default ‘skew’

param length_by:

Table column mapped to bar length (absolute value, 95th-percentile normalised). None draws uniform-length bars.

type length_by:

str or None, default ‘ellipt’

param streamlines:

Overlay smoothed strike streamlines (needs SciPy).

type streamlines:

bool, default True

param skew_max:

Upper clip of the |skew| colour scale, in degrees (only used when color_by='skew'). Skew above a few degrees already flags 3-D behaviour.

type skew_max:

float, default 6.0

param cmap:

Override the colour map (default 'RdYlGn_r' for skew, else 'viridis').

type cmap:

str, optional

param period_subsample:

Keep at most this many periods (evenly along the log axis) to thin a very dense grid.

type period_subsample:

int, optional

param bar_scale:

Matplotlib quiver scale – larger makes shorter bars.

type bar_scale:

float, default 26.0

param show_legend:

Draw the director / streamline legend.

type show_legend:

bool, default True

param title:

Axes title.

type title:

str, optional

param figsize:

Standard emtools plotting arguments.

param recursive:

Standard emtools plotting arguments.

param on_dup:

Standard emtools plotting arguments.

param strict:

Standard emtools plotting arguments.

param verbose:

Standard emtools plotting arguments.

param ax:

Standard emtools plotting arguments.

rtype:

matplotlib.axes.Axes

See also

plot_theta_vs_period

the linear scatter this supplements.

plot_phase_tensor_psection

per-cell ellipses (magnitudes as well).

Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_ellipticity_psection(sites, *, figsize=(8.5, 4.0), agg='median', recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_dimensionality_psection(sites, *, skew_th=3.0, ellipt_th=0.2, figsize=(8.5, 4.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_phase_tensor_rose(sites, *, style='pycsamt', band=None, freq_bands=None, band_labels=None, band_colors=None, bins=36, bar_style=<object object>, bar_color=<object object>, bar_alpha=<object object>, bar_edgecolor=<object object>, bar_edgelw=<object object>, cmap=<object object>, outer_ring_lw=<object object>, outer_ring_color=<object object>, n_rings=<object object>, ring_color=<object object>, ring_ls=<object object>, ring_lw=<object object>, ring_labels=<object object>, ring_label_angle=<object object>, ring_label_fontsize=<object object>, ring_label_color=<object object>, ring_label_fmt=<object object>, spoke_every=<object object>, spoke_color=<object object>, spoke_ls=<object object>, spoke_lw=<object object>, compass_labels=<object object>, compass_fontsize=<object object>, compass_color=<object object>, compass_fontweight=<object object>, show_mean=<object object>, mean_color=<object object>, mean_lw=<object object>, mean_ls=<object object>, show_secondary=<object object>, secondary_ls=<object object>, secondary_lw=<object object>, secondary_color=<object object>, show_annotation=<object object>, annotation_pos=<object object>, annotation_fontsize=<object object>, annotation_bg=<object object>, annotation_ec=<object object>, show_n=<object object>, figsize=(5.5, 5.5), title='', title_fontsize=10.0, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Publication-quality phase-tensor θ rose diagram.

Bars are drawn with axial symmetry — 0–180° mirrored to 180–360° — reflecting the inherent 180° ambiguity of the phase-tensor principal axis direction.

Parameters:

  • sites (any) – EDI paths, objects, or collection accepted by ensure_sites().

  • band ((lo_s, hi_s) or None) – Period window in seconds. None uses all available periods.

  • freq_bands (list of (lo_s, hi_s), optional) – Sub-bands for bar_style="bands" — one stacked bar colour per band.

  • band_labels (list[str], optional) – Legend labels for each entry in freq_bands.

  • band_colors (list, optional) – Colours for each freq_bands entry. Defaults to tab10.

  • bins (int) – Number of bins over 0–180°, mirrored to 360°. Default 36 gives 5° bins.

  • bar_style ({"gradient", "solid", "bands"}) – "gradient" colours bars by height via cmap; "solid" uses bar_color uniformly; "bands" stacks one colour per period sub-band.

  • bar_color (str) – Bar fill colour for bar_style="solid".

  • bar_edgecolor (str) – Bar edge colour ("none" → no edge).

  • bar_edgelw (float) – Bar edge line-width.

  • bar_alpha (float) – Bar opacity (0–1).

  • cmap (str) – Colormap for bar_style="gradient".

  • outer_ring_lw (float) – Line-width of the bold outer bounding circle.

  • outer_ring_color (str) – Colour of the outer circle.

  • n_rings (int) – Number of concentric reference rings.

  • ring_color (str) – Colour of concentric rings and spokes.

  • ring_ls (str) – Line-style of concentric rings.

  • ring_lw (float) – Line-width of concentric rings.

  • ring_labels (list[float], optional) – Explicit count values to annotate on the rings (e.g. [25, 50, 75, 100]). None → evenly spaced from rmax / n_rings to rmax.

  • ring_label_angle (float) – Clockwise angle from North (degrees) at which ring count labels are placed. Default 22.5.

  • ring_label_fontsize (float) – Font size for ring count labels.

  • ring_label_color (str) – Colour for ring count labels.

  • ring_label_fmt (str) – Format string for ring labels, e.g. "{:.0f}".

  • spoke_every (float) – Angular spacing (degrees) between radial spokes.

  • spoke_color (str) – Colour of radial spokes.

  • spoke_ls (str) – Line-style of radial spokes.

  • spoke_lw (float) – Line-width of radial spokes.

  • compass_labels ({"NESW", "degrees", "none"}) – Perimeter labels. "NESW" shows cardinal directions; "degrees" shows degree values; "none" hides all.

  • compass_fontsize (float) – Font size for perimeter labels.

  • compass_color (str) – Colour for perimeter labels.

  • compass_fontweight (str) – Font weight for perimeter labels.

  • show_mean (bool) – Draw the axial mean direction as a line through the centre.

  • mean_color (str) – Colour of the mean-direction line.

  • mean_lw (float) – Line-width of the mean-direction line.

  • mean_ls (str) – Line-style of the mean-direction line.

  • show_secondary (bool) – Draw the 180°-conjugate mean line.

  • secondary_ls (str) – Line-style of the conjugate line.

  • secondary_lw (float, optional) – Line-width of the conjugate line; defaults to mean_lw.

  • secondary_color (str, optional) – Colour of the conjugate line; defaults to mean_color.

  • show_annotation (bool) – Show a text box with the mean θ and station/pair count.

  • annotation_pos ((float, float)) – Axes-fraction (x, y) for the annotation box.

  • annotation_fontsize (float) – Font size of the annotation text.

  • annotation_bg (str) – Background colour of the annotation box.

  • annotation_ec (str) – Edge colour of the annotation box.

  • show_n (bool) – Append n = N to the annotation text.

  • figsize ((float, float)) – Figure size in inches.

  • title (str) – Axes title (set via ax.set_title).

  • title_fontsize (float) – Font size for title.

  • recursive (bool) – Passed to ensure_sites().

  • on_dup (str) – Passed to ensure_sites().

  • strict (bool) – Passed to ensure_sites().

  • verbose (int) – Passed to ensure_sites().

  • ax (matplotlib.axes.Axes, optional) – Pre-existing polar axes to draw into. Created when None.

  • style (str | RoseStyle | None)

Returns:

The polar axes containing the rose diagram.

Return type:

matplotlib.axes.Axes

Examples

Default gradient style, all periods:

>>> from pycsamt.emtools import plot_phase_tensor_rose
>>> ax = plot_phase_tensor_rose("path/to/edis/", figsize=(6, 6))

Frequency-band decomposition (stacked):

>>> ax = plot_phase_tensor_rose(
...     sites,
...     bar_style="bands",
...     freq_bands=[(1e-4, 1e-2), (1e-2, 1e0)],
...     band_labels=["Short period", "Long period"],
... )

Custom ring count labels:

>>> ax = plot_phase_tensor_rose(
...     sites,
...     ring_labels=[25, 50, 75, 100],
...     ring_label_angle=15.0,
... )
pycsamt.emtools.tensor.plot_phase_tensor_map(sites, *, period=10.0, scale=<object object>, normalise_by=<object object>, s1_ref=<object object>, min_aspect=<object object>, c_by=<object object>, cmap=<object object>, clim=None, clim_pct=<object object>, symmetric_clim=<object object>, alpha=<object object>, edgecolor=<object object>, linewidth=<object object>, skew_threshold=<object object>, mark_3d=<object object>, lw_3d_factor=<object object>, ref_ellipse=<object object>, show_tipper=True, tipper_convention='parkinson', tipper_component='real', tipper_scale=None, tipper_color='k', tipper_lw=1.4, bg_grid=None, station_labels=True, station_marker='v', station_ms=5.0, station_color='k', label_fontsize=7.0, title='', colorbar_label=None, coords=None, figsize=(9.0, 7.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Publication-quality phase-tensor map at a single period.

Renders each station as a phase-tensor ellipse positioned at its geographic coordinates. The ellipse shape encodes the phase-tensor principal values (φ_max, φ_min) and orientation (θ); fill colour encodes an additional scalar (default: skewness β). Induction arrows can be overlaid when tipper data are available, and an optional background field (gravity, resistivity, …) may be drawn behind the ellipses.

Parameters:

  • sites (any) – EDI paths, objects, or collection accepted by ensure_sites().

  • period (float) – Target period (s). The nearest available period in the data is used for each station independently.

  • scale (float or _UNSET) – Maximum ellipse semi-axis in geographic units (degrees). _UNSET → auto-derived from the median inter-station spacing.

  • normalise_by ("cell" | "unity" | "abs") – Size normalisation strategy, see PhaseTensorEllipseStyle.

  • s1_ref (float or None) – Manual reference s1 used with normalise_by="cell"/"unity".

  • min_aspect (float or _UNSET) – Minimum height/width ratio enforced on every ellipse; see plot_phase_tensor_psection(). Default: PYCSAMT_STYLE.pt_ellipse.min_aspect.

  • c_by (str) – Scalar quantity to map to fill colour. Recognised values: "skew", "beta", "|skew|", "theta", "ellipt", "phi_mean", "phi_max", "phi_min", "s1", "s2", "alpha". Defaults to PYCSAMT_STYLE.pt_ellipse.c_by.

  • cmap (str or None) – Matplotlib colormap. Auto-selected from c_by when None (same logic as PhaseTensorEllipseStyle).

  • clim ((vmin, vmax) or None) – Explicit colour limits. None → derived from clim_pct.

  • clim_pct ((lo, hi)) – Percentile window for automatic colour limits.

  • symmetric_clim (bool) – Force vmin = −vmax (useful for diverging quantities).

  • alpha (float) – Ellipse fill opacity.

  • edgecolor (str) – Ellipse border colour.

  • linewidth (float) – Normal ellipse border width (pts).

  • skew_threshold (float or None) – |β| above which a cell is flagged as 3-D.

  • mark_3d (bool) – Draw thicker borders on 3-D flagged ellipses.

  • lw_3d_factor (float) – Line-width multiplier for 3-D flagged borders.

  • ref_ellipse (bool) – Draw a reference circle in the lower-left corner as a scale bar.

  • show_tipper (bool) – Overlay induction arrows when tipper data are found.

  • tipper_convention ("parkinson" | "wiese") – Parkinson: arrow toward anomaly (negated real T); Wiese: arrow along real T.

  • tipper_component ("real" | "imag" | "both") – Which tipper component to draw.

  • tipper_scale (float or None) – Arrow length = tipper_scale × scale. Auto-derived when None.

  • tipper_color (str) – Arrow colour (real component). Imaginary component uses mcolors.to_rgba(tipper_color, 0.55).

  • tipper_lw (float) – Arrow line-width.

  • bg_grid (dict or None) –

    Optional background field drawn behind ellipses:

    bg_grid = dict(
    lons   = 1D or 2D longitude array,
    lats   = 1D or 2D latitude array,
    values = 2D array (shape matches meshgrid of lons × lats),
    cmap   = "RdYlGn",     # colormap
    clim   = (vmin, vmax), # or None → auto
    alpha  = 0.55,         # opacity
    label  = "Gravity (gu)",
)

  • station_labels (bool) – Annotate each station position with its name.

  • station_marker (str) – Marker style for station positions (default "v").

  • station_ms (float) – Marker size.

  • station_color (str) – Marker and label colour.

  • label_fontsize (float) – Font size for station labels.

  • title (str) – Axes title.

  • colorbar_label (str or None) – Override the automatic colorbar label derived from c_by.

  • coords (dict[str, (lat, lon)] or None) – Explicit station coordinates. When None the function reads ed.coords (a (lat, lon, elev) tuple) from each Site object.

  • figsize ((float, float)) – Figure size in inches.

  • recursive (bool) – Passed to ensure_sites().

  • on_dup (str) – Passed to ensure_sites().

  • strict (bool) – Passed to ensure_sites().

  • verbose (int) – Passed to ensure_sites().

  • ax (matplotlib.axes.Axes or None) – Pre-existing axes to draw into.

Return type:

matplotlib.axes.Axes

Examples

Default skew-coloured map:

>>> from pycsamt.emtools import plot_phase_tensor_map
>>> ax = plot_phase_tensor_map(sites, period=10.0)

Ellipticity coloured, with tipper arrows:

>>> ax = plot_phase_tensor_map(
...     sites, period=10.0,
...     c_by="ellipt", cmap="viridis",
...     show_tipper=True, tipper_convention="parkinson",
... )

With a gravity background:

>>> ax = plot_phase_tensor_map(
...     sites, period=10.0,
...     bg_grid=dict(lons=g_lon, lats=g_lat, values=g_bouguer,
...                  cmap="RdYlGn", alpha=0.45, label="Gravity (gu)"),
... )
pycsamt.emtools.tensor.plot_phase_tensor_summary(sites, *, stations=None, period_range=None, scale=<object object>, c_by=<object object>, cmap=<object object>, clim=None, skew_threshold=<object object>, ellipt_threshold=0.2, axes=None, figsize=(12.0, 9.0), recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Three-panel phase-tensor summary figure.

Panels#

(a) Ellipse pseudo-section — the full plot_phase_tensor_psection()

with all cell-size normalisations.

(b) Dimensionality classification grid — 1-D (white), 2-D (grey),

3-D (red), derived from skew_threshold and ellipt_threshold.

(c) Skew–ellipticity density hexbin — joint distribution over all

(station, period) cells, with contours at 20 / 50 / 80 % of the peak density.

param sites:

Passed directly to build_phase_tensor_table().

type sites:

any

param stations:

Restrict to a station subset (applied to all panels).

type stations:

list of str or None

param period_range:

Period window in seconds (applied to all panels).

type period_range:

(T_min, T_max) or None

param scale:

Passed to panel (a) — fraction of each cell to fill.

type scale:

float, default 0.85

param c_by:

Colour quantity for panel (a); see plot_phase_tensor_psection().

type c_by:

str, default "skew"

param cmap:

Colourmap for panel (a).

type cmap:

str, default "RdBu_r"

param clim:

Explicit colour limits for panel (a).

type clim:

(vmin, vmax) or None

param skew_threshold:

|β| threshold (°) for 1-D/2-D vs 3-D in panels (a) and (b).

type skew_threshold:

float, default 3.0

param ellipt_threshold:

Ellipticity threshold for 1-D vs 2-D in panel (b).

type ellipt_threshold:

float, default 0.2

param figsize:

type figsize:

(width, height), default (12.0, 9.0)

param recursive:

type recursive:

see ensure_sites().

param on_dup:

type on_dup:

see ensure_sites().

param strict:

type strict:

see ensure_sites().

param verbose:

type verbose:

see ensure_sites().

returns:

fig

rtype:

Figure

Parameters:
Return type:

Figure

pycsamt.emtools.tensor.phase_tensor_legend(*, size=1.0, figsize=(2.5, 2.5), ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_dimensionality_grid(sites, *, skew_th=3.0, ellipt_th=0.2, figsize=(8.5, 4.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_theta_stability_stripe(sites, *, win=5, figsize=(9.0, 4.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_skew_ellipt_density(sites, *, band=None, gridsize=40, figsize=(6.5, 5.5), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#
Parameters:
Return type:

Axes

pycsamt.emtools.tensor.plot_theta_rose_grid(sites, *, n_bands=6, axes=None, figsize=(13.0, 3.8), bins=24, style='pycsamt', panel_title_fontsize=7.5, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Phase-tensor θ rose grid — one pycsamt-styled rose per frequency decade.

Draws n_bands polar rose diagrams side by side, each covering one equal-log-width period band. Each rose applies axial symmetry (0–180° mirrored to 180–360°) and is rendered using the active RoseStyle.

Parameters:

  • sites (any) – Input accepted by ensure_sites().

  • n_bands (int, default 6) – Number of equal-log-width period bands.

  • figsize ((width, height), default (13.0, 3.8)) – Figure size in inches. Constrained layout is used internally so an external fig.suptitle fits without producing blank space.

  • bins (int, default 24) – Number of bins over 0–180° (mirrored to 360°).

  • style (str, RoseStyle, or None) – Rose visual style. Strings resolved via resolve_rose_style().

  • panel_title_fontsize (float, default 7.5) – Font size for the period-band label above each panel.

  • recursive (bool) – Passed to ensure_sites().

  • on_dup (str) – Passed to ensure_sites().

  • strict (bool) – Passed to ensure_sites().

  • verbose (int) – Passed to ensure_sites().

Return type:

matplotlib.figure.Figure

pycsamt.emtools.tensor.plot_phase_tensor_strip(sites, *, station=None, period_range=None, scale=<object object>, normalise_by=<object object>, s1_ref=None, min_aspect=<object object>, cells_per_decade=7.0, c_by=<object object>, cmap=<object object>, clim=None, clim_pct=<object object>, symmetric_clim=<object object>, edgecolor=<object object>, linewidth=<object object>, alpha=<object object>, skew_threshold=<object object>, mark_3d=<object object>, phase_ticks=(0.0, 45.0, 90.0), ylabel='', station_label=True, station_label_fontsize=8.0, title='', xlabel='', figsize=(6.0, 1.4), show_colorbar=True, colorbar_label=None, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Single-station phase-tensor ellipse strip vs period.

Draws one horizontal row of phase-tensor ellipses for a single station, one ellipse per period, in the classic “ellipse timeseries” style used e.g. by WinGLink / mtpy single-station PT plots. The y-axis carries no per-point data — it is a schematic 0°–90° phase scale (phase_ticks) used only to calibrate ellipse size by eye; the physical information (φ_max, φ_min, θ, fill colour) is identical to plot_phase_tensor_psection().

Combine several stations/profiles into the small-multiples layout (columns = profiles, rows = stations, one shared colorbar) with plot_phase_tensor_strip_grid().

Parameters:

  • sites (any) – EDI paths, glob pattern, Sites, any input accepted by ensure_sites(), or a pre-built pandas.DataFrame from build_phase_tensor_table() (already filtered to one station — in that case station may be left None).

  • station (str or None) – Station to plot. Required when sites resolves to more than one station.

  • period_range ((T_min, T_max) in seconds or None) – Restrict the period range plotted.

  • scale (see) – plot_phase_tensor_psection(). Sizing controls; normalise_by="unity" (φ=45° 1-D reference fills scale of the row) makes phase_ticks an exact scale. min_aspect floors the ellipse height so near-degenerate cells stay visible.

  • normalise_by (see) – plot_phase_tensor_psection(). Sizing controls; normalise_by="unity" (φ=45° 1-D reference fills scale of the row) makes phase_ticks an exact scale. min_aspect floors the ellipse height so near-degenerate cells stay visible.

  • s1_ref (see) – plot_phase_tensor_psection(). Sizing controls; normalise_by="unity" (φ=45° 1-D reference fills scale of the row) makes phase_ticks an exact scale. min_aspect floors the ellipse height so near-degenerate cells stay visible.

  • min_aspect (see) – plot_phase_tensor_psection(). Sizing controls; normalise_by="unity" (φ=45° 1-D reference fills scale of the row) makes phase_ticks an exact scale. min_aspect floors the ellipse height so near-degenerate cells stay visible.

  • cells_per_decade (float, default 7.0) – Visual ellipse pitch along the period axis, expressed as the number of ellipse-widths per log10 decade. Unlike plot_phase_tensor_psection() (one ellipse per station column), a period axis is typically sampled far more densely than is useful for ellipse width — sizing each ellipse to its local sample spacing would shrink it to an invisible sliver wherever sampling is dense. This value is independent of how many periods were actually measured, so ellipses overlap (by design — the classic single-station “ellipse timeseries” look) rather than shrinking as sampling gets denser.

  • c_by – Fill-colour controls; see plot_phase_tensor_psection().

  • cmap – Fill-colour controls; see plot_phase_tensor_psection().

  • clim (tuple[float, float] | None) – Fill-colour controls; see plot_phase_tensor_psection().

  • clim_pct – Fill-colour controls; see plot_phase_tensor_psection().

  • symmetric_clim – Fill-colour controls; see plot_phase_tensor_psection().

  • edgecolor (ellipse border/opacity controls.)

  • linewidth (ellipse border/opacity controls.)

  • alpha (ellipse border/opacity controls.)

  • skew_threshold (3-D cell highlighting, see) – plot_phase_tensor_psection().

  • mark_3d (3-D cell highlighting, see) – plot_phase_tensor_psection().

  • phase_ticks ((lo, mid, hi) or None, default (0.0, 45.0, 90.0)) – Tick values drawn on the schematic y-scale. None hides the y-axis entirely.

  • ylabel (str) – Y-axis label; defaults to "Phase (°)" when phase_ticks is not None.

  • station_label (bool, default True) – Annotate the station name in the upper-left corner of the axes.

  • station_label_fontsize (float, default 8.0)

  • title (str) – Axes title / x-label. xlabel defaults to "Period (s)".

  • xlabel (str) – Axes title / x-label. xlabel defaults to "Period (s)".

  • figsize ((float, float), default (6.0, 1.4)) – Figure size (ignored when ax is provided).

  • show_colorbar (bool, default True) – Attach a right-side colorbar. Set False when composing a grid with a single shared colorbar (see plot_phase_tensor_strip_grid()).

  • colorbar_label (str or None) – Override the automatic colorbar label derived from c_by.

  • recursive (see ensure_sites().)

  • on_dup (see ensure_sites().)

  • strict (see ensure_sites().)

  • verbose (see ensure_sites().)

  • ax (Axes or None) – If provided, draw into this axes and return it; otherwise create a new figure.

Returns:

ax

Return type:

Axes

Examples

>>> from pycsamt.emtools import plot_phase_tensor_strip
>>> ax = plot_phase_tensor_strip(sites, station="S1")

Fixed colour scale (for visual consistency across several calls):

>>> ax = plot_phase_tensor_strip(
...     sites, station="S1", c_by="skew", clim=(-9.0, 9.0),
... )

See also

plot_phase_tensor_strip_grid

Multi-station / multi-profile facet grid.

plot_phase_tensor_psection

Station × period pseudo-section.

pycsamt.emtools.tensor.plot_phase_tensor_strip_grid(sites, profiles, *, period_range=None, scale=<object object>, normalise_by=<object object>, s1_ref=None, min_aspect=<object object>, cells_per_decade=7.0, c_by=<object object>, cmap=<object object>, clim=None, clim_pct=<object object>, symmetric_clim=<object object>, edgecolor=<object object>, linewidth=<object object>, alpha=<object object>, skew_threshold=<object object>, mark_3d=<object object>, phase_ticks=(0.0, 45.0, 90.0), col_titles=None, xlabel='Period (s)', suptitle='', colorbar_label=None, panel_size=(4.4, 1.05), recursive=True, on_dup='replace', strict=False, verbose=0, axes=None)[source]#

Phase-tensor ellipse strips for several stations, grouped by profile.

Reproduces the classic multi-panel figure — one plot_phase_tensor_strip() row per selected station, tiled in a grid where each column is a profile/line and each row is one of the stations picked for that profile — with a single shared colorbar for the whole figure (so fill colours are comparable across every panel).

Parameters:

  • sites (any) – Input accepted by ensure_sites() covering every station referenced in profiles.

  • profiles (dict[str, list[str]]) –

    Mapping {profile_label: [station, ...]}, e.g.:

    {"Profile L1": ["S1", "S15", "S30", "S45"],
 "Profile L3": ["S1", "S4", "S7", "S11"]}

    Each list becomes one column; rows are aligned by position, not by station identity (profiles may list a different number of stations — empty cells are left blank).

  • period_range ((T_min, T_max) or None) – Restrict the period range plotted in every panel.

  • scale

  • normalise_by

  • s1_ref (float | None)

  • min_aspect

  • cells_per_decade (float)

  • c_by

  • cmap

  • clim (tuple[float, float] | None)

  • phase_ticks (tuple[float, float, float] | None)

  • col_titles (dict[str, str] | None)

  • xlabel (str)

  • suptitle (str)

  • colorbar_label (str | None)

  • panel_size (tuple[float, float])

  • recursive (bool)

  • on_dup (str)

  • strict (bool)

  • verbose (int)

  • axes (Any | None)

Return type:

Figure

:param : :param clim: :param clim_pct: :param symmetric_clim: :param edgecolor: :param linewidth: :param alpha: :param : :param skew_threshold: Forwarded to every plot_phase_tensor_strip() call; see its

docstring (and plot_phase_tensor_psection()) for details. When clim is None it is derived once from the pooled data of every listed station, so all panels share one colour scale.

Parameters:

  • mark_3d – Forwarded to every plot_phase_tensor_strip() call; see its docstring (and plot_phase_tensor_psection()) for details. When clim is None it is derived once from the pooled data of every listed station, so all panels share one colour scale.

  • phase_ticks ((lo, mid, hi) or None, default (0.0, 45.0, 90.0)) – Schematic y-scale ticks drawn on every panel.

  • col_titles (dict[str, str] or None) – Override the column title text; defaults to the profiles keys.

  • xlabel (str, default "Period (s)") – Shown once under the bottom-most panel of each column.

  • suptitle (str) – Figure-level title.

  • colorbar_label (str or None) – Override the automatic colorbar label derived from c_by.

  • panel_size ((width, height), default (4.4, 1.05)) – Per-panel size in inches; the figure size is (n_cols * width, n_rows * height).

  • recursive (see ensure_sites().)

  • on_dup (see ensure_sites().)

  • strict (see ensure_sites().)

  • verbose (see ensure_sites().)

  • axes (2-D array of Axes or None) – Pre-existing (n_rows, n_cols) axes grid to draw into (n_rows = max(len(v) for v in profiles.values()), n_cols = len(profiles)). A new figure is created when None.

  • sites (Any)

  • profiles (dict[str, list[str]])

  • period_range (tuple[float, float] | None)

  • s1_ref (float | None)

  • cells_per_decade (float)

  • clim (tuple[float, float] | None)

Returns:

fig

Return type:

Figure

Examples

>>> from pycsamt.emtools import plot_phase_tensor_strip_grid
>>> fig = plot_phase_tensor_strip_grid(
...     sites,
...     profiles={
...         "Profile L1": ["S1", "S15", "S30", "S45"],
...         "Profile L3": ["S1", "S4", "S7", "S11"],
...     },
...     c_by="skew", cmap="RdBu_r",
... )

See also

plot_phase_tensor_strip

Single-station ellipse strip (one panel).

plot_phase_tensor_psection

Station × period pseudo-section.