Is a set of utilities that deal with geological rocks, strata and stratigraphic details for log construction.

watex.utils.geotools.annotate_log(ax, thick, layers, *, ylims=None, colors=None, set_nul='*unknow', bbox_kws=None, set_nul_bbox_kws=None, **an_kws)

Draw annotate stratigraphic map.

Parameters:

• ax – obj, Matplotlib axis

• thick – list of the thicknesses of the layers

• layers – list of the name of layers

• set_nul – str set the Name of the unknow layers. Default is `*unknow. Can be changed with any other layer name.

:param bbox_kws:dict, Additional keywords arguments of Fancy boxstyle

arguments

Parameters:

set_nul_bbox_kws – dict, customize the boxstyle of the set_nul param. If you want the bbox to be the same like bbox_kws, we need just to write idem or same` or origin.

Returns:

ax: matplotlib axis properties

watex.utils.geotools.assert_len_lns_tres(lns, tres)

Assert the length of LN and Tres

watex.utils.geotools.assert_station(id, nm=None)

Assert station according to the number of stations investigated.

Parameters:

• id – int or str, station number. The station counter start from 01 as litteral count except whn provided value in string format following the letter S. For instance : S00 =1

• nm – matrix of new stratiraphy model built.

Returns:

Index at specific station

Example:

>>> import watex.utils.geotools as GU
>>> import watex.geology.core as GC
>>> obj= GC.quick_read_geomodel()
>>> GU.assert_station(id=47, nm=geoObj.nmSites)
...46

watex.utils.geotools.base_log(ax, thick, layers, *, ylims=None, hatch=None, color=None)

Plot pseudo-stratigraphy basemap and return axis.

Parameters:

• ax – obj, Matplotlib axis

• thick – list of the thicknesses of the layers

• layers – list of the name of layers

• hatch – list of the layer patterns

• color – list of the layer colors

Returns:

ax- matplotlib axis properties

watex.utils.geotools.display_s_infos(s_list, s_range, s_thick, **kws)

Display strata infos at the requested station.

Parameters:

• s_list – the pseudostratigraphic details list

• s_range – the pseudostratigraphic strata range

• s_thick – the pseudostratigraphic thicknesses

:param kws:additional keywords arguments.

watex.utils.geotools.find_distinct_items_and_indexes(items, cumsum=False)

Find distincts times and their indexes.

Parameters:

• items – list of items to get the distincts values

• cumsum – bool, cummulative sum when items is a numerical values

Returns:

• distinct _indexes unique indexes of distinct items

• distinct_items: unik items in the list

• cumsum: cumulative sum of numerical items

Example:

>>> import watex.utils.geotools as GU
>>> test_values = [2,2, 5, 8, 8, 8, 10, 12, 1, 1, 2, 3, 3,4, 4, 6]
>>> ditems, dindexes, cumsum = GU.find_distinct_items_and_indexes(
    test_values, cumsum =True)
>>> cumsum

watex.utils.geotools.fit_rocks(logS_array, lns_, tres_)

Find the pseudo rock name at each station from the pseudovalue intres.

Parameters:

• logS_array – array_like of under the station resistivity value

• lns – array_like of the rocks or the pseudolayers (automatick)

• tres – array_like of the TRES or the pseudo value of the TRES

Returns:

list of the unik corresponding resistivity value at each station and its fitting rock names.

Example:

>>> import watex.utils.geotools as GU
>>> import watex.geology.core as GC
>>> obj= GC.quick_read_geomodel()
>>> pslns , pstres,  ps_lnstres= GU.make_strata(obj)
>>> logS1 =obj.nmSites[0] # station S0
>>> fit_rock(logS1, lns_= pslns, tres_= pstres)

watex.utils.geotools.fit_stratum_property(fittedrocks, z, site_tres)

Separated whole blocks into different stratum and fit their corresponding property like depth and value of resistivities

Parameters:

• fittedrocks – array_like of layers fitted from the TRES

• z – array like of the depth

• site_tres – array like of the station TRES

Returns:

• s_grouped: Each stratum grouped from s_tres

• site_tres_grouped: The site resistivity value site_tres grouped

• z_grouped: The depth grouped (from the top to bottom )

• z_cumsum_grouped: The cumulative sum grouped from the top to bottom

Example:

>>> import watex.geology.core as GC
>>> obj= GC.quick_read_geomodel()
>>> logS1 = obj.nmSites[:, 0]
>>> sg, stg, zg, zcg= fit_stratum_property (
    obj.fitted_rocks, obj.z, obj.logS)

watex.utils.geotools.frame_top_to_bottom(top, bottom, data)

Compute the value range between the top and the bottom.

Find the main range value for plot ranged between the top model and

the bottom.

Parameters:

• top – is the top value where plot might be started

• bottom – is the bottom value where plot must end

• data – is the list of thicknesses of each layers

• cumsum_origin – is the list of cumul sum of the data

Returns:

• the index for other properties mapping. It indicates the

  index of layer for the top and the index of layer for the bottom for visualizing.

• the list of pairs top-bottom , ex: [10, 999.0]

  where tp -> 10 and bottom ->999. m

• the value of thicknesses ranged from the top to the bottom

  For instance: [49.0, 150.0, 590.0, 200.0] where - 49 is the thockness of the first layer - 200 m is the thickness of the

• the coverall allows to track bug issues.The thickness of layer

  for visualizing should be the same that shrank. Otherwise, the mapping was not successfully done. Therefore coverall will be different to 100% and function will return the raw data instead of raising errors.

Example:

>>> import watex.utils.geotools as GU
>>> layer_thicknesses = [ 59.0, 150.0, 590.0, 200.0]
>>> top , bottom = 10, 120 # in meters
>>> GU.frame_top_to_bottom( top = top, bottom =bottom,
                        data = layer_thicknesses)
...(([0, 2], [10, 120], [49.0, 61.0]), 'coverall = 100.0 %')

watex.utils.geotools.get_closest_gap(value, iter_obj, status='isin', condition_status=False, skip_value=0)

Get the value from the minimum gap found between iterable values.

Parameters:

• value – float Value to find its corresponding in the iter_obj

• iter_obj – iterable obj Object to iterate in oder to find the index and the value that match the best value.

:param condition_status:bool

If there is a condition to skip an existing value in the iter_obj, it should be set to True and mention the ship_value.

Parameters:

skip_value – float or obj Value to skip existing in the iter_obj.

:param status:str

If layer is in the databse, then get the electrical property and from that properties find the closest value in TRES If layer not in the database, then loop the database from the TRES and find the auto rock name from resistivity values in the TRES

Returns:

• ix_close_res: close value with its index found in` iter_obj`

:rtype:tuple

watex.utils.geotools.get_index_for_mapping(ix, tp)

get the index and set the stratpoint of the top or the endpoint of bottom from tuple list. The index should be used to map the o ther properties like color or hatches

watex.utils.geotools.get_s_thicknesses(grouped_z, grouped_s, display_s=True, station=None)

Compute the thickness of each stratum from the grouped strata from the top to the bottom.

Parameters:

• grouped_z – depth grouped according its TRES

• grouped_s – strata grouped according to its TRES

• s_display – bool, display infos in stdout

Returns:

• thick : The thickness of each layers

• strata: name of layers

• status: check whether the total thickness is equal to the

  depth of investigation(doi). Iftrue: `coverall= 100% otherwise coverall is less which mean there is a missing layer which was not probably taking account.

Example:

>>> import watex.geology.core as GC
>>> obj= GC.quick_read_geomodel()
>>> sg, _, zg, _= fit_stratum_property (obj.fitted_rocks,
...                                    obj.z, obj.nmSites[:, 0]  )
>>> get_s_thicknesses( zg, sg)
... ([13.0, 16.0, 260.0, 240.0, 470.0],
...     ['*i', 'igneous rocks', 'granite', 'igneous rocks', 'granite'],
...     'coverall =100%')

watex.utils.geotools.grouped_items(items, dindexes, force=True)

Grouped items with the same value from their corresponding indexes.

Parameters:

• items – list of items for grouping.

• dindexes – list of distinct indexes

• force – bool, force the last value to broken into two lists. Forcing value to be broke is usefull when the items are string. Otherwise, force param should be False when dealing numerical values.

Returns:

distinct items grouped

Example:

>>> import watex.utils.geotools as GU
>>> test_values = [2,2, 5, 8, 8, 8, 10, 12, 1, 1, 2, 3, 3,4, 4, 6]
>>> dindexes,* _ = GU.find_distinct_items_and_indexes(
    test_values, cumsum =False)
>>> GU.grouped_items( test_values, dindexes)
...  [[2, 2], [5], [8, 8, 8], [10], [12], [1, 1],
...      [2], [3, 3], [4, 4], [6]]
>>> GU.grouped_items( test_values, dindexes, force =False)
... [[2, 2], [5], [8, 8, 8], [10], [12], [1, 1],
    [2], [3, 3], [4, 4, 6]]

watex.utils.geotools.lns_and_tres_split(ix, lns, tres)

Indeed lns and tres from GeoStratigraphy model are updated.

Then splitting the lns and tres from the topped up values is necessary. Kind to resetting tres and `ln `back to original and return each split of inputting layers and TRES and the automatic rocks topped up during the NM construction.

Parameters:

• ix – int Number of autorocks added

• lns – list List of input layers

• tres – list List of input resistivities values.

watex.utils.geotools.map_bottom(bottom, data, origin=None)

Reduce the plot map from the top assumes to start at 0. to the bottom value.

Parameters:

• bottom – float, is the bottom value from which the plot must be end

• data – the list of layers thicknesses in meters

• origin – The top value for plotting.by the default the origin takes 0. as the starting point

Returns:

the mapping depth from the top to the maximum depth.

• the index indicated the endpoint of number of layer

  for visualizing.

• the list of pairs <top-bottom>, ex: [0, bottom]>

• the value of thicknesses ranged from 0. to the bottom

• the coverall, which is the cumul sum of the value of

  the thicknesses reduced compared to the total depth.

Note that to avoid raising errors, if coverall not equal to 100%, will return safety default values (original values).

Example:

>>> ex= [ 59.0, 150.0, 590.0, 200.0]
>>> map_bottom(60, ex)
... ((2, [0.0, 60], [59.0, 1.0]), 'coverall = 100.0 %')

watex.utils.geotools.map_top(top, data, end=None)

Reduce the plot map from the top value to the bottom assumed to be the maximum of investigation depth.

Parameters:

• top – float, is the top value from which the plot must be starts

• data – the list of layers thicknesses in meters

• end – The maximum depth for plotting. Might be reduced, but the default takes the maximum depth investigation depth

Returns:

the mapping depth from the top to the maximum depth.

• the index indicated the number of layer for visualizing to

  from the top to the max depth.

• the list of pairs <top-bottom>, ex: [top, max depth]>

• the value of thicknesses ranged from 0. to the bottom

• the coverall, which is the cumul sum of the value of

  the thicknesses reduced compared to the total depth. It allows to track a bug issue.

Note that if coverall is different 100%, will return the default values giving values.

Example:

>>> import watex.utils.geotools as GU
>>> ex= [ 59.0, 150.0, 590.0, 200.0] # layers thicknesses
>>> GU.map_top(60, ex)
... ((3, [60, 999.0], [149.0, 590.0, 200.0]), 'coverall = 100.0 %')

watex.utils.geotools.print_running_line_prop(obj, inversion_software='Occam2D')

print the file in stdout which is currently used ” for pseudostratigraphic plot when extracting station for the plot.

watex.utils.geotools.pseudostratigraphic_log(thick, layers, station, *, zoom=None, hatch=None, color=None, **annot_kws)

Make the pseudostratigraphic log with annotate figure.

Parameters:

• thick – list of the thicknesses of the layers

• layers – list of the name of layers

• hatch – list of the layer patterns

• color – list of the layer colors

Parm zoom:

float, list. If float value is given, it considered as a zoom ratio and it should be ranged between 0 and 1. For isntance:

• 0.25 –> 25% plot start from 0. to max depth * 0.25 m.

Otherwise if values given are in the list, they should be composed of two items which are the top and bottom of the plot. For instance:

• [10, 120] –> top =10m and bottom = 120 m.

Note that if the length of zoom list is greater than 2,

the function will return all the plot and no errors should raised.

Example:

>>> from watex.utils.geotools as GU
>>> layers= ['$(i)$', 'granite', '$(i)$', 'granite']
>>> thicknesses= [59.0, 150.0, 590.0, 200.0]
>>> hatch =['//.', '.--', '+++.', 'oo+.']
>>> color =[(0.5019607843137255, 0.0, 1.0), 'b', (0.8, 0.6, 1.), 'lime']
>>> GU.pseudostratigraphic_log (thicknesses, layers, hatch =hatch ,
...                   color =color, station='S00')
>>>  GU.pseudostratigraphic_log ( thicknesses,
                                 layers,
                                 hatch =hatch, zoom =0.25,
                                 color =color, station='S00')

watex.utils.geotools.set_default_hatch_color_values(hatch, color, dhatch='.--', dcolor=(0.5019607843137255, 0.0, 1.0), force=False)

Set the none hatch or color to their default values.

Parameters:

• hatch – str or list of layer patterns

• color – str or list of layers colors

• dhatch – default hatch

• dcolor – default color

• force –

  Return only single tuple values otherwise put the RGB tuple values in the list. For instance:

  -if ``False`` color =[(0.5019607843137255, 0.0, 1.0)]
  - if ``True`` color = (0.5019607843137255, 0.0, 1.0)
  

Example:

>>> from watex.utils.geotools as  GU.
>>> hatch =['//.', 'none', '+++.', None]
>>> color =[(0.5019607843137255, 0.0, 1.0), None, (0.8, 0.6, 1.),'lime']
>>> GU.set_default_hatch_color_values(hatch, color))

watex.utils.geotools.smart_zoom(v)

select the ratio or value for zooming. Don’t raise any error, just return the original size. No shrunk need to be apply when error occurs.

Parameters:

v –

str, float or iterable for zoom - str: 0.25% —> mean 25% view

1/4 —> means 25% view

• iterable: [0, 120]–> the top starts a 0.m and bottom at 120.m

note: terable should contains only the top value and the bottom

value.

Returns:

ratio float value of iteration list value including the the value range (top and the bottom values).

Example:

>>> import watex.utils.geotools as GU
>>> GU.smart_zoom ('1/4')
... 0.25
>>> GU.smart_zoom ([60, 20])
... [20, 60]

watex.utils.geotools.zoom_processing(zoom, data, layers=None, hatches=None, colors=None)

Zoom the necessary part of the plot.

If some optionals data are given such as hatches, colors, layers, they must be the same size like the data.

Parameters:

• zoom –

  float, list. If float value is given, it’s cnsidered as a zoom ratio than it should be ranged between 0 and 1. For isntance:

  • 0.25 –> 25% plot start from 0. to max depth * 0.25 m.

  Otherwise if values given are in the list, they should be composed of two items which are the top and bottom of the plot. For instance:

  • [10, 120] –> top =10m and bottom = 120 m.

  Note that if the length of list is greater than 2, the function will return the entire plot and no errors should be raised.

• data – list of composed data. It should be the thickness from the top to the bottom of the plot.

• layers – optional, list of layers that fits the data

• hatches – optional, list of hatches that correspond to the data

• colors – optional, list of colors that fits the data

Returns:

• top-botom pairs: list composed of top bottom values

• new_thicknesses: new layers thicknesses computed from top to bottom

• other optional arguments shrunk to match the number of layers and

  the name of exact layers at the depth.

Example:

>>> import watex.utils.geotools as GU
>>> layers= ['$(i)$', 'granite', '$(i)$', 'granite']
>>> thicknesses= [59.0, 150.0, 590.0, 200.0]
>>> hatch =['//.', 'none', '+++.', None]
>>> color =[(0.5019607843137255, 0.0, 1.0), None, (0.8, 0.6, 1.),'lime']
>>> GU.zoom_processing(zoom=0.5 , data= thicknesses, layers =layers,
                      hatches =hatch, colors =color)
... ([0.0, 499.5],
...     [59.0, 150.0, 290.5],
...     ['$(i)$', 'granite', '$(i)$'],
...     ['//.', 'none', '+++.'],
...     [(0.5019607843137255, 0.0, 1.0), None, (0.8, 0.6, 1.0)])