2.14.2.12. pycsamt.emtools.overview#

Combined single-station MT/CSAMT response overview.

plot_response_overview() reproduces the classic multi-panel MT “full response” figure (as produced by tools such as MTpy) – apparent resistivity and phase for the off-diagonal and diagonal impedance components, induction arrows, and phase-tensor ellipses, all sharing one period axis – while wiring the whole thing through pyCSAMT’s own style and view-control system (PYCSAMT_STYLE, PYCSAMT_CONTROL) so every colour, error bar, and axis convention matches the rest of emtools.

Functions

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

Single-station MT/CSAMT "full response" overview figure.

pycsamt.emtools.overview.plot_response_overview(sites, *, station=None, control=None, x_view='period', log_log_rho=<object object>, offdiag_components=('xy', 'yx'), diag_components=('xx', 'yy'), show_diag=True, phase_range=None, height_ratios=(2.0, 1.0, 1.4, 1.7), cbar_orientation='horizontal', cbar_height_ratio=0.12, cbar_pad_ratio=0.55, cbar_width_ratio=0.1, figsize=(11.0, 9.8), wspace=0.24, hspace=0.1, axes=None, colors=None, raw=False, force_style=False, show_error_bars=True, show_phase_error_bars=False, show_component_legend=True, title=None, show_arrows=True, arrow_colors=(None, None), arrow_tilt_decades=0.4, arrow_dy_scale=1.0, arrow_lw=1.3, arrow_mutation_scale=7.0, ylim_arrows=None, show_arrow_legend=True, show_ellipses=True, c_by=<object object>, cmap=<object object>, clim=None, clim_pct=<object object>, symmetric_clim=<object object>, ellipse_scale=1.5, min_aspect=<object object>, cells_per_decade=6.0, edgecolor=<object object>, linewidth=<object object>, ellipse_alpha=<object object>, skew_threshold=<object object>, mark_3d=<object object>, show_ellipse_colorbar=True, ellipse_colorbar_label=None, tick_fontsize=8, grid=True, recursive=True, on_dup='replace', strict=False, verbose=0)[source]

Single-station MT/CSAMT “full response” overview figure.

Reproduces the classic multi-panel layout used to QC a wideband MT sounding – apparent resistivity and phase for the off-diagonal (\(Z_{xy}, Z_{yx}\)) and diagonal (\(Z_{xx}, Z_{yy}\)) impedance components side by side, with induction arrows and phase-tensor ellipses spanning both columns underneath, all sharing one period/frequency axis – while going entirely through pyCSAMT’s own PYCSAMT_STYLE and PYCSAMT_CONTROL systems instead of hardcoded colours or axis conventions.

Layout (rows, top to bottom; all four data rows share the x-axis):

┌─────────────────┬─────────────────┐
│  App. Res. xy/yx │ App. Res. xx/yy │        height_ratios[0]
├─────────────────┼─────────────────┤
│  Phase xy/yx     │ Phase xx/yy     │        height_ratios[1]
├─────────────────┴─────────────────┤
│      Induction arrows (real/imag)  │        height_ratios[2]
├─────────────────────────────────────┤
│      Phase-tensor ellipse strip    │        height_ratios[3]
├─────────────────────────────────────┤
│           skew β (°) colourbar     │        cbar_height_ratio
└─────────────────────────────────────┘

The rho/phase/arrow/ellipse rows all span the full data width; the ellipse row’s colourbar lives in its own reserved row below it by default (see cbar_orientation) rather than a right-hand gutter, so it never narrows the ellipse row relative to the arrow row above it and the right margin stays free.

Every row shares one x-axis. By default (x_view = "period") that axis is a true Matplotlib log scale over raw period in seconds – the classic MT “log-log” quicklook, complete with Matplotlib’s own per-decade minor-tick grid. Apparent resistivity likewise defaults to a true log y-axis over raw \(\Omega\cdot\mathrm{m}\) values (log_log_rho), so the top row is genuinely log-log and the phase row below it (linear degrees over the same log x-axis) is genuinely semilog – both draw the dense reference-figure-style grid rather than sparse integer gridlines over pre-logged numbers. Pass x_view="log10_period" for the alternative \(\log_{10}T\,(\mathrm{s})\) linear-axis convention used elsewhere in emtools (e.g. plot_raw_sites_1d()), or x_view=None to defer entirely to control.x.view. Apparent resistivity similarly can be forced to the pre-logged \(\log_{10}\rho_a\) linear-axis convention with log_log_rho=False (then following control.rho.view), and phase follows control.phase throughout.

Parameters:

sites (Sites-like) – EDI path, glob pattern, Sites, or any input accepted by pycsamt.emtools.ensure_sites().
station (str or None) – Station to plot. Defaults to the first station (sorted by name) when sites resolves to more than one.
control (object, optional) – Plot view control. Defaults to pycsamt.api.control.PYCSAMT_CONTROL. Only control.phase (and, when log_log_rho is False, control.rho) is read directly from this object – the x-axis view is controlled separately by x_view so this function’s default log-log look does not depend on, or silently change, the shared global control’s x.view setting.
x_view (str or None, default "period") – X-axis convention for all four rows, applied as a local override on top of control (the shared control object is never mutated). One of "period", "log10_period", "frequency", "log10_frequency" (see pycsamt.api.control.FrequencyAxisControl), or None to use whatever control.x.view is already set to.
log_log_rho (bool, optional) – Force the apparent-resistivity row onto a true log y-axis over raw values (True) or the pre-logged \(\log_{10}\rho_a\)-on-linear-axis convention (False). Defaults to True when the resolved control.rho.view is "log10" (the package default) and False otherwise, so passing rho__view="linear" through control still works as expected without needing to also touch this flag.
offdiag_components ((str, str)) – Impedance components drawn (overlaid on the same axes pair) in the left and right column respectively. Any two-letter component keys accepted by PYCSAMT_STYLE.mt work here, so a TE/TM pair (("te", "tm")) is equally valid if that is how a survey was processed.
diag_components ((str, str)) – Impedance components drawn (overlaid on the same axes pair) in the left and right column respectively. Any two-letter component keys accepted by PYCSAMT_STYLE.mt work here, so a TE/TM pair (("te", "tm")) is equally valid if that is how a survey was processed.
show_diag (bool, default True) – Draw the right-hand (diag_components) column. When False the figure narrows to a single column and the arrow/ellipse rows span that one column’s width.
phase_range ((lo, hi) or None, optional) – Explicit phase display range shared by both columns. If omitted, the active control.phase policy is used (default \(\pm 180^\circ\)) – one consistent range for both columns, unlike tools that let the off-diagonal and diagonal phase axes drift to different ranges.
height_ratios ((rho, phase, arrows, ellipses), default (2.0, 1.0, 1.4, 1.7)) – Relative row heights. Apparent resistivity gets twice the phase row’s height by default (a 2:1 ratio, i.e. rho is 2/3 and phase 1/3 of the combined rho+phase height) – the conventional “big rho, small phase” look; pass e.g. (1.0, 1.0, ...) for equal rows instead.
cbar_orientation ({"horizontal", "vertical"}, default "horizontal") – Placement of the ellipse-row colourbar. "horizontal" (the default) adds it as its own thin row below the ellipse strip, spanning the full data width and freeing the right-hand margin entirely. "vertical" instead reserves a narrow gutter column to the right of every row (see cbar_width_ratio). Either way the space is reserved in the gridspec up front rather than carved out of the ellipse axes after the fact – the latter is what matplotlib.figure.Figure.colorbar()-via-divider approaches normally do, and it silently shrinks the ellipse row relative to the arrow row above it even though both still report “the same” x-limits, so a given period ends up at a different pixel column in each row. Reserving the space in advance keeps the arrow and ellipse rows pixel-aligned.
cbar_height_ratio (float, default 0.12) – Height of the horizontal colourbar row (cbar_orientation= "horizontal"), relative to the same units as height_ratios (e.g. relative to the ellipse row’s own height_ratios[3]).
cbar_pad_ratio (float, default 0.55) – Height of a blank spacer row inserted between the ellipse row and the horizontal colourbar row, in the same units as height_ratios. Needed because the ellipse row’s own x tick labels and “Period (s)” label are drawn outside its axes box, in the margin below it – with too little pad they collide with the colourbar’s own tick labels. Increase if your tick_fontsize or a custom x label still overlaps the colourbar.
cbar_width_ratio (float, default 0.10) – Width of the vertical colourbar column (cbar_orientation= "vertical"), as a fraction of one data column. Both cbar_height_ratio and cbar_width_ratio – like the rest of the reserved-space guarantee described under cbar_orientation – are ignored when axes is provided (the colourbar then falls back to narrowing the ellipse axes itself, since new gridspec rows/columns cannot be inserted into an already-built external layout).
figsize ((float, float), default (11.0, 9.8)) – Figure size (ignored when axes is provided).
wspace (float) – Column/row spacing (ignored when axes is provided).
hspace (float) – Column/row spacing (ignored when axes is provided).
axes (sequence of Axes or None) – Pre-built axes to draw into instead of creating a new figure and gridspec. Must supply, in order, the rho and phase axes for each column (2 * ncols axes, ncols=2 unless show_diag is False), followed by the arrow-row axes and the ellipse-row axes – e.g. for the default two-column layout: [ax_rho_off, ax_rho_diag, ax_phase_off, ax_phase_diag, ax_arrow, ax_ellipse]. Useful for composing this overview into a larger multi-station figure built with your own gridspec. Note the arrow/ellipse pixel-alignment guarantee described under cbar_width_ratio does not apply here – align them yourself if you supply axes.
colors (dict, optional) – Optional per-component colour overrides (keys are component letters, e.g. {"xy": "black"}). Omitted components keep their PYCSAMT_STYLE.mt colour – the package default is already the reference-figure convention (blue circles for \(Z_{xy}\), red squares for \(Z_{yx}\)).
raw (bool) – When raw=True, curves use PYCSAMT_STYLE.raw (a neutral diagnostic style) instead of per-component colours, unless force_style is also True. See plot_raw_sites_1d() for the same convention.
force_style (bool) – When raw=True, curves use PYCSAMT_STYLE.raw (a neutral diagnostic style) instead of per-component colours, unless force_style is also True. See plot_raw_sites_1d() for the same convention.
show_error_bars (bool, default True, False) – Toggle apparent-resistivity and phase error bars independently. Both use the same colour as their component’s curve (through style.errorbar_kwargs()), which is the “error bars based on that colour” behaviour.
show_phase_error_bars (bool, default True, False) – Toggle apparent-resistivity and phase error bars independently. Both use the same colour as their component’s curve (through style.errorbar_kwargs()), which is the “error bars based on that colour” behaviour.
show_component_legend (bool, default True) – Draw a small legend (component colour + marker) inside each top-row (apparent-resistivity) panel.
title (str or None) – Figure title. Defaults to the station name.
show_arrows (bool, default True) – Draw the induction-arrow row. Skipped (with a “no tipper” placeholder) when the station has no tipper data.
arrow_colors ((real, imag), default (None, None)) – Explicit colour override for the real- and imaginary-part arrows. None falls back to PYCSAMT_STYLE.mt.xy and PYCSAMT_STYLE.mt.yx respectively – the same real/imag colour convention already used by pycsamt.emtools.plot.plot_response_tipper().
arrow_tilt_decades (float, default 0.4) – Schematic horizontal fan applied to each arrow (see _draw_induction_arrow_row()); purely cosmetic separation, not a period shift.
arrow_dy_scale (float, default 1.0) – Scales the arrow’s vertical (physically meaningful) extent. Tipper magnitudes are typically O(0.01-1), so the default already matches a sensible row height; increase for a very “quiet” station or decrease if arrows overrun neighbouring rows.
arrow_lw (float) – Arrow line width and matplotlib mutation_scale (head size).
arrow_mutation_scale (float) – Arrow line width and matplotlib mutation_scale (head size).
ylim_arrows ((lo, hi) or None) – Explicit y-limits for the arrow row. Auto-scaled from the drawn arrow tips (with margin) when omitted.
show_arrow_legend (bool, default True) – Draw a “real”/”imag” legend below the arrow row.
show_ellipses (bool, default True) – Draw the phase-tensor ellipse row. Skipped (with a placeholder) when phase-tensor invariants cannot be computed for the station.
c_by
cmap
clim (tuple[float, float] | None)
clim_pct
symmetric_clim
ellipse_scale (float)
min_aspect
cells_per_decade (float)
show_ellipse_colorbar (bool)
ellipse_colorbar_label (str | None)
tick_fontsize (int)
grid (bool)
recursive (bool)
on_dup (str)
strict (bool)
verbose (int)

Return type:

Figure

:param : :param edgecolor: Phase-tensor ellipse controls – identical semantics to

pycsamt.emtools.tensor.plot_phase_tensor_strip(), defaulting to PYCSAMT_STYLE.pt_ellipse. To reproduce the classic MTpy “phimin” colouring (blue-to-orange-to-navy over \(0^\circ\)-\(90^\circ\)), pass c_by="phimin_deg", clim=(0.0, 90.0) together with a diverging colormap of your choice – note this differs from c_by="phi_min", which colours by the raw (tan-units) phase-tensor singular value instead of its arctan in degrees and saturates near one end of a 0-90 scale; the package default (c_by="skew") is the more diagnostic choice for flagging 3-D structure.

Parameters:

linewidth – Phase-tensor ellipse controls – identical semantics to pycsamt.emtools.tensor.plot_phase_tensor_strip(), defaulting to PYCSAMT_STYLE.pt_ellipse. To reproduce the classic MTpy “phimin” colouring (blue-to-orange-to-navy over \(0^\circ\)-\(90^\circ\)), pass c_by="phimin_deg", clim=(0.0, 90.0) together with a diverging colormap of your choice – note this differs from c_by="phi_min", which colours by the raw (tan-units) phase-tensor singular value instead of its arctan in degrees and saturates near one end of a 0-90 scale; the package default (c_by="skew") is the more diagnostic choice for flagging 3-D structure.
ellipse_alpha – Phase-tensor ellipse controls – identical semantics to pycsamt.emtools.tensor.plot_phase_tensor_strip(), defaulting to PYCSAMT_STYLE.pt_ellipse. To reproduce the classic MTpy “phimin” colouring (blue-to-orange-to-navy over \(0^\circ\)-\(90^\circ\)), pass c_by="phimin_deg", clim=(0.0, 90.0) together with a diverging colormap of your choice – note this differs from c_by="phi_min", which colours by the raw (tan-units) phase-tensor singular value instead of its arctan in degrees and saturates near one end of a 0-90 scale; the package default (c_by="skew") is the more diagnostic choice for flagging 3-D structure.
skew_threshold – Phase-tensor ellipse controls – identical semantics to pycsamt.emtools.tensor.plot_phase_tensor_strip(), defaulting to PYCSAMT_STYLE.pt_ellipse. To reproduce the classic MTpy “phimin” colouring (blue-to-orange-to-navy over \(0^\circ\)-\(90^\circ\)), pass c_by="phimin_deg", clim=(0.0, 90.0) together with a diverging colormap of your choice – note this differs from c_by="phi_min", which colours by the raw (tan-units) phase-tensor singular value instead of its arctan in degrees and saturates near one end of a 0-90 scale; the package default (c_by="skew") is the more diagnostic choice for flagging 3-D structure.
mark_3d – Phase-tensor ellipse controls – identical semantics to pycsamt.emtools.tensor.plot_phase_tensor_strip(), defaulting to PYCSAMT_STYLE.pt_ellipse. To reproduce the classic MTpy “phimin” colouring (blue-to-orange-to-navy over \(0^\circ\)-\(90^\circ\)), pass c_by="phimin_deg", clim=(0.0, 90.0) together with a diverging colormap of your choice – note this differs from c_by="phi_min", which colours by the raw (tan-units) phase-tensor singular value instead of its arctan in degrees and saturates near one end of a 0-90 scale; the package default (c_by="skew") is the more diagnostic choice for flagging 3-D structure.
cells_per_decade (float, default 8.0) – Visual ellipse pitch along the period axis (ellipse-widths per decade); see pycsamt.emtools.tensor.plot_phase_tensor_strip() for why this is independent of the actual sample spacing.
show_ellipse_colorbar (bool, default True) – Attach a colourbar to the ellipse row.
ellipse_colorbar_label (str or None) – Override the automatic colourbar label derived from c_by.
tick_fontsize (int, default 8) – Tick-label size shared by all rows.
grid (bool, default True) – Draw light panel grids on the rho/phase/arrow rows.
recursive (bool) – Forwarded to pycsamt.emtools.ensure_sites().
on_dup (str) – Forwarded to pycsamt.emtools.ensure_sites().
strict (bool) – Forwarded to pycsamt.emtools.ensure_sites().
verbose (int) – Forwarded to pycsamt.emtools.ensure_sites().
sites (Any)
station (str | None)
control (Any | None)
x_view (str | None)
offdiag_components (tuple[str, str])
diag_components (tuple[str, str])
show_diag (bool)
phase_range (tuple[float, float] | None)
height_ratios (tuple[float, float, float, float])
cbar_orientation (str)
cbar_height_ratio (float)
cbar_pad_ratio (float)
cbar_width_ratio (float)
figsize (tuple[float, float])
wspace (float)
hspace (float)
colors (dict[str, str] | None)
raw (bool)
force_style (bool)
show_error_bars (bool)
show_phase_error_bars (bool)
show_component_legend (bool)
title (str | None)
show_arrows (bool)
arrow_colors (tuple[str | None, str | None])
arrow_tilt_decades (float)
arrow_dy_scale (float)
arrow_lw (float)
arrow_mutation_scale (float)
ylim_arrows (tuple[float, float] | None)
show_arrow_legend (bool)
show_ellipses (bool)
clim (tuple[float, float] | None)
ellipse_scale (float)

Return type:

matplotlib.figure.Figure

Examples

>>> from pycsamt.emtools import plot_response_overview
>>> fig = plot_response_overview("data/gv_data/gv_final_edi", station="gv100")

Raw resistivity (not log10) and a “phimin”-style ellipse colouring:

>>> from pycsamt.api.control import PYCSAMT_CONTROL
>>> with PYCSAMT_CONTROL.context(rho__view="linear"):
...     fig = plot_response_overview(
...         "data/gv_data/gv_final_edi", station="gv100",
...         c_by="phimin_deg", clim=(0.0, 90.0), cmap="turbo",
...     )