pycsamt.metadata.quality

pycsamt.metadata.quality

Data-quality assessment for MT impedance sites.

DataQuality is a first-class object that captures the coverage, validity, and signal-to-noise ratio of every impedance component at a single station. assess_collection() computes quality for an entire Sites collection and returns a DataFrame suitable for reporting, filtering, or upstream ML pipelines.

Quality thresholds

Flag	Coverage	Meaning
GOOD	≥ 0.90	suitable for inversion
PARTIAL	0.50 – 0.90	use with care
POOR	0.01 – 0.50	likely noisy / incomplete
MISSING	0.00	component absent

Quick start

from pycsamt.metadata.quality import DataQuality, assess_collection

# single site
dq = DataQuality.from_site(site)
print(dq.overall)          # QualityFlag.GOOD / PARTIAL / POOR / MISSING
print(dq.summary())

# collection
df = assess_collection(sites)    # pandas DataFrame

Functions

assess_collection(sites)	Compute DataQuality for every site in sites.
quality_dataframe(sites, *[, api])	Return a pandas.DataFrame with one quality row per station.

Classes

ComponentQuality(name, coverage, n_valid, ...)	Quality metrics for a single impedance component.
DataQuality(station, n_freq[, freq_min, ...])	Data-quality summary for a single MT station.
QualityFlag(*values)	Data-quality classification for one component or a whole station.

class pycsamt.metadata.quality.QualityFlag(*values)

Bases: str, Enum

Data-quality classification for one component or a whole station.

Variables:

• GOOD ("good") – Coverage ≥ 90 %; component is reliable for inversion.

• PARTIAL ("partial") – 50 % ≤ coverage < 90 %; component has significant gaps.

• POOR ("poor") – 0 % < coverage < 50 %; component is largely missing or noisy.

• MISSING ("missing") – Zero finite values; component is absent.

GOOD = 'good'

PARTIAL = 'partial'

POOR = 'poor'

MISSING = 'missing'

classmethod from_coverage(coverage)

Return the flag that matches coverage (0–1).

Parameters:

coverage (float)

Return type:

QualityFlag

property rank: int

Numeric severity rank (0 = worst, 3 = best).

classmethod worst(flags)

Return the worst (lowest-rank) flag in flags.

Parameters:

flags (list[QualityFlag])

Return type:

QualityFlag

classmethod best(flags)

Return the best (highest-rank) flag in flags.

Parameters:

flags (list[QualityFlag])

Return type:

QualityFlag

class pycsamt.metadata.quality.ComponentQuality(name, coverage, n_valid, n_total, snr_mean=None, snr_std=None)

Bases: object

Quality metrics for a single impedance component.

Parameters:

• name (str) – Component label: "Zxx", "Zxy", "Zyx", "Zyy", or "Tipper".

• coverage (float) – Fraction of finite values in the frequency range (0–1).

• n_valid (int) – Number of frequencies with finite values.

• n_total (int) – Total number of frequencies.

• flag (QualityFlag) – Auto-computed classification from coverage.

• snr_mean (float, optional) – Mean signal-to-noise ratio (dB) when available.

• snr_std (float, optional) – Standard deviation of the SNR (dB) when available.

Examples

cq = ComponentQuality.from_array("Zxy", z_arr)
print(cq.flag)          # QualityFlag.GOOD
print(cq.pct_str)       # "100%"

name: str

coverage: float

n_valid: int

n_total: int

flag: QualityFlag

snr_mean: float | None = None

snr_std: float | None = None

property pct_str: str

Coverage as a formatted percentage string.

classmethod from_array(name, arr, snr=None)

Compute quality from a raw array.

Parameters:

• name (str) – Component label.

• arr (array-like or None) – Raw complex or real impedance values; shape (n,) or (n, 2, 2) (only the relevant component is expected).

• snr (array-like, optional) – Per-frequency SNR values in dB (same length as arr).

Return type:

ComponentQuality

to_dict()

Return type:

dict[str, Any]

class pycsamt.metadata.quality.DataQuality(station, n_freq, freq_min=None, freq_max=None, components=<factory>)

Bases: object

Data-quality summary for a single MT station.

Parameters:

• station (str) – Station identifier.

• n_freq (int) – Total number of frequencies.

• freq_min (float, optional) – Minimum frequency (Hz).

• freq_max (float, optional) – Maximum frequency (Hz).

• components (list of ComponentQuality) – Per-component quality records.

• overall (QualityFlag) – Worst flag across all present components (auto-computed).

Examples

dq = DataQuality.from_site(site)
print(dq.overall)
print(dq.get("Zxy").coverage)
df_row = dq.to_dict()

station: str

n_freq: int

freq_min: float | None = None

freq_max: float | None = None

components: list[ComponentQuality]

overall: QualityFlag

classmethod from_site(site)

Build a DataQuality from a Site-like object.

Accepts any object exposing .name, .freq, .z, and .tipper (as per SiteMixin).

Parameters:

site (Any)

Return type:

DataQuality

classmethod from_edi(edi_path)

Build from a spectra/impedance EDI file path.

Parameters:

edi_path (Any)

Return type:

DataQuality

get(name)

Return ComponentQuality for name, or None.

Parameters:

name (str)

Return type:

ComponentQuality | None

property z_components: list[ComponentQuality]

Return only the Z-tensor component records.

property has_tipper: bool

property mean_coverage: float

Mean coverage across all components that have data.

summary()

Return a compact multi-line summary.

Return type:

str

to_dict()

Return type:

dict[str, Any]

pycsamt.metadata.quality.assess_collection(sites)

Compute DataQuality for every site in sites.

Parameters:

sites (Any) – Iterable of Site-like objects (e.g. Sites).

Return type:

list of DataQuality

pycsamt.metadata.quality.quality_dataframe(sites, *, api=None)

Return a pandas.DataFrame with one quality row per station.

Columns: station, n_freq, freq_min, freq_max, overall, mean_coverage, and one cov_<component> column per impedance component.

Parameters:

• sites (Any)

• api (bool | None)

Return type:

Any