2.7.7.2. pycsamt.airborne.ztem.adapter#

Array-to-scientific-object adapter contract for ZTEM products.

ZTEM is represented as the standard vertical magnetic transfer function (tipper), while acquisition geometry records that the airborne Hz output is referenced to fixed ground Hx/Hy measurements. No proprietary native file schema is assumed here.

Shape/frequency/mask normalization that is not specific to the ZTEM tipper layout is delegated to pycsamt.airborne.validation (shared with pycsamt.airborne.mobilemt and, once it moves onto the same helpers, pycsamt.airborne.afmag) via its error_cls parameter, so every ZTEMValidationError raised here still comes from this module even though the check itself is not reimplemented per technology.

Functions

build_ztem_dataset(name, lines, *[, survey, ...])

Build a common airborne dataset from constructed ZTEM lines.

build_ztem_emtf(tipper, *[, frequency, ...])

Build one sample-level EMTF ZTEM response.

build_ztem_line(line_id, navigation, tipper, ...)

Build one ZTEM flight line from decoded sample-aligned arrays.

build_ztem_record(sample_id, tipper, *[, ...])

Build one airborne record from decoded ZTEM tipper values.

validate_ztem_transfer_function(tf)

Validate and return a ZTEM 1x2 vertical magnetic tipper.

Exceptions

ZTEMValidationError

Raised when decoded ZTEM scientific arrays are inconsistent.
exception pycsamt.airborne.ztem.adapter.ZTEMValidationError[source]

Bases: ValueError

Raised when decoded ZTEM scientific arrays are inconsistent.

pycsamt.airborne.ztem.adapter.validate_ztem_transfer_function(tf)[source]

Validate and return a ZTEM 1x2 vertical magnetic tipper.

Parameters:

tf (TransferFunction) – Transfer function to validate in place.

Returns:

tf, unchanged, for convenient chaining after add_transfer_function().

Return type:

TransferFunction

Raises:

  • TypeError – If tf is not a TransferFunction.

  • ZTEMValidationError – If tf does not use the standard EMTF tipper datatype with Hx/Hy inputs, Hz output, and matrix shape (1, 2).

pycsamt.airborne.ztem.adapter.build_ztem_emtf(tipper, *, frequency=None, periods=None, units='[]', variance=None, inverse_signal_covariance=None, residual_covariance=None, product_id=None, description=None, reference_station=None, system_spec=None, site=None, orientation=None, processing=None, attrs=None)[source]

Build one sample-level EMTF ZTEM response.

Parameters:

  • tipper (array-like) – Complex (Tzx, Tzy) values with shape (nf, 2) or canonical EMTF shape (nf, 1, 2). A single (2,) vector is accepted.

  • frequency (array-like, optional) – Exactly one positive frequency or period vector must be supplied.

  • periods (array-like, optional) – Exactly one positive frequency or period vector must be supplied.

  • variance (array-like, optional) – Component variance with shape (nf, 1, 2).

  • inverse_signal_covariance (array-like, optional) – Input covariance factor S with shape (nf, 2, 2).

  • residual_covariance (array-like, optional) – Output residual covariance N with shape (nf, 1, 1).

  • units (str | None)

  • product_id (str | None)

  • description (str | None)

  • reference_station (ZTEMReferenceStation | None)

  • system_spec (ZTEMSystemSpec | None)

  • site (SiteMeta | None)

  • orientation (OrientationMeta | None)

  • processing (ProcessingMeta | None)

  • attrs (Mapping[str, Any] | None)

Return type:

EMTF

Notes

ZTEM reuses the standard EMTF tipper datatype. The technology-specific distinction is acquisition geometry: airborne Hz is related to fixed ground-reference Hx and Hy. No line-axis orientation is inferred.

pycsamt.airborne.ztem.adapter.build_ztem_record(sample_id, tipper, *, frequency=None, periods=None, fields=None, quality=None, record_attrs=None, **emtf_kwargs)[source]

Build one airborne record from decoded ZTEM tipper values.

Parameters:

  • sample_id (str) – Navigation sample identifier for the new record.

  • tipper (array-like) – Forwarded to build_ztem_emtf().

  • frequency (array-like, optional) – Exactly one must be supplied; forwarded to build_ztem_emtf().

  • periods (array-like, optional) – Exactly one must be supplied; forwarded to build_ztem_emtf().

  • fields (dict, optional) – Forwarded to AirborneEMRecord.

  • quality (dict, optional) – Forwarded to AirborneEMRecord.

  • record_attrs (dict, optional) – Forwarded to AirborneEMRecord.

  • **emtf_kwargs – Forwarded to build_ztem_emtf().

Returns:

The record, with its EMTF product_id defaulted to str(sample_id) unless overridden in emtf_kwargs.

Return type:

AirborneEMRecord

pycsamt.airborne.ztem.adapter.build_ztem_line(line_id, navigation, tipper, *, frequency, record_mask=None, variance=None, inverse_signal_covariance=None, residual_covariance=None, units='[]', reference_station=None, system_spec=None, orientation=None, attrs=None)[source]

Build one ZTEM flight line from decoded sample-aligned arrays.

Parameters:

  • line_id (str) – Flight-line identifier.

  • navigation (NavigationTrack) – Sample-aligned navigation defining the line’s sample axis.

  • tipper (array-like) – Forwarded to _sample_axis_tipper(); accepts the per-sample analogues of every shape _normalize_tipper() accepts for one sample.

  • frequency (array-like) – Either one shared (nf,) vector or a per-sample (n_samples, nf) grid; see resolve_line_frequency_grid().

  • record_mask (array-like of bool, optional) – Marks which navigation samples get an attached record; None means every sample does. Samples excluded here never need a valid tipper/frequency row – navigation points are never deleted to represent a rejected EM sample.

  • variance (Any | None)

  • inverse_signal_covariance (Any | None)

  • residual_covariance (Any | None)

  • array-like – Per-sample statistical estimates, each shaped (n_samples, nf, *tail) (or unbatched when n_samples == 1); forwarded per sample to build_ztem_record().

  • optional – Per-sample statistical estimates, each shaped (n_samples, nf, *tail) (or unbatched when n_samples == 1); forwarded per sample to build_ztem_record().

  • units (str, optional) – Forwarded to build_ztem_emtf() for every sample.

  • reference_station (optional) – Forwarded to build_ztem_emtf() for every sample.

  • system_spec (optional) – Forwarded to build_ztem_emtf() for every sample.

  • orientation (optional) – Forwarded to build_ztem_emtf() for every sample.

  • attrs (dict, optional) – Line-level extension metadata; "technology" and "reference_station" are set here unless already present.

Returns:

The line, with one record per sample where record_mask (or its default) is True.

Return type:

AirborneEMLine

Raises:

  • TypeError – If navigation is not a NavigationTrack.

  • ZTEMValidationError – If tipper, frequency, record_mask, or any statistical estimate does not match its expected shape.

pycsamt.airborne.ztem.adapter.build_ztem_dataset(name, lines, *, survey=None, system_spec=None, instrument_serial=None, software_version='', attrs=None)[source]

Build a common airborne dataset from constructed ZTEM lines.

Parameters:

  • name (str) – Dataset/survey name.

  • lines (iterable of AirborneEMLine, or mapping of str to AirborneEMLine) – Lines to attach, typically previously built by build_ztem_line().

  • survey (SurveyMeta, optional) – Survey-level metadata.

  • system_spec (ZTEMSystemSpec, optional) – Used to build the dataset’s instrument metadata; defaults to published nominal values.

  • instrument_serial (str, optional) – Forwarded to ZTEMSystemSpec.to_instrument_meta().

  • software_version (str, optional) – Forwarded to ZTEMSystemSpec.to_instrument_meta().

  • attrs (dict, optional) – Dataset-level extension metadata; "technology" and "ztem_system" are set here unless already present.

Returns:

The dataset, with every line attached via add_line().

Return type:

AirborneEMDataset

Raises:

  • TypeError – If survey, system_spec, or an entry of lines has the wrong type.

  • ZTEMValidationError – If a line is explicitly tagged with a different technology.