watex.geology package#

Geology sub-package is dedicated for structural informations and strata layer building. It uses some modeling data exported as two-dimensional matrices block of resistivity (e.g ModEM, MTpy, pycsamt, OCCAM2D) and combined with the geological informations on the survey area to build the stratigraphy logs. It also give an alternative way to draw some drilling logs after the drilling operations.

class watex.geology.Borehole(lat=None, lon=None, area=None, status=None, depth=None, base_depth=None, geol=None, staticlevel=None, airlift=None, holeid=None, qmax=None, **kwds)[source]#

Bases: Geology

Focused on Wells and Borehole offered to the population. To use the data for prediction purpose, each Borehole provided must be referenced on coordinates values or provided the same as the one used on ves or erp file.

fit(data)[source]#: Fit Borehole data and populate the corrsponding attributes

class watex.geology.DSBorehole(hole=None, dname=None, projection='ll', utm_zone=None, datum='WGS84', epsg=None, reference_ellipsoid=23, encoding='utf-8', lonlat=None, verbose=0)[source]#

Bases: object

Class delas with Borehole datasets.

watex.geology.drilling.DSBorehole works with data collected in a single borehole. For instance, it could follow the arrangement of h502 data in watex.datasets.load_hlogs()

Parameters

hole (str) – Name or ID of the borehole.
dname (str, optional) – Depth column name. If depth is specify an attribute depth_ should be created. Depth specification is usefull for log plotting of machine training.
utm_zone (Optional, string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Default to the centre point of coordinates points in the survey area. It should be a string (##N or ##S) in the form of number and North or South hemisphere, 10S or 03N
projection (str, ['utm'|'dms'|'ll']) – The coordinate system in which the data points for the profile is collected. If not given, the auto-detection will be triggered and find the suitable coordinate system. However, it is recommended to provide it for consistency. Note that if x and y are composed of value less than 180 degrees for longitude and 90 degrees for latitude, it should be considered as longitude-latitude (ll) coordinates system. If x and y are degree-minutes-second (dms or dd:mm:ss) data, they must be specify as coordinate system in order to accept the non-numerical data before transforming to ll. If data is passed to the fit() method and dms is not specify, x and y values should be discarded.
datum (string, default = 'WGS84') – well known datum ex. WGS84, NAD27, NAD83, etc.
epsg (Optional, int) –

epsg number defining projection (
see http://spatialreference.org/ref/ for moreinfo)

Overrides utm_zone if both are provided.
reference_ellipsoid (int, default=23) – reference ellipsoids is derived from Peter H. Dana’s website- http://www.utexas.edu/depts/grg/gcraft/notes/datum/elist.html Department of Geography, University of Texas at Austin Internet: pdana@mail.utexas.edu . Default is 23 constrained to WGS84.
encoding (str, default ='utf8') – Default encoding for parsing data. Can also be [‘utf-16-be’] for reading bytes characters.
lonlat (Tuple, Optional) – longitude/latitude for borehole coordinates. The location where the borehole is performed.
verbose (int, default=0) – Output messages.

depth_#

Depth array if dname is specified.

Type: Series

data_#

Sanitized dataframe.

Type: Pandas DataFrame

Note

Each columns of the dataframe is an attribute. Note that all the non- alphabetic letters is removed and replace by ‘_’.

Examples

>>> import watex as wx
>>> from watex.geology import DSBorehole
>>> hdata= wx.fetch_data ('hlogs',samples = 12 ).frame
>>> b = DSBorehole (hole='H502').fit(hdata)
>>> b.feature_names_in_
Out[77]:
['depth_top',
 'depth_bottom',
 'layer_thickness',
 'resistivity',
 'gamma_gamma',
 'natural_gamma',
 'sp',
 'short_distance_gamma',
 'well_diameter',
 'aquifer_thickness',
 'hole_depth_before_pumping',
 'hole_depth_after_pumping',
 'hole_depth_loss',
 'depth_starting_pumping',
 'pumping_depth_at_the_end',
 'pumping_depth',
 'section_aperture',
 'k',
 'kp',
 'r',
 'rp',
 'hole_id',
 'strata_name',
 'rock_name',
 'aquifer_group',
 'pumping_level']
>>> b.strata_name
Out[78]:
0                       topsoil
1                        gravel
2                      mudstone
3                     siltstone
4                      mudstone

176 coal 177 siltstone 178 coarse-grained sandstone 179 fine-grained sandstone 180 coarse-grained sandstone Name: strata_name, Length: 181, dtype: object

fit(data, **fit_params)[source]#

Fit Borehole data and populate attribute data.

By default if the projection is given as latitude/longitude xlon, ylat are longitude and latitude respectively.

Parameters

data (pd.DataFrame or Path-like object.) – Data containing the borehole informations.
fit_params (dict,) – Keyword arguments passed to watex.utils.to_numeric_dtypes() for data management.

Returns

self – Instanced object for chaining method.

Return type

Instanced object

property inspect#: Inspect object whether is fitted or not

set_depth(z0=0.0, max_depth=None, reset_depth=Ellipsis)[source]#

Set the a random depth if depth is not supplied in the Borehole data

To fetch the depth, use attribute depth_. Note that if the depth exists, calling set_depth will erase the former depth value. Use in cautioness.

Parameters

z0 (float, default=0.) – The surface reference. Preferably, it is set to null.
max_depth (float, default=700.) – The maximum depth. Depth size must fit the length of the data in meters. Default depth is fixed to 700 meters.
reset_depth (bool, default =False,) – An alternative way to controle whether to keep the previous and new computed depth in the borehole data. The parameter erases the previous depth if exists the borehole data. If True a new depth is set in replacement to the previous depth and both are kept in the data otherwise.

Returns

self – Instanced object for chaining method.

Return type

Instanced object

Examples

>>> import watex as wx
>>> from watex.geology import DSBorehole
>>> hdata= wx.fetch_data ('hlogs').frame
>>> b = DSBorehole (hole='H502').fit(hdata)
>>> b.set_depth ()
>>> b.depth_
Out[82]:
0        0.000000
1        3.888889
2        7.777778
3       11.666667
4       15.555556

176 684.444444 177 688.333333 178 692.222222 179 696.111111 180 700.000000 Name: depth, Length: 181, dtype: float64 >>> b.set_depth (max_depth = 900, reset_depth= True ) >>> b.depth_ Out[85]: 0 0.0 1 5.0 2 10.0 3 15.0 4 20.0

176 880.0 177 885.0 178 890.0 179 895.0 180 900.0 Name: depth, Length: 181, dtype: float64

set_strata(add_electrical_properties=False, random_state=None, shuffle=True, reset_strata=Ellipsis, reset_electrical_properties=Ellipsis)[source]#

Generate a pseudo strata associated to each depth in the borehole data.

Parameters

add_electrical_properties (bool, default=False,) – Add electrical resistivty values associated to each generated stratum
random_state (int, array-like, BitGenerator, np.random.RandomState, np.random.Generator, optional) – If int, array-like, or BitGenerator, seed for random number generator. If np.random.RandomState or np.random.Generator, use as given.
shuffle (bool, default=True) – Shuffle the random generated thicknesses.
reset_strata (bool, default=False,) – generate new strata at each depth. If True and the name strata is valid in the borehole data colum name. Layer names that composes each stratum should be erased.
reset_electrical_properties (bool, default=False) – Erase the former electrical values and replace by new names that fit each strata.

Returns

self – Instanced object for chaining method.

Return type

Instanced object

Examples

>>> import watex as wx
>>> from watex.geology import DSBorehole
>>> hdata= wx.fetch_data ('hlogs', key='h803').frame
>>> b = DSBorehole (hole='H803').fit(hdata)
>>> b.set_strata ()
>>> b.strata_
Out[122]:
0                tourmalinite
1                        silt
2                         mud
3         volcaniclastic rock
4                ore minerals

129 sulphide-rich material 130 argillite 131 graphite 132 high-Mg basalt 133 shale Name: strata, Length: 134, dtype: object >>> b.set_strata (add_electrical_properties= True, reset_strata= True) >>> b.strata_ Out[123]: 0 phyllite 1 syenite 2 laterite 3 saprolite 4 psammopelite

129 chert 130 granulite 131 pyroclastic rock 132 lamprophyre 133 ignimbrite Name: strata, Length: 134, dtype: object

b.strata_electrical_properties_ Out[124]: 0 0.0 1 0.0 2 0.0 3 330.6 4 0.0

129 0.0 130 0.0 131 0.0 132 0.0 133 0.0 Name: strata_electrical_properties, Length: 134, dtype: float64 >>>

set_thickness(h0=1, shuffle=True, dirichlet_dist=Ellipsis, reset_layer_thickness=Ellipsis, reset_depth=Ellipsis, **kws)[source]#

Generate a random layer thickness from borehole refering to the depth.

To fetch the thickness, use attribute layer_thickness_. Use reset_layer_thickness to set new strata thicknesses.

Parameters

h0 (int, default='1m') – Thickness of the first layer.
shuffle (bool, default=True) – Shuffle the random generated thicknesses.
dirichlet_dis (bool, default=False) – Draw samples from the Dirichlet distribution. A Dirichlet-distributed random variable can be seen as a multivariate generalization of a Beta distribution. The Dirichlet distribution is a conjugate prior of a multinomial distribution in Bayesian inference.
reset_layer_thickness (bool, default=False,) – Set new layer thicknesses to the existing stratum. If True and the data included layer thicknesses, the latter should be dropped in replacement to the new ones. However, if False, no action is performed and both are kept in the data.
reset_depth (bool, default=False) – Note that thickness generating works with the depth. So, if the reset_depth is set to True, a new depth is computed and drop the former ones. From this new depth, the thickness generating is creating.
random_state (int, array-like, BitGenerator, np.random.RandomState, np.random.Generator, optional) – If int, array-like, or BitGenerator, seed for random number generator. If np.random.RandomState or np.random.Generator, use as given.
unit (str, default='m') – The reference unit for generated layer thicknesses. Default is meters

Returns

self – Instanced object for chaining method.

Return type

Instanced object

Examples

>>> import watex as wx
>>> from watex.geology import DSBorehole
>>> hdata= wx.fetch_data ('hlogs').frame
>>> b = DSBorehole (hole='H502').fit(hdata)
>>> b.set_thickness ()
>>> b.layer_thickness_
0      5.410380
1      2.068812
2      0.398028
3      6.352873
4      6.395714

176 3.396871 177 0.012463 178 7.124004 179 7.038323 180 3.439711 Name: layer_thickness, Length: 181, dtype: float64 >>> b.set_thickness (dirichlet_dist=True, reset_layer_thickness=True

).layer_thickness_

Out[89]: 0 0.681640 1 1.986043 2 6.413090 3 5.305284 4 0.000144

176 4.119242 177 12.161252 178 1.809102 179 0.408810 180 4.281848 Name: layer_thickness, Length: 181, dtype: float64

class watex.geology.DSBoreholes(area=None, holeid=None, lat=None, lon=None, projection='ll', utm_zone=None, datum='WGS84', epsg=None, encoding='utf-8', interp_coords=False, reference_ellipsoid=23, verbose=False)[source]#

Bases: object

Class deals with many boreholes dataset.

DSBoreholes works with the data set composed of multiple borehole data. The data columns are the all attributes of the object and any non-alphateic character is by _. For instance, a column name layer thickness should have an attribute named layer_thickness. Each borehole (row) data become its own object which encompasses all columns as attributes. To have full control of how data must be retrieved, holeid parameter must be set. For instance, to retrieve the borehole with ID equals to bx02, after fitting the class with appropriate parameters, attibute hole depth ( if exist in the data) can be retrieved as self.hole.bx02.hole_depth.

By default if the projection is given as latitude/longitude

Parameters

area (str) – Name of area where the data collection is made.
holeid (str, optional) –
The name of column of the boreholes collections ID. Note that if
given, it must exist in the borehole datasets. Note that if hole ID is not specified, each borehole can be fetched from a attribute hole count from 0 to n_samples. For instance, the borehole number 12 can be collected using:
>>> b = DSBoreholes ().fit(<borehole_data>) >>> b.hole.hole11
where 12 is the 12em position as Python index starts with 0. However when holeid is specified, the hole attribute is replaced by each value of the hole_id column as:
```
>>> borehole_data['hole_id'][:3]
0    B0092
1    B0093
2    B0094
Name: hole_id, dtype: object
>>> b.hole.B0092
>>> b.hole.B0094
```
where B0092 or B0094 are the borehole in the columns hole_id. Note that hole_id can be any other names at least it is explicitly specified as a argument of the ``holeid` parameter.
lon (ArrayLike 1d /str , optional) – One dimensional arrays. xlon can be consider as the abscissa of the landmark and ylat as ordinates array. If xlon or ylat is passed as string argument, data must be passed as fit_params keyword arguments and the name of xlon and y must be a column name of the data. By default xlon and ylat are considered as longitude and latitude when dms or ll coordinate system is passed.
lat (ArrayLike 1d /str , optional) – One dimensional arrays. xlon can be consider as the abscissa of the landmark and ylat as ordinates array. If xlon or ylat is passed as string argument, data must be passed as fit_params keyword arguments and the name of xlon and y must be a column name of the data. By default xlon and ylat are considered as longitude and latitude when dms or ll coordinate system is passed.
utm_zone (Optional, string) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Default to the centre point of coordinates points in the survey area. It should be a string (##N or ##S) in the form of number and North or South hemisphere, 10S or 03N
projection (str, ['utm'|'dms'|'ll']) – The coordinate system in which the data points for the profile is collected. If not given, the auto-detection will be triggered and find the suitable coordinate system. However, it is recommended to provide it for consistency. Note that if x and y are composed of value less than 180 degrees for longitude and 90 degrees for latitude, it should be considered as longitude-latitude (ll) coordinates system. If x and y are degree-minutes-second (dms or dd:mm:ss) data, they must be specify as coordinate system in order to accept the non-numerical data before transforming to ll. If data is passed to the fit() method and dms is not specify, x and y values should be discarded.
datum (string, default = 'WGS84') – well known datum ex. WGS84, NAD27, NAD83, etc.
epsg (Optional, int) –

epsg number defining projection (
see http://spatialreference.org/ref/ for moreinfo)

Overrides utm_zone if both are provided.
encoding (str, default ='utf8') – Default encoding for parsing data. Can also be [‘utf-16-be’] for reading bytes characters.
interp_coords (bool, default=False) – Interpolate position coordinates.
reference_ellipsoid (int, default=23) – reference ellipsoids is derived from Peter H. Dana’s website- http://www.utexas.edu/depts/grg/gcraft/notes/datum/elist.html Department of Geography, University of Texas at Austin Internet: pdana@mail.utexas.edu . Default is 23 constrained to WGS84.
verbose (int, default=0) – Output messages.

lon_, lat_

longitude/latitude of coordinates arrays.

Type: Arraylike,

`hole.<holeid>.<data_column>`

Each borehole, commonly which ID correspond to each row. Each row can be fetched as ‘holeID’. If holeid is nt specified, the string literal hole+index of data composed the borehole object.

Type: Boxspace

Notes

When data is supplied and lon and lat are given by their names existing in the dataframe columns, by default, the non-numerical data are removed. However, if y and x are given in DD:MM:SS in the dataframe, the coordinate system must explicitly set to ``dms` to keep the non-numerical values in the data.

Examples

>>> import watex as wx
>>> from watex.geology import DSBoreholes
>>> bs_data = wx.fetch_data ('nlogs', key='hydro', samples=12 ,
                             as_frame=True )
>>> bs=DSBoreholes ().fit(bs_data)
>>> bs.holeid
Out[61]: 'hole'
>>> # when the default object hole is set as:
>>> bs.hole # outputs a Boxspace object each borehole can be retrieved
>>> # as hole object count from 0. to number or rows -1. Here is an
>>> example of fetching the hole 11.
>>> bs.hole.hole10
Out[62]:
{'hole_id': 'B0103',
 'uniform_number': 1.1343e+16,
 'original_number': 'Guangzhou multi-element urban geological survey drilling 19ZXXSW11',
 'lon': '113:43:00.99',
 'lat': '23:16:17.23',
 'longitude': 113.71694166666668,
 'latitude': 23.271452777777775,
 'east': 2577207.0,
 'north': 19778060.0,
 'easting': 2577207.276,
 'northing': 19778177.29,
 'coordinate_system': 'Xian 90',
 'elevation': 22.0,
 'final_hole_depth': 60.1,
 'quaternary_thickness': 45.8,
 'aquifer_thickness': 18.1,
 'top_section_depth': 42.0,
 'bottom_section_depth': 60.1,
 'groundwater_type': 'igneous rock fissure water',
 'static_water_level': 2.36,
 'drawdown': 28.84,
 'water_inflow': 0.08,
 'unit_water_inflow': 0.003,
 'filter_pipe_diameter': 0.16,
 'water_inflow_in_m3_d': 2.94}
>>> # when we specified the hole ID to the column that compose the ID like:
>>> bs=DSBoreholes (holeid ='hole_id').fit(bs_data)
>>> bs.hole.B0103
Out[63]:
{'hole_id': 'B0103',
 'uniform_number': 1.1343e+16,
 'original_number': 'Guangzhou multi-element urban geological survey drilling 19ZXXSW11',
 'lon': '113:43:00.99',
 'lat': '23:16:17.23',
 'longitude': 113.71694166666668,
 'latitude': 23.271452777777775,
 'east': 2577207.0,
 'north': 19778060.0,
 'easting': 2577207.276,
 'northing': 19778177.29,
 'coordinate_system': 'Xian 90',
 'elevation': 22.0,
 'final_hole_depth': 60.1,
 'quaternary_thickness': 45.8,
 'aquifer_thickness': 18.1,
 'top_section_depth': 42.0,
 'bottom_section_depth': 60.1,
 'groundwater_type': 'igneous rock fissure water',
 'static_water_level': 2.36,
 'drawdown': 28.84,
 'water_inflow': 0.08,
 'unit_water_inflow': 0.003,
 'filter_pipe_diameter': 0.16,
 'water_inflow_in_m3_d': 2.94}
>>> # each columns can be fetched as
>>> bs.quaternary_thickness
Out[64]:
0     40.5
1     12.3
2     25.5
3     40.0
4     35.0
5     47.0
6     34.0
7     40.4
8     15.1
9     17.2
10    45.8
11    47.0
Name: quaternary_thickness, dtype: float64

fit(data, **fit_params)[source]#

Fit Hole data set and populate attributes.

Parameters

data (Path-like Object or DataFrame) – Hole data.
fit_params (dict,) – Keyword arguments passed to watex.to_numeric_dtypes() to sanitize the data.

Returns

self – Instanced object for chaining methods.

Return type

DSBoreholes

property inspect#: Inspect object whether is fitted or not

set_coordinates(reflong, reflat, step='5m', todms=False, r=45, **kws)[source]#

Generate longitude and latitude coordinates for boreholes.

It assumes boreholes are aligned along the same axis.

Parameters

reflong (float or string or list of [start, stop]) – Reference longitude in degree decimal or in DD:MM:SS for the first site considered as the origin of the landmark.
reflat (float or string or list of [start, stop]) – Reference latitude in degree decimal or in DD:MM:SS for the reference site considered as the landmark origin. If value is given in a list, it can containt the start point and the stop point.
step (float or str) – Offset or the distance of seperation between different sites in meters. If the value is given as string type, except the km, it should be considered as a m value. Only meters and kilometers are accepables.
r (float or int) – The rotate angle in degrees. Rotate the angle features toward the direction of the projection profile. Default value use the bearing() value in degrees.
todms (bool, Default=False) – Reconvert the longitude/latitude degree decimal values into the DD:MM:SS.
kws (dict,) – Additional keywords of makeCoords().

Returns

self – Instanced object for method chaining.

Return type

Instanced object

Examples

>>> bs_data = wx.fetch_data ('nlogs', key='ns', samples=7,
                             as_frame=True )
>>> bs=DSBoreholes ().fit(bs_data)
>>> bs.set_coordinates(reflong= 113.4, reflat=22.56, step ='10m')
>>> bs.set_coordinates(reflong= 113.4, reflat=22.56, step ='10m')
>>> bs.lat_
Out[71]:
array([22.56      , 22.56009391, 22.56018782, 22.56028174, 22.56037565,
       22.56046956, 22.56056347])
>>> bs.lon_
Out[72]:
array([113.4       , 113.40007436, 113.40014871, 113.40022307,
       113.40029742, 113.40037178, 113.40044614])

class watex.geology.DSDrill(area=None, holeid=None, dname=None, projection='ll', utm_zone=None, datum='WGS84', encoding='utf-8', epsg=None, reference_ellipsoid=23, properties=None, **kwd)[source]#

Bases: GeoBase

Drill data set class.

DSDrill reads, constructs the well/hole (drillhole:DH), geology and geochemistry samples into a data set for transforming geophysics, geology, GIS, and geochemistry data collecting in a survey area into a three dimensional representation with `Oasis montaj`_. Deal with drillhole menu of Oasis Montaj software. Build data and contruct three dimensional data with `Oasis montaj`_ in Seequent.

Parameters

area: str

Area where the drilling operation is performed.

holeid: str,

the column name in the data where the well/hole ID is stored.

dname: str, optional

Depth column name. If depth is specify an attribute depth_ should be created. Depth specification is usefull for log plotting of machine training.

utm_zone: Optional, string

zone number and ‘S’ or ‘N’ e.g. ‘55S’. Default to the centre point of coordinates points in the survey area. It should be a string (##N or ##S) in the form of number and North or South hemisphere, 10S or 03N

projection: str, [‘utm’|’dms’|’ll’]

The coordinate system in which the data points for the profile is collected. If not given, the auto-detection will be triggered and find the suitable coordinate system. However, it is recommended to provide it for consistency. Note that if x and y are composed of value less than 180 degrees for longitude and 90 degrees for latitude, it should be considered as longitude-latitude (ll) coordinates system. If x and y are degree-minutes-second (dms or dd:mm:ss) data, they must be specify as coordinate system in order to accept the non-numerical data before transforming to ll. If data is passed to the fit() method and dms is not specify, x and y values should be discarded.

datum: string, default = ‘WGS84’

well known datum ex. WGS84, NAD27, NAD83, etc.

encoding: str, default =’utf8’

Default encoding for parsing data. Can also be [‘utf-16-be’] for reading bytes characters.

epsg: Optional, int

epsg number defining projection (: see http://spatialreference.org/ref/ for moreinfo)

Overrides utm_zone if both are provided.

reference_ellipsoid: int, default=23

reference ellipsoids is derived from Peter H. Dana’s website- http://www.utexas.edu/depts/grg/gcraft/notes/datum/elist.html Department of Geography, University of Texas at Austin Internet: pdana@mail.utexas.edu . Default is 23 constrained to WGS84.

properties: dict,

Data column can not fit the Drilling property columns. In that case. Mapping the property names is usefull to specify the columns in the original data that fits the DSDrill property codes. For instance:

   properties ={"hole name": 'DH_Hole',
                    "easting": 'DH_East',
                    "northing": 'DH_Northing'
                    }

where "hole name", "easting" and "northing" are the column names in
the former data set. These names should be replaced by the "DH_Hole",
"DH_East" and "DH_North" respectively. The mapping can be used  to
specify any other property names. Note that the valuable properties
are:

- "DH_Hole": Well/hole ID
- "DH_East": Easting coordinates of the well/hole
- "DH_North":  Northing coordinates of the well/hole.
- "Mask": Any comment about the well/hole ID
- "DH_RH": Radius value of the well/hole ID
- 'DH_From': Top(roof) of any stratum/sample or rock in the well/hole.
- "DH_To" : Wall( bottom) of any stratum/sample or rock in the well/hole.
- "Rock" : Rock or strata/layer in the well/hole.
- "DH_Azimuth": Azimuth value in the well/hole.
- 'DH_Top': Surface-level of the well/hole compared to the level of sea.
- 'DH_Bottom': Maximum depth of the well/hole.
- 'DH_PlanDepth': Any section performed in the well/hole can be inputed.
- 'DH_Decr': Description of the well/hole.
- 'Sample': Sample collected in the well/hole at different depth.
- 'DH_Dip': Dip of the well/hole.
- 'Elevation': Elevation of the well/hole.
- 'DH_RL': Level of piezometric value if exists in the well/hole.

verbose: int, default=0: Output messages.

Attributes

depth_: Series: Depth array if dname is specified.
data_: Pandas DataFrame: Sanitized dataframe.
collar_:Pandas DataFrame: Collar data composed of each borehole description.
geology_: Pandas DataFrame: Geology data that compose each geological rocks
samples_: Pandas DataFrame: Each Geochemistry samples data compose each sample collected in the survey area.

build_collar(*, return_data=False, compute_azimuth=Ellipsis, utm_zone=Ellipsis, **kwd)[source]#

Build manually the collar data of collected drilling area.

Collar data is composed of well/hole description and usefull informations.

:meth:`build_collar collect each drillhole informations during the drilling operations or well contructions. The total of the information will build a collar dataset which can be used to Oasis Montaj software modeling. Below is an example of collar data set construction. This is some explanation of the prompt:

well/hole ID: Is the name or ID of the rocks or strata collected in the area
coordinates (xlon, xlat): is the geographical coordinates where the drilling operation is performed. Expect projection is ll. To enter the UTM coordinates, set the projection in the building object to utm like:
```
>>> DSDrill (projection='utm').build_collar (return_data =True )
```
radius (m): Is the radius of the hole/well
surface-level: The level of the well/hole compared to the level of the sea. By default it is set to null as the level of the sea.
depth: depth of the well/hole in meters.
dip: dip in degree of the well/hole.
elevation: elevation value of the well/hole in meters. Default is no topography i.e. equal null.
azimuth: azimuth value in degrees. If not given explicitely, it can be calculated using the utm coordinates provided that the parameter compute_azimuth is set to True and utm_zone is also provided. In this case, we assume that all well/hole collected belongs to the same area. Furthermore, azimuth calculation will cancel if one of the above condition is not met and if only a single borehole is supplied.
plan-depth: Is a litteral string to give at which stage a section in a borehole is performed. Note that this is optional parameter and can be skipped. It has no more influence about the collar construction.
description: Give a short description of well/hole mostly about the drilling settlment.
mask/comments: Is any comments aboud the well/hole.

Parameters

return_data (bool, default=False,) – Return the collar dataset rather than object (False) after entering the appropriate argumments. Note that even True, the collar data set can be retrieved via the attribute collar_.
compute_azimuth (bool, default=False) – Recompute the azimuth using the UTM coordinates. Note that projection need to be turned in ‘utm’ as well as the ‘utm_zone’ needs also to be supplied.
utm_zone (str,) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Default to the centre point of coordinates points in the survey area. It should be a string (##N or ##S)in the form of number and North or South hemisphere, 10S or 03N. if utm_zone is already set, it is not need to reset again. Resetting new utm_zone will erase the value of the former attribute. However for azimuth calculation, utm zone cannot be None otherwise the process is aborted.

Returns

self, collar dataset – Return object when return_data=False and DataFrame otherwise.

Return type

DSDrill or pd.DataFrame.

Examples

>>> col_data=DSDrill (projection ='utm').build_collar (return_collar =True )
Enter the well/hole ID:DXT03
Enter DXT03 coordinates (xlon, ylat):297856 352145
Enter DXT03 radius in meters [Optional]:.25
Enter DXT03 surface-level <top> in meters[0.]:
Enter DXT03 depth <bottom> in meters[700.]:120
Enter DXT03 dip in degrees [-90]:
Enter DXT03 elevation in meters [0.]:
Enter DXT03 azimuth [Optional]:
Enter DXT03 plan-depth [Optional]:wandx01
Enter DXT03 description [Optional]:hole-test
Enter valuable comments about DXT03 [Optional]:RAS
Tap "exit|0" to terminate or "Enter" to continue:
Enter the well/hole ID:toxg
Enter TOXG coordinates (xlon, ylat):125869 235645
Enter TOXG radius in meters [Optional]:2.3
Enter TOXG surface-level <top> in meters[0.]:-10
Enter TOXG depth <bottom> in meters[700.]:135
Enter TOXG dip in degrees [-90]:-70
Enter TOXG elevation in meters [0.]:3
Enter TOXG azimuth [Optional]:2.3
Enter TOXG plan-depth [Optional]:wxzu
Enter TOXG description [Optional]:None
Enter valuable comments about TOXG [Optional]:RAS
Tap "exit|0" to terminate or "Enter" to continue:0
>>> col_data
Out[3]:
  DH_Hole   DH_East  DH_North  DH_RH  ...  DH_Azimuth  DH_PlanDepth    DH_Decr  Mask
0   DXT03  297856.0  352145.0   0.25  ...         NaN       wandx01  hole-test   RAS
1    TOXG  125869.0  235645.0   2.30  ...         2.3          wxzu       None   RAS

build_drillholes(kind, return_data=Ellipsis, hole_elevation=0.0, compute_azimuth=Ellipsis, utm_zone=Ellipsis)[source]#

Build drillholes [‘collar|’geology’|’samples’] mannually through the parameter kind.

All the drillholes have the common attributes such as:

DH_Hole - well/hole , rock or sample ID: Is the ID of the geochemistry samples, rocks/strata or well/holes collected in the area
"DH_East" and "DH_North"- coordinates (xlon, xlat): is the geographical coordinates where the drilling operation is performed. Expect projection is ll. To enter the UTM coordinates, set the projection in the building object to utm like:
```
>>> DSDrill (projection='utm').build_collar (return_data =True )
```
"DH_RH" - radius (m): Is the radius of the hole/well
Mask - mask/comments: Is any comments aboud the samples/geology or well/hole.

Besides, there are some other specific attributes related to each drillhole. For instance, the following attributes are required for:

collar:
- "DH_Top" - surface-level: The level of the well/hole compared to the level of the sea. By default it is set to null as the level of the sea.
- "DH_Bottom" - depth: depth of the well/hole in meters.
- "DH_Dip" - dip: dip in degree of the well/hole.
- "Elevation" - elevation: elevation value of the well/hole in meters. Default is no topography i.e. equal null.
- "DH_Azimuth" - azimuth: azimuth value in degrees. If not given explicitely, it can be calculated using the utm coordinates provided that the parameter compute_azimuth is set to True and utm_zone is also provided. In this case, we assume that all well/hole collected belongs to the same area. Furthermore, azimuth calculation will cancel if one of the above condition is not met and if only a single borehole is supplied.
- "DH_PlanDepth" - plan-depth: Is a litteral string to give at which stage a section in a borehole is performed. Note that this is optional parameter and can be skipped. It has no more influence about the collar construction.
- DH_descr - description: Give a short description of well/hole mostly about the drilling settlment.
geology:
- "DH_From" and "DH_To" is computed from the layer thicknesses i.e. the thickness of each strata in the whole. Note that when many thicknesses are supplied, it may correspond to each layer. Thus, the number of thicknesses must equal to the number of layers.
- "Rock" - the rock/layer names. It should be equals to the number of layer thicknesses. If not the case, NA should be
  
  used to indicate the missing layer/rock name in the geology dataset.
samples:
- "DH_From" and "DH_To" - samples thickness: Ask about the thickness of the samples in the whole. Note that when many thickness are supplied, it means the same sample is collected at different depth. There are two kind of data to supply:
- t-value: Compose only with the layer thickness values. For instance t= "10 20 7 58" indicates four samples with thicknesses equals to 10, 20, 7 and 58 ( meters) respectively.
- tb-range: compose only with thickness range at each depth. For instance t= "0-10 10-30 40-47 101-159". Note the character used to separate thickness range is '-'. Here, the top(roof) and bottom(wall) of the sample are 0 (top) and 10 (bottom), 10 and 30, 40 and 47 , and 101 and 159 for the same sample.
- Note that any mixed types is not acceptable and willraises error. To verify whether the expected samples values is acceptable or not, use the following watex.utils.geotools.get_thick_from_range() or watex.utils.geotools.get_thick_from_values() functions.
- "Sample" - sample name: Is the name of samples collected refereing to the different depth. In principle, the number of samples thickness must equals to the number of samples. If not the case, NA should be used to indicate the missing samples in the geosamples dataset.

Parameters

kind (str) – kind of drillhole to build. It could be [‘collar|’geology’|’samples’] Until now, ‘elevation’ drillhole is not built yet.
return_data (bool, default=False,) – Return the geology dataset rather than object (False) after entering the appropriate argumments. Note that even True, the geology data set can be retrieved via the attribute geology_.
hole_elevation (float, default=0,) – The elevation or the level of surface of the well/hole compared to the level of sea. Note that elevation must be negative value on the top of the air for layer/strat calculation.
compute_azimuth (bool, default=False) – Recompute the azimuth using the UTM coordinates. Note that projection need to be turned in ‘utm’ as well as the ‘utm_zone’ needs also to be supplied.
utm_zone (str,) – zone number and ‘S’ or ‘N’ e.g. ‘55S’. Default to the centre point of coordinates points in the survey area. It should be a string (##N or ##S)in the form of number and North or South hemisphere, 10S or 03N. if utm_zone is already set, it is not need to reset again. Resetting new utm_zone will erase the value of the former attribute. However for azimuth calculation, utm zone cannot be None otherwise the process is aborted.

Returns

self, collar/geology/geochemistry samples dataset – Return object when return_data=False and DataFrame otherwise.

Return type

DSDrill or pd.DataFrame.

Examples

>>> from watex.geology import DSDrill
>>> DSDrill().build_drillholes ('collar', return_data=True)
Enter the well/hole ID:Dh00
Enter DH00 coordinates (x/lon, y/lat):11 15
Enter DH00 radius in meters [Optional]:0.2
Enter DH00 surface-level <top> in meters[0.]:
Enter DH00 depth <bottom> in meters[700.]:
Enter DH00 dip in degrees [-90]:
Enter DH00 elevation in meters [0.]:12
Enter DH00 azimuth [Optional]:
Enter DH00 plan-depth [Optional]:
Enter DH00 description [Optional]:
Enter valuable comments about DH00 [Optional]:testDh
Tap "exit|0" to terminate or "Enter" to continue:0
Out[16]:
  DH_Hole       DH_East       DH_North  ...  DH_PlanDepth  DH_Decr    Mask
0    DH00  1.659298e+06  715053.016841  ...           NaN      NaN  testDh
>>> DSDrill().build_drillholes('geology')
Enter the well/hole ID:Geo00
Enter GEO00 coordinates (x/lon, y/lat):11 15
Enter GEO00 radius in meters [Optional]:2
Enter the GEO00 depth in meters: 60
Enter each stratum thickness of GEO00 [top-->bottom] in meters:12
Enter the layer/rock names of GEO00 [top-->bottom]:sand
Enter valuable comments about GEO00 [Optional]:test-geo
Tap "exit|0" to terminate or "Enter" to continue:0
Out[19]:
  DH_Hole       DH_East       DH_North  DH_RH  DH_From  DH_To  Rock      Mask
0   GEO00  1.659298e+06  715053.016841    2.0      0.0   12.0  sand  test-geo
1   GEO00  1.659298e+06  715053.016841    2.0     12.0   60.0    NA  test-geo

build_geology(*, return_data=False, hole_elevation=0.0, **kwd)[source]#

Build manually the geology data of collected drilling area.

build_geology() collect the rocks or strata names collected during the drilling operations or well contructions. The collection of the information will build a geology dataset which can be used to Oasis Montaj software modeling. Below is an example of geology data set construction. This is some explanation of the prompt:

well/hole ID: Is the name or ID of the rocks or strata collected in the area
coordinates (xlon, xlat): is the geographical coordinates where the drilling operation is performed. Expect projection is ll. To enter the UTM coordinates, set the projection in the building object to utm like:
```
>>> DSDrill (projection='utm').build_geology (return_geology =True )
```
radius (m): Is the radius of the hole/well
depth: depth of the well/hole in meters.
layer thickness: The thickness of each strata in the whole. Note that when many thickness are supplied, it may correspond to each layer i.e. the number of thicknesses must equal to the number of layers. If not the case, NA should be used to indicate the missing layer/rock name in the geology dataset.
mask/comments: Is any comments aboud the well/hole.

Parameters

return_data (bool, default=False,) – Return the geology dataset rather than object (False) after entering the appropriate argumments. Note that even True, the geology data set can be retrieved via the attribute geology_.
hole_elevation (float, default=0,) – The elevation or the level of surface of the well/hole compared to the level of sea. Note that elevation must be negative value on the top of the air for layer/strat calculation.

Returns

self, geology dataset – Return object when return_geology=False and DataFrame otherwise.

Return type

DSDrill or pd.DataFrame.

Examples

>>> DSDrill ().build_geology (return_geology =True )
Enter the well/hole ID:GEOK4
Enter GEOK4 coordinates (xlon, ylat):10 15
Enter GEOK4 radius in meters [Optional]:12.2
Enter the GEOK4 depth in meters: 75
Enter each stratum thickness of GEOK4 [top-->bottom] in meters:10 20 11
Enter the layer/rock names of GEOK4 [top-->bottom]:granite gneiss
Enter valuable comments about GEOK4 [Optional]:building test
Tap exit|0 to terminate or enter to continue:0
Out[17]:
  DH_Hole       DH_East  DH_North  ...  DH_To     Rock           Mask
0   GEOK4  1.105412e+06  500000.0  ...   10.0  granite  building test
1   GEOK4  1.105412e+06  500000.0  ...   30.0   gneiss  building test
2   GEOK4  1.105412e+06  500000.0  ...   41.0       NA  building test
3   GEOK4  1.105412e+06  500000.0  ...   75.0       NA  building test

build_geosamples(*, return_data=False, **kwd)[source]#

Build manually the geochemistry samples of area.

build_geosamples() collect the geochemistry samples in the survey area with their geographical coordinates locations. The name as well as the sample thickness and the radium of the holes can be from the prompt. The collection of the information will build a geosamples dataset which can be used to Oasis Montaj software modeling. Below is an examples of Outputted. This is some indication of the prompts:

sample ID: Is the name or ID of the samples collected in the area
coordinates (xlon, xlat): is the geographical coordinates where the sampling is performed.
The radius (m): Is the radius of the hole did for collecting the sample.
samples thickness: Ask the thickness of the samples in the whole. Note that when many thickness are supplied, it means the same sample is collected at different depth. There are two kind of data to supply:
- t-value: Compose only with the layer thickness values. For instance t= "10 20 7 58" indicates four samples with thicknesses equals to 10, 20, 7 and 58 ( meters) respectively.
- tb-range: compose only with thickness range at each depth. For instance t= "0-10 10-30 40-47 101-159". Note the character used to separate thickness range is '-'. Here, the top(roof) and bottom(wall) of the sample are 0 (top) and 10 (bottom), 10 and 30, 40 and 47 , and 101 and 159 for the same sample.
- Note that any mixed types is not acceptable and willraises error. To verify whether the expected samples values is acceptable or not, use the following watex.utils.geotools.get_thick_from_range() or watex.utils.geotools.get_thick_from_values() functions.
sample name: Is the name of samples collected refereing to the different depth. In principle, the number of samples thickness must equals to the number of samples. If not the case, NA should be used to indicate the missing samples in the geosamples dataset.
mask/comments: Is any comments aboud the sample

Parameters: return_data (bool, default=False,) – Return the samples dataset rather than object (False) after prompted the appropriate argumments. Note that even True, the geosample data set can be retrieved via the attribute sample_.
Returns: self, geosample dataset – Return object when return_data=False and DataFrame otherwise.
Return type: DSDrill or pd.DataFrame.

Examples

>>> dr = DSDrill ().build_geosamples (return_samples =True )
Enter the sample ID:sx02
Enter SX02 coordinates (xlat, ylon):12 15
Enter SX02 radius in meters [Optional]:2.5
Enter the sample thickness of SX02 in meters:15 15 48 23
Enter the sample names of SX02:pup sup op
Enter valuable comments about SX02 [Optional]:t-value
Tap "exit|0" to terminate or "Enter" to continue:
Enter the sample ID:sx05
Enter SX05 coordinates (xlat, ylon):15 56
Enter SX05 radius in meters [Optional]:2.3
Enter the sample thickness of SX05 in meters:12-17 26-36 40-57
Enter the sample names of SX05:benz op
Enter valuable comments about SX05 [Optional]:t-range1
Tap "exit|0" to terminate or "Enter" to continue:
Enter the sample ID:sx07
Enter SX07 coordinates (xlat, ylon):10 15
Enter SX07 radius in meters [Optional]:1.25
Enter the sample thickness of SX07 in meters:56-76
Enter the sample names of SX07:gru
Enter valuable comments about SX07 [Optional]:t-range2
Tap "exit|0" to terminate or "Enter" to continue:0
>>> dr
Out[8]:
  DH_Hole       DH_East       DH_North  DH_RH  DH_From  DH_To Sample      Mask
0    SX02  1.326554e+06  500000.000000   2.50      0.0   15.0    pup   t-value
1    SX02  1.326554e+06  500000.000000   2.50     15.0   30.0    sup   t-value
2    SX02  1.326554e+06  500000.000000   2.50     30.0   78.0     op   t-value
3    SX02  1.326554e+06  500000.000000   2.50     78.0  101.0     NA   t-value
4    SX05  1.658569e+06  392487.772324   2.30     12.0   17.0   benz  t-range1
5    SX05  1.658569e+06  392487.772324   2.30     26.0   36.0     op  t-range1
6    SX05  1.658569e+06  392487.772324   2.30     40.0   57.0     NA  t-range1
7    SX07  1.105412e+06  500000.000000   1.25     56.0   76.0    gru  t-range2

code = ('DH_Hole', 'DH_East', 'DH_North', 'Mask', 'DH_RH', 'DH_From', 'DH_To', 'Rock', 'DH_Azimuth', 'DH_Top', 'DH_Bottom', 'DH_PlanDepth', 'DH_Decr', 'Sample', 'DH_Dip', 'Elevation', 'DH_RL')#

fit(data=None, **fit_params)[source]#

Fit drill data to build

Parameters

data (pd.DataFrame or Path-like object.) – Data containing the drilling informations.
fit_params (dict,) – Keyword arguments passed to watex.utils.to_numeric_dtypes() for data management.

Returns

self – Instanced object for chaining method.

Return type

Instanced object

Examples

>>> from watex.geology.drilling import Drill
>>> csv_data ='data/drill/nbleDH.csv'
>>> xlsx_data= 'data/drill/nbleDH.xlsx'
>>> dr0 = Drill().fit(csv_data)
>>> dr0.data_.head(2)
  DH_Hole__ID_      DH_East     DH_North  ... DH_Top    DH_Bottom DH_PlanDepth
0          S01  477205.6935  2830978.218  ...      0       968.83          NaN
1          S02  477261.7258  2830944.879  ...      0  974.8945704          NaN
>>> dr1 = Drill().fit(xlsx_data)
>>> dr1.data_.head(2)
    DH_Hole (ID)      DH_East  ...  sample03     sample04
  0          S01  477205.6935  ...       pup  Boudin Axis
  1          S02  477261.7258  ...       pup          pzs

fit_structures(kind, keep_acronyms=Ellipsis, fill_value=None, inplace=Ellipsis)[source]#

Set the geology or geochemistry samples to fit the AGSO database structures.

Parameters

kind (str, { "geology", "samples"}) – Kind of structure to be fitted.
keep_acronym (bool, default=False,) – Use the acronym of the structural and geological database info to replace the full geological/structural name.
fill_value (str, optional) – If None, the undetermined structured are not replaced. They are kept in the data. However, if the fill_value is provided, the missing structure from data is replaced by the fill_value.
inplace (bool, default=False) – If True, modifies the geology or samples dataset inplace and return None

Returns

data – Geology or Geochemistry fitted data. Data are modified in place if True and return None.

Return type

pd.DataFrame

Examples

>>> from watex.geology import DSDrill
>>> dr = DSDrill()
>>> dr.build_drillholes (kind='geology', return_data =True )
Enter the well/hole ID:GEO02
Enter GEO02 coordinates (x/lon, y/lat):12 26
Enter GEO02 radius in meters [Optional]:3.6
Enter the GEO02 depth in meters: 26
Enter each stratum thickness of GEO02 [top-->bottom] in meters:7
Enter the layer/rock names of GEO02 [top-->bottom]:limestone
Enter valuable comments about GEO02 [Optional]:test
Tap "exit|0" to terminate or "Enter" to continue:
Enter the well/hole ID:GEO03
Enter GEO03 coordinates (x/lon, y/lat):12 15
Enter GEO03 radius in meters [Optional]:3.10
Enter the GEO03 depth in meters: 36
Enter each stratum thickness of GEO03 [top-->bottom] in meters:12 10
Enter the layer/rock names of GEO03 [top-->bottom]:sand tuff
Enter valuable comments about GEO03 [Optional]:test2
Tap "exit|0" to terminate or "Enter" to continue:0
Out[1]:
  DH_Hole       DH_East       DH_North  DH_RH  DH_From  DH_To       Rock   Mask
0   GEO02  2.879133e+06  199681.925199    3.6      0.0    7.0  limestone  test1
1   GEO02  2.879133e+06  199681.925199    3.6      7.0   26.0         NA  test1
2   GEO03  1.660514e+06  177349.038212    3.1      0.0   12.0       sand  test2
3   GEO03  1.660514e+06  177349.038212    3.1     12.0   22.0       tuff  test2
4   GEO03  1.660514e+06  177349.038212    3.1     22.0   36.0         NA  test2
>>> dr.fit_structures('geology')
Out[2]:
  DH_Hole       DH_East       DH_North  ...  DH_To                      Rock   Mask
0   GEO02  2.879133e+06  199681.925199  ...    7.0                 limestone  test1
1   GEO02  2.879133e+06  199681.925199  ...   26.0  carbonate iron formation  test1
2   GEO03  1.660514e+06  177349.038212  ...   12.0                 sandstone  test2
3   GEO03  1.660514e+06  177349.038212  ...   22.0                      tuff  test2
4   GEO03  1.660514e+06  177349.038212  ...   36.0  carbonate iron formation  test2

get_collar(data=None, reset_collar=False, **kws)[source]#

Get or set the collar data.

Parameters

data (str, pd.Dataframe) – Path-like object of dataframe containing the collar data
reset_collar (bool, defult=False,) – If collar is provided, resetting the collar data will replace the previous collar data in the original data.
kws (dict,) – Keyword arguments passed to watex.utils.coreutils._is_readable()

Returns

self – Object instanced for method chaining

Return type

Instanced object

Examples

>>> from watex.geology.drilling import DSDrill
>>> xlsx_data= 'data/drill/nbleDH.xlsx'
>>> dr = DSDrill().fit(xlsx_data)
>>> dr2 = dr.get_collar (dr.collar_, reset_collar= True )
>>> dr2.collar_
  DH_Hole (ID)      DH_East     DH_North  ...  DH_PlanDepth  DH_Decr  Mask
0          S01  477205.6935  2830978.218  ...           NaN      NaN    NaN
1          S02  477261.7258  2830944.879  ...           NaN      NaN    NaN

>>> dr.holeid # id hole is autodetected if not given
'DH_Hole (ID)'
>>> # retreive the holeID S01
>>> dr.collar.S01
{'DH_Hole (ID)': 'S01',
 'DH_East': 477205.6935,
 'DH_North': 2830978.218,
 'DH_Dip': -90.0,
 'Elevation ': 0.0,
 'DH_Azimuth': 0.0,
 'DH_Top': 0.0,
 'DH_Bottom': 968.83,
 'DH_PlanDepth': nan,
 'DH_Decr': nan,
 'Mask ': nan}

get_geology(data=None, reset_geology=False, **kws)[source]#

Get the geological informations that composed each drilling.

Parameters

data (str, dataframe) – Path like object composed of layer thickness and geology
reset_geology (bool, default=False) – If True it assumes that the data
kws (dict,) – Keyword arguments passed to watex.utils.coreutils._is_readable()

Returns

self – Object instanced for method chaining

Return type

Instanced object

Examples

>>> from watex.geology.drilling import DSDrill
>>> xlsx_data= 'data/drill/nbleDH.xlsx'
>>> dr = DSDrill().fit(xlsx_data)
>>> dr.get_geology (dr.geology_, reset_geology=True ).geology_
  DH_Hole     Thick01  ...                    Rock03  Rock04
0     S01    0.200000  ...  carbonate iron formation    ROCK
1     S02  174.429396  ...                       GRT    ROCK
>>> dr.holeid # id hole is autodetected if not given
Out[62]: 'DH_Hole'
>>> # retreive the hole ID of S01  drilling.
>>> dr.geology.S01
{'DH_Hole': 'S01',
 'Thick01': 0.2,
 'Thick02': 98.62776918,
 'Thick03': 204.7500461,
 'Thick04': 420.0266651,
 'Rock01': 'clast supported breccia',
 'Rock02': 'sulphide-rich material',
 'Rock03': 'carbonate iron formation',
 'Rock04': 'ROCK'}

get_geosamples(data=None, reset_samples=False, **kws)[source]#

Get or set the geochemistry samples data.

Parameters

data (str, pd.Dataframe) – Path-like object of dataframe containing the geochemistry sample data
reset_geosamples (bool, default=False,) – If geochemistry samples is provided, resetting the samples data will replace the previous samples data in the original data.
kws (dict,) – Keyword arguments passed to watex.utils.coreutils._is_readable()

Returns

self – Object instanced for method chaining

Return type

Instanced object

Examples

>>> from watex.geology.drilling import DSDrill
>>> xlsx_data= 'data/drill/nbleDH.xlsx'
>>> dr = DSDrill().fit(xlsx_data)
>>> dr.get_geosamples (dr.samples_, reset_samples= True ).samples_
  DH_Hole  Thick01     Thick02  ...             sample02  sample03     sample04
0     S01     10.0   98.627769  ...                  prt       pup  Boudin Axis
1     S02     17.4  313.904388  ...  Banding/gneissosity       pup          pzs
>>> dr.holeid # id hole is autodetected if not given
'DH_Hole'
>>> # retreive the holeID geosamples S02
>>> dr.samples.S02
{'DH_Hole': 'S02',
 'Thick01': 17.4,
 'Thick02': 313.9043882,
 'Thick03': 400.12,
 'Thick04': 515.3,
 'sample01': 'pup',
 'sample02': 'Banding/gneissosity',
 'sample03': 'pup',
 'sample04': 'pzs'}

get_properties(kind)[source]#

Get a specific drillhole properties.

Parameters: kind (str, {"collar", "geology", "samples"}) – Kind of drillhole properties to fetch.
Returns: properties – Tuple of properties
Return type: Tuple

Examples

>>> from watex.geology import DSDrill
>>> DSDrill ().get_properties (kind='geology')
('DH_Hole', 'DH_East', 'DH_North', 'DH_RH', 'DH_From', 'DH_To', 'Rock', 'Mask')

property inspect#: Inspect object whether is fitted or not

out(kind, fname=None, format='.xlsx', savepath=None, **outkws)[source]#

Export the drillhole.

Parameters

kind (str, {"geology", "collar", "samples", "*", "data"}) –

Kind of data to export. If "*", the geology, collar and
samples are exported in single excel sheets or csv formats if format is set to .xlsx or .csv respectively.

fname: str,
Full path to filename. If fname is None, the filename used the kind name.
format (str, default=".xlsx") – Extension to export the file. Note that if the filename fname includes the file extension, it should be used.
savepath (str, optional) – Path to locate the files.
Outkws (dict,) – Keywords arguments passed to other pandas exportable readable formats.

Examples

>>> from watex.geology import DSDrill
>>> from watex.datasets import load_nlogs
>>> ndata = load_nlogs(samples =7 , as_frame =True)
>>> dr =DSDrill(projection='utm').fit(ndata)
>>> dr.out( kind="data")
>>> dr.out(fname = 'test_data.csv', kind ="data")

set_drillholes(kind, properties=None, return_data=False)[source]#

Transform the data and fit to the corresponding drillholes.

kind is used to specify the type of drillhole to build. The DH_ used to prefix the drillhole properties can be omitted when specifying the properties.

Parameters

kind (str, {"collar", "geology", "samples"}) – Kind of drillhole to build.
properties (dict,) – A mapper that uses to replace the column names from data to the values of the drillholes. If properties is not specified drillhole data returns NaN columns.
return_data (bool, default=False) – Out the drillhole data. Otherwise returns the drillhole object DSDrill.

Returns

self, data – DSDrill Object instanced or drillholes data set rebuild. Unmatch properties names should be replaced by NaN

Return type

Object instanced and pd.DataFrame

Examples

>>> import watex as wx
>>> from watex.geology import DSDrill
>>> ndata = wx.fetch_data ('nlogs', samples =12, as_frame = True )
>>> dr = DSDrill ().fit(ndata)
>>> dr.data_.head(2)
Out[26]:
  hole_id  uniform_number  ... filter_pipe_diameter water_inflow_in_m3_d
0   B0092    1.133960e+16  ...                0.120               15.249
1   B0093    1.133110e+16  ...                0.125              114.474
[2 rows x 25 columns]
>>> # try list data column names and find the suitable columns that
>>> # could fit the drillholes properies.
>>> dr.data_.columns
Out[27]:
Index(['hole_id', 'uniform_number', 'original_number', 'lon', 'lat',
       'longitude', 'latitude', 'east', 'north', 'easting', 'northing',
       'coordinate_system', 'elevation', 'final_hole_depth',
       'quaternary_thickness', 'aquifer_thickness', 'top_section_depth',
       'bottom_section_depth', 'groundwater_type', 'static_water_level',
       'drawdown', 'water_inflow', 'unit_water_inflow', 'filter_pipe_diameter',
       'water_inflow_in_m3_d'],
      dtype='object')
>>> To get properties, one needs to call get properties to have an idea
>>> # before setting the columns to fit the properties as
>>> DSDrill ().get_properties (kind='collar')
Out[29]:
('DH_Hole',
 'DH_East',
 'DH_North',
 'DH_RH',
 'DH_Top',
 'DH_Bottom',
 'DH_Dip',
 'Elevation',
 'DH_Azimuth',
 'DH_PlanDepth',
 'DH_Decr',
 'Mask')
>>> # Then we can match each data columns to the properties as:
>>> properties = {"hole_id": "DH_Hole", "easting": 'DH_East',
                  "northing": 'DH_North', "top_section_depth": "DH_Top",
                  "bottom_section_depth": "DH_Bottom",
                  "final_hole_depth": 'DH_PlanDepth'}
>>> dr.set_drillholes (kind='collar', properties = properties)
>>> dr.collar_
Out[30]:
   DH_Hole      DH_East     DH_North  ... DH_PlanDepth  DH_Decr  Mask
0    B0092  2509081.067  19774192.36  ...       200.14      NaN   NaN
1    B0093  2576045.247  19757910.23  ...        50.00      NaN   NaN
2    B0094  2579349.264  19763695.25  ...        47.00      NaN   NaN
3    B0095  2568832.229  19760491.25  ...        59.40      NaN   NaN
4    B0096  2566131.227  19765367.27  ...        42.00      NaN   NaN
5    B0097  2568517.240  19770396.28  ...        50.70      NaN   NaN
6    B0098  2583506.276  19763770.24  ...        50.00      NaN   NaN
7    B0099  2576326.263  19770189.27  ...        50.00      NaN   NaN
8    B0101  2567480.246  19777199.30  ...        60.00      NaN   NaN
9    B0102  2583420.292  19775988.28  ...        50.00      NaN   NaN
10   B0103  2577207.276  19778177.29  ...        60.10      NaN   NaN
11   B0106  2519089.079  19758966.30  ...        48.10      NaN   NaN
[12 rows x 12 columns]

class watex.geology.GeoStrataModel(area=None, beta=5, n_epochs=100, ptol=0.1, eta=0.0001, kind='linear', degree=1, z0=0.0, max_depth=700.0, step=50.0, doi='1km', tolog10=False, verbose=False, **kwargs)[source]#

Bases: GeoBase

Create a stratigraphic model from 2D inversion models blocks.

The Inversion model block is two dimensional array of shape (n_vertical_nodes, n_horizontal_nodes ). Can use external packages to

build blocks and provide the 2Dblock into crm parameter.

The challenge of this class is firstly to delineate with much accuracy the existing layer boundary (top and bottom) and secondly,to predict the stratigraphy log before the drilling operations at each station. Moreover, it’s a better way to select the right drilling locationand also to estimate the thickness of existing layer such as water table layer as well as to figure out the water reservoir rock in the case of groundwater exploration [1].

Note that if the model blocks is build from external softwares. User can provided model usefull details into the keyword arguments of the fit methods. For instance the model_station_locations, model_depth, model_x_nodes etc. See more details in fit method docstring.

Parameters

area (str, optional) – The name of the area where the survey is done.
beta (int, default=5) – Value to divide into the CRM blocks to improve the computation times.
n_epochs (int, default=100) – Number of iterations for new resistivity model construction (NM).
ptol (float, default=.1) – the error value to tolerate during NM construction between the tres values given and the calculated resistivity in crm. Higher is the error, less is the accuracy.
eta (float, default=1e4) – It is the learning rate for gradient descent computing to reach its convergence. If kind is set to polynomial the default value should be set`1e-8`.
kind (str , default='linear') – Kind of model function to compute the best fit model to replace the value in crm . Can be ‘linear’ or ‘polynomial’. if polynomial is set, specify the degree.
degree (int, default=1) – Polynomial function degree to implement gradient descent algorithm. If kind is set to Polynomial the default degree is 3.
z0 (float, default=0.) – The elevation at the first stations. Note here, we consider that no topography is included and the default is the level of the sea. If the model_depth`if provided in the `fit_params, no need to specify.
max_depth (float, default=700) – The maximum depth for building the block. by default, the unit is in meters. If model_depth is given, no need to provide.
step (float, default=50) – The step between stations. Here the unit is in meters. If the model_station_locations if given through the fit_params, no need to specified.
doi (default='1km') – the depth of investigation of the skin-depth. By default without any unit suffix, it should be in meters.
tolog10 (bool, default=False) – Convert the true values of layer resistivities to log10.
verbose (bool, default=False) – Output messages and warn users.

nm_#

The New resistivity model (NM) matrix with the same dimension with crm model blocks.

Type: Ndarray of ( n_depth , n_stations )

nmSites_#

The recomputed station locations of the new resistivity model (NM)

Type: ArrayLike

crmSites_#

The recomputed stations locations of the model-calculated resistivity (CRM)

Type: ArrayLike,

Examples

>>> import numpy as np
>>> from watex.geology.stratigraphic import GeoStrataModel
>>>
>>> # (1):  Using the CRM without any inversion specified files.
>>>
>>> # test while files
>>> np.random.seed (42)
>>> # generate a model calculated resistivity, layers and true
>>> # resistivities values
>>> crm = np.abs( np.random.randn (215 , 70 ) *1000 )
>>> tres = np.linspace (crm.min() +1  , crm.max() +1 , 12 ) #
>>> layers = ['granites', 'gneiss', 'sedim.']
>>> gs= GeoStrataModel( to_log10 =True )
>>> gs.fit(crm, tres = tres, layers =layers).buildNM(display_infos =True )
>>> print( gs.nm_.shape)
build-NM: 18B [00:01, 12.60B/s]
----------------------------------------------------------------------
                      layers [auto=automatic](13)
----------------------------------------------------------------------
   1. hard rock (auto)                2. clay (auto)
   3. conglomerate (auto)             4. sedimentary rock (auto)
   5. gravel (auto)                   6. igneous rock (auto)
   7. fresh water (auto)              8.Sedim.
   9.Gneiss                          10. *struture not found (auto)
  11. saprolite (auto)               12. duricrust (auto)
  13.Granites
----------------------------------------------------------------------
(215, 70)
>>> gs.strataModel () # plot strata model, by default kind ='NM'
>>> gs.plotStrata ('s7')  # plot strata log at station S7
Out[7]: watex.geology.stratigraphic.PseudoStratigraphic
>>>
>>> # (2): Works with occam2d inversion files if 'pycsamt' or 'mtpy'
>>> # is installed. It will call the module Geodrill from pycsamt to
>>> make occam2d 2D resistivity block for our demo.
>>> # It presumes pycsamt is installed.
>>>
>>> from pycsamt.geodrill.geocore import Geodrill
>>> path=r'data/inversfiles/inver_res/K4' # path to inversion files
>>> inversion_files = {'model_fn':'Occam2DModel',
...                   'mesh_fn': 'Occam2DMesh',
...                    "iter_fn":'ITER27.iter',
...                   'data_fn':'OccamDataFile.dat'
...                    }
>>> tres =[10, 66, 70, 180, 1000, 2000, 3000, 7000, 15000 ]
>>> layers =['river water', 'fracture zone', 'granite']
>>> inversion_files = {key:os.path.join(path, vv) for key,
                vv in inversion_files.items()}
>>> gdrill= Geodrill (**inversion_files,
                     input_resistivities=input_resistivity_values
                     )
>>> # we can collect the 'model_res' and occam2d inversion usefull
>>> # 'attributes' from  `gdrill object` and passed to the
>>> # 'GeoStrataModel' then fit_params keyword arguments method as
>>> geosObj = GeoStrataModel(ptol =0.1).fit(
                     crm = gdrill.model_res ,
                     tres=gdrill.input_resistivities,
                     layers=gdrill.input_layer_names,
                     model_x_nodes=gdrill.model_x_nodes,
                     model_stations= gdrill.station_names,
                     model_depth= gdrill.geo_depth,
                     model_station_locations= gdrill.station_locations,
                     data_fn = gdrill.data_fn ,
                     mesh_fn=gdrill.mesh_fn,
                     iter_fn= gdrill.iter_fn
                     model_fn= gdrill.model_fn)
>>> geosObj.buildNM ()
>>> zmodel = geosObj._zmodel
>>> geosobj.nm_ # New constructed resistivity 2D model block

Notes

Modules work properly with occam2d inversion files if ‘pycsamt’ or ‘mtpy’ is installed and inherits the GeoBase class which works with geological structures and properties. Furhermore, Occam2d inversion files are also acceptables for building model blocks. However the MODEM resistivity files development is still ongoing.

References

1: Kouadio, L. K., Liu, R., Malory, A. O., Liu, W., Liu, C., A novel approach for water reservoir mapping using controlled source audio - frequency magnetotelluric in Xingning area , Hunan Province, China. Geophys. Prospect., https://doi.org/10.1111/1365-2478.1338

buildNM(return_NM=Ellipsis, display_infos=Ellipsis)[source]#: Build New discrete resistivity from the model-calculated resistivity CRM Trigger the NM build and return the NM building option

fit(crm, tres=None, layers=None, **fit_params)[source]#

Check, populate attributes and rebuild the model-calculated resistivity (CRM).

Parameters

crm (ndarray of shape(n_vertical_nodes, n_horizontal_nodes ),) – Array-like of inversion two dimensional model blocks. Note that the n_vertical_nodes is the node from the surface to the depth while n_horizontal_nodes must include the station location (sites/stations)
tres (List, Arraylike of float,) – Layer true values of resistivity collected in the survey area. refer to [1] for more details. Resistivity is preferable to be distinct.
layers (list or ArrayLike of str) – The name of layers collected in the survey area. Their corresponding resistivity values are the argument of tres. Mostly, it refers to the geological informations of collected in the area.
fit_params (dict,) –
If a keyword argument refering to inversion model details, it should be prefixed by the keyword model_ such as the the following attributes:
- model_depth: Arraylike shape (n_depth, ) of the model. It is the depth the surface to the bottom of each layer that composed the pseudo-boreholes. It refer to the n_vertical nodes.
- model_resistivities: ArrayLike of shape ( y_nodes , x_nodes ). It is array of model block composed of resistivity values of vertical nodes and horizontal nodes. It is the model-calculated resistivity. No need if the value is passed to crm parameter.
- model_x_nodes: ArrayLike of shape (x_nodes, ) is the horizontal nodes of the model block.
- model_station_locations: Arraylike of offset of valid stations locations. It might truly refers to the number of investigated stations.
- model_stations: List or Arrylike of the stations names of the investigated area. It might be consistent with the model_station_locations.
- model_rms: Root-Mean-Squared values of the models after inversion. By default , the target is set to 1.0.
- model_roughness: Roughness of the models. This is an optional parameters and using when OCCAM2D software is used to invert the data.
Model files can also be includes. In that case, the attributes must suffixes with _fn. Some useful model files can be model, mesh data and iter. For instance to set the data file to a keyword arguments it sould be data_fn=xxxx whether the new data attribute should be retrived as data_fn. Note that:
- model_fn is the model files after inversions
- data_fn is the data files before inversions
- iter_fn is the iteration results files if applicable with
  the kind of inversion software used
- mesh_fn is the mesh files construct for forward modeling.

Returns

``self`` – return self for methods chaining.

Return type

watex.geology.stratigraphic.GeoStrataModel.

References

1: Kouadio, L. K., Liu, R., Malory, A. O., Liu, W., Liu, C., A novel approach for water reservoir mapping using controlled source audio - frequency magnetotelluric in Xingning area , Hunan Province, China. Geophys. Prospect., https://doi.org/10.1111/1365-2478.1338

classmethod geoArgumentsParser(config_file=None)[source]#

Read and parse the GeoStrataModel arguments files from the config [JSON|YAML] file. :param config_file: configuration file. Can be [JSON|YAML]

Example

>>> GeoStrataModel.geoArgumentsParser(
    'data/saveJSON/cj.data.json')
>>> GeoStrataModel.geoArgumentsParser(
    'data/saveYAML/cy.data.yml')

property inspect#: Inspect object whether is fitted or not

static plotStrata(station, zoom=None, annotate_kws=None, **kws)[source]#

Build the Stratalog. :param station: station to visualize the plot. :param zoom: float represented as visualization ratio

ex: 0.25 –> 25% view from top =0.to 0.25* investigation depth or a list composed of list [top, bottom].

Example

>>> input_resistivity_values =[10, 66,  700, 1000, 1500,  2000,
                        3000, 7000, 15000 ]
>>> input_layer_names =['river water', 'fracture zone', 'granite']
# Run it to create your model block alfter that you can only use
#  `plotStrata` only
# >>> obj= quick_read_geomodel(lns = input_layer_names,
#                             tres = input_resistivity_values)
>>> plotStrata(station ='S00')

set_inversion_model_attr(**model_params)[source]#

Set inversion model parameters as attributes. Note all related to the raw inversion model strats with attribte model_xxx ` while all related to files must must suffixed with `_fn. For instances the folling data such [‘model’, ‘iter’, ‘data’ , ‘mesh’] can be added as keywords arguments where _fn is suffixed to each names.

Parameters

model_parameters (dict) –

Keyword arguments from inversion model parameters. The useful attributes passed to accurathe model creation are:

model_depth: Arraylike shape (n_depth, ) of the model, mostly refer to the vertical nodes.
model_resistivities: ArrayLike of shape ( y_nodes , x_nodes ). It is array of model block composed of resistivity values of vertical nodels and horizontal nodes. It is the model-calculated resistivity. It is usefull to pass the same argument as crm parameters.
model_x_nodes: ArrayLike of shape (x_nodes, ) is the horizontal nodes of the model block.
model_station_locations: Arraylike of offset of valid stations locations. It might truly refers to the number of investigated stations.
model_stations: List or Arraylike of the stations names of the investigated area. It might be consistent with the model_station_locations.
model_rms: Root-Mean-Squared values of the models after inversion. By default , the target is set to 1.0.
model_roughness: Roughness of the models. This is an optional parameters and using when OCCAM2D software is used to invert the data.

Model files can also be includes. In that case, the attributes must suffixes with _fn. Some useful model files can be model, mesh data and iter. For instance to set the data file to a keyword arguments it sould be data_fn=xxxx whether the new data attribute should be retrived as data_fn. Note that:

model_fn is the model files after inversions
data_fn is the data files before inversions
iter_fn is the iteration results files if applicable with the kind of inversion software used
mesh_fn is the mesh files construct for forward modeling.

strataModel(kind='nm', **kwargs)[source]#

Visualize the strataModel after nm creating using decorator from :class:’~.geoplot2d’.

Parameters

kind – can be : - nm mean new model plots after inputs the tres - crm means calculated resistivity from occam model blocks default is nm.
plot_misft – Set to True if you want to visualise the error between the nm and crm.
scale – Can be m or km for plot scale
in_percent` – Set to True to see your plot map scaled in %.

Example

>>> from watex.geology.stratigraphic import GeostrataModel
>>> geosObj = GeostrataModel().fit(**inversion_files,
                      input_resistivities=input_resistivity_values,
                      layers=input_layer_names)
>>> geosObj.strataModel(kind='nm', misfit_G =False)

property subblocks#: Model subblocks divised by beta

property tres#: Input true resistivity

class watex.geology.Geology(geofn=None, **kwargs)[source]#

Bases: object

Geology class deals with all concerns the structures during investigation sites

class watex.geology.Structural(configfile=None, **kwds)[source]#

Bases: GeoBase

Geology strutural conventions class.

Note that the given structural objects are quite less than the litterature More structural object can be added as the structures is known. All geological structural informations are geostructral object.

Holds the following informations:

More attributes can be added by inputing a key word dictionary

Example

>>> from watex.geology import Structural
>>> s=Structural().fit()
>>> s.boudin_axis.code_
... 'lsb'
>>> s.boudin_axis.name_
... 'Boudin Axis'
>>> s.boudin_axis.color_
... 'R128GB'

fit(configfile=None, **kwd)[source]#: Configure the structural data and set each object as attributes

class watex.geology.Structures(configfile=None, **kwds)[source]#

Bases: GeoBase

This class is an auxilliary class to supplement geodatabase , if the GeodataBase doesnt reply to SQL request , then use this class to secah information about structures . If SQL is done as well , program won’t call this class as rescure . Containers of more than 150 geological strutures.

Attributes	Type	Explanation
names	array_like	names of all geological strutures
codes	array_like	names of all geological codes
**code	str	code of specific geological structure
**label	str	label of specific structure
**name	str	label of specific structure
**pattern	str	pattern of specific structure
**pat_size	str	pattern size of specific structure
**pat_density	str	pattern density l of specific structure
**pat_thickness	str	pttern thickess of specific structure
**color	str	color of specific structure

Note

To get the attribute value, merely replace the param “**” by the name of struture following by dot “.”. See examples:

Examples

To get the names of different strutures, write the script below:

>>> from watex.geology.geology import Structures
>>> geo_structure = Structures().fit()
>>> geo_structure.names_ # get the list of all geological strutures

To extract color and to get the code of structure like tonalite:

>>> from watex.geology.geology import Structures
>>> sobj = Structures().fit()
>>> sobj.tonalite.pat_thickness_
... 0.  # -> not implemented
>>> sobj.tonalite.code_
>>> ...'TNL'
>>> sobj.tonalite.color_
... ''RB128'

codef = ['code', 'label', '__description', 'pattern', 'pat_size', 'pat_density', 'pat_thickness', 'color']#

property coerce#: Force configuration if auto getting the property file fails.

fit(**kwd)[source]#

Fit and set the geological strutures as object attributes and kwd arguments refer to the argument below.

Parameters

configfile (str) – is a configure file from ‘AGS0’ data
fillna (float,) – fill NaN values in the AGS0 file. The default values to fill is 0 for False.

Notes

Each geological strutures can be retrieved as an attribute. For instance to get the code, the label and the pattern density of the ‘amphibolite’.

Example

>>> from watex.geology import Structures
>>> sobj = Structures().fit()
>>> sobj.amphibolite.code
... 'AMP'
>>> sobj.amphibolite.label_
... 'AMP'
>>> sobj.amphibolite.pat_density_
... 0. # not set
>>> # To get all the key (attributes of the structures ), uses::
>>> sobj.keys

watex.geology package#

Submodules#