2.7.6.2. pycsamt.airborne.afmag.adapter#

Scientific adapter contracts for historical and tensor AFMAG products.

No native vendor/archive parser is defined here. The module accepts decoded arrays and maps two distinct AFMAG generations into the common pyCSAMT model:

original comparator AFMAG -> scalar line-direction tilt response;
tensor AFMAG / AirMt -> 3 x 2 interstation magnetic transfer function plus the optional rotationally invariant amplification parameter.

Shape/frequency/mask/metadata normalization that is not specific to either AFMAG generation is delegated to pycsamt.airborne.validation (shared with pycsamt.airborne.mobilemt and pycsamt.airborne.ztem) via its error_cls parameter, so every AFMAGValidationError raised here still comes from this module even though the check itself is not reimplemented per technology. build_original_afmag_* and build_airmt_* remain genuinely separate below them, because the two AFMAG generations are scientifically distinct responses (a real scalar tilt versus a complex 3x2 interstation tensor), not two configurations of one response.

Functions

`build_airmt_dataset`(name, lines, *[, ...])	Build a common airborne dataset for tensor AFMAG/AirMt lines.
`build_airmt_emtf`(tensor, *[, frequency, ...])	Build one sample-level tensor AFMAG/AirMt `EMTF` response.
`build_airmt_line`(line_id, navigation, ...[, ...])	Build one tensor-AFMAG/AirMt flight line from decoded arrays.
`build_airmt_record`(sample_id, tensor, *[, ...])	Build one airborne record from decoded tensor AFMAG/AirMt data.
`build_original_afmag_dataset`(name, lines, *)	Build a common airborne dataset for original AFMAG lines.
`build_original_afmag_emtf`(tilt, *[, ...])	Build one historical comparator-AFMAG scalar tilt response.
`build_original_afmag_line`(line_id, ...[, ...])	Build one historical comparator-AFMAG flight line.
`build_original_afmag_record`(sample_id, tilt, *)	Build one record from a historical AFMAG tilt response.
`compute_airmt_amplification_parameter`(tensor, *)	Compute the AirMt rotation-invariant complex amplification parameter.
`validate_airmt_transfer_function`(tf)	Validate and return an AirMt 3 x 2 interstation magnetic TF.
`validate_original_afmag_tilt`(tf)	Validate and return an original AFMAG scalar tilt response.

Exceptions

AFMAGValidationError

Raised when decoded AFMAG scientific arrays are inconsistent.

exception pycsamt.airborne.afmag.adapter.AFMAGValidationError[source]

Bases: ValueError

Raised when decoded AFMAG scientific arrays are inconsistent.

pycsamt.airborne.afmag.adapter.compute_airmt_amplification_parameter(tensor, *, zero_policy='nan')[source]

Compute the AirMt rotation-invariant complex amplification parameter.

For the two column vectors T1 and T2 of a 3 x 2 magnetic transfer function, the implemented patent formulation is:

Kvec = T1 x T2
AP = Kvec . Re(Kvec) / |Re(Kvec)|

Parameters:

tensor (array-like) – One (3, 2) or (3, 3) matrix, or a family with those trailing dimensions. The patent parameter uses the first two column vectors in either case.
zero_policy ({"nan", "raise"}) – Behavior when |Re(Kvec)| is zero. Such a sample has no defined projection direction for this parameter.

Returns:

Complex AP with shape equal to the leading tensor dimensions.

Return type:

numpy.ndarray

pycsamt.airborne.afmag.adapter.validate_airmt_transfer_function(tf)[source]

Validate and return an AirMt 3 x 2 interstation magnetic TF.

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.
AFMAGValidationError – If tf does not use the standard EMTF interstation TI/interstation_transfer_functions datatype with Hx/Hy inputs, Hx/Hy/Hz outputs, and matrix shape (3, 2).

pycsamt.airborne.afmag.adapter.validate_original_afmag_tilt(tf)[source]

Validate and return an original AFMAG scalar tilt response.

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.
AFMAGValidationError – If tf does not use the afmag_tilt datatype, is not scalar (no input/output channels, matrix shape (1, 1)), or carries a non-zero imaginary component.

pycsamt.airborne.afmag.adapter.build_airmt_emtf(tensor, *, frequency=None, periods=None, units='[]', variance=None, inverse_signal_covariance=None, residual_covariance=None, include_amplification_parameter=True, amplification_zero_policy='nan', product_id=None, description=None, reference_station=None, system_spec=None, site=None, orientation=None, processing=None, attrs=None)[source]

Build one sample-level tensor AFMAG/AirMt EMTF response.

Parameters:

tensor (array-like) – Complex interstation magnetic transfer function with shape (nf, 3, 2), or one (3, 2) matrix for a single frequency.
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, 3, 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, 3, 3).
include_amplification_parameter (bool, default True) – Whether to also attach the derived airmt_amplification_parameter transfer function; see compute_airmt_amplification_parameter().
amplification_zero_policy ({"nan", "raise"}, default "nan") – Forwarded to compute_airmt_amplification_parameter().
reference_station (AFMAGReferenceStation, optional) – Fixed ground reference metadata; folded into EMTF.processing and EMTF.attrs["afmag"] (see _processing_for_reference()).
system_spec (AirMtSystemSpec, optional) – System-description metadata; defaults to published nominal values.
units (str | None)
product_id (str | None)
description (str | None)
site (SiteMeta | None)
orientation (OrientationMeta | None)
processing (ProcessingMeta | None)
attrs (Mapping[str, Any] | None)

Returns:

Document carrying the interstation_transfer_functions (TI) transfer function and, unless disabled, the derived amplification parameter.

Return type:

EMTF

Raises:

AFMAGValidationError – If tensor, frequency/periods, or any statistical estimate does not match its expected shape.
TypeError – If system_spec, reference_station, site, or orientation has the wrong type.

pycsamt.airborne.afmag.adapter.build_airmt_record(sample_id, tensor, *, frequency=None, periods=None, fields=None, quality=None, record_attrs=None, **emtf_kwargs)[source]

Build one airborne record from decoded tensor AFMAG/AirMt data.

Parameters:

sample_id (str) – Navigation sample identifier for the new record.
tensor (array-like) – Forwarded to build_airmt_emtf().
frequency (array-like, optional) – Exactly one must be supplied; forwarded to build_airmt_emtf().
periods (array-like, optional) – Exactly one must be supplied; forwarded to build_airmt_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_airmt_emtf().

Returns:

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

Return type:

AirborneEMRecord

pycsamt.airborne.afmag.adapter.build_airmt_line(line_id, navigation, tensor, *, frequency, record_mask=None, variance=None, inverse_signal_covariance=None, residual_covariance=None, units='[]', include_amplification_parameter=True, reference_station=None, system_spec=None, orientation=None, attrs=None)[source]

Build one tensor-AFMAG/AirMt flight line from decoded arrays.

Parameters:

line_id (str) – Flight-line identifier.
navigation (NavigationTrack) – Sample-aligned navigation defining the line’s sample axis.
tensor (array-like) – Line-batched interstation tensor. For n_samples == 1, a single (3, 2) matrix or one (nf, 3, 2) stack is also accepted (n_frequency is not known in advance, unlike normalize_sample_axis_array()’s contract); for n_samples > 1, the canonical (samples, nf, 3, 2) shape is required directly.
frequency (array-like) – Either one shared (nf,) vector or a per-sample (n_samples, nf) grid; see _line_frequency_rows().
record_mask (array-like of bool, optional) – Marks which navigation samples get an attached record; None means every sample does.
variance (Any | None)
inverse_signal_covariance (Any | None)
residual_covariance (Any | None)
array-like – Per-sample statistical estimates, each shaped (n_samples, nf, *tail); forwarded per sample to build_airmt_record().
optional – Per-sample statistical estimates, each shaped (n_samples, nf, *tail); forwarded per sample to build_airmt_record().
include_amplification_parameter (bool, default True) – Forwarded to build_airmt_emtf() for every sample.
units (optional) – Forwarded to build_airmt_emtf() for every sample.
reference_station (optional) – Forwarded to build_airmt_emtf() for every sample.
system_spec (optional) – Forwarded to build_airmt_emtf() for every sample.
orientation (optional) – Forwarded to build_airmt_emtf() for every sample.
attrs (dict, optional) – Line-level extension metadata; "technology" is set to "AirMt" here.

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.
AFMAGValidationError – If tensor, frequency, record_mask, or any statistical estimate does not match its expected shape.

pycsamt.airborne.afmag.adapter.build_airmt_dataset(name, lines, *, survey=None, system_spec=None, instrument_serial=None, attrs=None)[source]

Build a common airborne dataset for tensor AFMAG/AirMt lines.

Parameters:

name (str) – Dataset/survey name.
lines (iterable of AirborneEMLine) – Lines to attach, typically previously built by build_airmt_line().
survey (SurveyMeta, optional) – Survey-level metadata; defaults to SurveyMeta(name=name, method="AEM").
system_spec (AirMtSystemSpec, optional) – Used to build the dataset’s instrument metadata; defaults to published nominal values.
instrument_serial (str, optional) – Forwarded to AirMtSystemSpec.to_instrument_meta().
attrs (dict, optional) – Dataset-level extension metadata; "technology" is set to "AirMt" here.

Returns:

The dataset, with every line attached.

Return type:

AirborneEMDataset

Raises:

TypeError – If system_spec has the wrong type, or an entry of lines is not an AirborneEMLine (this is enforced by AirborneEMDataset construction, unlike build_ztem_dataset(), which checks explicitly beforehand and additionally rejects a line tagged with a conflicting technology; this function does not perform that second, stricter check).

pycsamt.airborne.afmag.adapter.build_original_afmag_emtf(tilt, *, frequency=None, periods=None, response_kind='tilt_angle', units=None, variance=None, product_id=None, description=None, system_spec=None, site=None, orientation=None, attrs=None)[source]

Build one historical comparator-AFMAG scalar tilt response.

response_kind='tilt_angle' represents a calibrated tilt angle and defaults to degrees. 'comparator_deflection' preserves an archival instrument deflection without pretending it is an angle; units should then be supplied when known.

Parameters:

tilt (array-like) – Real-valued tilt/deflection response, scalar or shape (nf,).
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.
response_kind (str, default "tilt_angle") – Either "tilt_angle" (a calibrated angle, defaulting to degrees) or "comparator_deflection" (a raw archival instrument deflection with no implied angular unit).
variance (array-like, optional) – Real-valued response variance, scalar or shape (nf,) / (nf, 1, 1).
system_spec (OriginalAFMAGSystemSpec, optional) – System-description metadata; defaults to published nominal values.
units (str | None)
product_id (str | None)
description (str | None)
site (SiteMeta | None)
orientation (OrientationMeta | None)
attrs (Mapping[str, Any] | None)

Returns:

Document carrying the afmag_tilt transfer function.

Return type:

EMTF

Raises:

AFMAGValidationError – If tilt, frequency/periods, or variance does not match its expected shape.
ValueError – If response_kind is not a recognized value.
TypeError – If system_spec, site, or orientation has the wrong type.

pycsamt.airborne.afmag.adapter.build_original_afmag_record(sample_id, tilt, *, frequency=None, periods=None, fields=None, quality=None, record_attrs=None, **emtf_kwargs)[source]

Build one record from a historical AFMAG tilt response.

Parameters:

sample_id (str) – Navigation sample identifier for the new record.
tilt (array-like) – Forwarded to build_original_afmag_emtf().
frequency (array-like, optional) – Exactly one must be supplied; forwarded to build_original_afmag_emtf().
periods (array-like, optional) – Exactly one must be supplied; forwarded to build_original_afmag_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_original_afmag_emtf().

Returns:

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

Return type:

AirborneEMRecord

pycsamt.airborne.afmag.adapter.build_original_afmag_line(line_id, navigation, tilt, *, frequency, record_mask=None, response_kind='tilt_angle', units=None, variance=None, system_spec=None, orientation=None, attrs=None)[source]

Build one historical comparator-AFMAG flight line.

Parameters:

line_id (str) – Flight-line identifier.
navigation (NavigationTrack) – Sample-aligned navigation defining the line’s sample axis.
tilt (array-like) – Line-batched real tilt/deflection response, shape (n_samples, nf) (or unbatched when n_samples == 1).
frequency (array-like) – Either one shared (nf,) vector or a per-sample (n_samples, nf) grid; see _line_frequency_rows().
record_mask (array-like of bool, optional) – Marks which navigation samples get an attached record; None means every sample does.
response_kind (optional) – Forwarded to build_original_afmag_emtf() for every sample.
units (optional) – Forwarded to build_original_afmag_emtf() for every sample.
variance (array-like, optional) – Per-sample response variance, shape (n_samples, nf).
system_spec (optional) – Forwarded to build_original_afmag_emtf() for every sample.
orientation (optional) – Forwarded to build_original_afmag_emtf() for every sample.
attrs (dict, optional) – Line-level extension metadata; "technology" is set to "AFMAG" here.

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.
AFMAGValidationError – If tilt, frequency, record_mask, or variance does not match its expected shape.

pycsamt.airborne.afmag.adapter.build_original_afmag_dataset(name, lines, *, survey=None, system_spec=None, instrument_serial=None, attrs=None)[source]

Build a common airborne dataset for original AFMAG lines.

Parameters:

name (str) – Dataset/survey name.
lines (iterable of AirborneEMLine) – Lines to attach, typically previously built by build_original_afmag_line().
survey (SurveyMeta, optional) – Survey-level metadata; defaults to SurveyMeta(name=name, method="AEM").
system_spec (OriginalAFMAGSystemSpec, optional) – Used to build the dataset’s instrument metadata; defaults to published nominal values.
instrument_serial (str, optional) – Forwarded to OriginalAFMAGSystemSpec.to_instrument_meta().
attrs (dict, optional) – Dataset-level extension metadata; "technology" is set to "AFMAG" here.

Returns:

The dataset, with every line attached.

Return type:

AirborneEMDataset

Raises:

TypeError – If system_spec has the wrong type, or an entry of lines is not an AirborneEMLine; see build_airmt_dataset() for how this differs from the ZTEM/MobileMT dataset builders.