2.7.7.1. pycsamt.airborne.ztem#

ZTEM scientific adapter contract.

The module maps decoded ZTEM tipper values into the existing EMTF T transfer function and common airborne containers. It intentionally does not invent a proprietary native file reader.

class pycsamt.airborne.ztem.ZTEMSystemSpec(practical_frequency_range_hz=(22.0, 720.0), common_processed_bands_hz=((30.0, 720.0), (25.0, 600.0)), typical_frequency_count=(5, 6), time_series_sampling_rate_hz=2000.0, nominal_output_rate_hz=2.5, input_channels=('Hx', 'Hy'), output_channels=('Hz', ), attrs=<factory>)

Bases: CoreObject

Published/declared ZTEM system characteristics.

The values are informative defaults. ZTEM frequency selection depends on platform speed, sampling, signal strength, and noise, so processed survey products may legitimately use a different subset or frequency grid; nothing here constrains build_ztem_emtf()’s accepted input.

Parameters:

  • practical_frequency_range_hz ((float, float), optional) – Published practical frequency band in Hz, (low, high) with 0 < low < high. See practical_frequency_mask().

  • common_processed_bands_hz (tuple of (float, float), optional) – Commonly published processed sub-bands in Hz; each validated the same way as practical_frequency_range_hz.

  • typical_frequency_count ((int, int), optional) – Typical minimum/maximum count of processed frequency windows, (low, high) with 0 < low <= high.

  • time_series_sampling_rate_hz (float, optional) – Published raw time-series sampling rate in Hz.

  • nominal_output_rate_hz (float, optional) – Published processed-output rate in Hz.

  • input_channels ((str, str), default ("Hx", "Hy")) – Fixed ground-reference horizontal magnetic input channels; must equal ("Hx", "Hy").

  • output_channels ((str,), default ("Hz",)) – Fixed airborne vertical magnetic output channel; must equal ("Hz",).

  • attrs (dict, optional) – Free-form extension metadata.

Raises:

ValueError – If any frequency range/band/count is not finite and correctly ordered, if any rate is not finite and positive, or if input_channels/output_channels differ from their fixed values.

practical_frequency_range_hz: tuple[float, float] = (22.0, 720.0)
common_processed_bands_hz: tuple[tuple[float, float], ...] = ((30.0, 720.0), (25.0, 600.0))
typical_frequency_count: tuple[int, int] = (5, 6)
time_series_sampling_rate_hz: float = 2000.0
nominal_output_rate_hz: float = 2.5
input_channels: tuple[str, ...] = ('Hx', 'Hy')
output_channels: tuple[str, ...] = ('Hz',)
attrs: dict[str, Any]
validate()

Normalize and range-check every descriptive field in place.

Return type:

None

practical_frequency_mask(frequency)

Return a mask for values inside the published practical band.

Parameters:

frequency (Any)

Return type:

ndarray

to_instrument_meta(*, serial=None, software_version='')

Return reusable instrument metadata without vendor guesses.

Only a magnetic_sensor is populated – electric_sensor stays None because ZTEM’s tipper geometry has no electric channel, unlike MobileMT’s admittance (see to_instrument_meta()).

Parameters:

  • serial (str | None)

  • software_version (str)

Return type:

InstrumentMeta

class pycsamt.airborne.ztem.ZTEMReferenceStation(station_id=None, site=None, magnetic_channels=('Hx', 'Hy'), attrs=<factory>)

Bases: CoreObject

Fixed ground magnetic reference station used by ZTEM processing.

Passed to build_ztem_emtf() to populate processing’s remote-reference metadata; see _processing_for_reference().

Parameters:

  • station_id (str, optional) – Explicit reference-station identifier. Falls back to site.preferred_name through preferred_id when omitted; see normalize_optional_identifier().

  • site (SiteMeta, optional) – Reference-station location/identity metadata.

  • magnetic_channels ((str, str), default ("Hx", "Hy")) – Fixed horizontal magnetic channels measured at the reference station; must equal ("Hx", "Hy").

  • attrs (dict, optional) – Free-form extension metadata.

Raises:
station_id: str | None = None
site: SiteMeta | None = None
magnetic_channels: tuple[str, str] = ('Hx', 'Hy')
attrs: dict[str, Any]
validate()

Normalize the identifier/channels and type-check site.

Return type:

None

property preferred_id: str | None

Return explicit station ID, then the SiteMeta preferred name.

exception pycsamt.airborne.ztem.ZTEMValidationError

Bases: ValueError

Raised when decoded ZTEM scientific arrays are inconsistent.

pycsamt.airborne.ztem.validate_ztem_transfer_function(tf)

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.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)

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.build_ztem_record(sample_id, tipper, *, frequency=None, periods=None, fields=None, quality=None, record_attrs=None, **emtf_kwargs)

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.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)

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.build_ztem_dataset(name, lines, *, survey=None, system_spec=None, instrument_serial=None, software_version='', attrs=None)

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.