pycsamt.transformers.spectra#

Transform SEG Spectra-format EDI files to MT-impedance EDI files.

The core operation is:

Spectra EDI → Z (impedance) + Tipper → Impedance EDI

This module exposes SpectraToEDI, the canonical transformer for this conversion. It accepts flexible input (single file, list of files, directory, EDIFile, or EDICollection) and always returns an EDICollection — even for single-site inputs.

Quick start#

from pycsamt.transformers import SpectraToEDI

# --- single file ---
col = SpectraToEDI().transform("site_spectra.edi")
col[0].write(savepath="output/")

# --- whole directory ---
col = SpectraToEDI().transform("spectra_dir/", output_dir="imp_edis/")

# --- with error propagation and tipper ---
col = SpectraToEDI(estimate_error=True, verbose=1).transform(
    "spectra_dir/",
    output_dir="imp_edis/",
)

# --- inspect failures ---
result = SpectraToEDI().transform_batch("spectra_dir/")
for r in result.failures:
    print(r.source, r.error)

Spectra → Z math#

Per frequency f, the impedance tensor is estimated as:

Z(f) = S_EH(f) · S_HH⁻¹(f)

where S_EH is the electric–magnetic cross-spectral matrix and S_HH is the magnetic auto-spectral block. The tipper is:

T(f) = S_ZH(f) · S_HH⁻¹(f)

Both are computed by to_Z().

Classes

`SpectraToEDI`(*[, e_labels, h_labels, ridge, ...])	Transform SEG spectra-EDI files to MT-impedance EDI files.
`TransformResult`(collection[, failures])	Outcome of a batch spectra→impedance conversion.

class pycsamt.transformers.spectra.SpectraToEDI(*, e_labels=('EX', 'EY'), h_labels=('HX', 'HY'), ridge=None, estimate_error=False, dof=None, use_remote=False, station_suffix='', skip_errors=True, verbose=0)[source]#

Bases: TransformerMixin

Transform SEG spectra-EDI files to MT-impedance EDI files.

The transformer calls from_file() on each input file, then to_edi() to recover Z and, when a vertical-magnetic channel is present, the tipper. All successfully converted files are collected into a single EDICollection.

Parameters:

e_labels (tuple of str, default ("EX", "EY")) – Electric-channel type labels used to identify E-field channels in the spectra block.
h_labels (tuple of str, default ("HX", "HY")) – Horizontal magnetic-channel type labels.
ridge (float, optional) – Tikhonov regularisation added to the magnetic block before inversion. Useful for numerically ill-conditioned spectra. None (default) applies no regularisation.
estimate_error (bool, default False) – Propagate 1-σ impedance uncertainties into >ZXX.VAR / >ZXY.VAR / … blocks using first-order complex-Wishart error propagation.
dof (float or ndarray, optional) – Effective degrees of freedom per frequency, forwarded to to_Z(). When None, the transformer tries to infer DoF from spectra metadata (segnum, avgt, bw).
use_remote (bool, default False) – When both local and remote electric channels are present, set True to select the remote reference.
station_suffix (str, default "") – Appended to the station name of every converted EDI. Use "_IMP" to reproduce the HBH03 → HBH03_IMP convention.
skip_errors (bool, default True) – If True, per-file conversion failures are caught, logged, and included in TransformResult.failures without aborting the batch. Set to False to raise on first error.
verbose (int, default 0) – Verbosity level. 1 prints per-file progress; 2 adds debug detail.

Examples

Single file:

col = SpectraToEDI().transform("HBH03.edi")
ed  = col[0]
ed.write(savepath="output/")

Directory, write to disk:

col = SpectraToEDI(estimate_error=True, station_suffix="_IMP").transform(
    "spectra_dir/",
    output_dir="imp_edis/",
)
print(len(col), "station(s) converted")

Batch with failure report:

result = SpectraToEDI(skip_errors=True).transform_batch(
    "spectra_dir/",
    output_dir="imp_edis/",
)
print(f"{result.n_ok} ok,  {result.n_fail} failed")

Force a station-name override for a single file:

col = SpectraToEDI().transform("site.edi", station_name="CUSTOM_01")

See also

pycsamt.seg.spectra.Spectra.to_Z: Underlying Z / tipper estimation.
pycsamt.seg.spectra.Spectra.to_edi: Single-file spectra → EDIFile conversion.
pycsamt.transformers.AVGtoEDI: Analogous transformer for Zonge AVG files.
pycsamt.transformers.JtoEDI: Analogous transformer for Jones J files.

transform(source, *, output_dir=None, station_name=None)[source]#

Transform one or multiple spectra EDIs to impedance EDIs.

Parameters:

source (path-like, EDIFile, EDICollection, Spectra, or list) –
Accepts:
- A single .edi file path (str / Path).
- A directory — all *.edi files inside are processed.
- A EDIFile that holds a spectra section (its .path is used for the source metadata).
- A EDICollection.
- A pre-loaded Spectra object.
- A list of any of the above.
output_dir (path-like, optional) – When given, each converted EDI is written to this directory. The directory is created if it does not exist.
station_name (str, optional) – Override the station name for single-file input only. Ignored when source resolves to multiple files.

Returns:

Successfully converted impedance EDI files.

Return type:

EDICollection

Raises:

RuntimeError – When skip_errors=False and any file fails to convert.
ValueError – When source resolves to zero convertible files.

transform_batch(source, *, output_dir=None, station_name=None)[source]#

Like transform() but always returns a TransformResult.

Useful when you want to inspect failures without raising.

Parameters:

source (Any) – Same as transform().
output_dir (str | Path | None) – Same as transform().
station_name (str | None) – Same as transform().

Return type:

TransformResult

classmethod with_errors(**kw)[source]#

Return a transformer with estimate_error=True.

Parameters:: kw (Any)
Return type:: SpectraToEDI

classmethod with_tipper_suffix(**kw)[source]#

Return a transformer that appends '_IMP' to station names.

Parameters:: kw (Any)
Return type:: SpectraToEDI

class pycsamt.transformers.spectra.TransformResult(collection, failures=<factory>)[source]#

Bases: object

Outcome of a batch spectra→impedance conversion.

Variables:

collection (EDICollection) – Successfully converted EDI files.
failures (list of _FailRecord) – Per-file failures (source path + error message).
n_ok (int) – Number of successful conversions.
n_fail (int) – Number of failed conversions.

Parameters:

collection (EDICollection)
failures (list[_FailRecord])

Examples

result = SpectraToEDI().transform_batch("spectra_dir/")
print(result.n_ok, "ok, ", result.n_fail, "failed")
for f in result.failures:
    print(f.source, "->", f.error)

collection: EDICollection#

failures: list[_FailRecord]#

property n_ok: int[source]#

property n_fail: int[source]#