Overview

LiquidEarth supports two ways to import borehole data:

Simple import for data that already follows the required canonical CSV format.
Advanced import for data that needs custom parsing, column mapping, or other reader settings.

Both workflows import the same three types of borehole data:

Collars: borehole collar locations at the surface.
Survey: borehole trajectory downhole.
Attributes: interval or point data along the borehole, such as lithology or assay values.

Simple Importer

Advanced Importer

Troubleshooting

Error Message	Likely Cause	Solution
ValueError: … missing required columns (x, y, z)	Collar file lacks coordinate data or column names differ.	Check Columns Map in the Collar Reader Settings to map `X`, `Y`, `Z` to `x`, `y`, `z`.
AttributeError: md column must be present	Survey file uses “Distance” or “Depth” instead of “md”.	Add `"Distance": "md"` (or your specific name) to the Survey Columns Map.
AssertionError: base column must be present	Attribute file is missing a depth endpoint.	Ensure `base` is defined, or if using interval data, map the correct depth column to `base`.
Garbled Characters / Unicode Issues	File encoding mismatch (e.g., UTF-8 vs ISO-8859-1).	Change the Encoding setting for the affected file.
Wrong Number Parsing (e.g., 1.234 read as 1234)	File uses commas as decimal separators instead of dots.	Set `additional_reader_kwargs` with `{"decimal": ","}`.
Boreholes Missing	Borehole IDs do not match exactly between Collar and Survey files.	Ensure ID spelling is identical (case-sensitive check).
AttributeError: component lith column must be present	`is_lith_attr` is set to `True` but the attribute file does not have a `component lith` column.	Either add a `columns_map` entry (e.g., `{"GEOLOGY": "component lith"}`) or set `is_lith_attr` to `False` if the file contains assay data, not lithology.

Example Files