2.5.1.8. 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.
`QualityComment`(text[, author])	Free-text transfer-function quality comment with optional author.
`QualityFlag`(*values)	Data-quality classification for one component or a whole station.
`TransferFunctionQuality`([rating, ...])	Archival quality assessment attached to an EM transfer function.

class pycsamt.metadata.quality.QualityFlag(*values)[source]

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)[source]

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

Parameters:: coverage (float)
Return type:: QualityFlag

property rank: int[source]: Numeric severity rank (0 = worst, 3 = best).

classmethod worst(flags)[source]

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

Parameters:: flags (list[QualityFlag])
Return type:: QualityFlag

classmethod best(flags)[source]

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)[source]

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[source]: Coverage as a formatted percentage string.

classmethod from_array(name, arr, snr=None)[source]

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()[source]

Return type:: dict[str, Any]

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

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)[source]

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)[source]

Build from a spectra/impedance EDI file path.

Parameters:: edi_path (Any)
Return type:: DataQuality

get(name)[source]

Return ComponentQuality for name, or None.

Parameters:: name (str)
Return type:: ComponentQuality | None

property z_components: list[ComponentQuality][source]: Return only the Z-tensor component records.

property has_tipper: bool[source]

property mean_coverage: float[source]: Mean coverage across all components that have data.

summary()[source]

Return a compact multi-line summary.

Return type:: str

to_dict()[source]

Return type:: dict[str, Any]

pycsamt.metadata.quality.assess_collection(sites)[source]

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)[source]

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

class pycsamt.metadata.quality.QualityComment(text, author=None)[source]

Bases: PyCSAMTObject

Free-text transfer-function quality comment with optional author.

Parameters:

text (str)
author (str | None)

text: str

author: str | None = None

validate()[source]

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:: None

class pycsamt.metadata.quality.TransferFunctionQuality(rating=None, good_from_period=None, good_to_period=None, comments=<factory>, warning_flag=None, warnings=<factory>, extra=<factory>)[source]

Bases: PyCSAMTObject

Archival quality assessment attached to an EM transfer function.

This class intentionally does not replace DataQuality. DataQuality is a pyCSAMT-computed coverage/SNR assessment, whereas TransferFunctionQuality preserves expert/archive metadata such as the EMTF 0–5 rating, accepted period range, warning flag, and comments.

Parameters:

rating (int | None)
good_from_period (float | None)
good_to_period (float | None)
comments (list[QualityComment])
warning_flag (int | None)
warnings (list[QualityComment])
extra (dict[str, Any])

rating: int | None = None

good_from_period: float | None = None

good_to_period: float | None = None

comments: list[QualityComment]

warning_flag: int | None = None

warnings: list[QualityComment]

extra: dict[str, Any]

validate()[source]

Validate object state.

Subclasses can override this hook. The base implementation intentionally accepts all states.

Return type:: None

property has_warning: bool[source]: Return whether an archive warning is explicitly present.

property rating_label: str | None[source]: Return the conventional EMTF rating interpretation.