pycsamt.tdem.io#

TEM data readers.

Currently implemented#

read_xyz() Generic white-space / CSV with columns: time data [error].

read_temavg() Zonge TEMAVG processed .AVG files. read_tem_z() Zonge TEMAVG contour .Z files. read_tem_log() Zonge TEMAVG processing .LOG files. read_tem_coordinates() TEM profile/point coordinates. read_temavg_soundings() TEMAVG files as TEMSounding objects. read_geosoft_dat() Geosoft line-data .dat / .DAT files

(Oasis Montaj ASCII export).

read_amira() AMIRA / EMIT .tem keyword-block files. read_zonge() Zonge GDP .avg / .tem sounding files. read_walkttem() WalkTEM / Aarhus Workbench .tem files.

Functions

`read_amira`(path, *[, current, tx_area, ...])	Read TEM data from an AMIRA / EMIT `.tem` keyword-block file.
`read_geosoft_dat`(path, *[, current, ...])	Read TEM data from a Geosoft ASCII line-data `.dat` file.
`read_tem_log`(path, *[, verbose, logger])	Read a Zonge TEMAVG processing `.LOG` file.
`read_tem_z`(path, *[, verbose, logger])	Read a Zonge TEMAVG contour `.Z` file.
`read_temavg`(path, *[, verbose, logger])	Read a Zonge TEMAVG processed `.AVG` file.
`read_walkttem`(path, *[, current, tx_area, ...])	Read WalkTEM / Aarhus Workbench `.tem` keyword-block files.
`read_xyz`(path, *, current[, tx_area, ...])	Read a TEM sounding from a plain-text XYZ / CSV file.
`read_xyz_multisite`(path, *[, site_col, ...])	Read multiple TEM soundings from a single XYZ file where the first column is a site identifier.
`read_zonge`(path, *[, current, tx_area, ...])	Read TEM sounding data from a Zonge GDP `.avg` / `.tem` file.

pycsamt.tdem.io.read_xyz(path, *, current, tx_area=None, loop_side=None, loop_radius=None, data_type='dBdt', rx_area=1.0, rx_turns=1, tx_turns=1, offset=0.0, station_name='', x=0.0, y=0.0, elevation=0.0, time_col=0, data_col=1, error_col=None, skip_header=0, delimiter=None, time_unit='s', data_unit='SI')[source]#

Read a TEM sounding from a plain-text XYZ / CSV file.

The file may contain any number of columns; only time_col and data_col (and optionally error_col) are read. Comment lines starting with # or ! are ignored.

Parameters:

path (str or Path) – Path to the text file.
current (float) – Transmitter current in Amperes.
tx_area (float, optional) – Transmitter loop area in square metres. Supply this or loop_side or loop_radius.
loop_side (float, optional) – Side of a square transmitter loop in metres.
loop_radius (float, optional) – Radius of a circular transmitter loop in metres.
data_type (str, optional) – Units / type of the data_col column. One of "dBdt", "dHdt", "voltage", "normalized_voltage". Default "dBdt".
rx_area (float, optional) – Receiver coil area in square metres. Default 1.0.
rx_turns (int, optional) – Receiver coil turns. Default 1.
tx_turns (int, optional) – Transmitter turns. Default 1.
offset (float, optional) – Tx-Rx horizontal separation in m. Default 0 (coincident).
station_name (str, optional) – Name to store in the output TEMSounding.
x (float, optional) – Station coordinates in metres.
y (float, optional) – Station coordinates in metres.
elevation (float, optional) – Station coordinates in metres.
time_col (int, optional) – Zero-based column index for time values. Default 0.
data_col (int, optional) – Zero-based column index for the decay data. Default 1.
error_col (int, optional) – Zero-based column index for uncertainty. Default None (no error column).
skip_header (int, optional) – Number of header lines to skip before data rows. Default 0.
delimiter (str, optional) – Column separator. None means any whitespace (default).
time_unit (str, optional) – Unit of the time column: "s" (default), "ms", "us".
data_unit (str, optional) – Unit of the data column: "SI" (no conversion), "nT/s" (convert nT/s to T/s), "pT/s", "nV/Am2".

Returns:

Populated TEMSounding instance.

Return type:

TEMSounding

Examples

A minimal two-column file (time in ms, dB/dt in nT/s):

# TEM sounding, site A01
010   1.24e+04
018   8.91e+03
031   5.23e+03

>>> snd = read_xyz(
...     "site_A01.xyz",
...     current=8.0,
...     loop_side=100.0,
...     time_unit="ms",
...     data_unit="nT/s",
... )

pycsamt.tdem.io.read_temavg(path, *, verbose=0, logger=None)[source]#

Read a Zonge TEMAVG processed .AVG file.

Parameters:

path (path-like) – Path to a processed TEMAVG .AVG file.
verbose (int)
logger (object | None)

Returns:

Parsed processed TEMAVG data and metadata.

Return type:

TEMAVG

pycsamt.tdem.io.read_tem_z(path, *, verbose=0, logger=None)[source]#

Read a Zonge TEMAVG contour .Z file.

Parameters:

path (path-like) – Path to a TEMAVG contour .Z file.
verbose (int)
logger (object | None)

Returns:

Parsed contour rows and metadata.

Return type:

TEMZPlot

pycsamt.tdem.io.read_tem_log(path, *, verbose=0, logger=None)[source]#

Read a Zonge TEMAVG processing .LOG file.

Parameters:

path (path-like) – Path to a TEMAVG processing log.
verbose (int)
logger (object | None)

Returns:

Parsed processing provenance and acquisition summary.

Return type:

TEMLog

pycsamt.tdem.io.read_tem_coordinates(path, *, verbose=0, logger=None)#

Read a TEM profile/point coordinate table.

Parameters:

path (path-like) – Coordinate file in CSV, TSV, XLS, or XLSX format.
verbose (int)
logger (object | None)

Returns:

Parsed coordinates keyed by (profile, point).

Return type:

TEMCoordinateTable

pycsamt.tdem.io.read_temavg_survey(path, *, pattern='*.AVG', coordinate_file=None, verbose=0, logger=None)#

Read a directory of Zonge TEMAVG processed files.

Parameters:

path (path-like) – Directory containing TEMAVG .AVG files and optional companion files such as .LOG, .Z, and .mde.
pattern (str, default “*.AVG”) – Glob pattern used to select processed average files.
coordinate_file (path-like, optional) – Profile/point coordinate file. If omitted, the reader looks for common coordinate-table names in path.
verbose (int)
logger (object | None)

Returns:

Parsed survey collection.

Return type:

TEMSurvey

Examples

>>> from pycsamt.tdem import read_temavg_survey
>>> survey = read_temavg_survey("data/TEMAVG/JIANGSU")
>>> len(survey.stations) > 0
True

pycsamt.tdem.io.read_temavg_soundings(path, *, pattern='*.AVG', coordinate_file=None, stems=None, component='Hz', frequency=None, data_column='magnitude', magnitude_unit='uV/A', data_type='voltage', rx_turns=1, tx_turns=1, min_gates=1, verbose=0, logger=None)#

Read a TEMAVG folder and return station soundings.

This helper performs the first half of the TEMAVG pipeline: parse a survey folder, attach coordinates when available, and build one TEMSounding per station.

Parameters:

path (path-like) – Folder containing TEMAVG .AVG files.
pattern (str, default “*.AVG”) – Glob pattern used to select processed average files.
coordinate_file (path-like, optional) – Coordinate table to attach by (profile, station). If omitted, common coordinate filenames are discovered automatically.
stems (list of str, optional) – File stems to convert, for example ["TEM100"]. When omitted, all parsed .AVG files are used.
component (str, default "Hz") – TEMAVG component to select.
frequency (float, optional) – Repetition frequency to select.
data_column ({"magnitude"}, default "magnitude") – TEMAVG transient column used for the sounding decay.
magnitude_unit (str, default "uV/A") – Unit of the TEMAVG magnitude column.
data_type (str, default "voltage") – Data convention stored in each sounding.
rx_turns (int, default 1) – Receiver and transmitter turn counts.
tx_turns (int, default 1) – Receiver and transmitter turn counts.
min_gates (int, default 1) – Minimum number of selected gates required per station.
verbose (int)
logger (object | None)

Returns:

Station-wise soundings ready for transformation.

Return type:

list of TEMSounding

pycsamt.tdem.io.transform_temavg_survey(path, *, pattern='*.AVG', coordinate_file=None, stems=None, component='Hz', frequency=None, data_column='magnitude', magnitude_unit='uV/A', data_type='voltage', rx_turns=1, tx_turns=1, min_gates=1, method='late_time', freq_convention='skin_depth', phase_mode='homogeneous', loop_geometry_correction=True, return_collection=False, savepath=None, verbose=0, logger=None)#

Run a complete TEMAVG-to-frequency workflow.

The function reads a TEMAVG survey folder, builds station soundings, transforms them to pseudo-frequency apparent resistivity and impedance, and optionally creates or writes EDI output.

Parameters:

path (path-like) – Folder containing TEMAVG .AVG files.
pattern (str, default “*.AVG”) – Glob pattern used to select processed average files.
coordinate_file (path-like, optional) – Coordinate table to attach by profile and station.
stems (list of str, optional) – File stems to convert. Use this to process one profile before scaling to a full survey folder.
component (str, default "Hz") – TEMAVG component to select.
frequency (float, optional) – Repetition frequency to select.
data_column ({"magnitude"}, default "magnitude") – TEMAVG transient column used for the sounding decay.
magnitude_unit (str, default "uV/A") – Unit of the TEMAVG magnitude column.
data_type (str, default "voltage") – Data convention stored in each sounding.
rx_turns (int, default 1) – Receiver and transmitter turn counts.
tx_turns (int, default 1) – Receiver and transmitter turn counts.
min_gates (int, default 1) – Minimum number of selected gates required per station.
method ({"late_time", "fourier"}, default "late_time") – Transformation method used by TEMtoEDI.
freq_convention (str, default "skin_depth") – Pseudo-frequency convention for late-time transforms.
phase_mode (str, default "homogeneous") – Phase model used for synthetic impedance.
loop_geometry_correction (bool, default True) – Whether to apply in-loop geometry corrections.
return_collection (bool, default False) – If True, also build an EDI collection in memory.
savepath (path-like, optional) – Directory where synthetic EDI files are written.
verbose (int)
logger (object | None)

Returns:

Bundle containing the parsed survey, station soundings, transform results, and optional EDI outputs.

Return type:

TEMAVGConversion

Examples

>>> from pycsamt.tdem import transform_temavg_survey
>>> out = transform_temavg_survey(
...     "data/TEMAVG/JIANGSU",
...     stems=["TEM100"],
... )
>>> out.n_soundings > 0
True

pycsamt.tdem.io.read_geosoft_dat(path, *, current=None, tx_area=None, loop_side=None, loop_radius=None, rx_area=1.0, rx_turns=1, data_unit='nV/Am2', data_type='dBdt', gate_times=None, gate_times_unit='ms', x_col='X', y_col='Y', elev_col='ELEV', station_col=None, gate_prefix='G', line_col=None)[source]#

Read TEM data from a Geosoft ASCII line-data .dat file.

Geosoft Oasis Montaj exports TEM soundings in a fixed-width or space-delimited ASCII file where:

Comment/metadata lines start with / or !.
Line identifiers start with L (L100, L200, …).
A single header row names every numeric channel.
Subsequent rows are one station (fiducial) per line.

Metadata embedded in / comment lines is parsed automatically:

/ Current: 8.0
/ LoopSide: 200.0        (or LoopArea / LoopRadius)
/ GateTimes(ms): 0.021 0.037 0.065 ...
/ DataUnit: nV/Am2

These override the keyword arguments of the same name.

Parameters:

path (str or Path) – Path to the .dat file.
current (float or None) – Transmitter current in Amperes. May also be given as a / Current: header line in the file.
tx_area (float or None) – Transmitter loop area in m².
loop_side (float or None) – Side of a square loop in m (used to compute tx_area).
loop_radius (float or None) – Radius of a circular loop in m (used to compute tx_area).
rx_area (float) – Receiver coil area in m². Default 1.0.
rx_turns (int) – Receiver coil turns. Default 1.
data_unit (str) – Units of the gate-data columns before conversion to SI. Recognised: "nV/Am2", "uV/Am2", "mV/Am2", "nT/s", "T/s", "SI". Default "nV/Am2".
data_type (str) – "dBdt" or "normalized_voltage". Default "dBdt".
gate_times (list of float or None) – Explicit gate-centre times (in gate_times_unit). When None the reader looks for a / GateTimes: header line.
gate_times_unit (str) – Time unit for gate_times: "ms" (default), "s", "us".
x_col (str) – Column names for easting, northing, elevation.
y_col (str) – Column names for easting, northing, elevation.
elev_col (str) – Column names for easting, northing, elevation.
station_col (str or None) – Column containing station identifiers. None → auto-number.
gate_prefix (str) – Prefix shared by all gate columns (e.g. "G" matches G1, G2, …, or "TEM_G" for TEM_G01, …). Default "G".
line_col (str or None) – Column name carrying the line number, if present.

Returns:

One TEMSounding per data row.

Return type:

list of TEMSounding

Raises:

FileNotFoundError –
ValueError – If gate times cannot be determined from the file or arguments.

Examples

/ Geosoft TEM export
/ Current: 8.0
/ LoopSide: 200.0
/ GateTimes(ms): 0.021 0.037 0.065 0.090
/ DataUnit: nV/Am2
X        Y        ELEV    G1       G2       G3       G4
1000.0   2000.0   0.0     1.24e4   8.91e3   5.23e3   3.12e3
2000.0   2000.0   0.0     9.87e3   6.54e3   4.32e3   2.61e3

>>> soundings = read_geosoft_dat(
...     "survey.dat",
...     current=8.0,
...     loop_side=200.0,
... )

pycsamt.tdem.io.read_amira(path, *, current=None, tx_area=None, loop_side=None, loop_radius=None, rx_area=1.0, rx_turns=1, data_unit='nV/Am2', data_type='dBdt', gate_times=None, gate_times_unit='ms')[source]#

Read TEM data from an AMIRA / EMIT .tem keyword-block file.

The EMIT .tem format organises acquisition parameters in keyword-value blocks separated by blank lines. Comment lines begin with ; or #. A minimal complete file looks like:

; EMIT TEM data — site survey
TRANSMITTER_AREA   40000
TRANSMITTER_CURRENT  8.0
TRANSMITTER_TURNS    1
RECEIVER_AREA  1.0
RECEIVER_TURNS 1
GATE_TIMES_UNIT ms
GATE_TIMES  0.021 0.037 0.065 0.090 0.135 0.200
DATA_UNIT   nV/Am2

DATA
; StnName  X         Y         Elev    D1        D2      ...
S001  1000.0  2000.0    0.0  1.24e+04  8.91e+03  ...
S002  2000.0  2000.0    0.0  9.87e+03  6.54e+03  ...
END DATA

Keyword recognition is case-insensitive. The DATA … END DATA block may alternatively start with [DATA] or DATASETS.

Parameters:

path (str or Path)
current (float or None) – Transmitter current [A]. Overrides TRANSMITTER_CURRENT in file.
tx_area (float or None) – Transmitter loop area [m²]. Overrides TRANSMITTER_AREA.
loop_side (float or None) – Square loop side length [m].
loop_radius (float or None) – Circular loop radius [m].
rx_area (float) – Receiver coil area [m²]. Overrides RECEIVER_AREA. Default 1.0.
rx_turns (int) – Receiver coil turns. Overrides RECEIVER_TURNS. Default 1.
data_unit (str) – Units of gate-data values. Overrides DATA_UNIT in file.
data_type (str) – "dBdt" or "normalized_voltage". Default "dBdt".
gate_times (list of float or None) – Gate-centre times (in gate_times_unit). Overrides GATE_TIMES in file.
gate_times_unit (str) – Unit for gate_times. Overrides GATE_TIMES_UNIT in file.

Return type:

list of TEMSounding

Raises:

FileNotFoundError –
ValueError –

pycsamt.tdem.io.read_zonge(path, *, current=None, tx_area=None, loop_side=None, loop_radius=None, rx_area=1.0, rx_turns=1, data_unit='nV/Am2', data_type='dBdt', gate_times=None, gate_times_unit='ms')[source]#

Read TEM sounding data from a Zonge GDP .avg / .tem file.

The Zonge GDP receiver outputs an ASCII sounding file whose structure mirrors the TEMAVG processed format but at a per-sounding (not per-station-per-window) granularity. Comment / metadata lines begin with * or \. A representative file:

* Zonge GDP-32 TEM sounding
* Station: S001
* X: 1000.0   Y: 2000.0   Elev: 0.0
* Current: 8.00 A
* TxArea: 40000 m^2
* GateTimes(ms): 0.021 0.037 0.065 0.090
* DataUnit: nV/Am2
Win  Time(ms)    Hz(nV/Am2)   Error
  1    0.021     1.2400e+04   5.0e+02
  2    0.037     8.9100e+03   4.0e+02
  3    0.065     5.2300e+03   2.5e+02
  4    0.090     3.1200e+03   1.8e+02
* Station: S002
...

Multiple soundings in one file are separated by a new * Station: line.

Parameters:

path (str or Path)
current (float or None) – Transmitter current [A].
tx_area (float or None)
loop_side (float or None)
loop_radius (float or None)
rx_area (float)
rx_turns (int)
data_unit (str) – Data column units. Overrides * DataUnit: in file.
data_type (str) – "dBdt" (default) or "normalized_voltage".
gate_times (list of float or None) – Explicit gate times (override * GateTimes: in file).
gate_times_unit (str)

Return type:

list of TEMSounding

Raises:

FileNotFoundError –
ValueError –

pycsamt.tdem.io.read_walkttem(path, *, current=None, tx_area=None, loop_side=None, loop_radius=None, rx_area=1.0, rx_turns=1, data_unit='nV/Am2', data_type='dBdt', gate_times=None, gate_times_unit='ms', low_moment=True)[source]#

Read WalkTEM / Aarhus Workbench .tem keyword-block files.

The Aarhus Workbench TEM format uses /-prefixed comment lines and section keywords in ALL-CAPS followed by their contents. Sections end with END_<KEYWORD>. A representative file:

/ WalkTEM data — Aarhus Workbench export
/
GENERALHEADER
WalkTEM System
END_GENERALHEADER

TXOPERATION
LoopSize    40.000
Current      6.60
TurnsNumber  1
Waveform     Full_Waveform
END_TXOPERATION

RXOPERATION
CoilMoment  0.01
END_RXOPERATION

GATESET
NumberOfGates 20
GateTimes  0.008 0.015 0.025 0.043 0.072 0.120 0.200
GateSigns  1 1 1 1 1 1 1
END_GATESET

DATA
! Line  Fid   X        Y       Elev   d1      d2      ...
100  1000  1000.0  2000.0   0.0  1.5e-7  9.2e-8  ...
100  2000  1200.0  2000.0   0.0  1.3e-7  8.1e-8  ...
END_DATA

Section names and keyword matching are case-insensitive.

Parameters:

path (str or Path)
current (float or None) – Transmitter current [A]. Overrides file value.
tx_area (float or None)
loop_side (float or None)
loop_radius (float or None)
rx_area (float)
rx_turns (int)
data_unit (str) – Units for data gate columns (default "nV/Am2"). WalkTEM data may also be in "T/s" or "SI".
data_type (str) – "dBdt" (default) or "normalized_voltage".
gate_times (list of float or None) – Explicit gate times (overrides GATESET block).
gate_times_unit (str)
low_moment (bool) – WalkTEM instruments record two moments (LM and HM) per sounding. When True (default) only the low-moment (first) channel is read; set False to read the high-moment channel.

Return type:

list of TEMSounding

Raises:

FileNotFoundError –
ValueError –