pycsamt.emtools.qc#

Quality-control confidence ratios for EM transfer functions.

The composite confidence ratio (CR) used by this module is a bounded, weighted score:

CR = sum_k w_k s_k / sum_k w_k, for finite component scores s_k.

The default components are data coverage, tensor uncertainty, off-diagonal consistency, diagonal leakage, phase smoothness, and spatial coherence. Each score is clipped to [0, 1], where 1 is most trustworthy. The default manuscript classes are CR >= 0.95 (safe), 0.85 <= CR < 0.95 (recoverable/marginal), and CR < 0.85 (reject/review).

Functions

build_qc_table(sites, *[, include_skew, ...])

confidence_ratio(scores, *[, weights, ...])

Compute the composite confidence ratio from diagnostic scores.

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

Return frequency-level confidence scores for EM stations.

overlay_noise_cone(ax, period, lo, hi, *[, ...])

Overlay lower and upper noise envelopes on an existing period axis.

overlay_spectral_holes(ax, sites, *[, ...])

Highlight gaps in spectral coverage on an existing QC plot.

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

Plot line-wide confidence statistics for each period sample.

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

Profile confidence-ratio (CR) scatter plot along the survey line.

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

Plot cross-station response consistency as a fan diagram.

plot_coverage_psection(sites, *[, metric, ...])

Plot frequency coverage and data availability as a pseudosection.

plot_frequency_confidence_psection(sites, *)

Plot frequency confidence as a station-period pseudo-section.

plot_qc_quicklook(sites, *[, axes, figsize, ...])

Create a compact multi-panel quality-control summary for a survey.

plot_snr_hist(sites, *[, bins, figsize, ...])

Plot the distribution of signal-to-noise ratios across survey data.

plot_station_confidence_dashboard(sites, *)

Plot a 2-by-3 confidence dashboard for one station.

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

Plot confidence components versus period for one station.

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

Map XY/YX crossover behaviour across stations and frequencies.

qc_flags(sites, *[, min_frac_ok, ...])

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

Return station-level confidence scores for EM transfer functions.
pycsamt.emtools.qc.build_qc_table(sites, *, include_skew=True, recursive=True, on_dup='replace', strict=False, verbose=0, api=None)[source]#
Parameters:
Return type:

Any

pycsamt.emtools.qc.confidence_ratio(scores, *, weights=None, n_freq=1, return_error=False)[source]#

Compute the composite confidence ratio from diagnostic scores.

The confidence ratio is a weighted finite-score mean:

\[\mathrm{CR} = \frac{\sum_k w_k s_k \mathbf{1}_{s_k\ finite}} {\sum_k w_k \mathbf{1}_{s_k\ finite}}, \qquad 0 \leq s_k \leq 1.\]

The default score vector is coverage, uncertainty, offdiag, diagonal, phase, spatial with weights 0.35, 0.20, 0.15, 0.10, 0.10, 0.10. Missing scores are ignored and all finite scores are clipped to [0, 1].

The optional error is the population spread of available component scores; when only one score is available it falls back to the binomial standard error sqrt(CR * (1 - CR) / n_freq).

Parameters:
Return type:

float | tuple[float, float]

pycsamt.emtools.qc.frequency_confidence_table(sites, *, method='composite', weights=None, ci_hi=0.95, ci_lo=0.85, relerr_threshold=0.2, offdiag_tolerance_log10=0.35, diagonal_leakage_max=0.35, phase_jump_tolerance_deg=90.0, spatial_tolerance_log10=0.6, spacing_m=200.0, recursive=True, on_dup='replace', strict=False, verbose=0, api=None)[source]#

Return frequency-level confidence scores for EM stations.

The returned table has one row for each station-frequency sample. It is designed as a reusable quality-control source for plots, masking rules, and inversion-preparation reports. method="presence" scores only finite impedance-tensor availability. method="composite" combines coverage, tensor uncertainty, off-diagonal consistency, diagonal leakage, phase smoothness, and same-frequency spatial coherence.

Parameters:
Return type:

Any

pycsamt.emtools.qc.plot_confidence_band_summary(sites, *, method='composite', ci_hi=0.95, ci_lo=0.85, figsize=(8.0, 4.0), spacing_m=200.0, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Plot line-wide confidence statistics for each period sample.

Parameters:
Return type:

Axes

pycsamt.emtools.qc.plot_confidence_profile(sites, *, method='presence', ci_hi=0.95, ci_lo=0.85, shade_recoverable=True, shade_mode='score', annotate_low=True, station_labels=True, station_label_step=None, show_errorbars=True, smart_ylim=True, ylim=None, weights=None, spacing_m=200.0, figsize=(9.0, 4.0), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Profile confidence-ratio (CR) scatter plot along the survey line.

Reproduces the Fig. 3 style from Kouadio et al. (2024): one dot per station coloured green (CR >= ci_hi), pink (ci_lo <= CR < ci_hi), or red (CR < ci_lo), with dashed threshold lines.

With method="presence", CR is the fraction of frequencies with a valid finite Z tensor. With method="composite", CR combines coverage, tensor uncertainty, off-diagonal consistency, diagonal leakage, phase smoothness, and neighbor coherence.

Parameters:

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

  • ci_hi (float) – Upper CR threshold (default 0.95, “safe”, green).

  • ci_lo (float) – Lower CR threshold (default 0.85, “recoverable”, pink).

  • shade_recoverable (bool) – If True, draw an interval cue for stations below ci_hi.

  • shade_mode ({"score", "full", "none"}) – "score" draws compact vertical intervals tied to each station point. "full" preserves the older full-height station shading. "none" disables station interval shading.

  • station_label_step (int or None) – Gap between visible station labels on the top axis. None chooses a readable spacing automatically while keeping all station tick marks.

  • show_errorbars (bool) – If True, draw the station-level confidence uncertainty returned by station_confidence_table().

  • smart_ylim (bool) – If True, zoom the lower y-limit when every station confidence is above ci_lo so small departures from the safe threshold remain visible.

  • ylim (tuple of float or None) – Explicit y-axis limits. Overrides smart_ylim when provided.

  • spacing_m (float) – Fallback station spacing [m] used when no coordinate metadata is available on the EDI objects.

  • figsize (tuple) – Figure size when a new figure is created.

  • 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) – Axes to draw on; created if None.

  • method (str)

  • annotate_low (bool)

  • station_labels (bool)

  • weights (dict[str, float] | None)

Returns:

ax

Return type:

matplotlib.axes.Axes

pycsamt.emtools.qc.plot_frequency_confidence_psection(sites, *, method='composite', ci_hi=0.95, ci_lo=0.85, metric='confidence', cmap='RdYlGn', section='dynamic', figsize=None, station_label_step=None, station_preset='pseudosection', station_style=None, spacing_m=200.0, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Plot frequency confidence as a station-period pseudo-section.

Parameters:
Return type:

Axes

pycsamt.emtools.qc.plot_station_confidence_dashboard(sites, *, station=None, method='composite', ci_hi=0.95, ci_lo=0.85, axes=None, figsize=(10.5, 6.0), spacing_m=200.0, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#

Plot a 2-by-3 confidence dashboard for one station.

The dashboard separates the final confidence score from the diagnostic components used to build it, avoiding the visual crowding of a single overlay axis.

Parameters:
Return type:

Figure

pycsamt.emtools.qc.plot_station_confidence_spectrum(sites, *, station=None, method='composite', ci_hi=0.95, ci_lo=0.85, figsize=(7.0, 4.0), spacing_m=200.0, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)[source]#

Plot confidence components versus period for one station.

Parameters:
Return type:

Axes

pycsamt.emtools.qc.qc_flags(sites, *, min_frac_ok=0.6, min_snr_med=2.0, max_skew_med=6.0, recursive=True, on_dup='replace', strict=False, verbose=0)[source]#
Parameters:
Return type:

DataFrame

pycsamt.emtools.qc.station_confidence_table(sites, *, method='composite', weights=None, relerr_threshold=0.2, offdiag_tolerance_log10=0.35, diagonal_leakage_max=0.35, phase_jump_tolerance_deg=90.0, spatial_tolerance_log10=0.6, spacing_m=200.0, recursive=True, on_dup='replace', strict=False, verbose=0, api=None)[source]#

Return station-level confidence scores for EM transfer functions.

method="presence" reproduces the legacy criterion based only on finite tensor rows. method="composite" combines several station trust indicators: finite data coverage, tensor uncertainty when error tensors exist, off-diagonal consistency, diagonal leakage, phase smoothness, and spatial coherence with neighboring stations.

Parameters:
Return type:

Any