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, id=None, qmax=None, **kwds)

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)

Fit Borehole data and populate the corrsponding attributes

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

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:

• name (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 ‘_’.

fit(data, **fit_params)

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 xlon and y values as series. Then if xlon and y are given as string argument, their names must be included in the data columns. Otherwise an error will raise.

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)

Set the a random depth if depth is not given.

To fetch the depth, use attribute depth_. Note that if the depth exist, calling set_depth will arase 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.

Returns:

self – Instanced object for chaining method.

Return type:

Instanced object

set_thickness(h0=1, **kws)

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

To fetch the thickness, use attribute layer_thickness_.

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.

• 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

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_ellipsoide=23, verbose=False)

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 replaced 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 should exist in the borehole datasets.

• 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.

fit(data, **fit_params)

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)

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

class watex.geology.GeoStrataModel(beta=5, ptol=0.1, n_epochs=100, tres=None, eta=0.0001, kind='linear', degree=1, build=False, **kwargs)

Bases: GeoBase

Create a stratigraphic model from 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 location and 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.

Note that if the model blocks is build from externam softwares. You may as in the keywordsr argumments of GeoStrataModel the following attributes:

• model_res2D resitivity model of (n_vertical_nodes, n_horizontal_nodes)

  If crm is given , no need to provided it.

• geo_depth: Is the depth the surface to the bottom of each layer that

  composed the pseudo-boreholes. Note the N-vertical nodes values

• input_resistivities: list of input resistivities. If the tres is passed

  not need to given.

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)

• beta (int,) – Value to divide into the CRM blocks to improve the computation times. default is`5`

• n_epochs (int,) – Number of iterations. default is 100

• tres (array_like,) – Truth values of resistivities. Refer to Geodrill for more details

• ptols (float,) – Existing tolerance error between the tres values given and the calculated resistivity in crm

• input_layers (list or array_like) – True input_layers names : geological informations of collected in the area.

• kind (str) – 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. Default is ‘linear’.

• alpha (float ,) – Learning rate for gradient descent computing. Default is 1e+4 for linear. If kind is set to polynomial the default value should be 1e-8.

• degree (int,) – Polynomial function degree to implement gradient descent algorithm. If kind is set to Polynomial the default degree is 3. and details sequences

• **nm** (ndarray) – The NM matrix with the same dimension with crm model blocks.

Examples

>>> from watex.geology.stratigraphic import GeoStrataModel
>>> # Works with occam2d inversion files if 'pycsamt' or 'mtpy' is installed
>>> # 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'
...                    }
>>> input_resistivity_values =[10, 66, 70, 180, 1000, 2000,
...                           3000, 50, 7]
>>> input_resistivity_values =[10, 66, 70, 180, 1000, 2000,
...                               3000, 7000, 15000 ]
>>> input_layer_names =['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 'geo_depth_attributes' from
>>> # `gdrill object` and passed to 'GeoStrataModel' fit method as
>>> geosObj = GeoStrataModel(ptol =0.1).fit(crm = model_res ,
                     input_resistivities=gdrill.input_resistivity_values
                     geo_depth= gdrill.geo_depth )
>>> zmodel = geosObj._zmodel
>>> geosObj.nm # resistivity 2D model block is constructed

Notes

Modules work properly with occam2d inversion files if ‘pycsamt’ or ‘mtpy’ is installed and inherits the Base package which works with occam2d model. Occam2d inversion files are also acceptables for building model blocks. However the MODEM resistivity files development is still ongoing

property beta

Block constructor param

property build

Trigger the NM build and return the NM building option

fit(crm=None, beta=5, ptol=0.1, **kws)

Fit, populate attributes and construct the new stratigraphic model (NM)

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)

• beta (int,) – Value to divide into the CRM blocks to improve the computation times. default is`5`

• n_epochs (int,) – Number of iterations. default is 100

• ptols (float,) – Existing tolerance error between the tres values given and the calculated resistivity in crm

Returns:

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

Return type:

watex.geology.stratigraphic.GeoStrataModel.

classmethod geoArgumentsParser(config_file=None)

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')

static gradient_descent(z, s, alpha, n_epochs, **kws)

Gradient descent algorithm to fit the best model parameter.

Parameters:

• z – vertical nodes containing the values of depth V

• s – vertical vector containin the resistivity values

• alpha – step descent parameter or learning rate. Default is ``0.01`

• n_epochs – number of iterations. Default is 100 Can be changed to other values

Returns:

• F: New model values with the best W parameters found.

• W: vector containing the parameters fits

• cost_history: Containing the error at each Itiretaions.

Example:

>>> z= np.array([0, 6, 13, 20, 29 ,39, 49, 59, 69, 89, 109, 129,
                 149, 179])
>>> res= np.array( [1.59268,1.59268,2.64917,3.30592,3.76168,
                    4.09031,4.33606, 4.53951,4.71819,4.90838,
      5.01096,5.0536,5.0655,5.06767])
>>> fz, weights, cost_history = gradient_descent(z=z, s=res,
                                     n_epochs=10,
                                     alpha=1e-8,
                                     degree=2)
>>> import matplotlib.pyplot as plt
>>> plt.scatter (z, res)
>>> plt.plot(z, fz)

property inspect

Inspect object whether is fitted or not

property n_epochs

Iteration numbers

static plotPseudostratigraphic(station, zoom=None, annotate_kws=None, **kws)

Build the pseudostratigraphic log. :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
#  `plotPseudostratigraphic` only
# >>> obj= quick_read_geomodel(lns = input_layer_names,
#                             tres = input_resistivity_values)
>>> plotPseudostratigraphic(station ='S00')

property ptol

Tolerance parameter

strataModel(kind='nm', **kwargs)

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,
                      input_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)

Bases: object

Geology class deals with all concerns the structures during investigation sites

class watex.geology.Structural(configfile=None, **kwds)

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)

Configure the structural data and set each object as attributes

class watex.geology.Structures(configfile=None, **kwds)

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)

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

Submodules

• Core geology
• GeoBase
• fetching_data_from_repo()
• get_agso_properties()
• mapping_stratum()
• set_agso_properties()
• GeoDataBase
• DBSetting
  • DBSetting.closeDB()
  • DBSetting.commit()
  • DBSetting.connect_DB()
  • DBSetting.dicT_sqlDB()
  • DBSetting.drop_TableDB()
  • DBSetting.executeReq()
  • DBSetting.export_req()
  • DBSetting.print_query()
• GeoDataBase
  • GeoDataBase.codef
  • GeoDataBase.colorMPL
  • GeoDataBase.electrical_props
  • GeoDataBase.geoDataBase
  • GeoDataBase.hatch
  • GeoDataBase.make_pattern_symbol
  • GeoDataBase.pattern
  • GeoDataBase.rgb
• Borehole
  • Borehole.fit()
• DSBorehole
  • DSBorehole.depth_
  • DSBorehole.data_
  • DSBorehole.fit()
  • DSBorehole.inspect
  • DSBorehole.set_depth()
  • DSBorehole.set_thickness()
• DSBoreholes
  • DSBoreholes.fit()
  • DSBoreholes.inspect
  • DSBoreholes.set_coordinates()
• Drill
  • Drill.dhGeology()
  • Drill.dhSample()
  • Drill.dhSurveyElevAz()
  • Drill.writeDHData()
• Geology
• Structural
  • Structural.fit()
• Structures
  • Structures.codef
  • Structures.coerce
  • Structures.fit()
• setstructures()
• Stratigraphic
• GeoStrataModel
  • GeoStrataModel.beta
  • GeoStrataModel.build
  • GeoStrataModel.fit()
  • GeoStrataModel.geoArgumentsParser()
  • GeoStrataModel.gradient_descent()
  • GeoStrataModel.inspect
  • GeoStrataModel.n_epochs
  • GeoStrataModel.plotPseudostratigraphic()
  • GeoStrataModel.ptol
  • GeoStrataModel.strataModel()
  • GeoStrataModel.subblocks
  • GeoStrataModel.tres