2.6. pycsamt.emtf#
Format-neutral electromagnetic transfer-function scientific core: the
EMTF document, matrix-oriented TransferFunction/StatisticalEstimate
objects, the EMTF datatype registry, EDI/EDI-SPECTRA/EMTF-XML
interoperability, and rotation/covariance transformation.
Format-neutral electromagnetic transfer-function scientific core.
- class pycsamt.emtf.EMTF(product_id=None, description=None, subtype=None, tags=<factory>, periods=None, transfer_functions=<factory>, provenance=None, copyright=None, site=None, site_layout=None, orientation=None, processing=None, quality=None, field_notes=<factory>, station=None, station_id=None, lat=None, lon=None, elev=None, azimuth=None, metadata=<factory>, attrs=<factory>)#
Bases:
MTBaseFormat-neutral electromagnetic transfer-function document.
EMTFis the scientific object that EDI and EMTF XML adapters will eventually populate. Phase 2 adds reusable metadata objects while keeping the model independent of XML parsing andpycsamt.seg.- Parameters:
product_id (str | None)
description (str | None)
subtype (str | None)
periods (Any | None)
transfer_functions (dict[str, TransferFunction])
provenance (ProvenanceMeta | None)
copyright (CopyrightInfo | None)
site (SiteMeta | None)
site_layout (SiteLayout | None)
orientation (OrientationMeta | None)
processing (ProcessingMeta | None)
quality (TransferFunctionQuality | None)
station (str | None)
lat (float | None)
lon (float | None)
elev (float | None)
azimuth (float | None)
- transfer_functions: dict[str, TransferFunction]#
- provenance: ProvenanceMeta | None = None#
- copyright: CopyrightInfo | None = None#
- site_layout: SiteLayout | None = None#
- orientation: OrientationMeta | None = None#
- processing: ProcessingMeta | None = None#
- quality: TransferFunctionQuality | None = None#
- validate()#
Normalize document state and validate attached TF period grids.
- Return type:
None
- add_transfer_function(tf, *, key=None, replace=False)#
Attach one scientific transfer function to the document.
- Parameters:
tf (TransferFunction)
key (str | None)
replace (bool)
- Return type:
- get_transfer_function(key)#
Return a TF by semantic key or registered short code.
- Parameters:
key (str)
- Return type:
TransferFunction | None
- property impedance: TransferFunction | None#
Return the matrix-oriented impedance TF.
- property tipper_tf: TransferFunction | None#
Return the matrix-oriented tipper TF.
- property Z#
Build the existing
pycsamt.z.Zcompatibility object.
- property Tip#
Build the existing
pycsamt.z.tipper.Tipperobject.
- classmethod from_xml(source, *, strict=True)#
Read an EMTF XML document through the XML adapter.
The import is intentionally local so constructing the scientific core never requires XML serialization support unless this method is called.
- classmethod from_edi(source, **kwargs)#
Convert a historical SEG EDI object or path into
EMTF.EDI SPECTRA are preferred by default when present because they retain the full information needed to recover transfer-function covariance. Pass
prefer_spectra=Falseto force the traditional impedance/tipper blocks instead. The adapter import remains local so the scientific core is independent ofpycsamt.seguntil requested.- Return type:
- classmethod from_edi_spectra(source, **kwargs)#
Recover EMTFs and full covariance directly from EDI SPECTRA.
This is the explicit Phase-8 entry point for single-station and remote-reference cross-power spectra. Any requested rotation is delegated to the format-neutral Phase-7 rotation engine.
- Return type:
- to_edi(*, on_loss='warn')#
Return an in-memory
pycsamt.seg.EDIFilerepresentation.- Parameters:
on_loss ({"warn", "raise", "ignore"}) – Policy for EMTF content that standard EDI cannot preserve.
- to_xml(*, strict=True, precision=17, pretty=True, xml_declaration=True)#
Serialize this scientific document to an EMTF XML string.
- write_xml(target, *, strict=True, precision=17, pretty=True, xml_declaration=True, encoding='utf-8')#
Write this document in EMTF XML format.
- write(target, *, format='emtf_xml', **kwargs)#
Write this document using a supported serialization format.
Phase 6 supports EMTF XML and historical SEG EDI. EDI conversion is explicit and may emit
DataLossWarningfor content that the historical format cannot represent.- Parameters:
format (str)
- rotate(angle=0.0, *, target='orthogonal', inplace=False, source_angles=None, use_legacy_edi_rotation=False, variance_policy='drop', unsupported_estimates='drop', derived_policy='drop')#
Rotate transfer functions with the format-neutral EMTF engine.
The original
SiteLayoutremains physical acquisition metadata and is never rotated. Full covariance factors are transformed consistently when present.
- exception pycsamt.emtf.EMTFRotationError#
Bases:
ValueErrorRaised when an EMTF rotation cannot be defined unambiguously.
- exception pycsamt.emtf.EMTFRotationWarning#
Bases:
UserWarningBase warning for scientifically incomplete EMTF rotations.
- exception pycsamt.emtf.ApproximateVarianceRotationWarning#
Bases:
EMTFRotationWarningWarn that variance was handled without complete covariance.
- exception pycsamt.emtf.UnsupportedEstimateRotationWarning#
Bases:
EMTFRotationWarningWarn that a statistical estimate cannot be rotated safely.
- exception pycsamt.emtf.DerivedDataRotationWarning#
Bases:
EMTFRotationWarningWarn that derived products were dropped or retained stale.
- exception pycsamt.emtf.LegacyRotationAssumptionWarning#
Bases:
EMTFRotationWarningWarn that historical EDI rotation metadata are being interpreted.
- class pycsamt.emtf.RotationMatrices(input_matrix, output_matrix, source_mode, target_mode, source_angles, target_angle)#
Bases:
objectPer-period input and output matrices used in an EMTF rotation.
- Parameters:
input_matrix (ndarray) – Array of shape
(n_period, n_input, n_input)containingU.output_matrix (ndarray) – Array of shape
(n_period, n_output, n_output)containingV.source_mode (str) – Coordinate-frame modes used to construct the matrices.
target_mode (str) – Coordinate-frame modes used to construct the matrices.
source_angles (ndarray or None) – Orthogonal source azimuth(s), in degrees clockwise from geographic north.
Nonewhen the source follows the physical site layout.target_angle (float or None) – Orthogonal target azimuth.
Nonefor site-layout targets.
- pycsamt.emtf.horizontal_rotation_matrix(theta1, theta2, target_angle)#
Return the FCU
Qtransform from two channels to an orthogonal frame.Angles are degrees clockwise from geographic north. The source channels need not be orthogonal. The matrix maps source vector components into a right-handed orthogonal coordinate frame whose x-axis has azimuth
target_angle.
- pycsamt.emtf.horizontal_inverse_rotation_matrix(theta1, theta2, target_angle)#
Return the inverse of
horizontal_rotation_matrix().The explicit formula mirrors EMTF FCU
rot2invand permits a non-orthogonal original site layout. Parallel channels are singular and therefore rejected.
- pycsamt.emtf.rotate_covariance(covariance, matrices, *, side)#
Rotate an inverse-signal or residual covariance matrix family.
- Parameters:
covariance (array-like) – Shape
(n_period, n, n).matrices (array-like) – The corresponding
UorVmatrices for every period.side ({"input", "output"}) – Descriptive validation label. Both covariance kinds use
R @ C @ R.T; the side identifies which matrix family is supplied.
- Return type:
- pycsamt.emtf.rotate_transfer_function(tf, *, source_mode, target_mode='orthogonal', target_angle=0.0, source_angles=None, site_layout=None, variance_policy='drop', unsupported_estimates='drop')#
Rotate one matrix-valued transfer function and supported estimates.
Full
INVSIGCOV+RESIDCOVfactors are rotated exactly andVARis recomputed from their diagonal products. If full covariance is absent,variance_policycontrols whetherVARis dropped, rejected, or transformed under an explicit approximation.- Parameters:
tf (TransferFunction)
source_mode (str)
target_mode (str)
target_angle (float | None)
source_angles (Any | None)
site_layout (SiteLayout | None)
variance_policy (str)
unsupported_estimates (str)
- Return type:
- pycsamt.emtf.rotate_emtf(document, angle=0.0, *, target='orthogonal', inplace=False, source_angles=None, use_legacy_edi_rotation=False, variance_policy='drop', unsupported_estimates='drop', derived_policy='drop')#
Rotate all primary transfer functions in an
EMTFdocument.- Parameters:
document (EMTF) – Source scientific document.
angle (float, optional) – Target azimuth in degrees clockwise from geographic north. Ignored for
target='sitelayout'.target ({"orthogonal", "sitelayout"}) – Coordinate frame to produce.
inplace (bool, default=False) – If
True, mutate and returndocument. The original physicalSiteLayoutobject is never modified.source_angles (scalar, array-like, mapping, optional) – Explicit orthogonal source angle(s). A mapping may provide different vectors by TF tag/code, useful for historical principal-axis EDI.
use_legacy_edi_rotation (bool, default=False) – Opt in to interpreting retained
edi_zrot/edi_trotvectors as orthogonal source frames when document-level orientation is ambiguous.variance_policy ({"drop", "raise", "independent", "fcu"}) – Behavior for
VARwhen full covariance factors are unavailable.unsupported_estimates ({"drop", "keep", "raise"}) – Policy for estimates without a defined rotation law.
derived_policy ({"drop", "keep", "raise"}) – Derived products are not rotated directly; normally they should be recomputed after rotating their primary transfer function.
- Return type:
- exception pycsamt.emtf.DataLossWarning#
Bases:
UserWarningWarning emitted when an EDI conversion cannot preserve information.
- exception pycsamt.emtf.EMTFEDIConversionError#
Bases:
ValueErrorRaised when an EDI conversion would be scientifically invalid.
- exception pycsamt.emtf.SpectraCovarianceWarning#
Bases:
UserWarningWarning emitted for recoverable SPECTRA covariance issues.
- exception pycsamt.emtf.SpectraRecoveryError#
Bases:
EdIDataErrorRaised when an exact EDI SPECTRA recovery cannot be performed.
- class pycsamt.emtf.SpectraChannelMap(hx, hy, ex, ey, hz=None, rx=None, ry=None, channel_types=())#
Bases:
objectResolved local, remote, and output channel indices.
- Parameters:
- class pycsamt.emtf.SpectraRecoveryResult(frequency, periods, transfer_functions, channel_map, used_indices, skipped_indices, avgt, rotspec, combined_residual_covariance=None, combined_output_channels=())#
Bases:
objectNumerical result of one FCU-compatible SPECTRA recovery.
- Parameters:
- transfer_functions: dict[str, TransferFunction]#
- channel_map: SpectraChannelMap#
- property impedance: TransferFunction#
- property tipper: TransferFunction | None#
- pycsamt.emtf.resolve_spectra_channels(spectra)#
Resolve FCU local/remote channel roles from SPECTRA channel order.
Historical files commonly encode remote H channels as a second
HX/HYpair. ExplicitRX/RYorRHX/RHYlabels are also accepted. When no remote pair is present, the localHX/HYpair is reused exactly as FCU does for a single-station analysis.- Parameters:
spectra (Any)
- Return type:
- pycsamt.emtf.recover_spectra_transfer_functions(spectra, *, nfreq_policy='raise', missing_policy='raise', avgt_policy='raise')#
Recover Z/T and full covariance from an EDI SPECTRA container.
The implementation mirrors EMTF FCU’s
read_edi_spectraequations. It intentionally does not rotate the spectra or the recovered TFs; Phase 7’s EMTF rotation engine performs any requested coordinate transformation.- Parameters:
- Return type:
- pycsamt.emtf.spectra_to_emtf(source, *, spectra=None, nfreq_policy='raise', missing_policy='raise', avgt_policy='raise', target_angle=None)#
Convert EDI SPECTRA to the format-neutral EMTF scientific model.
If
target_angleis supplied, the recovered full-covariance TFs are passed to the Phase-7 rotation engine; no spectra-specific rotation code is used here.
- pycsamt.emtf.edi_to_emtf(source, *, prefer_spectra=True, spectra_nfreq_policy='raise', spectra_missing_policy='raise', spectra_avgt_policy='raise')#
Convert a historical SEG EDI object/path into
EMTF.EDI SPECTRA are preferred when present because they retain enough cross-power information to recover the full inverse-signal and residual covariance matrices. Set
prefer_spectra=Falseto force the historical impedance/tipper blocks.Notes
pyCSAMT historically stores
Z.z_err = sqrt(EDI complex variance). The non-SPECTRA path therefore reconstructs EMTFVARasz_err**2exactly, preserving the EDI file’s complex-variance convention without redefining the publicZ.z_errAPI. The standard error of a real or imaginary component, when needed statistically, issqrt(VAR / 2).
- pycsamt.emtf.emtf_to_edi(document, *, on_loss='warn')#
Convert
EMTFinto an in-memory historicalEDIFile.The standard EDI representation used here stores impedance/tipper and component variances. Rich covariance matrices, arbitrary TF types, and several EMTF metadata blocks have no lossless destination;
on_losscontrols whether those reductions warn, raise, or are explicitly ignored.
- pycsamt.emtf.write_edi(obj, target, *, on_loss='warn', preserve_zero=True, stamp_headers=False, force_tipper=None, **kwargs)#
Write an
EMTForEDIFileto an exact filesystem target.Existing
EDIFile.write()behavior remains unchanged by default. This neutral adapter opts intopreserve_zero=Trueso finite physical zeros are not turned into the EDI missing-value sentinel during format conversion; NaN/Inf values are still serialized as the sentinel.
- pycsamt.emtf.emtf_to_bundle(document)#
Return a backward-compatible
TFBundleview of an EMTF document.
- class pycsamt.emtf.TransferFunction(name, data, input_channels=<factory>, output_channels=<factory>, units=None, periods=None, estimates=<factory>, attrs=<factory>)#
Bases:
MTBaseRepresent one matrix-valued electromagnetic transfer function.
The canonical array layout is
(n_period, n_output_channels, n_input_channels). The matrix axes retain physical channel meaning, unlike EDI’s disconnected component blocks. No EDI or XML syntax is stored in this object.- Parameters:
- estimates: dict[str, StatisticalEstimate]#
- validate()#
Normalize and validate matrix, channels, periods, and estimates.
- Return type:
None
- property definition: DataTypeDefinition | None#
Return the registry definition associated with this TF.
- add_estimate(estimate, *, key=None, replace=False)#
Attach a statistical estimate to this transfer function.
- Parameters:
estimate (StatisticalEstimate)
key (str | None)
replace (bool)
- Return type:
- get_estimate(key)#
Return an attached estimate by key, code, or semantic kind.
- Parameters:
key (str)
- Return type:
StatisticalEstimate | None
- copy()#
Return a detached copy of data, periods, estimates, and attrs.
- Return type:
- class pycsamt.emtf.StatisticalEstimate(name, data, kind, units=None, attrs=<factory>)#
Bases:
PyCSAMTObjectRepresent a frequency-indexed statistical estimate.
The object deliberately stores the estimate as supplied instead of coercing all uncertainty information into the legacy
z_errmodel. This is essential for later support of full covariance matrices.- Parameters:
name (str) – Short code, e.g.
"VAR"or"RESIDCOV".data (array-like) – Numerical estimate. Real and complex arrays are supported.
kind (str) – Semantic name such as
"variance"or"inverse_signal_covariance".units (str or None) – Units when defined.
attrs (dict) – Additional non-serialization-specific metadata.
- validate()#
Normalize and validate the estimate in place.
- Return type:
None
- copy()#
Return a detached copy of the estimate.
- Return type:
- class pycsamt.emtf.DataTypeDefinition(name, tag, data_kind, input_kind=None, output_kind=None, units=None, intention='primary', description='', derived_from=None, aliases=<factory>, see_also=<factory>)#
Bases:
PyCSAMTObjectDescribe one electromagnetic transfer-function data type.
- Parameters:
name (str) – Short EMTF/FCU code, for example
"Z"or"T".tag (str) – Stable semantic key, for example
"impedance".data_kind ({"real", "complex"}) – Numerical representation of the data.
input_kind (str or None) – Broad channel families used by EMTF (typically
"H"or"E"). Scalar derived products may omit these values.output_kind (str or None) – Broad channel families used by EMTF (typically
"H"or"E"). Scalar derived products may omit these values.units (str or None) – Native units recorded by the format definition.
intention ({"primary", "derived"}) – Whether the quantity is measured/estimated as a primary TF or derived from another response.
description (str) – Human-readable description.
derived_from (str or None) – Semantic tag of the parent quantity for derived products.
aliases (tuple of str) – Alternate historical codes accepted for lookup. These are useful because the 2020 EMTF paper and FCU v4.1 differ for a few names (for example Q/P versus ZI/TI).
- pycsamt.emtf.register_emtf_datatype(definition, *, overwrite=False)#
Register and return an EMTF data-type definition.
The semantic
tagis the unique registry identity. Short names can be shared by compatible variants (notably full and off-diagonal impedance), therefore the first short-name registration remains the default lookup unlessoverwrite=Trueis explicitly requested.- Parameters:
definition (DataTypeDefinition)
overwrite (bool)
- Return type:
- pycsamt.emtf.get_emtf_datatype(key)#
Return a registered definition by semantic tag, code, or alias.
- Parameters:
key (str)
- Return type:
DataTypeDefinition | None
- pycsamt.emtf.list_emtf_datatypes(*, intention=None)#
Return a copy of registered data types keyed by semantic tag.
- Parameters:
intention (str | None)
- Return type:
- class pycsamt.emtf.EMTFXMLReader(*, strict=True)#
Bases:
PyCSAMTObjectRead EMTF XML without routing the document through EDI.
- Parameters:
strict (bool, default=True) – In strict mode malformed scientific content raises
EMTFXMLParseError. In permissive mode recoverable problems are warned about and the reader preserves as much content as possible.
- exception pycsamt.emtf.EMTFXMLParseError#
Bases:
ValueErrorRaised when an EMTF XML document cannot be interpreted safely.
- exception pycsamt.emtf.EMTFXMLWarning#
Bases:
UserWarningWarning emitted for recoverable EMTF XML inconsistencies.
- pycsamt.emtf.read_emtf_xml(source, *, strict=True)#
Convenience wrapper around
EMTFXMLReader.
- class pycsamt.emtf.EMTFXMLSerializer(*, strict=True, precision=17)#
Bases:
PyCSAMTObjectBuild a deterministic EMTF XML element tree from an
EMTF.- Parameters:
strict (bool, default=True) – Reject unsupported or scientifically ambiguous content. Permissive mode warns and omits only the problematic component.
precision (int, default=17) – Significant decimal digits used for floating-point response data. Seventeen digits are sufficient to round-trip IEEE float64 values.
- exception pycsamt.emtf.EMTFXMLSerializationError#
Bases:
ValueErrorRaised when an EMTF object cannot be serialized safely.
- exception pycsamt.emtf.EMTFXMLWriteWarning#
Bases:
UserWarningWarning emitted when permissive XML writing omits unsafe content.
- class pycsamt.emtf.EMTFXMLWriter(*, strict=True, precision=17, pretty=True)#
Bases:
PyCSAMTObjectSerialize
EMTFdocuments as EMTF XML.- Parameters:
- to_element(document)#
Return a serialized root element.
- dumps(document, *, xml_declaration=True, encoding='utf-8')#
Return a Unicode EMTF XML document.
- pycsamt.emtf.write_emtf_xml(document, target, *, strict=True, precision=17, pretty=True, xml_declaration=True, encoding='utf-8')#
Convenience wrapper around
EMTFXMLWriter.
2.6.1. Core Scientific Model#
|
Document-level electromagnetic transfer-function scientific container. |
|
Matrix-oriented electromagnetic transfer-function scientific objects. |
|
Statistical estimate objects used by the format-neutral EMTF core. |
|
Registry of EMTF primary and derived electromagnetic data types. |
|
Validation helpers for the format-neutral EMTF scientific model. |
|
Shared constants for the format-neutral EMTF scientific core. |
2.6.2. Rotation and Covariance#
|
Format-neutral EMTF rotation and covariance transformations. |
2.6.3. EDI and TFBundle Interoperability#
|
Explicit conversion between SEG EDI and the format-neutral EMTF model. |
|
FCU-compatible recovery of EMTFs from historical EDI SPECTRA. |
|
Small explicit wrappers for EMTF <-> TFBundle interoperability. |
2.6.4. EMTF XML#
|
EMTF XML -> format-neutral |
|
Filesystem/stream writer for the EMTF XML serializer. |
|
EMTF scientific objects -> deterministic XML element trees. |
|
Low-level, namespace-safe helpers for EMTF XML parsing. |
|
Constants used by the EMTF XML reader. |