pycsamt.transformers._base#

Classes

TransformerMixin()

Template utilities for AVG/J -> EDI transformations.

class pycsamt.transformers._base.TransformerMixin[source]#

Bases: MTBase

Template utilities for AVG/J -> EDI transformations.

This module defines TransformerMixin, a light template that standardizes the steps needed to convert foreign transfer-function containers (e.g. Zonge AVG or Jones J) into EDI files or collections.

The mixin focuses on finalization of a neutral payload (pycsamt.core.base.TFBundle): validating the station name, ordering and de-duplicating frequencies, and optionally filling missing pieces (Z vs rho/phase) according to user config.

Notes

Subclasses provide the data plumbing:

TransformerMixin.extract() pulls a TFBundle out of the source object or file.
TransformerMixin.emit_edi() builds an EDI object from the finalized bundle.
TransformerMixin.post_emit() can attach metadata or perform small last-mile fixes.

The default hooks for filling missing parts are no-ops. Backends can override TransformerMixin.compute_res_from_z() and TransformerMixin.compute_z_from_res().

Subclasses implement the data path while this mixin handles standard finalization steps on a TFBundle:

Validate or synthesize the station name using the global policy.
Order frequencies per config (asc/desc).
De-duplicate nearly equal frequencies using a relative tolerance.
Optionally fill missing parts (Z vs rho/phase) via overridable hooks.

Finalization obeys the global configuration from pycsamt.core.config. In particular:

freq_order controls sorting.
freq_tol controls de-duplication.
compute_res_from_z and compute_z_from_res toggle filling behavior.

See also

pycsamt.core.transformers.AVGtoEDI: Concrete AVG → EDI/EDICollection converter.
pycsamt.core.transformers.JtoEDI: Concrete J → EDI/EDICollection converter.
pycsamt.core.base.TFBundle: Neutral payload used across backends.
pycsamt.core.config: Global configuration and frequency policies.

Examples

A minimal custom transformer:

>>> from pycsamt.core._transformers import TransformerMixin
>>> from pycsamt.core.base import TFBundle
>>>
>>> class MyX(TransformerMixin):
...     def extract(self, source):
...         # pull TF data from source into a bundle
...         return TFBundle(freq=[1.0], rho=[100.], phase=[45.])
...     def emit_edi(self, bundle):
...         # return an EDI-like stub for illustration
...         return {'freq': bundle.freq, 'rho': bundle.rho}
...
>>> out = MyX().transform(object())
>>> isinstance(out, dict)
True

References

extract(source)[source]#

Extract a TFBundle from source.

This is the ingest step. Implementors parse the foreign object (or file path) and return a neutral bundle. Keep the method free of side effects.

Parameters:: source (Any) – Backend-specific object or path.
Returns:: A bundle containing frequencies and transfer functions.
Return type:: TFBundle
Raises:: NotImplementedError – Must be provided by subclasses.

Notes

Prefer leaving station naming and frequency manipulation to the mixin. Provide raw content here.

emit_edi(bundle)[source]#

Materialize an EDI object from a finalized bundle.

This is the emit step. Implementors build and return an EDI object (or a compatible stub).

Must be provided by subclasses.

Notes

Do not attempt to reorder frequencies here. The bundle has already been finalized by _finalize().

Parameters:: bundle (TFBundle)
Return type:: Any

post_emit(edi_obj, source, bundle)[source]#

Optional last-mile adjustments after EDI creation.

Use this hook to enrich the EDI object with auxiliary metadata (e.g. site location, elevation) that is awkward to thread through earlier steps.

Parameters:

edi_obj (Any) – The EDI object returned by emit_edi().
source (Any) – The original source object used in extract().
bundle (TFBundle) – The finalized bundle.

Returns:

The potentially modified EDI object.

Return type:

Any

Notes

The default implementation returns edi_obj unmodified.

compute_res_from_z(b)[source]#

Compute apparent resistivity/phase from Z.

This hook is called by _fill_missing() when compute_res_from_z is True in the global config, and the bundle holds Z but lacks (rho, phase).

Parameters:: b (TFBundle) – Input bundle.
Returns:: The updated bundle (may be the same instance).
Return type:: TFBundle

Notes

The default implementation is a no-op. Subclasses may override to apply the standard MT relations [1] [2].

compute_z_from_res(b)[source]#

Reconstruct Z from apparent resistivity/phase.

This hook is called by _fill_missing() when compute_z_from_res is True in the global config, and the bundle lacks Z but holds (rho, phase).

Parameters:: b (TFBundle) – Input bundle.
Returns:: The updated bundle (may be the same instance).
Return type:: TFBundle

Notes

The default implementation is a no-op. Subclasses may override to apply physically consistent reconstruction.

transform(source, *, name=None, station_id=None)[source]#

One-shot transform: extract → finalize → emit → post.

This orchestrates the whole conversion pipeline:

extract() to build a TFBundle.
_finalize() to normalize the bundle.
emit_edi() to create the EDI object.
post_emit() for optional enrichment.

Parameters:

source (Any) – Source object or file path.
name (str, optional) – Preferred station name override.
station_id (str or int, optional) – Identifier used if a name must be synthesized.

Returns:

The resulting EDI object (or compatible subtype).

Return type:

Any

Examples

>>> from pycsamt.core._transformers import TransformerMixin
>>> class Mini(TransformerMixin):
...     def extract(self, s):
...         from pycsamt.core.base import TFBundle
...         return TFBundle(freq=[1.], rho=[100.], phase=[45.])
...     def emit_edi(self, b):
...         return {'ok': True, 'n': len(b.freq)}
...
>>> Mini().transform(object())['ok']
True