Data and processing#

What the package can read, how it checks a dataset, and what it can invert. This covers stages 2 and 3 of the loop: turning an acquisition into a dataset, and a dataset into a model.

Reading field data#

Instrument formats are read directly, so a file off the instrument needs no conversion step. Every reader returns the same contract, an electrode or geometry array alongside a table of measurements, so the rest of the package does not care which instrument produced the survey.

Method	Format	Notes
ERT	DAS-1 `.Data`	Self-describing. The column map is read from each file’s own header rather than assumed, so a non-standard layout still loads.
ERT	`.tx0`	Lippmann 4-Point Light and GeoTest exports, including the explicit electrode table.
ERT	Res2DInv `.dat`	General-array format.
ERT	AGI SuperSting `.stg`	SuperSting and Sting R1 exports. The format writes electrode positions into every record instead of an electrode table, so the table is rebuilt from the measurements; the instrument’s own geometric factor is carried alongside, which is what makes a nominal-versus-surveyed geometry mismatch visible. IP decay windows are read when the acquisition recorded them.
ERT	Subsurface Insights `results_processed_*.csv`	Read by column name, because the firmware inserts columns between releases (2026-05 builds add `resistance_contact[ohms]`). `cable-electrode` labels are numbered along the cables in order, so cables of unequal length share one numbering. The file carries no coordinates, only the instrument’s geometric factors; on a straight, evenly spaced line those fix the spacing exactly, and the positions are rebuilt from them and checked against every measurement - anything else needs the surveyed electrode file. Potential, current and contact resistance come along for QC. The potential’s sample spread is kept as a diagnostic but is not used as a data error: it describes the samples within one reading, not the reading.
ERT	BGS PRIME / RESIMGR `.tab`	Read by column name, with every unit taken from the file’s own `#Units` row: resistance in ohm, potential and current converted from mV and mA, and the instrument’s error from tenths of a percent. A row that leaves the current electrodes blank repeats the previous ones, and the firmware’s `**Error` lines are skipped and counted. Electrodes are numbered by channel (113-160 on a 48-electrode line) and the export carries no positions unless its header holds an electrode table, so they are a 1 m placeholder, numbering gaps kept, until the surveyed electrode file is loaded. The phase is kept apart, not read as IP, and `pt_error_code` is kept as written: its flags are undocumented, so no reading is dropped for one. ResIPy reads the format too, but swaps the current and potential electrodes, so this reader is used even when ResIPy is installed.
ERT	`.ohm`, `.dat`	E4D and pyGIMLi/BERT files, plus ResIPy for processing.
Seismic	SEG-2	Through ObsPy when it is installed, with a text fallback for arrays that were already exported.
TDEM	TEM2Go project, `.tiw` or `.db`	Station stacks, gate flags, errors, geometry and saved inversion settings. Both project layouts are detected automatically.
TDEM	TEM2Go acquisition folder, `.stb`	A folder copied straight off the instrument, with no project and no export. Gate times, calibration and loop geometry come from the raw stream itself.
TDEM	`_StationData.xyz`, `_RawData.xyz`	Self-describing exports. Station stacks are preferred for inversion.
TDEM	tTEM raw, `.skb` with `.sps`	Uses the system GEX for geometry, waveform, gates and calibration, and the TFI import filter when both are present.
Gravity, magnetics	Table formats	Column files with the survey geometry alongside.

Checking a dataset#

Quality control runs before inversion rather than as an afterthought. Reciprocal measurements give the error estimate, following the definition in the induced-polarisation literature (Slater et al. 2000; Binley and Kemna 2005; Binley and Slater 2020, chapter 6). Gate-level tests for electromagnetic data apply the acquisition protocol’s own thresholds, so a survey is filtered on the terms it was recorded under.

The readers were written from the published file formats and from the standard DC-resistivity literature.

Recovering a model#

Inversion	What it is for
Single survey	One acquisition, 2D or 3D, ERT or seismic refraction.
Time-lapse	A monitoring series inverted together, so the recovered change is constrained rather than differenced after the fact.
Windowed time-lapse	Long series inverted in overlapping windows, which keeps memory bounded on a survey that would not fit at once.
Structure-constrained	Seismic structure guides a resistivity inversion where the two respond to the same boundary.
Joint ERT and seismic	Complementary measurements inverted against a shared structure.
Laterally constrained, EM	Neighbouring soundings tied along a line, with both moments fitted to one layered model.
Gravity and magnetics	Potential-field inversion on the same mesh infrastructure.

Solvers and uncertainty#

A Gauss-Newton normal matrix is symmetric positive definite by construction, and the solvers treat it as one: spd_cholesky and spd_cg are available alongside the least-squares methods, and generalized_solver reports a mismatch between the method and the system it was handed.

An optional differentiable 2.5D ERT backend runs on the GPU through CuPy and cuDSS. It falls back to the built-in engine when CUDA is unavailable, and the engine that actually ran is reported, so a fallback is visible rather than silent.

For uncertainty, the package provides a linearized posterior covariance, model resolution, ensemble Kalman updating, and Monte Carlo propagation of petrophysical parameter uncertainty into the recovered quantity.

Where to go next#

Field ERT Data QC walks a field dataset through checking and export.
Time-Lapse Monitoring builds and inverts a monitoring series.
API Reference documents every function named above.