BedAnalyst#

Algorithms for analyzing riverbed clogging through visualization functions, geospatial interpolation, and a novel fuzzy degree of clogging

The BedAnalyst (flusstools.bedanalyst) modules provide Python3 functions for substrate sample analysis and a fuzzy logic assessment of so-called riverbed clogging.

Usage#

Import#

Import bedanalyst from flusstools:

from flusstools import bedanalyst as bea

Example (code block)#

from flusstools import bedanalyst as bea
clogging_pars = bea.fuzzy_analyze("/sample-data/sample.csv")

Example (showcase)#

A showcase is provided in the flusstools example degree of clogging.

Code structure#

The following diagram highlights function locations in Python scripts and how those are linked to each other.

structure

The modules cd_profiles, nABP_degree_clogging, and interp_z2shp are independent from the degree_clogging module.

Script and function docs#

Package Head: bedanalyst#

This module contains all the necessary mathematical definitions of the membership functions, which may be altered by the user, if necessary.

The first input is the dictionary containing two points for the fuzzy and defuzzification functions. Two points define a function and the have the following format:

(parameter_values, corresponding_membership_values)

For example, for the parameter fine sediment share, the point with the lowest value in the y-axis is written as follows:

(fs_c_llow, fs_mu_c_llow)

where fs stands for fine sediment share, c indicates the membership function associated to clogging, mu indicates the membership value, and llow indicates the relative position of the point in the curve.

The second input is the local address of the csv file containing the parameters of the samples.

The third input is composed by two booleans that indicates the algorithm to print the fuzzy functions and the aggregation functions inside the folder output.

Another algorithm degree_clogging#

This module calls the necessary functions to perform the computation of degree of clogging.

flusstools.bedanalyst.degree_clogging.degree_clogging(df_samples, output_csv_path, plot=[False, False])[source]#
Function for computing degree of clogging using the input riverbed parameter along the riverbed depth:

  • Fine Sediment Saare/Fraction (fsf/fss): [%]

  • Hydraulic Conductivity (kf): [m/s]

  • Porosity (n): [-]

  • Interstitial Dissolved Oxygen Content (IDOC): [mg/L]

  • Bridging criterion according to Huston & Fox (2015; referred as ‘ratio’ here): [-]

Parameters

  • df_samples (pandas.DataFrame) – df containing the columns ‘id’ (sample id), ‘fss’, ‘kf’, ‘n’, ‘idoc’ and ‘ratio’

  • output_csv_path (str) – path to output csv containing the results of the fuzzy inference and final computed degree of clogging

  • plot (list) – List of two boolean objects indicating if the plots for the aggregation function and the fuzzy

  • required (membership functions of the above mentione dparameters is required. Should be True if) –

  • respectively. –

Returns

None

Another algorithm interp_z2shp#

flusstools.bedanalyst.interp_z2shp.interp_z2shp(df, lonlat, crs, sample_column, interp_at_z_stamps, new_attr_names, meas_at_cols, path_shp)[source]#

Interpolates vertical riverbed measurements (e.g., kf, IDOS) to desired z (vertical) stamps, enters them as attributes for creating a point shapefile

Parameters

  • df (pandas.DataFrame) – df with rows indicating samples and columns indicating parameters

  • lonlat (tuple of str) – name of the columns containing longitude and latitude, respectively (x, y)

  • crs (str) – of type ‘epsg:xxxx or xxxxx’, coordinate system of the input longitude and latitude values

  • sample_column (str) – name of the column in the df which contains the sample names

  • interp_at_z_stamps (numpy.array of floats) – contains the z (vertical) stamps where the measurement should be interpolated

  • new_attr_names (list of str) – names of the attributes referring to the selected new z stamps.

  • meas_at_cols (tuple of str) – contains the column names as a tuple (z_stamp, measurement) of the df that have the vertical spatial stamp of the measurement and the value measured at the corresponding z stamp.

  • path_shp (str) – path to save the shapefile

Returns

geopandas.GeoDataFrame

Another algorithm utils#

This module contains the functions called by main.

flusstools.bedanalyst.utils.activate_fuzzy_funs(probe, dc_param_range, dc_fuzzy_funs)[source]#

Function to compute the membership values of the fuzzy functions for the parameters of a real sample. :param probe: float values of the parameters of a sample in the following order (F.S, kf, n, IDOC, ratio) :type probe: tuple :param dc_param_range: arrays of float values of the six parameters defined into utils.generate_ranges() :type dc_param_range: dict :param dc_fuzzy_funs: arrays with the membership values of the fuzzy functions :type dc_fuzzy_funs: dict

Returns

fuzzy membership float values corresponding to the parameter values of the real sample

Return type

dc_fuzzy_activated (dict)

flusstools.bedanalyst.utils.add_columns(df_samples)[source]#

Function to add columns of csv output

Parameters

df_samples (Dataframe) – dataframe with the parameters of the samples

Returns

same input Dataframe but with new columns

Return type

df_samples (Dataframe)

flusstools.bedanalyst.utils.add_results(df, step, degree_of_clogging_corrected, degree_of_clogging, dc_mu_desfuzzy_values, dc_af)[source]#

Function to add computed result to output-Dataframe

Parameters

  • df (Dataframe) – input Dataframe

  • step (int) – nth sample

  • degree_of_clogging_corrected (float) – dregree of clogging corrected to interval [0, 1]

  • degree_of_clogging (float) – degree of clogging in the

  • [centroid_of_no_clogging (interval) –

  • centroid_of_strong_clogging] –

  • dc_mu_desfuzzy_values (dict) – three float values of the sample-activated defuzzification functions

  • dc_af (dict) – membership float values of the activated fuzzy functions

  • step – nth sample

Returns

output Dataframe

Return type

df (Dataframe)

flusstools.bedanalyst.utils.apply_fuzzy_rules(dc_af=None, dc_desfuzzy_funs=None, centroid=False, mu_list=None)[source]#

Function to choose membership value of defuzzification functions based on the fuzzy rules.

Parameters

  • dc_af (dict) – membership values of fuzzy functions of a sample

  • dc_desfuzzy_funs (dict) – arrays with the membership values of the defuzzification functions

  • centroid (boolean) – True to correct the limits of degree of clogging to [0,1]

  • mu_list (list) – corrected membership function values of the activated defuzzification functions

Returns

array of membership values that define area under the curve of the defuzzification functions dc_mu_defuzzy_values (dict): three float values of the sample-activated defuzzification functions

Return type

dc_mu_defuzzy (dict)

flusstools.bedanalyst.utils.compute_bcs(dc_limits)[source]#

Function to compute bs and cs constants that define the sigmoid fuzzy membership functions (y = 1 / (1. + exp[- c * (x - b)]))

Parameters

dc_limits (dict) – thresholds of the membership functions defined in config.py

Returns

b values of the membership functions dc_c (dict): c values of the membership functions

Return type

dc_b (dict)

flusstools.bedanalyst.utils.compute_desfuzzy_funs(dc_param_range, dc_b, dc_c)[source]#

Function to compute defuzzification membership functions. The functions for high and low degree of clogging are Sigmoids and for medium degree of clogging is Gaussian. :param dc_param_range: arrays of float values of the six parameters defined into utils.generate_ranges()

Returns

arrays with the membership values of the defuzzification functions

Return type

(dict)

flusstools.bedanalyst.utils.compute_fuzzy_functions(dc, dc_b, dc_c)[source]#

Function to compute bs and cs constants that define the sigmoid fuzzy membership functions (y = 1 / (1. + exp[- c * (x - b)]))

Parameters

  • dc_limits (dict) – thresholds of the membership functions defined in config.py

  • dc_b (dict) – b values of the membership functions

  • dc_c (dict) – c values of the membership functions

Returns

arrays with the membership values of the fuzzy functions

Return type

(dict)

flusstools.bedanalyst.utils.correct_degree_of_clogging(dc_defuzzy_centroids, degree_of_clogging)[source]#

Function to correct degree of clogging from the interval [centroid_of_no_clogging, centroid_of_strong_clogging] to [0, 1]

Parameters

  • degree_of_clogging (float) – original degree of clogging

  • dc_defuzzy_centroids (dict) – two float values that represent the centroids of sc and nc defuzzi-functions

Returns

degree of clogging in the interval [0, 1]

Return type

degree_of_clogging_corrected (float)

flusstools.bedanalyst.utils.find_centroids(dc_desfuzzy_funs, dc_param_range)[source]#

Function to find centroids of the non clogging and strong clogging defuzzification functions

Parameters

  • dc_param_range (dict) – arrays of float values of the six parameters defined into utils.generate_ranges()

  • dc_desfuzzy_funs (dict) – arrays with the membership values of the defuzzification functions

Returns

two float values that represent the centroids of sc and nc defuzzi-functions

Return type

dc_defuzzy_centroids (dict)

flusstools.bedanalyst.utils.generate_ranges()[source]#

Function to define de ranges of the parameters

Parameters

None –

Returns

array with the ranges of the parameters

Return type

(dict)

flusstools.bedanalyst.utils.plot_aggregation(dc_param_range, dc_mu_desfuzzy, dc_desfuzzy_funs, activation, degree_of_clogging, aggregated, step)[source]#

Function to compute the membership values of the fuzzy functions for the parameters of a real sample. :param dc_param_range: arrays of float values of the six parameters defined into utils.generate_ranges() :type dc_param_range: dict :param dc_mu_desfuzzy: defuzzified membership float values corresponding to the parameter values

of the real sample

Parameters

  • dc_desfuzzy_funs (dict) – arrays with the membership values of the defuzzification functions

  • activation (float) – degree of clogging that equals to the center of mass of tha sum of the areas under

  • functions (the activated defuzzification) –

  • degree_of_clogging (float) – degree of clogging correct between 0 and 1 in utils.correct_degree_of_clogging()

  • aggregated (array) – membership float values that define the summed area below the

  • functions. (activated defuzzification) –

  • step (int) – integer that represents the nth sample

Returns

None

flusstools.bedanalyst.utils.plot_funs(dc_param_range, dc_fuzzy_funs, dc_disfuzzy_funs)[source]#

Function to plot the membership functions of the parameters and defuzzyfication membership functions into one plot.

Parameters

  • dc_param_range (dict) – arrays of float values of the six parameters defined into utils.generate_ranges()

  • dc_fuzzy_funs (dict) – arrays of membership fuzzy functions values of the given ranges of the six parameters

  • dc_disfuzzy_funs (dict) – arrays of membership defuzzy functions values of the given ranges of the six parameters

Returns

None