PyBorehole API Reference#

pyborehole.borehole module#

class pyborehole.borehole.Borehole(name: str)#

Bases: object

Class to initiate a borehole object.

Parameters: name (str) – Name of the Borehole, e.g. name='Weisweiler R1'.
Return type: Borehole
Raises: TypeError – If the wrong input data types are provided.

Examples

>>> from pyborehole.borehole import Borehole
>>> borehole = Borehole(name='Weisweiler R1')
>>> borehole.name

New in version 0.0.1.

add_deviation(path: Union[str, pandas.core.frame.DataFrame], delimiter: str = ',', step: Union[float, int] = 1, md_column: str = 'MD', dip_column: str = 'DIP', azimuth_column: str = 'AZI', add_origin: bool = True)#

Add deviation to the Borehole Object.

Parameters

path (str) – Path to the deviation file or DataFrame containing the deviation values, e.g. path='deviation.csv'.
delimiter (str, default: ',') – Delimiter to read the deviation file correctly, e.g. delimiter=';'.
step (Union[float, int], default: 1) – Step for resampling the deviation data, e.g. step=5.
md_column (str, default: 'MD') – Column containing the measured depths, e.g. md_column='MD'.
dip_column (str, default: 'DIP') – Column containing the dip values, e.g. dip_column='DIP'.
azimuth_column (str, default: 'AZI') – Column containing the azimuth values, e.g. azimuth_column='AZI'.
add_origin (bool, default: True) – Boolean value to add the location of the borehole to survey DataFrames.

Raises

TypeError – If the wrong input data types are provided.
ValueError – If the wrong column names are provided.

Examples

>>> borehole.add_deviation(path='Deviation.csv', delimiter=';', md_column='MD', dip_column='DIP', azimuth_column='AZI')
>>> borehole.deviation.deviation_df
    Measured Depth  Inclination  Azimuth
0   0.05            0.0          0.0
1   0.10            0.0          0.0
2   0.15            0.0          0.0

New in version 0.0.1.

add_litholog(path: str, delimiter: str = ',')#

Add LithoLog to the Borehole Object.

Parameters

path (str) – Path to the LitoLog file, e.g. path='LithoLog.csv'.
delimiter (str, default: ',') – Delimiter for the LithoLog file, e.g. delimiter=','.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> borehole.add_litholog(path='LithoLog.csv', delimiter=';')
>>> borehole.litholog.df
    Top              MD
0   Infill           3.0
1   Base Quaternary  9.5
2   Sand 1           28.5
3   Clay             32.0

New in version 0.0.1.

add_well_design()#

add_well_logs(path: str, nodata: Union[int, float] = - 9999)#

Add Well Logs to the Borehole Object.

Parameters

path (str) – Path to the well log file, e.g. path='Well_Logs.las'.
nodata (Union[int, float], default: -9999) – Nodata value to be replaces by np.NaN, e.g. nodata=-9999.

Raises

TypeError – If the wrong input data types are provided.
ValueError – If neither of the permitted file types are provided.

Examples

>>> borehole.add_well_logs(path='Well_logs.las')
>>> borehole.logs.well_header
    mnemonic   unit   value               descr
 STRT       M      100.0               Log Start Depth
 STOP       M      0.05                Log Stop Depth
 STEP       M      -0.05               Log Increment
 NULL              -999.25             Null Value
 COMP              RWE Power           Company Name
 WELL              EB 1                Well Name
 FLD               KW Weisweiler       Field Name
 LOC                                   Location
 PROV                                  Province
 SRVC                                  Service Company
DATE              26-Oct-2023         Date
UWI                                   Unique Well ID

New in version 0.0.1.

add_well_tops(path: str, delimiter: str = ',', unit: str = 'm')#

Add Well Tops to the Borehole Object.

Parameters

path (str) – Path to the well top file, e.g. path='Well_Tops.csv'.
delimiter (str, default: ',') – Delimiter for the well top file, e.g. delimiter=','.
unit (str) – Unit of the depth measurements, e.g. unit='m'.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> borehole.add_well_tops(path='Well_Tops.csv', delimiter=';')
>>> borehole.well_tops.df
    Top              MD
0   Infill           3.0
1   Base Quaternary  9.5
2   Sand 1           28.5
3   Clay             32.0

New in version 0.0.1.

boreholes = []#

create_df()#

Create DataFrame from Borehole Object Attributes.

Returns: df – DataFrame containing the Borehole Metadata.
Return type: pd.DataFrame

Examples

>>> borehole.create_df()
>>> borehole.df
                                    Value
Name                                RWE EB1
Address                             Am Kraftwerk 17, 52249 Eschweiler, Germany
Location                            POINT (6.313031 50.835676)
X                                   6.313031
Y                                   50.835676
Coordinate Reference System         EPSG:4326
Coordinate Reference System PyProj  EPSG:4326
Altitude above sea level            136
Altitude above KB                   None

New in version 0.0.1.

create_properties_df()#

Create Properties DataFrame from Borehole Object Attributes.

Returns: df – DataFrame containing the Borehole Properties.
Return type: pd.DataFrame

Examples

>>> borehole.create_properties_df()
>>> borehole.properties
                                    Value
Name                                True
Address                             True
Location                            True
X                                   True
Y                                   True
Coordinate Reference System         True
Coordinate Reference System PyProj  True
Altitude above sea level            True
Altitude above KB                   False

New in version 0.0.1.

init_properties(address: str = None, location: Tuple[float, float] = None, crs: Union[str, pyproj.crs.crs.CRS] = None, altitude_above_sea_level: Union[int, float] = None, altitude_above_kb: Union[int, float] = None, id: Union[str, int, float] = None, borehole_type: str = None, md: Union[int, float] = None, tvd: Union[int, float] = None, depth_unit: str = None, vertical: bool = True, contractee: str = None, drilling_contractor: str = None, logging_contractor: str = None, field: str = None, project: str = None, start_drilling: str = None, end_drilling: str = None, start_logging: str = None, end_logging: str = None)#

Initiate Borehole properties.

Parameters

address (str) – Address of the Borehole, e.g. address='Am Kraftwerk 17, 52249 Eschweiler, Deutschland'.
location (tuple) – Coordinates tuple representing the location of the Borehole, e.g. location=(6.313031, 50.835676).
crs (Union[str, pyproj.crs.crs.CRS]) – Coordinate Reference System of the coordinates, e.g. crs='EPSG:4326'.
altitude_above_sea_level (Union[int, float]) – Altitude above sea level, e.g. altitude_above_sea_level=136.
altitude_above_kb (Union[int, float]) – Altitude above KB, e.g. altitude_above_kb=140.
id (Union[str, int, float]) – Unique identifier for this borehole, e.g. id='DABO123456'.
borehole_type (str) – Borehole type, e.g. borehole_type='exploration'.
md (Union[int, float]) – Measured depth of the borehole, e.g. md=100.
tvd (Union[int, float]) – True vertical depth of the borehole, e.g. tvd=95.
depth_unit (str) – Unit for the depth values, e.g. depth_values='m'.
vertical (bool, default is True) – Variable to state if the borehole is vertical (True) or deviated (False), e.g. vertical=True.
contractee (str) – Contractee of the drilling operation, e.g. contractee='Fraunhofer IEG'.
drilling_contractor (str) – Drilling contractor who performed the drilling, e.g. drilling_contractor='RWE BOWA'.
logging_contractor (str) – Logging contractor who performed the logging, e.g. logging_contractor='DMT GmbH'.
field (str) – Name of the field the well was drilled in, e.g. field='Erdwärme Aachen'.
project (str) – Name of the project the borehole was drilled for, e.g. project='DGE Rollout'.
start_drilling (str) – Start date of the drilling operation, e.g. start_drilling='2023-10-18'.
end_drilling (str) – End date of the drilling operation, e.g. end_drilling='2023-10-28'.
start_logging (str) – Start date of the logging operation, e.g. start_logging='2023-10-18'.
end_logging (str) – End date of the logging operation, e.g. end_logging='2023-10-28'.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> from pyborehole.borehole import Borehole
>>> borehole.init_properties(address='Am Kraftwerk 17, 52249 Eschweiler, Deutschland', location=(6.313031, 50.835676), crs='EPSG:4326', altitude_above_sea_level=136)
>>> borehole.df
                                        Value
    Name                                RWE EB1
    Address                             Am Kraftwerk 17, 52249 Eschweiler, Germany
    Location                            POINT (6.313031 50.835676)
    X                                   6.313031
    Y                                   50.835676
    Coordinate Reference System         EPSG:4326
    Coordinate Reference System PyProj  EPSG:4326
    Altitude above sea level            136
    Altitude above KB                   None

New in version 0.0.1.

to_gdf(crs: Union[str, pyproj.crs.crs.CRS] = None)#

Create GeoDataFrame from DataFrame.

Parameters: crs (Union[str, pyproj.crs.crs.CRS]) – Coordinate Reference System of the coordinates, e.g. crs='EPSG:4326'.
Return type: gpd.GeoDataFrame

Examples

>>> borehole.to_gdf()
    ID         Name    geometry
0   DABO123456 RWE EB1 POINT (6.31303 50.83568)

New in version 0.0.1.

update_df(data_dict: dict)#

Update DataFrame with data from data_dict.

Parameters: data_dict (dict) – Dictionary containing the new data, e.g. data_dict={'Date': 2023}.
Raises: TypeError – If the wrong input data types are provided.

Examples

>>> borehole.update_df(data_dict={'Date': 2023})
>>> borehole.df
                                    Value
Name                                RWE EB1
Address                             Am Kraftwerk 17, 52249 Eschweiler, Germany
Location                            POINT (6.313031 50.835676)
X                                   6.313031
Y                                   50.835676
Coordinate Reference System         EPSG:4326
Coordinate Reference System PyProj  EPSG:4326
Altitude above sea level            136
Altitude above KB                   None
Data                                2023

New in version 0.0.1.

update_value(attribute: str, value: Union[int, float, str, tuple], crs: Union[str, pyproj.crs.crs.CRS] = None, transform_coordinates: bool = None)#

Update attribute and DataFrame value.

Parameters

attribute (str) – Borehole object attribute provided as str, e.g. attribute='name'.
value (Union[int, float, str]) – Value of the attribute to be updated, e.g. value='RWE EB2'.
crs (Union[str, pyproj.crs.crs.CRS]) – Coordinate Reference System of the coordinates, e.g. crs='EPSG:4326'.
transform_coordinates (bool) – Boolean value to transform the coordinates if a new Coordinate Reference System is provided, e.g. transform_coordinates=True.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> borehole.name
'RWE EB1'
>>> borehole.update_value(attribute='name', value='RWE EB2')
>>> borehole.name
'RWE EB2'

New in version 0.0.1.

class pyborehole.borehole.DLISLogs(borehole, path: str, nodata: Union[int, float] = - 9999)#

Bases: pyborehole.borehole.Borehole

Class to initiate a Well Log Object.

Parameters: path (str) – Path to the well logs, e.g. path='logs.dlis'.

class pyborehole.borehole.LASLogs(borehole, path: str)#

Bases: pyborehole.borehole.Borehole

Class to initiate a Well Log Object.

Parameters: path (str) – Path to the well logs, e.g. path='logs.las'.

plot_well_log_along_path(log: str, coordinates: pandas.core.frame.DataFrame, spacing: float = 0.5, radius_factor: float = 75)#

Raises

ModuleNotFoundError – Raises error if PyVista is not installed.
TypeError – If the wrong input data types are provided.
ValueError – Raises error if the wrong column names are provided.

plot_well_logs(tracks: Union[str, list], depth_column: str = 'MD', colors: Union[str, list] = None, add_well_tops: bool = False, fill_between: int = None)#

Plot well logs.

Parameters

tracks (Union[str, list]) – Name/s of the logs to be plotted, e.g. tracks='SGR' or ``tracks=[‘SGR’, ‘K’].
depth_column (str) – Name of the column holding the depths, e.g. depth_column='MD'.
colors (Union[str, list]) – Colors of the logs, e.g. colors='black' or ``colors=[‘black’, ‘blue’].
add_well_tops (bool, default = False) – Boolean to add well tops to the plot.

class pyborehole.borehole.LithoLog(path: str, delimiter: str = ',')#

Bases: pyborehole.borehole.Borehole

Class to initiate the LithoLog.

Parameters

path (str) – Path to the litholog, e.g. path='LithoLog.csv'.
delimiter (str) – Delimiter to read the litholog file correctly, e.g. delimiter=','.

class pyborehole.borehole.WellTops(path: str, delimiter: str = ',', unit: str = 'm')#

Bases: pyborehole.borehole.Borehole

Class to initiate Well Tops.

Parameters

path (str) – Path to the well tops, e.g. path='Well_Tops.csv'.
delimiter (str) – Delimiter to read the well tops file correctly, e.g. delimiter=','.
unit (str) – Unit of the depth measurements, e.g. unit='m'.

pyborehole.borehole.get_points_along_spline(spline, dist: numpy.ndarray)#

Return the closest point on the spline a given a length along a spline.

Parameters

spline (pv.core.pointset.PolyData) – Spline with the resampled vertices
dist (np.ndarray) – np.ndarray containing the measured depths (MD) of values along the well path

Returns

spline.points[idx_list] – PyVista Array containing the selected points

Return type

pv.core.pyvista_ndarray.pyvista_ndarray

New in version 1.0.x.

pyborehole.borehole.merge_logs(paths: List[str], resampling: Union[float, int]) → pandas.core.frame.DataFrame#

pyborehole.borehole.polyline_from_points(points: numpy.ndarray)#

Create PyVista PolyLine from points

Parameters: points (np.ndarray) – Points defining the PolyLine.
Returns: poly
Return type: pv.core.pointset.PolyData

New in version 1.0.x.

pyborehole.borehole.resample_between_well_deviation_points(coordinates: numpy.ndarray, spacing: Union[float, int]) → numpy.ndarray#

Resample between points that define the path of a well.

Parameters: coordinates (np.ndarray) – Nx3 Numpy array containing the X, Y, and Z coordinates that define the path of a well.
Returns: points_resampled – Resampled points along a well.
Return type: np.ndarray

New in version 1.0.x.

pyborehole.borehole.resample_log(log: Union[geopandas.geodataframe.GeoDataFrame, shapely.geometry.linestring.LineString, pandas.core.frame.DataFrame], resampling: int, column_name: str = None, resampling_start=0, resampling_end=None, rounding_precision=5, drop_first: bool = False, drop_last: bool = False) → geopandas.geodataframe.GeoDataFrame#: Resample one log. Data must be provided as GeoDataFrame with the log Data as Shapely Points.

pyborehole.borehole.resample_logs(logs: pandas.core.frame.DataFrame, resampling: int, resampling_start=0, resampling_end=None, rounding_precision=5, drop_first: bool = True, drop_last: bool = True)#

class pyborehole.deviation.Deviation(borehole, path: Union[str, pandas.core.frame.DataFrame], delimiter: str, step: Union[float, int] = 5, md_column: str = 'MD', dip_column: str = 'DIP', azimuth_column: str = 'AZI', add_origin: bool = True)#

Bases: object

Class to initiate a Deviation object.

Parameters

path (str) – Path to the deviation file, e.g. path='Well_deviation.csv'.
delimiter (str) – Delimiter to read the deviation file correctly, e.g. delimiter=';'.
step (float, default: 5) – Step for resampling the deviation data, e.g. step=5.
md_column (str, default: 'MD') – Column containing the measured depths.
dip_column (str, default: 'DIP') – Column containing the dip values.
azimuth_column (str, default: 'AZI') – Column containing the azimuth values.
add_origin (bool, default: True) – Boolean value to add the location of the borehole to survey DataFrames.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> borehole.add_deviation(path='Deviation.csv', delimiter=';', md_column='MD', dip_column='DIP', azimuth_column='AZI')
>>> borehole.deviation.deviation_df
    Measured Depth  Inclination  Azimuth
0   0.05            0.0          0.0
1   0.10            0.0          0.0
2   0.15            0.0          0.0

New in version 0.0.1.

add_origin_to_desurveying(x: Union[float, int] = None, y: Union[float, int] = None, z: Union[float, int] = None)#

Add origin to desurveying.

Parameters

x (Union[float, int]) – X-Coordinate of the origin, e.g. x=1000.
y (Union[float, int]) – Y-Coordinate of the origin, e.g. y=1000.
z (Union[float, int]) – Altitude of the origin, e.g. z=200.

Raises

ValueError – If a non-Cartesian coordinate system is used.
TypeError – If the wrong input data types are provided.

Examples

>>> borehole.deviation.add_origin_to_desurveying(x=100, y=100, z=000)

New in version 0.0.1.

get_borehole_tube(radius: Union[float, int] = 10, x: Union[float, int] = 0, y: Union[float, int] = 0, z: Union[float, int] = 0, relative: bool = False)#

Get borehole tube.

Parameters

radius (Union[float, int], default: 10) – Radius of the borehole tube, e.g. radius=10.
x (Union[float, int], default: 0) – X-coordinate of the borehole, e.g. x=1000.
y (Union[float, int], default: 0) – Y-coordinate of the borehole, e.g. y=1000.
z (Union[float, int], default: 0) – Z-coordinate of the borehole, e.g. y=100.
relative (bool, default: False) – Boolean value to plot the plot with relative coordinates.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> borehole.deviation.get_borehole_tube(radius=10)

New in version 0.0.1.

plot_deviation_3d(elev: Union[float, int] = 45, azim: Union[float, int] = 45, roll: Union[float, int] = 0, relative: bool = False)#

Create 3D Deviation Plot.

Parameters

elev (Union[float, int], default: 45) – Elevation angle for view, e.g. elev=45.
azim (Union[float, int], default: 45) – Azimuth angle for view, e.g. azim=45.
roll (Union[float, int], default: 0) – Rolling angle for view, e.g. roll=0.
relative (bool, default: False) – Boolean value to plot the plot with relative coordinates.

Returns

fig (matplotlib.figure) – Matplotlib figure.
ax (matplotlib.axes.Axes) – Matplotlib axis.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> borehole.deviation.plot_deviation_3d()

New in version 0.0.1.

plot_deviation_polar_plot(c: numpy.ndarray = None, vmin: Union[float, int] = None, vmax: Union[float, int] = None, cmap: str = 'viridis')#

Add polar plot representing the deviation of a borehole.

Parameters

c (np.ndarray) – Array for coloring the well path.
vmin (Union[float, int]) – Minimum value for colormap, e.g. vmin=0.
vmax (Union[float, int]) – Maximum value for colormap, e.g. vmax=100.
cmap (str, default: 'viridis') – Name of the colormap to be used, e.g. cmap='viridis'.

Raises

TypeError – If the wrong input data types are provided.

Examples

>>> borehole.deviation.plot_deviation_polar_plot()

New in version 0.0.1.

PyBorehole - Processing Tool for Borehole Data

PyBorehole API Reference

Contents

PyBorehole API Reference#

pyborehole.borehole module#