Package: smace
SMACE --- Semi-Model-Agnostic Contextual ExplainerPython code forSMACE: A New Method for the Interpretability of Composite Decision Systems.The code is stored in two main repositories:smaceandevaluation. The first one contains the code behind the method (see below forUsage).
Theevaluationfolder contains anotebookssubfolder, where some simple example are given asJupyter Notebook.
Aggregated experiments are in theexperimentsfolder and the results saved in theresultssubfolder.EvaluationThe experiments in Section5.1 Simple casesof the paper are available as notebooks (inevaluation/notebooks) :rule_only.ipynbrefers toRules onlyhybrid_paper.ipynbrefers toSymple hybrid systemThe folder also contains additional experiments.The experiment in Section5.2 Realistic use caseof the paper is generated bytelco.pyinevaluation/experiments. The folder contains additional experiments with different decision-making systems on synthetic data.
These experiments should be performed individually, and when finished, the results will be available in the directoryevaluation/experiments/results.UsageFirst,  one must define the decision-making system,i.e.,  aDMobject.  To define it,  you need a set of rules in JSON format,  a list of models,  and apandas DataFrame.1. Define your set of rulesThe rules must be defined in a JSON object,  resulting in Python lists/dictionaries.  Eachruleis a dictionary with two fields:conditionsanddecision.  The latter is the output of the decision process,  if the rule is satisfied.  A condition is defined by the triple(name, operator, value):nameis the variable referred to;operatorcan begeq($\geq$),gt($>$),leq($\leq$),lt($<$);valueis the cutoff.As an example,  let us say our set of variables includes four features:  $x_1$,  $x_2$,  $x_3$,  $x_4$,  and two models:model_1andmodel_2.  The JSON with two rulesrule1andrule2can be as follow:{"rule1": {"conditions": [{"name": "x2",
                             "operator": "geq",
                             "value": 0.6},
                            {"name": "x3",
                             "operator": "geq",
                             "value": 0.25},
                            {"name": "model_1",
                             "operator": "geq",
                             "value": 1},
                            {"name": "model_2",
                             "operator": "leq",
                             "value": 50}],
            "decision": "decision1"},
"rule2": {"conditions": [{"name": "x4",
                             "operator": "geq",
                             "value": 0.1},
                            {"name": "model_1",
                             "operator": "geq",
                             "value": 0.2},
                            {"name": "x1",
                             "operator": "geq",
                             "value": 0.1},
                            {"name": "x4",
                             "operator": "leq",
                             "value": 0.9}],
            "decision": "decision2"}
}Once defined,  to read a JSON file one can use thejson(docs here)  to read it:import json
with open('rules.json', 'r') as fp:
    rules_json = json.load(fp)2. Define your list of modelsA model can be any function that works on a subset of the original data,  with a numerical output.DMneeds aModelobject initialized asModel(predictive_function, model_name, data),  wherepredictive_functionis the function that produces the output. In the case of asklearnmodelmfor regression (resp., for classification), for instance, it corresponds tom.predict(resp.,m.predict_proba);model_nameis the name used in the rules to refer to the output of the model;datais thepandas.DataFrameto which the model is applied.For example,  assuming we have a datasetXand two targetsy1andy2,  we can proceed as follows:from smace.models import Model

lm = linear_model.LinearRegression()
lm.fit(X,y1)

xgb = xgboost.XGBClassifier()
xgb.fit(X,y2)

model_1 = Model(lm.predict, 'model_1', df)
model_2 = Model(xgb.predict_proba, 'model_2', df)

models_list = [model_1, model_2]3. Define theDMobjectHaving the rulesrules_json,  the list of modelsmodels_listand the input datasetdf,  you can construct theDMobject asfrom smace.decisions import DM
dm = DM(rules_json, models_list, df)To get the decision explicitly for an example,  we use themake_decision()function:example = np.random.rand(4)
decision = dm.make_decision(example, verbose=True)Output:
    Rule(s) ['rule1'] triggered.
    Decision(s) ['decision1'] made.Apply SMACEOnce the configuration is complete,  you can use SMACE to explain the decisions of the defined system.Let us say we want to explain why for the example aboverule2was not triggered:from smace.explainer import Smace
explainer = Smace(dm)

explanation = explainer.explain(example, 'rule2')explanationcontains all the information computed by SMACE.  The following methods can be applied:explanation.table()andexplanation.bar()to obtain the overall contributions of the input features as tables or bars, respectively;explanation.rule_table()andexplanation.rule_bar()to get the contributions of all variables in the rule as tables or bars, respectively;explanation.model_table('mod')andexplanation.model_bar('mod')to get the importance of input features to the model named'mod'.It is possible to specify the maximum number of variables to display through thenum_featuresparameters.