2.6.1.1. pycsamt.emtf.document#

Document-level electromagnetic transfer-function scientific container.

Classes

EMTF([product_id, description, subtype, ...])

Format-neutral electromagnetic transfer-function document.
class pycsamt.emtf.document.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>)[source]

Bases: MTBase

Format-neutral electromagnetic transfer-function document.

EMTF is 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 and pycsamt.seg.

Parameters:
product_id: str | None = None
description: str | None = None
subtype: str | None = None
tags: tuple[str, ...]
periods: Any | None = None
transfer_functions: dict[str, TransferFunction]
provenance: ProvenanceMeta | None = None
copyright: CopyrightInfo | None = None
site: SiteMeta | None = None
site_layout: SiteLayout | None = None
orientation: OrientationMeta | None = None
processing: ProcessingMeta | None = None
quality: TransferFunctionQuality | None = None
field_notes: dict[str, Any]
station: str | None = None
station_id: str | int | None = None
lat: float | None = None
lon: float | None = None
elev: float | None = None
azimuth: float | None = None
metadata: dict[str, Any]
attrs: dict[str, Any]
validate()[source]

Normalize document state and validate attached TF period grids.

Return type:

None

property frequency: ndarray | None[source]

Return the document frequency vector in Hz when available.

property n_periods: int[source]

Return the common number of period samples when known.

add_transfer_function(tf, *, key=None, replace=False)[source]

Attach one scientific transfer function to the document.

Parameters:
Return type:

EMTF

get_transfer_function(key)[source]

Return a TF by semantic key or registered short code.

Parameters:

key (str)

Return type:

TransferFunction | None

property impedance: TransferFunction | None[source]

Return the matrix-oriented impedance TF.

property tipper_tf: TransferFunction | None[source]

Return the matrix-oriented tipper TF.

property z: ndarray | None[source]

Return the impedance array for legacy-style access.

property z_err: ndarray | None[source]

Return legacy standard errors when explicitly available.

property tipper: ndarray | None[source]

Return tipper data in the pyCSAMT (n, 1, 2) shape.

property tipper_err: ndarray | None[source]

Return legacy tipper standard errors when available.

property rho: ndarray | None[source]

Return stored apparent resistivity, or derive it from Z.

property phase: ndarray | None[source]

Return stored impedance phase, or derive it from Z.

property Z[source]

Build the existing pycsamt.z.Z compatibility object.

property Tip[source]

Build the existing pycsamt.z.tipper.Tipper object.

classmethod from_xml(source, *, strict=True)[source]

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.

Parameters:

strict (bool)

Return type:

EMTF

classmethod from_edi(source, **kwargs)[source]

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=False to force the traditional impedance/tipper blocks instead. The adapter import remains local so the scientific core is independent of pycsamt.seg until requested.

Return type:

EMTF

classmethod from_edi_spectra(source, **kwargs)[source]

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:

EMTF

to_edi(*, on_loss='warn')[source]

Return an in-memory pycsamt.seg.EDIFile representation.

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

Serialize this scientific document to an EMTF XML string.

Parameters:
Return type:

str

write_xml(target, *, strict=True, precision=17, pretty=True, xml_declaration=True, encoding='utf-8')[source]

Write this document in EMTF XML format.

Parameters:
write(target, *, format='emtf_xml', **kwargs)[source]

Write this document using a supported serialization format.

Phase 6 supports EMTF XML and historical SEG EDI. EDI conversion is explicit and may emit DataLossWarning for 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')[source]

Rotate transfer functions with the format-neutral EMTF engine.

The original SiteLayout remains physical acquisition metadata and is never rotated. Full covariance factors are transformed consistently when present.

Parameters:

  • angle (float | None)

  • target (str)

  • inplace (bool)

  • use_legacy_edi_rotation (bool)

  • variance_policy (str)

  • unsupported_estimates (str)

  • derived_policy (str)

Return type:

EMTF

is_empty()[source]

Return True when no transfer-function content is attached.

Return type:

bool

to_bundle()[source]

Return a backward-compatible TFBundle view.

Return type:

TFBundle

classmethod from_bundle(bundle)[source]

Build an EMTF document from a legacy/generalized bundle.

Parameters:

bundle (TFBundle)

Return type:

EMTF