Package: acv-dev
Active Coalition of Variables (ACV):ACV is a python library that aims to explainany machine learning modelsordata.It giveslocal rule-basedexplanations for any model or data.It providesa better estimation of Shapley Values for tree-based model(more accurate thanpath-dependent TreeSHAP).
It also proposes new Shapley Values that have better local fidelity.and thecorrect way of computing Shapley Values of categorical variables after encoding
(eg., One Hot or Dummy, etc.)We can regroup the different explanations in two groups:Agnostic ExplanationsandTree-based Explanations.See the papershere.InstallationRequirementsPython 3.7-3.9OSX: ACV uses Cython extensions that need to be compiled with multi-threading support enabled.
The default Apple Clang compiler does not support OpenMP.
To solve this issue, obtain the lastest gcc version with Homebrew that has multi-threading enabled:
see for examplepysteps installation for OSX.Windows: Install MinGW (a Windows distribution of gcc) or Microsoft’s Visual CInstall the acv package:$ pip install acv-expA. Agnostic explanationsThe Agnostic approaches explain any data (X,Y) or model (X,f(X)) using the following
explanation methods:Same Decision Probability (SDP) andSufficient ExplanationsSufficient RulesSee the paperConsistent Sufficient Explanations and Minimal Local Rules for explaining regression and classification modelsfor more details.I. First, we need to fit our explainer (ACXplainers) to input-output of the data(X, Y)or model(X, f(X))if we want to explain the data or the model respectively.fromacv_explainersimportACXplainer# It has the same params as a Random Forest, and it should be tuned to maximize the performance.acv_xplainer=ACXplainer(classifier=True,n_estimators=50,max_depth=5)acv_xplainer.fit(X_train,y_train)roc=roc_auc_score(acv_xplainer.predict(X_test),y_test)II. Then, we can load all the explanations in a webApp as follow:importacv_appimportos# compile the ACXplaineracv_app.compile_ACXplainers(acv_xplainer,X_train,y_train,X_test,y_test,path=os.getcwd())# Launch the webAppacv_app.run_webapp(pickle_path=os.getcwd())III. Or we can compute each explanation separately as follow:Same Decision Probability (SDP)The main tool of our explanations is the Same Decision Probability (SDP). Given, the same decision probabilityof variablesis the probabilty that the prediction remains the same when we fixed variablesor when the variablesare missing.How to compute?sdp=acv_xplainer.compute_sdp_rf(X,S,data_bground)# data_bground is the background dataset that is used for the estimation. It should be the training samples.Minimal Sufficient ExplanationsThe Sufficient Explanations is the Minimal Subset S such that fixing the valuespermit to maintain the prediction with high probability.
See the paperherefor more details.How to compute the Minimal Sufficient Explanation?The following code return the Sufficient Explanation with minimal cardinality.sdp_importance,min_sufficient_expl,size,sdp=acv_xplainer.importance_sdp_rf(X,y,X_train,y_train,pi_level=0.9)How to compute all the Sufficient Explanations  ?Since the Minimal Sufficient Explanation may not be unique for a given instance, we can compute all of them.sufficient_expl,sdp_expl,sdp_global=acv_xplainer.sufficient_expl_rf(X,y,X_train,y_train,pi_level=0.9)Local Explanatory ImportanceFor a given instance, the local explanatory importance of each variable corresponds to the frequency of
apparition of the given variable in the Sufficient Explanations. See the paperherefor more details.How to compute the Local Explanatory Importance ?lximp=acv_xplainer.compute_local_sdp(d=X_train.shape[1],sufficient_expl)Local rule-based explanationsFor a given instance(x, y)and its Sufficient Explanation S such that, we compute a local minimal rule which containsxsuch
that every observationzthat satisfies this rule has. See the paperherefor more detailsHow to compute the local rule explanations ?sdp,rules,_,_,_=acv_xplainer.compute_sdp_maxrules(X,y,data_bground,y_bground,S)# data_bground is the background dataset that is used for the estimation. It should be the training samples.B. Tree-based explanationsACV gives Shapley Values explanations for XGBoost, LightGBM, CatBoostClassifier, scikit-learn and pyspark tree models. It
provides the following  Shapley Values:Classic local Shapley Values (The value function is the conditional expectation)Active Shapley values (Local fidelity and Sparse by design)Swing Shapley Values (The Shapley values are interpretable by design)(Coming soon)In addition, we use the coalitional version of SVto properly handle categorical variables in the computation of SV.See the papershereTo explain the tree-based models above, we need to transform our model into ACVTree.fromacv_explainersimportACVTreeforest=XGBClassifier()# or any Tree Based models#...trained the modelacvtree=ACVTree(forest,data_bground)# data_bground is the background dataset that is used for the estimation. It should be the training samples.Accurate Shapley Valuessv=acvtree.shap_values(X)Note that it provides a better estimation of thetree-path dependent of TreeSHAPwhen the variables are dependent.Accurate Shapley Values with encoded categorical variablesLet assume we have a categorical variable Y with k modalities that we encoded by introducing the dummy variables. As shown in the paper, we must take the coalition of the dummy variables to correctly compute the Shapley values.# cat_index := list[list[int]] that contains the column indices of the dummies or one-hot variables grouped# together for each variable. For example, if we have only 2 categorical variables Y, Z# transformed into [Y_0, Y_1, Y_2] and [Z_0, Z_1, Z_2]cat_index=[[0,1,2],[3,4,5]]forest_sv=acvtree.shap_values(X,C=cat_index)In addition, we can compute the SV given any coalitions. For example, let assume we have 10 variablesand we want the following coalitioncoalition=[[0,1,2],[3,4],[5,6]]forest_sv=acvtree.shap_values(X,C=coalition)How to computefor tree-based classifier ?Recall that theis the probability that the prediction remains the same when we fixed variablesgiven the subset S.sdp=acvtree.compute_sdp_clf(X,S,data_bground)# data_bground is the background dataset that is used for the estimation. It should be the training samples.How to compute the Sufficient Coalitionand the Global SDP importance for tree-based classifier ?Recall that the Minimal Sufficient Explanations is the Minimal Subset S such that fixing the valuespermit to maintain the prediction with high probability.sdp_importance,sdp_index,size,sdp=acvtree.importance_sdp_clf(X,data_bground)# data_bground is the background dataset that is used for the estimation. It should be the training samples.Active Shapley valuesThe Active Shapley values is a SV based on a new game defined in the Paper (Accurate and robust Shapley Values for explaining predictions and focusing on local important variablessuch that null (non-important) variables has zero SV and the "payout" is fairly distribute among active variables.How to compute Active Shapley values ?importacv_explainers# First, we need to compute the Active and Null coalitionsdp_importance,sdp_index,size,sdp=acvtree.importance_sdp_clf(X,data_bground)S_star,N_star=acv_explainers.utils.get_active_null_coalition_list(sdp_index,size)# Then, we used the active coalition found to compute the Active Shapley values.forest_asv_adap=acvtree.shap_values_acv_adap(X,C,S_star,N_star,size)Remarks for tree-based explanations:If you don't want to use multi-threaded (due to scaling or memory problem), you have to add "_nopa" to each function (e.g. compute_sdp_clf ==> compute_sdp_clf_nopa).
You can also compute the different values needed in cache by setting cache=True
in ACVTree initialization e.g. ACVTree(model, data_bground, cache=True).Examples and tutorials (a lot more to come...)We can find a tutorial of the usages of ACV indemo_acvand
the notebooks below demonstrate different use cases for ACV. Look inside the notebook directory of the repository if you want to try playing with the original notebooks yourself.