ex-fuzzy 1.0.0__tar.gz

ex_fuzzy-1.0.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.1
+Name: ex_fuzzy
+Version: 1.0.0
+Summary: Library to perform explainable AI using fuzzy logic.
+Home-page: 
+Download-URL: 
+Maintainer: Javier Fumanal Idocin
+Maintainer-email: javierfumanalidocin@gmail.com
+License: GPL-3.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Description-Content-Type: text/markdown
+
+# Ex-Fuzzy
+ex-Fuzzy is a fuzzy toolbox library for Python with special focus in its accesibility to use and visualization of results. In this way, we focus on the ex(-Fuzzy)plainable capacities of approximate reasoning.
+
+Some of the tools available in this library include:
+
+- Support for approximate reasoning using fuzzy association rules, for both classification and regression problems. This includes rule base optimization using genetic algorithms and rule visualization.
+- Precomputed and optimized fuzzy variables and their correspondent linguistic variables (i.e low, medium, high).
+- Support for various kinds of fuzzy sets, including classic fuzzy sets, IV-fuzzy sets and General Type 2 fuzzy sets.
+
+## Main Characteristics
+
+### Easy to use
+
+ex-Fuzzy is designed to be easy to use. Linguistic variables can be precomputed and optimized without any understading of its implementation. Choosing one kind of fuzzy set only requires to set one flag. 
+
+### Reusable code
+
+Code is designed so that some parts can be easily extendable, so that some use cases, like research, can be also supported. The rule base optimization is done using a Genetic Algorithm, but almost any other pymoo search algorithm will do. Fuzzy sets can be extended with ease, just as the kind of partitions, membership functions, etc.
+
+### Sci-py like interface
+
+ex-Fuzzy is built taking into account the actual machine-learing frameworks used in Python. Training amd sing a rule base classifier works exactly as sci-kit learn classifier. Parameters such as the number of rules or antecedents are also built 
+
+### Visualization
+
+Use plots to visualize any kind of fuzzy sets, and use graphs to visualize rules or print them on screen.
+
+
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/12574757/210235257-17b22ede-762b-406c-880a-497e06964f17.png" width="350" title="Fuzzy graph">
+  <img src="https://user-images.githubusercontent.com/12574757/210235264-be98fff9-d1b6-4f3b-8b93-b11e0466a48c.png" width="350" title="Type 1 example">
+  <img src="https://github.com/Fuminides/exFuzzy/assets/12574757/b37e2f4e-0e19-4d4b-a504-b121e41c9399" width="350" title="Type 2 example">
+  <img src="https://github.com/Fuminides/exFuzzy/assets/12574757/8e3c036f-2ab7-4281-8ef8-b8891fbf354a" width="350" title="General Type 2 example">
+  
+</p>
+
+## Dependencies
+
+- Numpy
+- Pandas
+- Matplotlib
+- Networkx
+- Pymoo
+
+## Installation
+
+You can install ex-Fuzzy using pip, from the PyPi repository, with the following command:
+
+`pip install ex-fuzzy`
+
+
+## Contributors
+Javier Fumanal Idocin, Javier Andreu-Perez
+
+All rights reserved, 2021-2024
+
+

ex_fuzzy-1.0.0/README.md

@@ -0,0 +1,57 @@
+# Ex-Fuzzy
+ex-Fuzzy is a fuzzy toolbox library for Python with special focus in its accesibility to use and visualization of results. In this way, we focus on the ex(-Fuzzy)plainable capacities of approximate reasoning.
+
+Some of the tools available in this library include:
+
+- Support for approximate reasoning using fuzzy association rules, for both classification and regression problems. This includes rule base optimization using genetic algorithms and rule visualization.
+- Precomputed and optimized fuzzy variables and their correspondent linguistic variables (i.e low, medium, high).
+- Support for various kinds of fuzzy sets, including classic fuzzy sets, IV-fuzzy sets and General Type 2 fuzzy sets.
+
+## Main Characteristics
+
+### Easy to use
+
+ex-Fuzzy is designed to be easy to use. Linguistic variables can be precomputed and optimized without any understading of its implementation. Choosing one kind of fuzzy set only requires to set one flag. 
+
+### Reusable code
+
+Code is designed so that some parts can be easily extendable, so that some use cases, like research, can be also supported. The rule base optimization is done using a Genetic Algorithm, but almost any other pymoo search algorithm will do. Fuzzy sets can be extended with ease, just as the kind of partitions, membership functions, etc.
+
+### Sci-py like interface
+
+ex-Fuzzy is built taking into account the actual machine-learing frameworks used in Python. Training amd sing a rule base classifier works exactly as sci-kit learn classifier. Parameters such as the number of rules or antecedents are also built 
+
+### Visualization
+
+Use plots to visualize any kind of fuzzy sets, and use graphs to visualize rules or print them on screen.
+
+
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/12574757/210235257-17b22ede-762b-406c-880a-497e06964f17.png" width="350" title="Fuzzy graph">
+  <img src="https://user-images.githubusercontent.com/12574757/210235264-be98fff9-d1b6-4f3b-8b93-b11e0466a48c.png" width="350" title="Type 1 example">
+  <img src="https://github.com/Fuminides/exFuzzy/assets/12574757/b37e2f4e-0e19-4d4b-a504-b121e41c9399" width="350" title="Type 2 example">
+  <img src="https://github.com/Fuminides/exFuzzy/assets/12574757/8e3c036f-2ab7-4281-8ef8-b8891fbf354a" width="350" title="General Type 2 example">
+  
+</p>
+
+## Dependencies
+
+- Numpy
+- Pandas
+- Matplotlib
+- Networkx
+- Pymoo
+
+## Installation
+
+You can install ex-Fuzzy using pip, from the PyPi repository, with the following command:
+
+`pip install ex-fuzzy`
+
+
+## Contributors
+Javier Fumanal Idocin, Javier Andreu-Perez
+
+All rights reserved, 2021-2024
+
+

ex_fuzzy-1.0.0/ex_fuzzy/ex_fuzzy/__init__.py

@@ -0,0 +1,10 @@
+from . import centroid
+from . import eval_rules
+from . import eval_tools
+from . import evolutionary_fit
+from . import fuzzy_sets
+from . import rules
+from . import vis_rules
+from . import utils
+from . import persistence
+from . import maintenance

ex_fuzzy-1.0.0/ex_fuzzy/ex_fuzzy/centroid.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+"""
+This is the source file that contains functions to compute centroids for the case of IV fuzzy sets,
+which are commonly used when using the IV-T2 fuzzy sets.
+"""
+import numpy as np
+
+
+def center_of_masses(z: np.array, w: np.array) -> np.array:
+    '''
+    Computes the ponderated centroid with normalized weighting.
+
+    :param z: Vector of the referencial values.
+    :param w: Vector of the fuzzy memberships.
+    :return: The ponderated sum.
+    '''
+    return z @ w / np.sum(w)
+
+
+def compute_centroid_t2_l(z: np.array, memberships: np.array) -> float:
+    '''
+    Computes the Karnik and Mendel algorithm to find the centroid of an IV fuzzy set.
+
+    :param z: Vector of the referencial values.
+    :param memberships: vector of the fuzzy memberships.
+    :return: The centroid.
+    '''
+    centros = np.mean(memberships, axis=1)
+    w = centros
+
+    yhat = center_of_masses(z, w)
+
+    yhat_2 = None
+
+    while(yhat != yhat_2):
+        try:
+            k = np.argwhere((z - yhat) >= 0)[-1][0]
+            k = min(len(centros)-1, k)
+        except IndexError:
+            k = 0
+
+        # k_vector = np.argwhere((z - yhat) > 0)
+        # k = k_vector[0][0] + 1
+        w[0:k] = memberships[:, 1][:k]
+        w[k:] = memberships[:, 0][k:]
+
+        yhat_2 = yhat
+        yhat = center_of_masses(z, w)
+
+    return yhat
+
+
+def compute_centroid_t2_r(z: np.array, memberships: np.array) -> float:
+    '''
+    Computes the Karnik and Mendel algorithm to find the right component of a centroid of an IV fuzzy set.
+
+    :param z: Vector of the referencial values.
+    :param memberships: vector of the fuzzy memberships.
+    :return: The lowest membership of the centroid.
+    '''
+    centros = np.mean(memberships, axis=1)
+    w = centros
+
+    yhat = center_of_masses(z, w)
+
+    yhat_2 = None
+
+    while(yhat != yhat_2):
+        try:
+            k = np.argwhere((z - yhat) >= 0)[-1][0]
+            k = min(len(centros)-1, k)
+        except IndexError:
+            k = 0
+
+        w[0:k+1] = memberships[:, 0][:k+1]
+        w[k+1:] = memberships[:, 1][k+1:]
+
+        yhat_2 = yhat
+        yhat = center_of_masses(z, w)
+
+    return yhat
+
+
+def consequent_centroid_r(antecedent_memberships: np.array, centroids_r: np.array) -> float:
+    '''
+    Computes the Karnik and Mendel algorithm to find the right component of a centroid of an IV fuzzy set
+    using the centroids of the consequents and the antecedents memeberships.
+
+    :param antecedent_memberships: M x 2 matrix. M rules and iv dimension (2). Vector of memberships.
+    :param centroids_r: M sized vector. Contains the referencial values.
+    :return: the IV centroid.
+    '''
+
+    memberships_left = antecedent_memberships[:, 0]
+    memberships_right = antecedent_memberships[:, 1]
+    initial_f = (memberships_left + memberships_right) / 2
+
+    yhat = center_of_masses(centroids_r, initial_f)
+    yhat2 = None
+
+    while(yhat != yhat2):
+        try:
+            r_R = np.argwhere((yhat - centroids_r) >= 0)[-1][0]
+            r_R = min(len(centroids_r)-1, r_R)
+        except IndexError:
+            r_R = 0
+
+        new_memberships = initial_f
+        new_memberships[0:r_R+1] = memberships_left[0:r_R+1]
+        new_memberships[r_R+1:] = memberships_right[r_R+1:]
+
+        yhat2 = yhat
+        if np.sum(new_memberships) == 0:
+            yhat = 0
+        else:
+            yhat = center_of_masses(centroids_r, new_memberships)
+
+    return yhat2
+
+
+def consequent_centroid_l(antecedent_memberships: np.array, centroids_l: np.array) -> float:
+    '''
+    Computes the Karnik and Mendel algorithm to find the left component of a centroid of an IV fuzzy set
+    using the centroids of the consequents and the antecedents memeberships.
+
+    :param antecedent_memberships: M x 2 matrix. M rules and iv dimension (2). Vector of memberships.
+    :param centroids_r: M sized vector. Contains the referencial values.
+    :return: the IV centroid.
+    '''
+
+    memberships_left = antecedent_memberships[:, 0]
+    memberships_right = antecedent_memberships[:, 1]
+    initial_f = (memberships_left + memberships_right) / 2
+
+    # (memberships_right * centroids_r) / np.sum(memberships_right)
+    yhat = center_of_masses(centroids_l, initial_f)
+    yhat2 = -100
+
+    #R = np.where(yhat - centroids_r)[0]
+    while(yhat != yhat2):
+        try:
+            r_R = np.argwhere((yhat - centroids_l) >= 0)[-1][0]
+            r_R = min(len(centroids_l)-1, r_R)
+        except IndexError:
+            r_R = 0
+
+        new_memberships = initial_f
+        new_memberships[0:r_R+1] = memberships_right[0:r_R+1]
+        new_memberships[r_R+1:] = memberships_left[r_R+1:]
+        yhat2 = yhat
+        if np.sum(new_memberships) == 0:
+            yhat = 0
+        else:
+            yhat = center_of_masses(centroids_l, new_memberships)
+
+    return yhat2
+
+
+def compute_centroid_iv(z: np.array, memberships: np.array) -> np.array:
+    '''
+    Computes Karnik and Mendel algorithm to find the centroid of a iv fuzzy set. 
+
+    :param z: Vector of the referencial values.
+    :param memberships: vector of the fuzzy memberships.
+    :return: The centroid.
+    '''
+    res = np.zeros((2,))
+    res[0] = compute_centroid_t2_l(z, memberships)
+    res[1] = compute_centroid_t2_r(z, memberships)
+    return res
+
+
+def consequent_centroid(antecedent_memberships: np.array, centroids: np.array) -> np.array:
+    '''
+    Computes Karnik and Mendel algorithm to find the centroid of a consequent iv fuzzy set given the centroids of the consequents
+    and the antecedents memberships. 
+
+    :param antecedent_memberships: M x 2 matrix. M rules and iv dimension (2). Vector of memberships.
+    :param centroids: M x 2 matrix. M rules and iv dimension (2). Vector of centroids.
+    :return: The centroid.
+    '''
+    centroids_l = centroids[:, 0]
+    centroids_r = centroids[:, 1]
+    res = np.zeros((2,))
+
+    res[0] = consequent_centroid_l(antecedent_memberships, centroids_l)
+    res[1] = consequent_centroid_r(antecedent_memberships, centroids_r)
+
+    return res
+
+
+

ex_fuzzy-1.0.0/ex_fuzzy/ex_fuzzy/classifiers.py

@@ -0,0 +1,209 @@
+'''
+Module that contains classifiers that uses two step genetic optimization and rule mining based on the support of the candidate rules. 
+
+'''
+
+import numpy as np
+from sklearn.base import ClassifierMixin
+
+try:
+    from . import fuzzy_sets as fs
+    from . import evolutionary_fit as evf
+    from . import rule_mining as rm
+    from . import utils
+    from . import maintenance as mnt
+except:
+    import fuzzy_sets as fs
+    import evolutionary_fit as evf
+    import rule_mining as rm
+    import utils
+    import maintenance as mnt
+
+
+class RuleMineClassifier(ClassifierMixin):
+    """A classifier that works by mining a set of candidate rules with a minimum support, confidence and lift, and then using a genetic algorithm that chooses
+    the optimal combination of those rules."""
+
+    def __init__(self, nRules: int = 30, nAnts: int = 4, fuzzy_type: fs.FUZZY_SETS = None, tolerance: float = 0.0,
+                verbose=False, n_class: int=None, runner: int=1, linguistic_variables: list[fs.fuzzyVariable]=None) -> None:
+        '''
+        Inits the optimizer with the corresponding parameters.
+
+        :param nRules: number of rules to optimize.
+        :param nAnts: max number of antecedents to use.
+        :param fuzzy type: FUZZY_SET enum type in fuzzy_sets module. The kind of fuzzy set used.
+        :param tolerance: tolerance for the support/dominance score of the rules.
+        :param verbose: if True, prints the progress of the optimization.
+        :param n_class: number of classes in the problem. If None (default) the classifier will compute it empirically.
+        :param runner: number of threads to use.
+        :param linguistic_variables: linguistic variables per antecedent.
+        '''
+        if mnt.save_usage_flag:
+            mnt.usage_data[mnt.usage_categories.Classification]['data_mining'] += 1
+        
+        self.nAnts = nAnts
+        self.fl_classifier = evf.BaseFuzzyRulesClassifier(nRules=nRules, linguistic_variables=linguistic_variables, 
+                                            fuzzy_type=fuzzy_type, verbose=verbose, tolerance=tolerance, runner=runner, n_class=n_class)
+        self.fuzzy_type = fuzzy_type
+        self.tolerance = tolerance
+
+
+    def fit(self, X: np.array, y: np.array, n_gen:int=30, pop_size:int=50):
+        '''
+        Trains the model with the given data.
+
+        :param X: samples to train.
+        :param y: labels for each sample.
+        '''
+        fuzzy_vars = utils.construct_partitions(X, self.fuzzy_type)
+        candidate_rules = rm.multiclass_mine_rulebase(X, y, fuzzy_vars, self.tolerance, max_depth=self.nAnts)
+        self.fl_classifier.fit(X, y, checkpoints=0, candidate_rules=candidate_rules, n_gen=n_gen, pop_size=pop_size)
+
+
+    def predict(self, X: np.array) -> np.array:
+        '''
+        Predict for each sample the corresponding class.
+
+        :param X: samples to predict.
+        :return: a class for each sample.
+        '''
+        # Make predictions using the fitted model
+        y_pred = self.fl_classifier.predict(X)
+
+        return y_pred
+    
+
+    def internal_classifier(self) -> evf.BaseFuzzyRulesClassifier:
+        # Returns the classifier that performs the final predictions
+        return self.fl_classifier
+    
+
+
+class FuzzyRulesClassifier(ClassifierMixin):
+    """A classifier that works by performing a double optimization process. First, it creates a candidate rule base using genetic optimization
+    and then uses it as a basis to obtain a better one that satisfies the constrain of antecedents and number of rules."""
+
+    def __init__(self, nRules: int = 30, nAnts: int = 4, fuzzy_type: fs.FUZZY_SETS = None, tolerance: float = 0.0, 
+                 verbose=False, n_class: int=None, runner: int=1, expansion_factor:int=1, linguistic_variables: list[fs.fuzzyVariable]=None) -> None:
+        '''
+        Inits the optimizer with the corresponding parameters.
+
+        :param nRules: number of rules to optimize.
+        :param nAnts: max number of antecedents to use.
+        :param fuzzy type: FUZZY_SET enum type in fuzzy_sets module. The kind of fuzzy set used.
+        :param tolerance: tolerance for the dominance score of the rules.
+        :param verbose: if True, prints the progress of the optimization.
+        :param n_class: number of classes in the problem. If None (default) the classifier will compute it empirically.
+        :param runner: number of threads to use.
+        :param expansion_factor: if > 1, it will compute inthe first optimization process n times the nRules parameters. (So that the search space for the second step is bigger)
+        :param linguistic_variables: linguistic variables per antecedent.
+        '''
+        if mnt.save_usage_flag:
+            mnt.usage_data[mnt.usage_categories.Classification]['double_go'] += 1
+
+
+        self.fl_classifier1 = evf.BaseFuzzyRulesClassifier(nRules=nRules* 1, linguistic_variables=linguistic_variables, nAnts=nAnts, # We give this one more number rules so that then the second optimization has a bigger search space
+                                            fuzzy_type=fuzzy_type, verbose=verbose, tolerance=tolerance, runner=runner, n_class=n_class) 
+        self.fl_classifier2 = evf.BaseFuzzyRulesClassifier(nRules=nRules, linguistic_variables=linguistic_variables, nAnts=nAnts, 
+                                            fuzzy_type=fuzzy_type, verbose=verbose, tolerance=tolerance, runner=runner, n_class=n_class)
+        self.fuzzy_type = fuzzy_type
+        self.tolerance = tolerance
+
+
+    def fit(self, X: np.array, y: np.array, n_gen:int=30, pop_size:int=50, checkpoints:int=0, n_runner:int=1):
+        '''
+        Trains the model with the given data.
+
+        :param X: samples to train.
+        :param y: labels for each sample.
+        :param n_gen: number of generations to compute in the genetic optimization.
+        :param pop_size: number of subjects per generation.
+        :param checkpoints: if bigger than 0, will save the best subject per x generations in a text file.
+        :param n_runner: number of threds to use.
+        '''
+        self.fl_classifier1.fit(X, y, n_gen, pop_size, checkpoints)
+        self.phase1_rules = self.fl_classifier1.rule_base
+        self.fl_classifier2.fit(X, y, n_gen, pop_size, checkpoints, initial_rules=self.phase1_rules, n_runner=n_runner)
+        
+
+    def predict(self, X: np.array) -> np.array:
+        '''
+        Predcit for each sample the correspondent class.
+
+        :param X: samples to predict.
+        :return: a class for each sample.
+        '''
+        # Make predictions using the fitted model
+        y_pred = self.fl_classifier2.predict(X)
+
+        return y_pred
+    
+
+    def internal_classifier(self) -> evf.BaseFuzzyRulesClassifier:
+        # Returns the classifier that performs the final predictions
+        return self.fl_classifier2
+    
+
+class RuleFineTuneClassifier(ClassifierMixin):
+    """A classifier that works by mining a set of candidate rules with a minimum support and then uses a two step genetic optimization that chooses
+    the optimal combination of those rules and fine tunes them."""
+
+    def __init__(self, nRules: int = 30, nAnts: int = 4, fuzzy_type: fs.FUZZY_SETS = None, tolerance: float = 0.0, 
+                 verbose=False, n_class: int=None, runner: int=1, expansion_factor:int=1, linguistic_variables: list[fs.fuzzyVariable]=None) -> None:
+        '''
+        Inits the optimizer with the corresponding parameters.
+
+        :param nRules: number of rules to optimize.
+        :param nAnts: max number of antecedents to use.
+        :param fuzzy type: FUZZY_SET enum type in fuzzy_sets module. The kind of fuzzy set used.
+        :param tolerance: tolerance for the dominance score of the rules.
+        :param verbose: if True, prints the progress of the optimization.
+        :param n_class: number of classes in the problem. If None (default) the classifier will compute it empirically.
+        :param linguistic_variables: linguistic variables per antecedent.
+        '''
+        if mnt.save_usage_flag:
+            mnt.usage_data[mnt.usage_categories.Classification]['double_go'] += 1
+            mnt.usage_data[mnt.usage_categories.Classification]['data_mining'] += 1
+
+        self.fl_classifier1 = evf.BaseFuzzyRulesClassifier(nRules=nRules* expansion_factor, linguistic_variables=linguistic_variables, nAnts=nAnts, # We give this one more number rules so that then the second optimization has a bigger search space
+                                            fuzzy_type=fuzzy_type, verbose=verbose, tolerance=tolerance, runner=runner, n_class=n_class) 
+        self.fl_classifier2 = evf.BaseFuzzyRulesClassifier(nRules=nRules, linguistic_variables=linguistic_variables, nAnts=nAnts, 
+                                            fuzzy_type=fuzzy_type, verbose=verbose, tolerance=tolerance, runner=runner, n_class=n_class)
+        self.fuzzy_type = fuzzy_type
+        self.tolerance = tolerance
+
+
+    def fit(self, X: np.array, y: np.array, n_gen:int=30, pop_size:int=50, checkpoints:int=0, n_runner:int=1):
+        '''
+        Trains the model with the given data.
+
+        :param X: samples to train.
+        :param y: labels for each sample.
+        :param n_gen: number of generations to compute in the genetic optimization.
+        :param pop_size: number of subjects per generation.
+        :param checkpoints: if bigger than 0, will save the best subject per x generations in a text file.
+        :param n_runner: number of threds to use.
+        '''
+        candidate_rules = rm.multiclass_mine_rulebase(X, y, self.fl_classifier1.lvs, self.tolerance)
+
+        self.fl_classifier1.fit(X, y, n_gen, pop_size, checkpoints, candidate_rules=candidate_rules)
+        self.phase1_rules = self.fl_classifier1.rule_base
+        self.fl_classifier2.fit(X, y, n_gen, pop_size, checkpoints, initial_rules=self.phase1_rules, n_runner=n_runner)
+
+
+    def predict(self, X: np.array) -> np.array:
+        '''
+        Predcit for each sample the correspondent class.
+
+        :param X: samples to predict.
+        :return: a class for each sample.
+        '''
+        # Make predictions using the fitted model
+        y_pred = self.fl_classifier.predict(X)
+
+        return y_pred
+    
+
+    def internal_classifier(self) -> evf.BaseFuzzyRulesClassifier:
+        # Returns the classifier that performs the final predictions
+        return self.fl_classifier2