antakia 0.2.1__tar.gz

antakia-0.2.1/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 AI-VIDENCE
+
+LICENSE BSD 3_Clause
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

antakia-0.2.1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.1
+Name: antakia
+Version: 0.2.1
+Summary: AI made Xplainable
+Keywords: XAI,explainability,AI,ML,machine learning,artificial intelligence
+Author: Antoine EDY
+Author-email: antoineedy@outlook.fr
+Requires-Python: >=3.11,<3.12
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Dist: antakia-ac
+Requires-Dist: antakia-core
+Requires-Dist: interpret (>=0.4.4)
+Requires-Dist: ipyvuetify (>=1.8.10,<2.0.0)
+Requires-Dist: ipywidgets (>=8.1.1,<9.0.0)
+Requires-Dist: lime (>=0.2.0.1,<0.3.0.0)
+Requires-Dist: numba
+Requires-Dist: opentsne (>=1.0.0,<2.0.0)
+Requires-Dist: pacmap (>=0.7.1,<0.8.0)
+Requires-Dist: pandas (>=1.5.3)
+Requires-Dist: plotly (>=5.18.0,<6.0.0)
+Requires-Dist: pygam (>=0.9.0,<0.10.0)
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Requires-Dist: scikit-learn (>=1.3.2,<2.0.0)
+Requires-Dist: shap (>=0.43.0,<0.44.0)
+Requires-Dist: skope-rules-temp (>=0.1.0,<0.2.0)
+Requires-Dist: tomaster (>=0.0.5,<0.0.6)
+Requires-Dist: umap-learn (>=0.5.4,<0.6.0)
+Requires-Dist: voila (>=0.5.5,<0.6.0)
+Description-Content-Type: text/markdown
+
+# Welcome to AntakIA !
+
+AntakIA is an open-source tool from AI-vidence to explain ML black box models.
+
+Here is a quick tour of AntakIA:
+![AntakIA demo](/docs/img/antakia.gif)
+
+See full video on [Youtube](https://youtu.be/wQFC_20OIOM).
+
+## Install and run from source code
+
+Clone the repo and create a virtual environment
+
+```
+git clone https://github.com/AI-vidence/antakia.git
+cd antakia
+```
+
+Then, with `pip` :
+
+```
+python3.10 -m venv .
+source bin/activate
+pip install -e .
+```
+
+Or,if you prefer `poetry` :
+
+```
+poetry shell
+peotry install
+```
+
+Got to https://doc.antakia.ai to learn how to use AntakIA.
+
+You may also need to install Git LFS to download our CSV files in /data:
+```
+brew install git-lfs # if you're a Mac / brew user
+git lfs install
+cd antakia
+git lfs track "*.csv"
+git add .gitattributes
+git lfs fetch
+git lfs checkout
+```
+
+Reference : [see Git-LFS website](https://git-lfs.com)
+
+> [!IMPORTANT] 
+Install your antakia env in IPython, in order to select it from Jupyter :
+
+```
+python -m ipykernel install --user --name antakia --display-name "Antakia"
+```
+
+Finally, launch Jupyter server from `antakia` folder :
+```
+jupyter notebook
+```
+and open a notebook .ipynb file in `example` folder.
+
+### Troubleshooting 
+
+If you get JS errors in your notebook / see broken link icons for each widget / see this kind of errors `404 GET /static/jupyterlab-plotly.js` or other missing JS library :
+* try to remove your local `etc/` folder in `antakia` folder
+* try `jupyter lab` instead of `jupyter notebook`
+* probably useless but worth trying : `jupyter nbextension enable --py widgetsnbextension`
+* try to `pip install --force-reinstall` ipywidgets widgetsnbextension
+ 
+
+## Install and run with Docker
+
+> [!IMPORTANT] 
+Be sure to have a Docker engine running on your computer (ie. launch Docker Desktop)
+
+```
+docker build -t demo-antakia .
+docker run -p 8888:8888 demo-antakia
+```
+
+In your Terminal, click on the `http://127.0.0.1:8888/lab?token=WHATEVER_YOUR_TOKEN_IS URL` link.
+

antakia-0.2.1/README.md

@@ -0,0 +1,81 @@
+# Welcome to AntakIA !
+
+AntakIA is an open-source tool from AI-vidence to explain ML black box models.
+
+Here is a quick tour of AntakIA:
+![AntakIA demo](/docs/img/antakia.gif)
+
+See full video on [Youtube](https://youtu.be/wQFC_20OIOM).
+
+## Install and run from source code
+
+Clone the repo and create a virtual environment
+
+```
+git clone https://github.com/AI-vidence/antakia.git
+cd antakia
+```
+
+Then, with `pip` :
+
+```
+python3.10 -m venv .
+source bin/activate
+pip install -e .
+```
+
+Or,if you prefer `poetry` :
+
+```
+poetry shell
+peotry install
+```
+
+Got to https://doc.antakia.ai to learn how to use AntakIA.
+
+You may also need to install Git LFS to download our CSV files in /data:
+```
+brew install git-lfs # if you're a Mac / brew user
+git lfs install
+cd antakia
+git lfs track "*.csv"
+git add .gitattributes
+git lfs fetch
+git lfs checkout
+```
+
+Reference : [see Git-LFS website](https://git-lfs.com)
+
+> [!IMPORTANT] 
+Install your antakia env in IPython, in order to select it from Jupyter :
+
+```
+python -m ipykernel install --user --name antakia --display-name "Antakia"
+```
+
+Finally, launch Jupyter server from `antakia` folder :
+```
+jupyter notebook
+```
+and open a notebook .ipynb file in `example` folder.
+
+### Troubleshooting 
+
+If you get JS errors in your notebook / see broken link icons for each widget / see this kind of errors `404 GET /static/jupyterlab-plotly.js` or other missing JS library :
+* try to remove your local `etc/` folder in `antakia` folder
+* try `jupyter lab` instead of `jupyter notebook`
+* probably useless but worth trying : `jupyter nbextension enable --py widgetsnbextension`
+* try to `pip install --force-reinstall` ipywidgets widgetsnbextension
+ 
+
+## Install and run with Docker
+
+> [!IMPORTANT] 
+Be sure to have a Docker engine running on your computer (ie. launch Docker Desktop)
+
+```
+docker build -t demo-antakia .
+docker run -p 8888:8888 demo-antakia
+```
+
+In your Terminal, click on the `http://127.0.0.1:8888/lab?token=WHATEVER_YOUR_TOKEN_IS URL` link.

antakia-0.2.1/antakia/__init__.py

@@ -0,0 +1,5 @@
+
+__version__ = "0.2.1"
+__author__ = "AI-vidence "
+
+from antakia.antakia import AntakIA

antakia-0.2.1/antakia/antakia.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from typing import List, Dict, Any
+
+import numpy as np
+import pandas as pd
+
+from dotenv import load_dotenv
+
+from antakia_core.utils.utils import ProblemCategory
+
+load_dotenv()
+
+from antakia.utils.checks import is_valid_model
+from antakia_core.utils.variable import Variable, DataVariables
+from antakia.gui.gui import GUI
+
+
+class AntakIA:
+    """
+    AntakIA class. 
+
+    Antakia instances provide data and methods to explain a ML model.
+
+    Instance attributes
+    -------------------
+    X : pd.DataFrame the training dataset
+    y : pd.Series the target value
+    model : Model
+        the model to explain
+    variables : a list of Variables, describing X_list[0]
+    X_test : pd.DataFrame the test dataset
+    y_test : pd.Series the test target value
+    score : reference scoring function
+    """
+
+    def __init__(
+            self,
+            X: pd.DataFrame,
+            y: pd.Series,
+            model,
+            variables: DataVariables | List[Dict[str, Any]] | pd.DataFrame | None = None,
+            X_test: pd.DataFrame = None,
+            y_test: pd.Series = None,
+            X_exp: pd.DataFrame | None = None,
+            score: callable | str = 'auto',
+            problem_category: str = 'auto'
+    ):
+        """
+        AntakiIA constructor.
+
+        Parameters:
+            X : pd.DataFrame the training dataset
+            y : pd.Series the target value
+            model : Model
+                the model to explain
+            variables : a list of Variables, describing X_list[0]
+            X_test : pd.DataFrame the test dataset
+            y_test : pd.Series the test target value
+            score : reference scoring function
+        """
+
+        load_dotenv()
+
+        if not is_valid_model(model):
+            raise ValueError(model, " should implement predict and score methods")
+        X, y, X_exp = self._preprocess_data(X, y, X_exp)
+
+        self.X = X
+        self.X_test = X_test
+        if y.ndim > 1:
+            y = y.squeeze()
+        self.y = y.astype(float)
+        if y_test is not None and y_test.ndim > 1:
+            y_test = y_test.squeeze()
+        self.y_test = y_test
+        self.model = model
+        self.X_exp = X_exp
+        self.problem_category = self._preprocess_problem_category(problem_category, model, X)
+        self.score = self._preprocess_score(score, self.problem_category)
+
+        self.set_variables(X, variables)
+
+        self.gui = GUI(
+            self.X,
+            self.y,
+            self.model,
+            self.variables,
+            self.X_test,
+            self.y_test,
+            self.X_exp,
+            self.score,
+            self.problem_category
+        )
+
+    def set_variables(self, X, variables):
+        if variables is not None:
+            if isinstance(variables, list):
+                self.variables: DataVariables = Variable.import_variable_list(variables)
+                if len(self.variables) != len(X.columns):
+                    raise ValueError("Provided variable list must be the same length of the dataframe")
+            elif isinstance(variables, pd.DataFrame):
+                self.variables = Variable.import_variable_df(variables)
+            else:
+                raise ValueError("Provided variable list must be a list or a pandas DataFrame")
+        else:
+            self.variables = Variable.guess_variables(X)
+
+    def start_gui(self) -> GUI:
+        return self.gui.show_splash_screen()
+
+    def export_regions(self):
+        return self.gui.region_set
+
+    def _preprocess_data(self, X: pd.DataFrame, y, X_exp: pd.DataFrame):
+        if isinstance(X, np.ndarray):
+            X = pd.DataFrame(X)
+        if isinstance(X_exp, np.ndarray):
+            X_exp = pd.DataFrame(X_exp)
+        if isinstance(y, np.ndarray):
+            y = pd.Series(y)
+
+        X.columns = [str(col) for col in X.columns]
+        if X_exp is not None:
+            X_exp.columns = X.columns
+
+        if X_exp is not None:
+            pd.testing.assert_index_equal(X.index, X_exp.index, check_names=False)
+            if X.reindex(X_exp.index).iloc[:, 0].isna().sum() != X.iloc[:, 0].isna().sum():
+                raise IndexError('X and X_exp must share the same index')
+        pd.testing.assert_index_equal(X.index, y.index, check_names=False)
+        return X, y, X_exp
+
+    def _preprocess_problem_category(self, problem_category: str, model, X: pd.DataFrame) -> ProblemCategory:
+        if problem_category not in [e.name for e in ProblemCategory]:
+            raise ValueError('Invalid problem category')
+        if problem_category == 'auto':
+            if hasattr(model, 'predict_proba'):
+                return ProblemCategory['classification_with_proba']
+            pred = self.model.predict(self.X.sample(min(100, len(self.X))))
+            if len(pred.shape) > 1 and pred.shape[1] > 1:
+                return ProblemCategory['classification_proba']
+            return ProblemCategory['regression']
+        if problem_category == 'classification':
+            if hasattr(model, 'prodict_proba'):
+                return ProblemCategory['classification_with_proba']
+            pred = model.predict(X.sample(min(100, len(X))))
+            if len(pred.shape) > 1 and pred.shape[1] > 1:
+                return ProblemCategory['classification_proba']
+            return ProblemCategory['classification_label_only']
+        return ProblemCategory[problem_category]
+
+    def _preprocess_score(self, score, problem_category):
+        if callable(score):
+            return score
+        if score != 'auto':
+            return score
+        if problem_category == ProblemCategory.regression:
+            return 'mse'
+        return 'accuracy'

antakia-0.2.1/antakia/config.py

@@ -0,0 +1,17 @@
+import os
+
+DEFAULT_EXPLANATION_METHOD = int(os.environ.get('DEFAULT_EXPLANATION_METHOD', 1))
+DEFAULT_DIMENSION = int(os.environ.get('DEFAULT_VS_DIMENSION', 2))
+DEFAULT_PROJECTION = 'PaCMAP'
+
+INIT_FIG_WIDTH = int(os.environ.get('INIT_FIG_WIDTH', 1800))
+MAX_DOTS = int(os.environ.get('MAX_DOTS', 5000))
+
+# Rule format
+USE_INTERVALS_FOR_RULES = os.environ.get('USE_INTERVALS_FOR_RULES', 'True') == 'True'
+MAX_RULES_DESCR_LENGTH = int(os.environ.get('MAX_RULES_DESCR_LENGTH', 200))
+
+SHOW_LOG_MODULE_WIDGET = os.environ.get('SHOW_LOG_MODULE_WIDGET', 'False') == 'True'
+
+#Auto cluster
+MIN_POINTS_NUMBER = 100

antakia-0.2.1/antakia/explanation/explanation_method.py

@@ -0,0 +1,66 @@
+import pandas as pd
+
+from antakia_core.utils.long_task import LongTask
+
+
+class ExplanationMethod(LongTask):
+    """
+    Abstract class (see Long Task) to compute explaination values for the Explanation Space (ES)
+
+    Attributes
+    model : the model to explain
+    explanation_method : SHAP or LIME
+    """
+
+    # Class attributes
+    NONE = 0  # no explanation, ie: original values
+    SHAP = 1
+    LIME = 2
+
+    def __init__(
+            self,
+            explanation_method: int,
+            X: pd.DataFrame,
+            model,
+            task_type,
+            progress_updated: callable = None,
+    ):
+        if not ExplanationMethod.is_valid_explanation_method(explanation_method):
+            raise ValueError(explanation_method, " is a bad explanation method")
+        self.explanation_method = explanation_method
+        super().__init__(X, progress_updated)
+        self.task_type = task_type
+        self.model = model
+
+    @staticmethod
+    def is_valid_explanation_method(method: int) -> bool:
+        """
+        Returns True if this is a valid explanation method.
+        """
+        return (
+                method == ExplanationMethod.SHAP
+                or method == ExplanationMethod.LIME
+                or method == ExplanationMethod.NONE
+        )
+
+    @staticmethod
+    def explanation_methods_as_list() -> list:
+        return [ExplanationMethod.SHAP, ExplanationMethod.LIME]
+
+    @staticmethod
+    def explain_method_as_str(method: int) -> str:
+        if method == ExplanationMethod.SHAP:
+            return "SHAP"
+        elif method == ExplanationMethod.LIME:
+            return "LIME"
+        else:
+            raise ValueError(method, " is a bad explanation method")
+
+    @staticmethod
+    def explain_method_as_int(method: str) -> int:
+        if method.upper() == "SHAP":
+            return ExplanationMethod.SHAP
+        elif method.upper() == "LIME":
+            return ExplanationMethod.LIME
+        else:
+            raise ValueError(method, " is a bad explanation method")

antakia-0.2.1/antakia/explanation/explanations.py

@@ -0,0 +1,108 @@
+import lime
+import numpy as np
+import pandas as pd
+import shap
+from antakia_core.utils.utils import ProblemCategory
+
+from antakia.explanation.explanation_method import ExplanationMethod
+
+
+# ===========================================================
+#              Explanations implementations
+# ===========================================================
+
+
+class SHAPExplanation(ExplanationMethod):
+    """
+    SHAP computation class.
+    """
+
+    def __init__(self, X: pd.DataFrame, model, task_type, progress_updated: callable = None):
+        super().__init__(ExplanationMethod.SHAP, X, model, task_type, progress_updated)
+
+    @property
+    def link(self):
+        if self.task_type == ProblemCategory.regression:
+            return "identity"
+        return "logit"
+
+    def compute(self) -> pd.DataFrame:
+        self.publish_progress(0)
+        try:
+            explainer = shap.TreeExplainer(self.model)
+        except:
+            explainer = shap.KernelExplainer(self.model.predict, self.X.sample(min(200, len(self.X))), link=self.link)
+        chunck_size = 200
+        shap_val_list = []
+        for i in range(0, len(self.X), chunck_size):
+            explanations = explainer.shap_values(self.X.iloc[i:i + chunck_size])
+            shap_val_list.append(
+                pd.DataFrame(explanations, columns=self.X.columns, index=self.X.index[i:i + chunck_size]))
+            self.publish_progress(int(100 * (i * chunck_size) / len(self.X)))
+        shap_values = pd.concat(shap_val_list)
+        self.publish_progress(100)
+        return shap_values
+
+
+class LIMExplanation(ExplanationMethod):
+    """
+    LIME computation class.
+    """
+
+    def __init__(self, X: pd.DataFrame, model, task_type, progress_updated: callable = None):
+        super().__init__(ExplanationMethod.LIME, X, model, task_type, progress_updated)
+
+    @property
+    def mode(self):
+        print(self.task_type)
+        if self.task_type == ProblemCategory.regression:
+            return 'regression'
+        else:
+            return 'classification'
+
+    def compute(self) -> pd.DataFrame:
+        self.publish_progress(0)
+
+        explainer = lime.lime_tabular.LimeTabularExplainer(
+            self.X.sample(min(len(self.X), 500)).values,
+            feature_names=self.X.columns,
+            verbose=False,
+            mode=self.mode,
+            discretize_continuous=False
+        )
+
+        values_lime = pd.DataFrame(
+            np.zeros(self.X.shape),
+            index=self.X.index,
+            columns=self.X.columns
+        )
+        progress = 0
+        if self.mode == 'regression':
+            predict_fct = self.model.predict
+            i = 0
+        else:
+            i = 1
+            if hasattr(self.model, 'predict_proba'):
+                predict_fct = self.model.predict_proba
+            else:
+                predict_fct = self.model.predict
+        for index, row in self.X.iterrows():
+            exp = explainer.explain_instance(row.values, predict_fct)
+
+            values_lime.loc[index] = pd.Series(exp.local_exp[i], index=explainer.feature_names).str[1]
+            progress += 100 / len(self.X)
+            self.publish_progress(int(progress))
+        self.publish_progress(100)
+        return values_lime
+
+
+def compute_explanations(X: pd.DataFrame, model, explanation_method: int, task_type,
+                         callback: callable) -> pd.DataFrame:
+    """ Generic method to compute explanations, SHAP or LIME
+    """
+    if explanation_method == ExplanationMethod.SHAP:
+        return SHAPExplanation(X, model, task_type, callback).compute()
+    elif explanation_method == ExplanationMethod.LIME:
+        return LIMExplanation(X, model, task_type, callback).compute()
+    else:
+        raise ValueError(f"This explanation method {explanation_method} is not valid!")

antakia-0.2.1/antakia/gui/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.1.1"
+__author__ = "AI-vidence"

antakia-0.2.1/antakia/gui/colorTable.py

@@ -0,0 +1,52 @@
+from traitlets import traitlets
+import ipyvuetify as v
+from antakia_core.utils.utils import colors
+
+
+class ColorTable(v.VuetifyTemplate):
+    """
+    table to display regions
+    """
+    headers = traitlets.List([]).tag(sync=True, allow_null=True)
+    items = traitlets.List([]).tag(sync=True, allow_null=True)
+    selected = traitlets.List([]).tag(sync=True, allow_null=True)
+    colors = traitlets.List(colors).tag(sync=True)
+    template = traitlets.Unicode('''
+        <template>
+            <v-data-table
+                v-model="selected"
+                :headers="headers"
+                :items="items"
+                item-key="Region"
+                show-select
+                :hide-default-footer="false"
+                @item-selected="tableselect"
+            >
+            <template #header.data-table-select></template>
+            <template v-slot:item.Region="{ item }">
+              <v-chip :color="item.color" >
+                {{ item.Region }}
+              </v-chip>
+            </template>
+            </v-data-table>
+        </template>
+        ''').tag(sync=True)  # type: ignore
+    disable_sort = True
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.callback = None
+
+    @staticmethod
+    def get_color(item):
+        return item.color
+
+    # @click:row="tableclick"
+    # def vue_tableclick(self, data):
+    #     raise ValueError(f"click event data = {data}")
+
+    def set_callback(self, callback: callable):  # type: ignore
+        self.callback = callback
+
+    def vue_tableselect(self, data):
+        self.callback(data)

antakia-0.2.1/antakia/gui/data_store.py

@@ -0,0 +1,8 @@
+class DataStore:
+    def __init__(
+            self,
+            X,
+            y,
+            X_test,
+            y_test,
+    ):