xwhy 0.0.0.1__tar.gz

xwhy-0.0.0.1/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.1
+Name: xwhy
+Version: 0.0.0.1
+Summary: Explain Why (XWhy) with Statistical Model-agnostic Interpretability with Local Explanations (SMILE)
+Home-page: https://github.com/Dependable-Intelligent-Systems-Lab/xwhy
+Author: Mojgan Hashemian, Koorosh Aslansefat (corresponding), Mohammad Naveed Akram, Ioannis Sorokos, Martin Walker, Yiannis Papadopoulos
+Author-email: koo.ec2008@gmail.com
+License: BSD
+Description: UNKNOWN
+Platform: UNKNOWN
+Requires-Python: >=3.5
+Provides-Extra: dev

xwhy-0.0.0.1/README.md

@@ -0,0 +1,63 @@
+<p align="left"> </p>
+
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+ <a href="https://standardjs.com"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Standard - \Python Style Guide"></a> 
+ 
+# X-Why
+XWhy: eXplain Why with <b>SMILE</b> -- <b>S</b>tatistical <b>M</b>odel-agnostic <b>I</b>nterpretability with <b>L</b>ocal <b>E</b>xplanations
+ 
+<p align="center">
+ <img src="https://github.com/koo-ec/xwhy/blob/main/docs/graphics/XWhy_Logo_v1.png" alt="XWhy, SMILE, Explainability, Interpretability, XAI, machine learning explainability, responsible ai"> </p>
+
+## Abstract
+<p align="justify">Machine learning is currently undergoing an explosion in capability, popularity, and sophistication. However, one of the major barriers to widespread acceptance of machine learning (ML) is trustworthiness: most ML models operate as black boxes, their inner workings opaque and mysterious, and it can be difficult to trust their conclusions without understanding how those conclusions are reached. Explainability is therefore a key aspect of improving trustworthiness: the ability to better understand, interpret, and anticipate the behaviour of ML models. To this end, we propose a SMILE, a new method that builds on previous approaches by making use of statistical distance measures to improve explainability while remaining applicable to a wide range of input data domains.</p>
+
+<!--
+## Installation
+```
+pip install xwhy
+```
+
+## Simple Example
+```
+import xwhy
+import xgboost
+
+# train an XGBoost model
+X, y = xwhy.datasets.boston()
+model = xgboost.XGBRegressor().fit(X, y)
+
+# explain the model's predictions using xwhy
+# (same syntax works for LightGBM, CatBoost, scikit-learn, transformers, Spark, etc.)
+explainer = xwhy.Explainer(model)
+xwhy_values = explainer(X)
+
+# visualize the first prediction's explanation
+xwhy.plots.waterfall(xwhy_values[0])
+
+```
+-->
+ 
+ 
+ 
+## Citations
+It would be appreciated a citation to our paper as follows if you use X-Why for your research:
+```
+@article{Aslansefat2021Xwhy,
+   author  = {{Aslansefat}, Koorosh and {Hashemian}, Mojgan and {Martin}, Walker, {Akram} Mohammed Naveed, {Sorokos} Ioannis and {Papadopoulos}, Yiannis},
+   title   = "{SMILE: Statistical Model-agnostic Interpretability with Local Explanations}",
+   journal = {arXiv e-prints},
+   year    = {2021},
+   url     = {https://arxiv.org/abs/...},
+   eprint  = {},
+}
+```
+ 
+## Acknowledgment
+<p align="justify">This project is supported by the <a href = "https://www.sesame-project.org"><b>Secure and Safe Multi-Robot Systems (SESAME)</b></a> H2020 Project under Grant Agreement 101017258.</p>
+
+## Awards
+<a href = "https://www.turing.ac.uk/post-doctoral-enrichment-awards-pdea">Post-Doctoral Enrichment Award from the Alan Turing Institute</a>
+
+## Contribution 
+If you are interested in contributing to this project, please check the [contribution guidelines](https://github.com/koo-ec/xwhy/blob/main/docs/contribute/contributing.md).

xwhy-0.0.0.1/setup.cfg

@@ -0,0 +1,7 @@
+[flake8]
+max-line-length = 100
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

xwhy-0.0.0.1/setup.py

@@ -0,0 +1,26 @@
+from setuptools import setup, find_packages
+
+setup(name='xwhy',
+      version='0.0.0.1',
+      description='Explain Why (XWhy) with Statistical Model-agnostic Interpretability with Local Explanations (SMILE)',
+      url='https://github.com/Dependable-Intelligent-Systems-Lab/xwhy',
+      author='Mojgan Hashemian, Koorosh Aslansefat (corresponding), Mohammad Naveed Akram, Ioannis Sorokos, Martin Walker, Yiannis Papadopoulos',
+      author_email='koo.ec2008@gmail.com',
+      license='BSD',
+      packages=find_packages(exclude=['js', 'node_modules', 'tests']),
+      python_requires='>=3.5',
+      install_requires=[
+          'matplotlib',
+          'numpy',
+          'scipy',
+          'tqdm >= 4.29.1',
+          'scikit-learn>=0.18',
+          'scikit-image>=0.12',
+          'pyDOE2==1.3.0',
+          'twine==1.13.0'
+      ],
+      extras_require={
+          'dev': ['pytest', 'flake8'],
+      },
+      include_package_data=True,
+      zip_safe=False)

xwhy-0.0.0.1/xwhy/__init__.py

@@ -0,0 +1,8 @@
+import warnings
+import sys
+
+__version__ = '0.41.0'
+
+# check python version
+if (sys.version_info < (3, 0)):
+    warnings.warn("As of version 0.29.0 shap only supports Python 3 (not 2)!")

xwhy-0.0.0.1/xwhy/datasets.py

@@ -0,0 +1,267 @@
+# This file is a modified copy of SHAP package.py with some modification
+# source: https://github.com/slundberg/shap/blob/master/shap/datasets.py
+
+import pandas as pd
+import numpy as np
+import sklearn.datasets
+import os
+
+try:
+    from urllib.request import urlretrieve
+except ImportError:
+    from urllib import urlretrieve
+
+github_data_url = "https://github.com/koo-ec/smile/tree/main/data"
+
+def imagenet50(display=False, resolution=224):
+    """ This is a set of 50 images representative of ImageNet images.
+    This dataset was collected by randomly finding a working ImageNet link and then pasting the
+    original ImageNet image into Google image search restricted to images licensed for reuse. A
+    similar image (now with rights to reuse) was downloaded as a rough replacment for the original
+    ImageNet image. The point is to have a random sample of ImageNet for use as a background
+    distribution for explaining models trained on ImageNet data.
+    Note that because the images are only rough replacements the labels might no longer be correct.
+    """
+
+    prefix = github_data_url + "imagenet50_"
+    X = np.load(cache(prefix + "%sx%s.npy" % (resolution, resolution))).astype(np.float32)
+    y = np.loadtxt(cache(prefix + "labels.csv"))
+    return X, y
+
+def boston(display=False):
+    """ Return the boston housing price prediction data, and here is the list of features:
+        CRIM: Per capita crime rate by town
+        ZN: Proportion of residential land zoned for lots over 25,000 sq. ft
+        INDUS: Proportion of non-retail business acres per town
+        CHAS: Charles River dummy variable (= 1 if tract bounds river; 0 otherwise)
+        NOX: Nitric oxide concentration (parts per 10 million)RM: Average number of rooms per dwelling
+        AGE: Proportion of owner-occupied units built prior to 1940DIS: Weighted distances to five Boston employment centers
+        RAD: Index of accessibility to radial highwaysTAX: Full-value property tax rate per $10,000
+        PTRATIO: Pupil-teacher ratio by townB: 1000(Bk — 0.63)², where Bk is the proportion of [people of African American descent] by town
+        LSTAT: Percentage of lower status of the populationMEDV: Median value of owner-occupied homes in $1000s
+    """
+
+    d = sklearn.datasets.load_boston()
+    df = pd.DataFrame(data=d.data, columns=d.feature_names) # pylint: disable=E1101
+    return df, d.target # pylint: disable=E1101
+
+
+def linnerud(display=False):
+    """ Return the linnerud data in a nice package (multi-target regression). """
+
+    d = sklearn.datasets.load_linnerud()
+    X = pd.DataFrame(d.data, columns=d.feature_names) # pylint: disable=E1101
+    y = pd.DataFrame(d.target, columns=d.target_names) # pylint: disable=E1101
+    return X, y # pylint: disable=E1101
+
+
+def imdb(display=False):
+    """ Return the clssic IMDB sentiment analysis training data in a nice package.
+    Full data is at: http://ai.stanford.edu/~amaas/data/sentiment/aclImdb_v1.tar.gz
+    Paper to cite when using the data is: http://www.aclweb.org/anthology/P11-1015
+    """
+
+    with open(cache(github_data_url + "imdb_train.txt")) as f:
+        data = f.readlines()
+    y = np.ones(25000, dtype=np.bool)
+    y[:12500] = 0
+    return data, y
+
+def communitiesandcrime(display=False):
+    """ Predict total number of non-violent crimes per 100K popuation.
+    This dataset is from the classic UCI Machine Learning repository:
+    https://archive.ics.uci.edu/ml/datasets/Communities+and+Crime+Unnormalized
+    """
+
+    raw_data = pd.read_csv(
+        cache(github_data_url + "CommViolPredUnnormalizedData.txt"),
+        na_values="?"
+    )
+
+    # find the indices where the total violent crimes are known
+    valid_inds = np.where(np.invert(np.isnan(raw_data.iloc[:,-2])))[0]
+    y = np.array(raw_data.iloc[valid_inds,-2], dtype=np.float)
+
+    # extract the predictive features and remove columns with missing values
+    X = raw_data.iloc[valid_inds,5:-18]
+    valid_cols = np.where(np.isnan(X.values).sum(0) == 0)[0]
+    X = X.iloc[:,valid_cols]
+
+    return X, y
+
+def diabetes(display=False):
+    """ Return the diabetes data in a nice package. """
+
+    d = sklearn.datasets.load_diabetes()
+    df = pd.DataFrame(data=d.data, columns=d.feature_names) # pylint: disable=E1101
+    return df, d.target # pylint: disable=E1101
+
+
+def iris(display=False):
+    """ Return the classic iris data in a nice package. """
+
+    d = sklearn.datasets.load_iris()
+    df = pd.DataFrame(data=d.data, columns=d.feature_names) # pylint: disable=E1101
+    if display:
+        return df, [d.target_names[v] for v in d.target] # pylint: disable=E1101
+    else:
+        return df, d.target # pylint: disable=E1101
+
+
+def adult(display=False):
+    """ Return the Adult census data in a nice package. """
+    dtypes = [
+        ("Age", "float32"), ("Workclass", "category"), ("fnlwgt", "float32"),
+        ("Education", "category"), ("Education-Num", "float32"), ("Marital Status", "category"),
+        ("Occupation", "category"), ("Relationship", "category"), ("Race", "category"),
+        ("Sex", "category"), ("Capital Gain", "float32"), ("Capital Loss", "float32"),
+        ("Hours per week", "float32"), ("Country", "category"), ("Target", "category")
+    ]
+    raw_data = pd.read_csv(
+        cache(github_data_url + "adult.data"),
+        names=[d[0] for d in dtypes],
+        na_values="?",
+        dtype=dict(dtypes)
+    )
+    data = raw_data.drop(["Education"], axis=1)  # redundant with Education-Num
+    filt_dtypes = list(filter(lambda x: not (x[0] in ["Target", "Education"]), dtypes))
+    data["Target"] = data["Target"] == " >50K"
+    rcode = {
+        "Not-in-family": 0,
+        "Unmarried": 1,
+        "Other-relative": 2,
+        "Own-child": 3,
+        "Husband": 4,
+        "Wife": 5
+    }
+    for k, dtype in filt_dtypes:
+        if dtype == "category":
+            if k == "Relationship":
+                data[k] = np.array([rcode[v.strip()] for v in data[k]])
+            else:
+                data[k] = data[k].cat.codes
+
+    if display:
+        return raw_data.drop(["Education", "Target", "fnlwgt"], axis=1), data["Target"].values
+    else:
+        return data.drop(["Target", "fnlwgt"], axis=1), data["Target"].values
+
+
+def nhanesi(display=False):
+    """ A nicely packaged version of NHANES I data with surivival times as labels.
+    """
+    X = pd.read_csv(cache(github_data_url + "NHANESI_X.csv"), index_col=0)
+    y = pd.read_csv(cache(github_data_url + "NHANESI_y.csv"), index_col=0)["y"]
+    if display:
+        X_display = X.copy()
+        #X_display["sex_isFemale"] = ["Female" if v else "Male" for v in X["sex_isFemale"]]
+        return X_display, np.array(y)
+    else:
+        return X, np.array(y)
+
+
+def corrgroups60(display=False):
+    """ Correlated Groups 60
+    
+    A simulated dataset with tight correlations among distinct groups of features.
+    """
+
+    # set a constant seed
+    old_seed = np.random.seed()
+    np.random.seed(0)
+
+    # generate dataset with known correlation
+    N = 1000
+    M = 60
+
+    # set one coefficent from each group of 3 to 1
+    beta = np.zeros(M)
+    beta[0:30:3] = 1
+
+    # build a correlation matrix with groups of 3 tightly correlated features
+    C = np.eye(M)
+    for i in range(0,30,3):
+        C[i,i+1] = C[i+1,i] = 0.99
+        C[i,i+2] = C[i+2,i] = 0.99
+        C[i+1,i+2] = C[i+2,i+1] = 0.99
+    f = lambda X: np.matmul(X, beta)
+
+    # Make sure the sample correlation is a perfect match
+    X_start = np.random.randn(N, M)
+    X_centered = X_start - X_start.mean(0)
+    Sigma = np.matmul(X_centered.T, X_centered) / X_centered.shape[0]
+    W = np.linalg.cholesky(np.linalg.inv(Sigma)).T
+    X_white = np.matmul(X_centered, W.T)
+    assert np.linalg.norm(np.corrcoef(np.matmul(X_centered, W.T).T) - np.eye(M)) < 1e-6 # ensure this decorrelates the data
+
+    # create the final data
+    X_final = np.matmul(X_white, np.linalg.cholesky(C).T)
+    X = X_final
+    y = f(X) + np.random.randn(N) * 1e-2
+
+    # restore the previous numpy random seed
+    np.random.seed(old_seed)
+
+    return pd.DataFrame(X), y
+
+
+def independentlinear60(display=False):
+    """ 
+    A simulated dataset with tight correlations among distinct groups of features.
+    """
+
+    # set a constant seed
+    old_seed = np.random.seed()
+    np.random.seed(0)
+
+    # generate dataset with known correlation
+    N = 1000
+    M = 60
+
+    # set one coefficent from each group of 3 to 1
+    beta = np.zeros(M)
+    beta[0:30:3] = 1
+    f = lambda X: np.matmul(X, beta)
+
+    # Make sure the sample correlation is a perfect match
+    X_start = np.random.randn(N, M)
+    X = X_start - X_start.mean(0)
+    y = f(X) + np.random.randn(N) * 1e-2
+
+    # restore the previous numpy random seed
+    np.random.seed(old_seed)
+
+    return pd.DataFrame(X), y
+
+
+def a1a():
+    """
+    A sparse dataset in scipy csr matrix format.
+    """
+    return sklearn.datasets.load_svmlight_file(cache(github_data_url + 'a1a.svmlight'))
+
+
+def rank():
+    """ 
+    Ranking datasets from lightgbm repository.
+    """
+    rank_data_url = 'https://raw.githubusercontent.com/Microsoft/LightGBM/master/examples/lambdarank/'
+    x_train, y_train = sklearn.datasets.load_svmlight_file(cache(rank_data_url + 'rank.train'))
+    x_test, y_test = sklearn.datasets.load_svmlight_file(cache(rank_data_url + 'rank.test'))
+    q_train = np.loadtxt(cache(rank_data_url + 'rank.train.query'))
+    q_test = np.loadtxt(cache(rank_data_url + 'rank.test.query'))
+    return x_train, y_train, x_test, y_test, q_train, q_test
+
+
+def cache(url, file_name=None):
+    if file_name is None:
+        file_name = os.path.basename(url)
+    data_dir = os.path.join(os.path.dirname(__file__), "cached_data")
+    if not os.path.isdir(data_dir):
+        os.mkdir(data_dir)
+    
+    file_path = os.path.join(data_dir, file_name)
+    if not os.path.isfile(file_path):
+        urlretrieve(url, file_path)
+
+    return file_path

xwhy-0.0.0.1/xwhy/smile_graph.py

@@ -0,0 +1,263 @@
+import numpy as np
+from matplotlib import pyplot as plt
+from matplotlib.ticker import MultipleLocator
+import scipy.linalg as la
+import networkx as nx
+import random, time, math
+from collections import Counter
+
+import fun as f
+from Graph import Graph
+from Watts_Strogatz import watts_strogatz_graph
+from Erdos_Renyi import erdos_renyi_graph
+
+from sklearn.linear_model import LinearRegression
+from sklearn.preprocessing import normalize
+
+import graph_nets
+from graph_nets.graphs import GraphsTuple
+import graph_attribution as gatt
+
+def Wasserstein_Dist(cdfX, cdfY):
+  
+    Res = 0
+    power = 1
+    n = len(cdfX)
+
+    for ii in range(0, n-2):
+        height = abs(cdfX[ii]-cdfY[ii])
+        width = cdfX[ii+1] - cdfX[ii]
+        Res = Res + (height ** power) * width 
+ 
+    return Res
+
+
+def r_eigenv(G_i, G_j):
+    #Eigen-decomposition of G_j
+    A_Gi = (nx.adjacency_matrix(G_i)).todense()
+    D_i = np.diag(np.asarray(sum(A_Gi))[0])
+    eigenvalues_Gi, eigenvectors_Gi = la.eig(D_i - A_Gi)
+    r_eigenv_Gi = sorted(zip(eigenvalues_Gi.real, eigenvectors_Gi.T), key=lambda x: x[0])
+
+    #Eigen-decomposition of G_j
+    A_Gj = (nx.adjacency_matrix(G_j)).todense()
+    D_j = np.diag(np.asarray(sum(A_Gj))[0])
+    eigenvalues_Gj, eigenvectors_Gj = la.eig(D_j - A_Gj)
+    r_eigenv_Gj = sorted(zip(eigenvalues_Gj.real, eigenvectors_Gj.T), key=lambda x: x[0])
+    
+    r = 4
+    signs =[-1,1]
+    temp = []
+    for  sign_s in signs:
+        for sign_l in signs:
+            vri = sorted(f.normalize_eigenv(sign_s * r_eigenv_Gi[r][1]))
+            vrj = sorted(f.normalize_eigenv(sign_l * r_eigenv_Gj[r][1]))
+            cdf_dist = f.cdf_dist(vri, vrj)
+            temp.append(cdf_dist)
+    
+    #Compute empirical CDF
+    step = 0.005
+    x=np.arange(0, 1, step)
+    cdf_grid_Gip = f.cdf(len(r_eigenv_Gi[r][1]),x,
+                   f.normalize_eigenv(sorted(r_eigenv_Gi[r][1], key=lambda x: x)))
+    cdf_grid_Gin = f.cdf(len(r_eigenv_Gi[r][1]),x,
+                   f.normalize_eigenv(sorted(-r_eigenv_Gi[r][1], key=lambda x: x)))
+
+    cdf_grid_Gjp = f.cdf(len(r_eigenv_Gj[r][1]),x,
+                   f.normalize_eigenv(sorted(r_eigenv_Gj[r][1], key=lambda x: x)))
+    cdf_grid_Gjn = f.cdf(len(r_eigenv_Gj[r][1]),x,
+                   f.normalize_eigenv(sorted(-r_eigenv_Gj[r][1], key=lambda x: x)))
+    
+    WD1 = Wasserstein_Dist(cdf_grid_Gip, cdf_grid_Gjp)
+    WD2 = Wasserstein_Dist(cdf_grid_Gip, cdf_grid_Gjn)
+    WD3 = Wasserstein_Dist(cdf_grid_Gin, cdf_grid_Gjp)
+    WD4 = Wasserstein_Dist(cdf_grid_Gin, cdf_grid_Gjn)
+
+    WD = [WD1, WD2, WD3, WD4]
+    
+    return max(temp), max(WD)
+
+def xwhy_graph_edges(X_input_graph, model, num_perturb = 50, kernel_width = 0.25, num_top_features = 10, eps=1):    
+    #num_perturb = 5000
+    
+    num_uniqe_words = len(X_input_graph.edges)
+
+    perturbations = np.random.binomial(1, 0.5, size=(num_perturb, num_uniqe_words))
+
+    def perturb_graph_edge(input_graph, perturbation):
+        perturbed_graph = input_graph.copy()
+        ebun = []
+        for ii, ed in enumerate(perturbed_graph.edges):
+            if perturbation[ii] == 0:
+                ebun.append(ed)
+        perturbed_graph.remove_edges_from(ebun)
+        return perturbed_graph
+        
+    predictions = []
+    WD_dist = []
+    for pert in perturbations:
+        p_graph = perturb_graph_edge(X_input_graph, pert)
+        pred = model.predict(graph_nets.utils_np.networkxs_to_graphs_tuple([p_graph]))
+        predictions.append(pred)
+        Sscore, WD_score = r_eigenv(X_input_graph, p_graph)
+        WD_dist.append(WD_score)
+
+    predictions = np.array(predictions)   
+    WD_dist = np.array(WD_dist) 
+    
+    weights = np.sqrt(np.exp(-((eps*WD_dist)**2)/kernel_width**2)) #Kernel function
+                
+    class_to_explain = 0
+    simpler_model = LinearRegression()
+    simpler_model.fit(X=perturbations, y=predictions, sample_weight=weights)
+    coeff = simpler_model.coef_[0]
+    
+    top_features = np.argsort(abs(coeff))[-num_top_features:] 
+    
+    coeff2 = simpler_model.coef_
+
+    odds = np.exp(coeff2)
+
+    Bounded_coeff = 2*(normalize(coeff[:,np.newaxis], axis=0).ravel()+1)
+    
+    return coeff, odds, top_features, Bounded_coeff, simpler_model 
+  
+def perturb_graph_node(input_graph, perturbation, Remove_Zero_Degree_Nodes=False):
+    """
+    This function modifies an input graph by removing nodes based on a specified perturbation.
+
+    Parameters:
+    - input_graph (networkx.Graph): The input graph to be perturbed.
+    - perturbation (List[List[int]]): A 2D list of 0/1 values indicating whether each node in the input graph should be removed (1) or not (0).
+    - Remove_Zero_Degree_Nodes (bool): Indicates whether nodes with zero degree should be removed (True) or not (False).
+
+    Returns:
+    - perturbed_node_graph_reordered (networkx.Graph): The perturbed graph with reordered node labels.
+
+    Raises:
+    - ValueError: If the length of `perturbation` does not match the number of nodes in `input_graph`.
+    """
+
+    if len(perturbation[0]) != len(input_graph.nodes):
+        raise ValueError("The length of `perturbation` must match the number of nodes in `input_graph`.")
+    
+    perturbed_node_graph = input_graph.copy()
+    ebun = []
+    for ii, nd in enumerate(perturbed_node_graph.nodes):
+        if perturbation[0][ii] == 1:
+            ebun.append(nd)
+    perturbed_node_graph.remove_nodes_from(ebun)
+
+    if Remove_Zero_Degree_Nodes:
+        Zdegree_nodes = []
+        for n, d in perturbed_node_graph.degree():
+            if d == 0:
+                Zdegree_nodes.append(n)
+
+        perturbed_node_graph.remove_nodes_from(Zdegree_nodes)
+
+    perturbed_node_graph_reordered = nx.convert_node_labels_to_integers(perturbed_node_graph, first_label=0)
+
+    return perturbed_node_graph_reordered
+  
+def perturb_graph_edge(input_graph, perturbation):
+    """
+    This function modifies an input graph by removing edges based on a specified perturbation.
+
+    Parameters:
+    - input_graph (networkx.Graph): The input graph to be perturbed.
+    - perturbation (List[int]): A list of 0/1 values indicating whether each edge in the input graph should be removed (1) or not (0).
+
+    Returns:
+    - perturbed_graph (networkx.Graph): The perturbed graph.
+
+    Raises:
+    - ValueError: If the length of `perturbation` does not match the number of edges in `input_graph`.
+    """
+
+    if len(perturbation) != len(input_graph.edges):
+        raise ValueError("The length of `perturbation` must match the number of edges in `input_graph`.")
+    
+    perturbed_graph = input_graph.copy()
+    ebun = []
+    for ii, ed in enumerate(perturbed_graph.edges):
+        if perturbation[ii] == 1:
+            ebun.append(ed)
+    perturbed_graph.remove_edges_from(ebun)
+    
+    return perturbed_graph
+
+  
+ def explain_graph_nodes(input_graph, model, num_perturbations=5000, kernel_width=0.25, num_top_features=10, epsilon=1, remove_zero_degree_nodes=False):
+    """
+    This function explains the contribution of each node to the prediction of a given graph-based model. 
+    It uses a white-box model interpretation method XWhy to calculate the contribution of each node by 
+    perturbing the input graph and measuring the change in the model's prediction.
+
+    Parameters:
+    input_graph (nx.Graph) : A networkx graph representing the input graph.
+    model (sklearn.BaseEstimator) : The graph-based model to be explained.
+    num_perturbations (int) : The number of perturbations to be applied to the input graph (default is 5000).
+    kernel_width (float) : The width of the kernel function (default is 0.25).
+    num_top_features (int) : The number of top features to be returned (default is 10).
+    epsilon (float) : The hyperparameter for the kernel function (default is 1).
+    remove_zero_degree_nodes (bool) : A flag indicating whether to remove nodes with zero degree after perturbation (default is False).
+
+    Returns:
+    coeff (np.ndarray) : The coefficients of the linear regression model that explains the relationship between the node perturbations and the change in prediction.
+    odds (np.ndarray) : The odds ratio of the linear regression model.
+    top_features (np.ndarray) : The indices of the top `num_top_features` features based on the absolute values of the coefficients.
+    bounded_coeff (np.ndarray) : The normalized coefficients of the linear regression model.
+    simpler_model (LinearRegression) : The linear regression model used to explain the relationship between the node perturbations and the change in prediction.
+    
+    Raises:
+    ValueError : If the number of perturbations is not a positive integer.
+    ValueError : If the kernel width is not positive.
+    ValueError : If the number of top features is not a positive integer.
+    ValueError : If the epsilon is not positive.
+    """
+    # Validate the input arguments
+    if not isinstance(num_perturbations, int) or num_perturbations <= 0:
+        raise ValueError("The number of perturbations must be a positive integer.")
+    if not isinstance(kernel_width, (int, float)) or kernel_width <= 0:
+        raise ValueError("The kernel width must be a positive number.")
+    if not isinstance(num_top_features, int) or num_top_features <= 0:
+        raise ValueError("The number of top features must be a positive integer.")
+    if not isinstance(epsilon, (int, float)) or epsilon <= 0:
+        raise ValueError("The epsilon must be a positive number.")  
+    
+    num_uniqe_nodes = len(X_input_graph.nodes)
+
+    perturbations = np.random.binomial(1, 0.5, size=(num_perturb, num_uniqe_nodes))
+        
+    predictions = []
+    WD_dist = []
+    for pert in perturbations:
+        p_graph = perturb_graph_node(X_input_graph, pert)
+        if len(p_graph.nodes) != 0:
+            pred = model.predict(graph_nets.utils_np.networkxs_to_graphs_tuple([p_graph]))
+            predictions.append(pred)
+            Sscore, WD_score = r_eigenv(X_input_graph, p_graph)
+            WD_dist.append(WD_score)
+
+    predictions = np.array(predictions)   
+    WD_dist = np.array(WD_dist) 
+    
+    weights = np.sqrt(np.exp(-((eps*WD_dist)**2)/kernel_width**2)) #Kernel function
+                
+    class_to_explain = 0
+    simpler_model = LinearRegression()
+    simpler_model.fit(X=perturbations, y=predictions, sample_weight=weights)
+    coeff = simpler_model.coef_[0]
+    
+    top_features = np.argsort(abs(coeff))[-num_top_features:] 
+    
+    coeff2 = simpler_model.coef_
+
+    odds = np.exp(coeff2)
+    
+    from sklearn.preprocessing import normalize
+
+    Bounded_coeff = normalize(coeff[:,np.newaxis], axis=0).ravel()
+    
+    return coeff, odds, top_features, Bounded_coeff, simpler_model 

xwhy-0.0.0.1/xwhy/smile_image.py

@@ -0,0 +1,127 @@
+import numpy as np
+import keras
+from keras.applications.imagenet_utils import decode_predictions
+import skimage.io 
+import skimage.segmentation
+import copy
+import sklearn
+import sklearn.metrics
+from sklearn.linear_model import LinearRegression
+
+def Wasserstein_Dist(XX, YY):
+  
+    '''
+    Wasserstein_Dist_PVal is for Wasserstein distance measure with Boostrap-based p-value calculation.
+    The p-Value can be used to validate statistical distance measures.
+    
+    XX: The first input vector. It should be a numpy array with length of n.
+    YY: The second input vector. It should be a numpy array with lenght of m.
+    '''
+  
+    import numpy as np
+    nx = len(XX)
+    ny = len(YY)
+    n = nx + ny
+
+    XY = np.concatenate([XX,YY])
+    X2 = np.concatenate([np.repeat(1/nx, nx), np.repeat(0, ny)])
+    Y2 = np.concatenate([np.repeat(0, nx), np.repeat(1/ny, ny)])
+
+    S_Ind = np.argsort(XY)
+    XY_Sorted = XY[S_Ind]
+    X2_Sorted = X2[S_Ind]
+    Y2_Sorted = Y2[S_Ind]
+
+    Res = 0
+    E_CDF = 0
+    F_CDF = 0
+    power = 1
+
+    for ii in range(0, n-2):
+        E_CDF = E_CDF + X2_Sorted[ii]
+        F_CDF = F_CDF + Y2_Sorted[ii]
+        height = abs(F_CDF-E_CDF)
+        width = XY_Sorted[ii+1] - XY_Sorted[ii]
+        Res = Res + (height ** power) * width;  
+ 
+    return Res
+
+def  Wasserstein_Dist_PVal(XX, YY):
+    # Information about Bootstrap: 
+    # https://towardsdatascience.com/an-introduction-to-the-bootstrap-method-58bcb51b4d60
+    import random
+    nboots = 1000
+    WD = Wasserstein_Dist(XX,YY)
+    na = len(XX)
+    nb = len(YY)
+    n = na + nb
+    comb = np.concatenate([XX,YY])
+    reps = 0
+    bigger = 0
+    for ii in range(1, nboots):
+        e = random.sample(range(n), na)
+        f = random.sample(range(n), nb)
+        boost_WD = Wasserstein_Dist(comb[e],comb[f]);
+        if (boost_WD > WD):
+            bigger = 1 + bigger
+            
+    pVal = bigger/nboots;
+
+    return pVal, WD
+
+def Wasserstein_Dist_Image(img1, img2):
+    if img1.shape[0] != img2.shape[0] or img1.shape[1] != img2.shape[1]:
+        print('input images should have the same size')
+    else:
+        WD = []
+        for ii in range(3):
+            
+            im1 = np.array(img1[:,:,ii].flatten())
+            im2 = np.array(img2[:,:,ii].flatten())
+
+            WD.append(Wasserstein_Dist(im1, im2))
+            
+    return sum(WD)
+  
+def xwhy_image2(X_input, model, perturbations, num_perturb = 150, kernel_width = 0.25):
+    
+    superpixels = skimage.segmentation.quickshift(X_input, kernel_size=4,max_dist=200, ratio=0.2)
+    num_superpixels = np.unique(superpixels).shape[0]
+    #perturbations = np.random.binomial(1, 0.5, size=(num_perturb, num_superpixels))
+    
+    
+    def perturb_image(img,perturbation,segments):
+        active_pixels = np.where(perturbation == 1)[0]
+        mask = np.zeros(segments.shape)
+        for active in active_pixels:
+              mask[segments == active] = 1 
+        perturbed_image = copy.deepcopy(img)
+        perturbed_image = perturbed_image*mask[:,:,np.newaxis]
+        return perturbed_image
+    
+    predictions = []
+    WD_dist = []
+    for pert in perturbations:
+        perturbed_img = perturb_image(X_input,pert,superpixels)
+        pred = model.predict(perturbed_img[np.newaxis,:,:,:])
+        predictions.append(pred)
+        WD_dist = Wasserstein_Dist_Image(X_input, perturbed_img)
+        
+
+    predictions = np.array(predictions)
+    
+    original_image = np.ones(num_superpixels)[np.newaxis,:] #Perturbation with all superpixels enabled 
+    # distances = sklearn.metrics.pairwise_distances(perturbations,original_image, metric='cosine').ravel()
+    
+    
+    weights = np.sqrt(np.exp(-(WD_dist**2)/kernel_width**2)) #Kernel function
+    
+    preds = model.predict(X_input[np.newaxis,:,:,:])
+    decode_predictions(preds)
+    top_pred_classes = preds[0].argsort()[-5:][::-1]
+    
+    class_to_explain = top_pred_classes[0]
+    simpler_model = LinearRegression()
+    simpler_model.fit(X=perturbations, y=predictions[:,:,class_to_explain], sample_weight=weights)
+    coeff = simpler_model.coef_[0]
+        

xwhy-0.0.0.1/xwhy/smile_quantum.py

@@ -0,0 +1 @@
+# reserved for future developement

xwhy-0.0.0.1/xwhy/smile_tabular.py

@@ -0,0 +1,153 @@
+import numpy as np
+import pandas as pd
+import sklearn
+import sklearn.metrics
+from sklearn.linear_model import LinearRegression
+from SafeML.Wasserstein_Dist_PVal import Wasserstein_Dist
+import SafeML 
+
+def WasserstainLIME2(X_input, model, num_perturb = 500, L_num_perturb = 100, kernel_width2 = 0.75, epsilon = 0.1):
+    '''
+    WasserstainLIME is a statistical version of LIME (local interpretable model-agnostic explanations) 
+    in which instead of Euclidean distance, the ECDF-based distance is used.
+    
+    X_input: should be a numpy array that represents one point in a n-dimensional space.
+    
+    num_perturb: Is the number of perturbations that the algorithm uses.
+    
+    L_num_perturb: Is the number of perturbations in the local areas that the algorithm uses.
+    
+    kernel_width: Is the Kernel Width. When the decision space is very dynamic, the kernel width should be low like 0.2, 
+    otherwise kernel with around 0.75 would be ideal.
+    
+    model: It is the trained model that can be for a classification or regression. 
+    
+    epsilon: It is used to normalize the WD values.
+    
+    '''
+    
+    X_input = (X_input - np.mean(X_input,axis=0)) / np.std(X_input,axis=0) #Standarization of data
+
+    X_lime = np.random.normal(0,1,size=(num_perturb,X_input.shape[0]))
+    
+    Xi2 = np.zeros((L_num_perturb,X_input.shape[0]))
+    
+    for jj in range(X_input.shape[0]):
+        Xi2[:,jj] = X_input[jj] + np.random.normal(0,0.05,L_num_perturb)
+
+    y_lime2  = np.zeros((num_perturb,1))
+    WD       = np.zeros((num_perturb,1))
+    weights2 = np.zeros((num_perturb,1))
+    
+    for ind, ii in enumerate(X_lime):
+        
+        df2 = pd.DataFrame()
+        
+        for jj in range(X_input.shape[0]):
+            temp1 = ii[jj] + np.random.normal(0,0.3,L_num_perturb)
+            df2[len(df2.columns)] = temp1
+
+        temp3 = model.predict(df2.to_numpy())
+
+        y_lime2[ind] = np.mean(temp3)  # For classification: np.argmax(np.bincount(temp3))
+        
+        WD1 = np.zeros((X_input.shape[0],1))
+        
+        df2 = df2.to_numpy()
+        
+        for kk in range(X_input.shape[0]):
+            #print( df2.shape)
+            WD1[kk] = Wasserstein_Dist(Xi2[:,kk], df2[:,kk])
+        
+        #print(WD1)
+        #print(ind)
+        WD[ind] = sum(WD1)
+        #print(WD)
+    
+        weights2[ind] = np.sqrt(np.exp(-((epsilon*WD[ind])**2)/(kernel_width2**2))) 
+        #print(weights2[ind])
+        
+        del df2
+    
+    weights2 = weights2.flatten()
+    #print(weights2)
+    
+    simpler_model2 = LinearRegression() 
+    simpler_model2.fit(X_lime, y_lime2, sample_weight=weights2)
+    y_linmodel2 = simpler_model2.predict(X_lime)
+    y_linmodel2 = y_linmodel2 < 0.5 #Conver to binary class
+    y_linmodel2 = y_linmodel2.flatten()
+    
+    return X_lime, y_lime2, weights2, y_linmodel2, simpler_model2.coef_.flatten()
+
+def WasserstainLIME(X_input, model, num_perturb = 500, kernel_width2 = 0.2):
+    
+    '''
+    WasserstainLIME(X_input, num_perturb = 500, kernel_width2 = 0.2):
+
+    X_input: The input feature data for the WassersteinLIME function. It should be a 1D numpy array with two elements.
+    
+    kernel_width2: The kernel width parameter for the Wasserstein distance calculation. It determines the size of the 
+                   region around the original feature data that is considered for the linear regression model. Larger 
+                   values of kernel_width2 result in a wider region and more perturbations being included in the explanation,
+                   while smaller values result in a more localized explanation. The default value is 0.2.
+
+    This function uses Wasserstein distance to generate local explanations for a binary classifier. 
+    It creates num_perturb number of perturbed versions of the input feature data, and for each perturbation 
+    it predicts the class probabilities, computes the Wasserstein distances between the original 
+    and perturbed feature data, and uses the distances to weight a linear regression model that explains the binary predictions. 
+    The function returns the perturbed feature data, binary predictions, weight of each perturbation, 
+    coefficients of the linear regression model, and the predictions of the linear regression model.
+    '''
+    
+    try:
+        if not isinstance(X_input, np.ndarray) or X_input.ndim != 2:
+            raise TypeError("X_input must be a 2-dimensional array.")
+    except TypeError as te:
+        print(te)
+    
+    try:
+        if not isinstance(num_perturb, int):
+            raise ValueError("num_perturb must be an integer.")
+    except ValueError as ve:
+        print(ve)
+        
+    try:
+        if not np.isscalar(kernel_width2):
+            raise ValueError("kernel_width2 must be a scalar.")
+    except ValueError as ve:
+        print(ve)
+    
+    X_lime = np.random.normal(0,1,size=(num_perturb,X_input.shape[1]))
+    
+    Xi2 = np.zeros((100,2))
+    Xi2[:,0] = X_input[0] + np.random.normal(0,0.05,100)
+    Xi2[:,1] = X_input[1] + np.random.normal(0,0.05,100)
+
+    y_lime2  = np.zeros((num_perturb,1))
+    WD       = np.zeros((num_perturb,1))
+    weights2 = np.zeros((num_perturb,1))
+
+    for ind, ii in enumerate(X_lime):
+        temp1 = ii[0] + np.random.normal(0,0.4,100)
+        temp2 = ii[1] + np.random.normal(0,0.4,100)
+        df2 = pd.DataFrame()
+        df2['x1'] = temp1
+        df2['x2'] = temp2
+        temp3 = model.predict(df2)
+        y_lime2[ind] = np.argmax(np.bincount(temp3))
+        WD1 = Wasserstein_Dist(Xi2[:,0], df2[:]['x1'])
+        WD2 = Wasserstein_Dist(Xi2[:,1], df2[:]['x2'])
+        WD[ind] = sum([WD1, WD2])
+    
+        weights2[ind] = np.sqrt(np.exp(-(WD[ind]**2)/(kernel_width2**2))) 
+    
+    weights2 = weights2.flatten()
+    
+    simpler_model2 = LinearRegression() 
+    simpler_model2.fit(X_lime, y_lime2, sample_weight=weights2)
+    y_linmodel2 = simpler_model2.predict(X_lime)
+    y_linmodel2 = y_linmodel2 < 0.5 #Conver to binary class
+    y_linmodel2 = y_linmodel2.flatten()
+    
+    return X_lime, y_lime2, weights2, y_linmodel2, simpler_model2.coef_.flatten()

xwhy-0.0.0.1/xwhy/smile_text.py

@@ -0,0 +1,128 @@
+import numpy as np
+
+import lime
+
+import numpy as np
+import pandas as pd
+import sklearn
+import sklearn.ensemble
+import sklearn.metrics
+#from __future__ import print_function
+
+import sklearn
+import sklearn.metrics
+from sklearn.linear_model import LinearRegression
+from sklearn.datasets import fetch_20newsgroups
+
+import string
+import re
+import nltk
+from nltk.tokenize import TweetTokenizer
+
+# embd = embedding_google
+
+def xwhy_text(X_input_text, model, perturbations, embd, num_perturb = 50, kernel_width = 0.25, num_top_features = 10, eps=0.5):
+    
+#     # NLP pre-processing
+#     # remove urls, handles, and the hashtag from hashtags 
+#     # (taken from https://stackoverflow.com/questions/8376691/how-to-remove-hashtag-user-link-of-a-tweet-using-regular-expression)
+#     def remove_urls(text):
+#         new_text = ' '.join(re.sub("(@[A-Za-z0-9]+)|([^0-9A-Za-z \t])|(\w+:\/\/\S+)"," ",text).split())
+#         return new_text
+
+#     # make all text lowercase
+#     def text_lowercase(text): 
+#         return text.lower()
+
+#     # remove numbers
+#     def remove_numbers(text): 
+#         result = re.sub(r'\d+', '', text) 
+#         return result
+
+#     # remove punctuation
+#     def remove_punctuation(text): 
+#         translator = str.maketrans('', '', string.punctuation)
+#         return text.translate(translator)
+
+#     # function for all pre-processing steps
+#     def preprocessing(text):
+#         text = text_lowercase(text)
+#         text = remove_urls(text)
+#         text = remove_numbers(text)
+#         text = remove_punctuation(text)
+#         return text
+
+#     # pre-processing the text body column
+#     pp_text = []
+#     for text_data in X_input_text:
+#         # check if string
+#         if isinstance(text_data, str):
+#             pp_text_data = preprocessing(text_data)
+#             pp_text.append(pp_text_data)
+#         # if not string
+#         else:
+#             pp_text.append(np.NaN)
+#     cleaned_words = clean_text(X_input_text)
+
+    wod = X_input_text.split()
+
+    wod = [word.strip('-.,!;()[]@><:') for word in wod]
+#     wod = [word.replace("'s", '') for word in wod]
+    wod = [word.replace(".", '') for word in wod]
+    wod = [word.replace("-", '') for word in wod]
+#     words = [word.replace(":", '') for word in words]
+#     words = [word.replace(">", '') for word in words]
+    
+
+    #finding unique
+    unique = []
+    for word in wod:
+        if word not in unique:
+            unique.append(word)
+
+    # Sorting the Unique Values
+    unique.sort()
+    
+    #num_perturb = 150
+    num_uniqe_words = len(wod)
+    perturbations = np.random.binomial(1, 0.5, size=(num_perturb, num_uniqe_words))
+    text_list = wod.copy()
+    
+    def perturb_text(text_list, perturbation):
+        for x, y in enumerate(text_list):
+            if perturbation[x] == 0:
+                text_list.remove(y)
+                
+    predictions = []
+    WD_dist = []
+    for pert in perturbations:
+        perturbed_text = perturb_text(text_list, pert)
+        pred = model.predict_proba([str(perturbed_text)])
+        predictions.append(pred)
+        WD_score = embd.wmdistance(str(wod), str(perturbed_text))
+        WD_dist.append(WD_score)
+
+    predictions = np.array(predictions)   
+    WD_dist = np.array(WD_dist) 
+    
+    weights = np.sqrt(np.exp(-((eps*WD_dist)**2)/kernel_width**2)) #Kernel function
+                
+    class_to_explain = 0
+    simpler_model = LinearRegression()
+    simpler_model.fit(X=perturbations, y=predictions[:,:, class_to_explain], sample_weight=weights)
+    coeff = simpler_model.coef_[0]
+    
+    print(coeff.shape)
+
+    coeff3 = coeff[0:50]
+    
+    num_top_features = 50
+    top_features = np.argsort(abs(coeff))[-num_top_features:] 
+    
+    coeff2 = simpler_model.coef_
+    
+    print(coeff3.shape)
+    # https://stackoverflow.com/questions/39626401/how-to-get-odds-ratios-and-other-related-features-with-scikit-learn
+    odds = np.exp(coeff2)
+     
+    return coeff3, coeff, odds, top_features, wod

xwhy-0.0.0.1/xwhy.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.1
+Name: xwhy
+Version: 0.0.0.1
+Summary: Explain Why (XWhy) with Statistical Model-agnostic Interpretability with Local Explanations (SMILE)
+Home-page: https://github.com/Dependable-Intelligent-Systems-Lab/xwhy
+Author: Mojgan Hashemian, Koorosh Aslansefat (corresponding), Mohammad Naveed Akram, Ioannis Sorokos, Martin Walker, Yiannis Papadopoulos
+Author-email: koo.ec2008@gmail.com
+License: BSD
+Description: UNKNOWN
+Platform: UNKNOWN
+Requires-Python: >=3.5
+Provides-Extra: dev

xwhy-0.0.0.1/xwhy.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+setup.cfg
+setup.py
+xwhy/__init__.py
+xwhy/datasets.py
+xwhy/smile_graph.py
+xwhy/smile_image.py
+xwhy/smile_quantum.py
+xwhy/smile_tabular.py
+xwhy/smile_text.py
+xwhy.egg-info/PKG-INFO
+xwhy.egg-info/SOURCES.txt
+xwhy.egg-info/dependency_links.txt
+xwhy.egg-info/not-zip-safe
+xwhy.egg-info/requires.txt
+xwhy.egg-info/top_level.txt

xwhy-0.0.0.1/xwhy.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xwhy-0.0.0.1/xwhy.egg-info/not-zip-safe

@@ -0,0 +1 @@
+

xwhy-0.0.0.1/xwhy.egg-info/requires.txt

@@ -0,0 +1,12 @@
+matplotlib
+numpy
+scipy
+tqdm>=4.29.1
+scikit-learn>=0.18
+scikit-image>=0.12
+pyDOE2==1.3.0
+twine==1.13.0
+
+[dev]
+pytest
+flake8

xwhy-0.0.0.1/xwhy.egg-info/top_level.txt

@@ -0,0 +1 @@
+xwhy