pycsamt.emtools.frequency

Functions

align_grid(sites, *[, mode, ref_station, ...])
decimate_step(sites, *[, step, inplace, ...])
drop_duplicates(sites, *[, tol, inplace, ...])
drop_low_confidence_frequencies(sites, *[, ...])	Drop rows whose frequency confidence is below threshold.
edit_frequencies_by_confidence(sites, *[, ...])	Edit frequency rows and return diagnostics in one workflow.
frequency_edit_decision_table(before_sites, ...)	Return one row per original station-frequency edit decision.
frequency_edit_report(before_sites, ...[, ...])	Summarize station-level changes after frequency editing.
mask_low_confidence_frequencies(sites, *[, ...])	Set low-confidence frequency rows to NaN without changing the grid.
plot_apparent_depth_psection(sites, *[, ...])
plot_band_microstrips(sites, *[, bands, ...])
plot_coverage_quality_heatmap(sites, *[, ...])
plot_frequency_edit_decisions(before_sites, ...)	Plot dropped, masked, recovered, and kept frequency decisions.
plot_frequency_edit_summary(before_sites, ...)	Plot station-level before/after frequency-edit summary.
recover_low_confidence_frequencies(sites, *)	Recover recoverable frequency rows using trusted neighboring rows.
regrid_logspace(sites, *[, fmin, fmax, ...])
regrid_to(sites, target_freq, *[, method, ...])
select_band(sites, *[, fmin, fmax, band_hz, ...])
smooth_mavg(sites, *[, k, window, on, ...])

Classes

FrequencyEditResult(sites, report, ...)

Container returned by confidence-based frequency editing.

class pycsamt.emtools.frequency.FrequencyEditResult(sites, report, decisions, mode, method, ci_hi, ci_lo, reject, interpolation)

Bases: object

Container returned by confidence-based frequency editing.

Parameters:

• sites (Any)

• report (Any)

• decisions (Any)

• mode (str)

• method (str)

• ci_hi (float)

• ci_lo (float)

• reject (str)

• interpolation (str)

sites: Any

report: Any

decisions: Any

mode: str

method: str

ci_hi: float

ci_lo: float

reject: str

interpolation: str

property n_dropped: int

Total number of dropped station-frequency rows.

property n_masked: int

Total number of masked station-frequency rows.

property n_recovered: int

Total number of recovered station-frequency rows.

summary()

Return a compact text summary of the edit result.

Return type:

str

pycsamt.emtools.frequency.select_band(sites, *, fmin=None, fmax=None, band_hz=None, keep=None, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Parameters:

• sites (Any)

• fmin (float | None)

• fmax (float | None)

• band_hz (Sequence[float] | None)

• keep (Sequence[float] | None)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.drop_duplicates(sites, *, tol=1e-10, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Parameters:

• sites (Any)

• tol (float)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.drop_low_confidence_frequencies(sites, *, method='composite', threshold=0.5, weights=None, also='both', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Drop rows whose frequency confidence is below threshold.

The confidence scores are computed with pycsamt.emtools.qc.frequency_confidence_table(). The operation is station-aware: each station keeps or drops its own bad frequency rows. A new Sites object is returned unless inplace=True.

Parameters:

• sites (Any)

• method (str)

• threshold (float)

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

• also (str)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.mask_low_confidence_frequencies(sites, *, method='composite', threshold=0.5, weights=None, also='both', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Set low-confidence frequency rows to NaN without changing the grid.

Parameters:

• sites (Any)

• method (str)

• threshold (float)

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

• also (str)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.recover_low_confidence_frequencies(sites, *, method='composite', ci_hi=0.9, ci_lo=0.5, weights=None, interpolation='linear', reject='mask', also='both', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Recover recoverable frequency rows using trusted neighboring rows.

Rows with confidence in [ci_lo, ci_hi) are treated as recoverable and are interpolated in log-frequency from rows with confidence >= ci_hi. Rows below ci_lo are considered rejected and are either masked, dropped, or kept depending on reject.

Parameters:

• sites (Any)

• method (str)

• ci_hi (float)

• ci_lo (float)

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

• interpolation (str)

• reject (str)

• also (str)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.edit_frequencies_by_confidence(sites, *, mode='recover', before_sites=None, method='composite', threshold=0.5, ci_hi=0.9, ci_lo=0.5, weights=None, interpolation='linear', reject='drop', also='both', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0, api=None)

Edit frequency rows and return diagnostics in one workflow.

This is the high-level confidence-editing entry point. It applies one of the low-level edit strategies and immediately computes a station report and a station-frequency decision table. Use before_sites when sites is already an in-memory object and a reliable before/after comparison is required, because lower-level site editors can mutate the wrapped impedance objects while constructing the edited return value.

Parameters:

• sites (path-like, EDI-like, Sites, or sequence) – Input data to edit. Path-like inputs are normally safe to use directly because they can be loaded independently by the package. In-memory objects should be paired with before_sites when the report must preserve an untouched baseline.

• mode ({'recover', 'drop', 'mask'}, default 'recover') – Frequency-editing strategy. 'recover' interpolates recoverable rows in log-frequency and handles rejected rows according to reject. 'drop' removes rows below threshold. 'mask' keeps the frequency grid but replaces low-confidence tensor rows by missing values when the container allows it.

• before_sites (optional) – Independent baseline used only for reporting and decision tracking. If omitted, sites is used as the baseline.

• method (str, default 'composite') – Confidence metric passed to pycsamt.emtools.qc.frequency_confidence_table().

• threshold (float, default 0.50) – Confidence threshold used by mode='drop' and mode='mask'.

• ci_hi (float, default 0.90 and 0.50) – High-confidence and low-confidence limits used by mode='recover' and by the diagnostic report.

• ci_lo (float, default 0.90 and 0.50) – High-confidence and low-confidence limits used by mode='recover' and by the diagnostic report.

• weights (dict or None, default None) – Optional confidence-metric weights.

• interpolation ({'linear', 'nearest'}, default 'linear') – Interpolation strategy for recoverable rows in mode='recover'.

• reject ({'drop', 'mask', 'keep'}, default 'drop') – Handling of rows below ci_lo in mode='recover'.

• also ({'z', 'tipper', 'both'}, default 'both') – Data blocks edited when present.

• inplace (bool, default False) – Forwarded to the low-level edit function.

• recursive (bool) – Site-loading options forwarded to ensure_sites().

• on_dup (str) – Site-loading options forwarded to ensure_sites().

• strict (bool) – Site-loading options forwarded to ensure_sites().

• verbose (int) – Site-loading options forwarded to ensure_sites().

• api (bool | None)

Returns:

Edited sites together with station-level and station-frequency diagnostics.

Return type:

FrequencyEditResult

pycsamt.emtools.frequency.frequency_edit_report(before_sites, after_sites, *, method='composite', ci_hi=0.9, ci_lo=0.5, weights=None, recursive=True, on_dup='replace', strict=False, verbose=0, api=None)

Summarize station-level changes after frequency editing.

The report compares the native frequency rows and finite tensor rows before and after an edit such as dropping, masking, or recovery. It also carries the median confidence from pycsamt.emtools.qc.frequency_confidence_table().

Parameters:

• before_sites (Any)

• after_sites (Any)

• method (str)

• ci_hi (float)

• ci_lo (float)

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

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

• api (bool | None)

pycsamt.emtools.frequency.frequency_edit_decision_table(before_sites, after_sites, *, method='composite', ci_hi=0.9, ci_lo=0.5, weights=None, recursive=True, on_dup='replace', strict=False, verbose=0, api=None)

Return one row per original station-frequency edit decision.

Parameters:

• before_sites (Any)

• after_sites (Any)

• method (str)

• ci_hi (float)

• ci_lo (float)

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

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

• api (bool | None)

pycsamt.emtools.frequency.plot_frequency_edit_summary(before_sites, after_sites, *, method='composite', ci_hi=0.9, ci_lo=0.5, figsize=(9.0, 4.0), station_label_step=1, station_preset='pseudosection', station_style=None, ax=None)

Plot station-level before/after frequency-edit summary.

Parameters:

• before_sites (Any)

• after_sites (Any)

• method (str)

• ci_hi (float)

• ci_lo (float)

• figsize (tuple[float, float])

• station_label_step (int | None)

• station_preset (str)

• station_style (Any | None)

• ax (Any | None)

pycsamt.emtools.frequency.plot_frequency_edit_decisions(before_sites, after_sites, *, method='composite', ci_hi=0.9, ci_lo=0.5, figsize=(10.0, 5.0), station_label_step=1, station_preset='pseudosection', station_style=None, ax=None)

Plot dropped, masked, recovered, and kept frequency decisions.

Parameters:

• before_sites (Any)

• after_sites (Any)

• method (str)

• ci_hi (float)

• ci_lo (float)

• figsize (tuple[float, float])

• station_label_step (int | None)

• station_preset (str)

• station_style (Any | None)

• ax (Any | None)

pycsamt.emtools.frequency.regrid_to(sites, target_freq, *, method='nearest', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Parameters:

• sites (Any)

• target_freq (Sequence[float])

• method (str)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.regrid_logspace(sites, *, fmin=None, fmax=None, band_hz=None, per_decade=6, n_per_decade=None, method='nearest', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Parameters:

• sites (Any)

• fmin (float | None)

• fmax (float | None)

• band_hz (Sequence[float] | None)

• per_decade (int)

• n_per_decade (int | None)

• method (str)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.decimate_step(sites, *, step=2, inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Parameters:

• sites (Any)

• step (int)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.smooth_mavg(sites, *, k=3, window=None, on='both', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Parameters:

• sites (Any)

• k (int)

• window (int | None)

• on (str)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.align_grid(sites, *, mode='union', ref_station=None, method='nearest', inplace=False, recursive=True, on_dup='replace', strict=False, verbose=0)

Parameters:

• sites (Any)

• mode (str)

• ref_station (str | None)

• method (str)

• inplace (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

pycsamt.emtools.frequency.plot_coverage_quality_heatmap(sites, *, axis='period', figsize=(7.5, 4.5), recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)

Parameters:

• sites (Any)

• axis (str)

• figsize (tuple[float, float])

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

• ax (Axes | None)

Return type:

Axes

pycsamt.emtools.frequency.plot_apparent_depth_psection(sites, *, axis_y='period', agg='median', figsize=(7.5, 4.5), log_color=True, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)

Parameters:

• sites (Any)

• axis_y (str)

• agg (str)

• figsize (tuple[float, float])

• log_color (bool)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

• ax (Axes | None)

Return type:

Axes

pycsamt.emtools.frequency.plot_band_microstrips(sites, *, bands=None, n_bands=6, figsize=(9.0, 6.0), marker_size=16.0, recursive=True, on_dup='replace', strict=False, verbose=0, ax=None)

Parameters:

• sites (Any)

• bands (Sequence[tuple[float, float]] | None)

• n_bands (int)

• figsize (tuple[float, float])

• marker_size (float)

• recursive (bool)

• on_dup (str)

• strict (bool)

• verbose (int)

• ax (Axes | None)

Return type:

Axes