Package: dalex
dalexdalex: Responsible Machine Learning in PythonOverviewUnverified black box model is the path to the failure. Opaqueness leads to distrust. Distrust leads to ignoration. Ignoration leads to rejection.Thedalexpackage xrays any model and helps to explore and explain its behaviour, helps to understand how complex models are working.
The mainExplainerobject creates a wrapper around a predictive model. Wrapped models may then be explored and compared with a collection of model-level and predict-level explanations. Moreover, there are fairness methods and interactive exploration dashboards available to the user.The philosophy behinddalexexplanations is described in theExplanatory Model Analysisbook.InstallationThedalexpackage is available onPyPIandconda-forge.pip install dalex -Uconda install -c conda-forge dalexOne can install optional dependencies for all additional features usingpip install dalex[full].Resources:https://dalex.drwhy.ai/pythonAPI reference:https://dalex.drwhy.ai/python/apiAuthorsThe authors of thedalexpackage are:Hubert BanieckiWojciech KretowiczPiotr Piatyszekmaintains thearenamoduleJakub Wisniewskimaintains thefairnessmoduleMateusz Krzyzinskimaintains theaspectmoduleArtur Zolkowskimaintains theaspectmodulePrzemyslaw BiecekWe welcome contributions:start by opening an issue on GitHub.CitationIf you usedalex, please cite ourJMLR paper:@article{JMLR:v22:20-1473,
  author  = {Hubert Baniecki and
             Wojciech Kretowicz and
             Piotr Piatyszek and 
             Jakub Wisniewski and 
             Przemyslaw Biecek},
  title   = {dalex: Responsible Machine Learning 
             with Interactive Explainability and Fairness in Python},
  journal = {Journal of Machine Learning Research},
  year    = {2021},
  volume  = {22},
  number  = {214},
  pages   = {1-7},
  url     = {http://jmlr.org/papers/v22/20-1473.html}
}Changelogv1.7.0 (2024-02-28)increase the dependencies topython>=3.8,pandas>=1.5.0,numpy>=1.23.3and addpython==3.11to CIaddedkeras.src.models.sequential.Sequentialto classes with a knownpredict_function; it should fix changes inkeras==3.0.0andtensorflow==2.16.0turn offverbosein the predict method of tensorflow/keras models thatchangedintensorflow>=2.9.0update the warning occurring when specifyingvariable_splits(#558)fix an error occuring inpredict_profile()when a DataFrame has MultiIndex inpandas>=1.3.0(#550)fix gaussiannorm()calculation inmodel_profile()frompi*sqrt(2)tosqrt(2*pi)fix a warning (future error) betweenprepare_numerical_categorical()andprepare_x()withpandas==2.1.0fix a warning (future error) concerning the default value ofnumeric_onlyinpandas.DataFrame.corr()indalex.aspect.calculate_assoc_matrix()v1.6.0 (2023-02-16)addZeroDivisionErrorto precision and recall functions (#532)add a warning tocalculate_depend_matrix()when there is a variable with only one value (#537)fix missing EDA plots in (Python) Arena (#544)fix baseline positions in the subplots of the predict parts explanations: BreakDown, Shap (#545)v1.5.0 (2022-09-07)This release consists of mostly maintenance updates and, after a year, marks the Beta -> Stable release.increase the dependency frompython>=3.6topython>=3.7(at this moment, bothnumpyandpandasdepend onpython>=3.8), and addpython==3.10to CIincrease the dependencies topandas>=1.2.5,numpy>=1.20.3(#526),scipy>=1.6.3,plotly>=5.1.0, andtqdm>=4.61.2due to errors withpandas(seetqdm/#1199)remove the use ofpd.Series.append()(#489)remove the use ofnp.isnancausing error indalex.fairness(#491)fix iBreakDown plot y-axis labels (#493)stop the Arena'swerkzeugserver using a clearner and still supported API (#518)v1.4.1 (2021-11-08)featuresadded fairness plot for regression models toArena(dalex/#408)added newfacet_scalesparameter toAP.plotandCP.plot, which allows to free the y-axis withfacet_scales="free"(dalex/#469); consistent with R (DALEX/#468,ingredients/#140)fixesfixedAPandCPprogress barsv1.4.0 (2021-09-09)added newaspectmodule, which will focus on groups of dependent variables@krzyzinskim&@arturzolkowskiadded newscipy>=1.5.4dependencybreaking changesimproved the calculation of AUC, ROC plot (#459)fixeswrong yaxis labels inVariableImportance.plot(split="variable")(#451)repr_html()didn't work for explanation objects before using thefitmethod (#449)featuresadded newAspectobject with thepredict_triplot,model_triplot,predict_parts,model_parts,get_aspectsmethodsadded newPredictTriplot,ModelTriplot,PredictAspectImportance,ModelAspectImportanceobjects with theplotmethodv1.3.0 (2021-07-17)featuresadded bias mitigation techniques (resample,reweight,roc_pivot) into thefairnessmodule (#432)v1.2.0 (2021-05-31)breaking changesmethodset_optionsin Arena now takiesoption_categoryinstead ofplot_type(SHAPValues=>ShapleyValues,FeatureImportance=>VariableImportance) (#420)methods using theNparameter now properly sample rows fromdatafixesfixed wrong error value when nopredict_functionis found inExplainer(77ca90d)set multiprocessing context to'spawn'(#412)fixed bug inmetric_scoresplot that made only one subgroup appear on y-axis (#416)added support for older keras models (#415)featuresadded a resource mechanism to Arena (#419)addedShapleyValuesImportanceandShapleyValuesDependenceplots to Arena (#420)returnerrorinstead ofNaNwhen AUC is calculated on observations from one class only (#415)v1.1.0 (2021-04-18)breaking changesfixed concurrent random seeds whenprocesses > 1(#392), which means that the results of parallel computation will vary betweenv1.1.0and previous versionsfixesGroupFairnessX.plot(type='fairness_check')generates ticks according to the x-axis range (#409)GroupFainressRegression.plot(type='density')has a more readable hover - only for outliers (#409)BreakDown.plot()wrongly displayed the "+all factors" bar whenmax_vars < p(#401)GroupFairnessClassification.plot(type='metric_scores')did not handleNaN's (#399)featuresExperimental support for regression models in thefairnessmodule. AddedGroupFairnessRegressionobject, with theplotmethod having two types:fairness_checkanddensity.Explainer.model_fairnessmethod now depends on themodel_typeattribute. (#391)addedNparameter to thepredict_partsmethod which isNoneby default (#402)epsilonis now an argument of theGroupFairnessClassificationobject (#397)v1.0.1 (2021-02-19)fixesfixed broken range onyaxisinfairness_checkplot (#376)warnings becausenp.floatis depracated sincenumpyv1.20 (#384)otheraddedipythonto test dependenciesv1.0.0 (2020-12-29)breaking changesThese are summed up in (#368):rename modules:dataset_levelintomodel_explanations,instance_levelintopredict_explanations,_arenamodule intoarenause__dir__method to define autocompletion in IPython environment - show only['Explainer', 'Arena', 'fairness', 'datasets']addplotmethod andresultattribute toLimeExplanation(uselime.explanation.Explanation.as_pyplot_figure()andlime.explanation.Explanation.as_list())CeterisParibus.plot(variable_type='categorical')now has horizontal barplots -horizontal_spacing=Noneby default (varies onvariable_type). Also, once again added the "dot" for observation value.predict_fninpredict_surrogatenow usespredict_function(trying to make it work for more frameworks)fixesfixed wrong verbose output when any value iny_hat/residualswas anintnotfloatadded proper"-"sign to negative dropout losses inVariableImportance.plotfeaturesaddedgeom='bars'toAggregateProfiles.plotto force the categorical plotaddedgeom='roc'andgeom='lift'toModelPerformance.plotadded Fairness plot to ArenaotherremovecolorizefromExplainerupdated the documentation, refactored code (import modules not functions, unify variable names inobject.py, move utils funcitons fromchecks.pytoutils.py, etc.)added license notice next to datav0.4.1 (2020-12-03)added support forh2o.estimators.*(#332)addedtensorflow.python.keras.engine.functional.Functionalto thetensorflowlistupdated theplotlydependency to>=4.12.0code maintenance:yhat,check_datafixesfixedcheck_if_empty_fields()used in loading theExplainerfrom a pickle file, since several checks were changedfixedplot()method inGroupFairnessClassificationas it omitted plotting a metric whenNaNwas present in metric ratios (result)fixeddragonsandHRdatasets having,delimeter instead of., which transformed numerical columns into categorical.fixed representation of theShapWrapperclass (removed_repr_html_method)featuresallow foryto be apandas.DataFrame(converted)allow fordata,yto be aH2OFrame(converted)addedlabelparameter to all the relevantdx.Explainermethods, which overrides the default label in explanation'sresultnow usingGradientExplainerfortf.keras.engine.sequential.Sequential, added proper warning whenshap_explainer_typeisNone(#366)defaultsunify verbose output ofExplainerv0.4.0 (2020-11-17)added newarenamodule, which adds the backend for Arena dashboard@piotrpiatyszekfeaturesadded new aliases todx.Explainermethods (#350)
inmodel_partsit is{'permutational': 'variable_importance', 'feature_importance': 'variable_importance'},
inmodel_profileit is{'pdp': 'partial', 'ale': 'accumulated'}addedArenaobject for dashboard backend. Seehttps://github.com/ModelOriented/Arenanewfairnessplot types:stacked,radar,performance_and_fairness,heatmap,ceteris_paribus_cutoffupgradedfairness_check()v0.3.0 (2020-10-26)added newfairnessmodule, which will focus on bias detection, visualization and mitigation@jakwisnfixesremoved unnecessary warning whenprecalculate=False and verbose=False(#340)featuresaddedmodel_fairnessmethod to theExplainer, which performs fairness explanationaddedGroupFairnessClassificationobject, with theplotmethod having two types:fairness_checkandmetric_scoresdefaultsadded theN=50000argument toResidualDiagnostics.plot, which samples observations from
theresultparameter to omit performance issues whensmooth=True(#341)v0.2.2 (2020-09-21)added support fortensorflow.python.keras.engine.sequential.Sequentialandtensorflow.python.keras.engine.training.Model(#326)updated thetqdmdependency to>=4.48.2,pandasdependency to>=1.1.2andnumpydependency to>=1.18.4fixesfixed the wrong order ofExplainerverbose messagesfixed a bug that causedmodel_infoparameter to be overwritten by the default valuesfixed a bug occurring when the variable fromgroupswas not ofstrtype (#327)fixedmodel_profile:variable_type='categorical'not working when user passedvariablesparameter (#329) +
the reverse order of bars in'categorical'plots + (again) addedvariable_splits_typeparameter tomodel_profileto specify how grid points
shall be calculated (#266) + allow for both'quantile'and'quantiles'types (alias)featuresadded informative error messages when importing optional dependencies (#316)allow fordataandyto beNone- added checks inExplainermethodsdefaultswrong parameter nametitle_xchanged toy_titleinCeterisParibus.plotandAggregatedProfiles.plot(#317)now warning the user inExplainerwhenpredict_functionreturns an error or doesn't returnnumpy.ndarray (1d)(#325)v0.2.1 (2020-08-31)updated thepandasdependency to>=1.1.0fixesModelPerformance.plotnow uses a drwhy color paletteuseuniquemethod instead ofnp.uniqueinvariable_splits(#293)v0.2.0didn't export new datasetsfixed a bug wherepredict_parts(type='shap')calculated wrongcontributions(#300)model_profileuses observation mean instead of profile mean in_yhat_centeringfixed barplot baseline in categoricalmodel_profileandpredict_profileplots
(#297)fixedmodel_profile(type='accumulated')giving wrong results
(#302)vertical/horizontal lines in plots now end on the plot edgesfeaturesadded newtype='shap_wrapper'topredict_partsandmodel_partsmethods, which returns a newShapWrapperobject. It contains the main result attribute (shapley_values) and the plot method
(force_plotandsummary_plotrespectively). These come from theshappackageExplainer.predictmethod now acceptsnumpy.ndarrayadded theResidualDiagnosticsobject with aplotmethodaddedmodel_diagnosticsmethod to theExplainer, which performs residual diagnosticsaddedpredict_surrogatemethod to theExplainer, which is a wrapper for thelimetabular explanation from thelimepackageaddedmodel_surrogatemethod to theExplainer, which creates a basic surrogate decision tree
or linear model from the black-box model using thescikit-learnpackageadded a_repr_html_method to all of the explanation objects (it prints theresultattribute)addeddalex.__version__added informative error messages inExplainermethods whenyis of wrong type
(#294)CeterisParibus.plot(variable_type='categorical')now allows for multiple observationsnew verbose checks formodel_typeaddtypetomodel_infoindumpanddumpsfor R compatibility
(#303)ModelPerformance.resultnow haslabelas indexdefaultsremoved_grid_column inAggregatedProfiles.resultandcenteronly works withtype=accumulatedusePipeline._final_estimatorto extractmodel_classof the actual modelusemodel._estimator_typeto extractmodel_typeif possiblev0.2.0 (2020-08-07)major documentation update (#270)unified the order of function parametersfixesv0.1.9had wrong_original_column inpredict_profilevertical_spacingacts as intended inVariableImportance.plotwhensplit='variable'loss_function='auc'now usesloss_one_minus_aucas this should be a descending measureplots are now saved with the original height and widthmodel_profilenow properly passes thevariablesparameter toCeterisParibusvariablesparameter inpredict_profilenow can also be a stringfeaturesusepx.expressinstead of coreplotlyto makemodel_profileandpredict_profileplots;
thus, enhance performance and scalabilityaddedverboseparameter wheretqdmis used to verbose progress baraddedloss_one_minus_aucfunction that can be used withloss_function='1-auc'inmodel_partsadded new example data sets:apartments,dragonsandhraddedcolor,opacity,title_xparameters tomodel_profileandpredict_profileplots (#236),
changed tooltips and legends (#262)addedgeom='profiles'parameter tomodel_profileplot andraw_profilesattribute toAggregatedProfilesaddedvariable_splits_typeparameter topredict_profileto specify how grid points
shall be calculated (#266)addedvariable_splits_with_obsparameter topredict_profilefunction to extend split points with observation
variable values (#269)addedvariable_splitsparameter tomodel_profiledefaultsuse differentloss_functionfor classification and regression (#248)models that useprobayhats now getmodel_type='classification'if it's not specifieduse uniform way of grid points calculation inpredict_profileandmodel_profile(seevariable_splits_typeparameter)add the variable values ofnew_observationtovariable_splitsinpredict_profile(seevariable_splits_with_obsparameter)useN=1000inmodel_partsandN=300inmodel_profileto comply with the R versionkeep_raw_permutationis now set toFalseinstead ofNoneinmodel_partsinterceptparameter inmodel_profileis now namedcenterv0.1.9 (2020-07-01)feature:addedrandom_stateparameter forpredict_parts(type='shap')andmodel_profilefor reproducible calculationsfix:fixedrandom_stateparameter inmodel_partsfeature:multiprocessing added for:model_profile,model_parts,predict_profileandpredict_parts(type='shap'), through theprocessesparameterfix:significantly improved the speed ofaccumulatedandconditionaltypes inmodel_profilebugfix:usepd.api.types.is_numeric_dtype()instead ofnp.issubdtype()to cover more types; e.g. it caused errors withstringtypedefaults:usepd.convert_dtypes()on the result ofCeterisParibusto fix variable dtypes and
later allow for a concatenation without the dtype conversionfix:variablesparameter now can be a singlestrvaluefix:number rounding inpredict_parts,model_parts(#245)fix:CP calculations for models that take only variables as an inputv0.1.8 (2020-05-28)bugfix:variable_splitsparameter now works correctly inpredict_profilebugfix:fix baseline for 3+ models inAggregatedProfiles.plot(#234)printing:now rounding numbers inExplainermessagesfix:minor checks fixes ininstance_levelbugfix:AggregatedProfiles.plotnow works withgroupsv0.1.7 (2020-05-10)feature:parameterNinmodel_profilecan be set toNone, to select all observationsinput:groupsandvariableparameters inmodel_profilecan be:str,list,numpy.ndarray,pandas.Seriesfix:check_labelreturned only a first letterbugfix:removed the conversion ofall_variablestostrinprepare_all_variables, which caused an error inmodel_profile(#214)defaults:change numpy data variable names from numbers to stringsv0.1.6 (2020-04-30)fix:changeshort_nameencoding infifadataset (utf8->ascii)fix:removescipydependencydefaults:defaultloss_root_mean_squarein model parts changed tormsebugfix:checks related tonew_observationinBreakDown, Shap, CeterisParibusnow work for multiple inputs
(#207)bugfix:CeterisParibus.fitandCeterisParibus.plotnow work for
more types ofnew_observation.index, but won't work for aboleantype
(#211)v0.1.5 (2020-04-21)feature:addxgboostpackage compatibility (#188)feature:addedmodel_classparameter toExplainerto handle wrapped
modelsfeature:Exaplainerattributemodel_inforemembers if parameters are defaultbugfix:variable_groupsparameter now works correctly inmodel_partsfix:changed parameter order inExplainer:model_type,model_info,colorizedocumentation:model_partsdocumentation is updatedfeature:newshowparameter inplotmethods that (if False) returnsplotly Figure(#190)feature:load_fifa()function which loads the preprocessedplayers_20
datasetfix:CeterisParibus.plottooltipv0.1.4 (2020-04-14)feature:newExplainer.residualmethod which usesresidual_functionto calculateresidualsfeature:newdumpanddumpsmethods for savingExplainerin a binary form;loadandloadsmethods for loadingExplainerfrom binary formfix:Explainerconstructor verbose textbugfix:B:=B+1-Shapnow stores average results asB=0and path results asB=1,2,...bugfix:Explainer.model_performancemethod usesself.model_typewhenmodel_typeisNonebugfix:values inBreakDownandShapare now rounded to 4 significant
places (#180)bugfix:Shapby default usespath='average',signcolumn is
properly updated and bars inplotare sorted byabs(contribution)v0.1.3 (2020-04-10)releaseof thedalexpackageExplainerobject withpredict,predict_parts,predict_profile,model_performance,model_partsandmodel_profilemethodsBreakDown,Shap,CeterisParibus,ModelPerformance,VariableImportanceandAggregatedProfilesobjects with aplotmethodload_titanic()function which loads thetitanic_imputeddataset