geost.read_borehole_table#

geost.read_borehole_table(file: str | Path, horizontal_reference: str | int | CRS = 28992, vertical_reference: str | int | CRS = 5709, has_inclined: bool = False, as_collection: bool = True, column_mapper: dict = None, **kwargs) → BoreholeCollection[source]#

Read tabular borehole information. This is a file (parquet, csv or Excel) that includes row data for each (borehole) layer and must at least include the following column headers:

  • nr : Object id

  • x : X-coordinates according to the given horizontal_reference

  • y : Y-coordinates according to the given horizontal_reference

  • surface : Surface elevation according to the given vertical_reference

  • end : End depth according to the given vertical_reference

  • top : Top depth of each layer

  • bottom : Bottom depth of each layer

In case there are inclined boreholes in the layer data, you additionally require:

  • x_bot : X-coordinates of the layer bottoms

  • y_bot : Y-coordinates of the layer bottoms

If you are reading a file that uses different column names, see the optional argument “column_mapper” below. There are no further limits or requirements to additional (data) columns.

Parameters:

  • file (str | Path) – Path to file to be read. Depending on the file extension, the corresponding Pandas read function will be called. This can be either pandas.read_parquet, pandas.read_csv or pandas.read_excel. The **kwargs that can be given to this function will be passed to the selected Panda’s read function.

  • horizontal_reference (str | int | CRS, optional) – EPSG of the data’s horizontal reference. Takes anything that can be interpreted by pyproj.crs.CRS.from_user_input(). The default is 28992.

  • vertical_reference (str | int | CRS, optional) – EPSG of the data’s vertical datum. Takes anything that can be interpreted by pyproj.crs.CRS.from_user_input(). However, it must be a vertical datum. FYI: “NAP” is EPSG 5709 and The Belgian reference system (Ostend height) is ESPG 5710. The default is 5709.

  • has_inclined (bool, optional) – If True, the borehole data table contains inclined boreholes. The default is False.

  • as_collection (bool, optional) – If True, the borehole table will be read as a Collection which includes a header object and spatial selection functionality. If False, a LayeredData object is returned. The default is True.

  • column_mapper (dict, optional) – If the file to be read uses different column names than the ones given in the description above, you can use a dictionary mapping to translate the column names to the required format. column_mapper is None by default, in which case the user is asked for input if not all required columns are encountered in the file.

  • kwargs (optional) – Optional keyword arguments for Pandas.read_parquet, Pandas.read_csv or Pandas.read_excel.

Returns:

Instance of BoreholeCollection or LayeredData depending on if the table is read as a collection or not.

Return type:

BoreholeCollection or LayeredData

Examples

Suppose we have a file of boreholes with columns ‘nr’, ‘x’, ‘y’, ‘maaiveld’, ‘end’, ‘top’ and ‘bottom’. The column ‘maaiveld’ corresponds to the required column ‘surface’ in GeoST and thus needs to be remapped. The x and y-coordinates are given in WGS84 UTM 31N whereas the vertical datum is given in the Belgian Ostend height vertical datum:

>>> read_borehole_table(file, 32631, 'Ostend height', column_mapper={'maaiveld': 'surface'})