ӆhȒJSSKJr SSKrSSKrSSKJrJr SSKJrJ r J r SSK r SSK rSSKrSSKrSSKrSSKrSSKJrJrJr SSKJr SSKJr SS KJr \"S 5r\"S S 55r"S S\ 5r!"SS\!S9r"SSjr#SSjr$Sr%SSjr&"SS5r'SSjr(Sr)g)) annotationsN) dataclassfield)AnyCallablecast)AliasObjSlicer)hclust_ordering)DimensionError)OpChainzshap.Explanationc`\rSrSr%SrS\S'S\S'SrS\S '\"\S 9r S \S 'S r S\S'Sr g) OpHistoryItemzS?S1jjr+S@S;S2jjr,SASBS3jjr-SCSDS4jjr.SES5jr/SFS6jr0SGS7jr1S8r2S9r3g)H Explanation[aHA sliceable set of parallel arrays representing a SHAP explanation. Notes ----- The *instance* methods such as `.max()` return new Explanation objects with the operation applied. The *class* methods such as `Explanation.max` return OpChain objects that represent a set of dot chained operations without actually running them. Nc:/UlXl[U[5(a&UnURnUR nUR n[XX75Ul[U5nUcS[UR5S:Xa:UURSnUcS5e[U5Vs/sHnSU3PM nn[[U55S:Xam[U5S:a([U5US:Xa[[U5S5nO6[U5S:a'[U5US:Xa[[U5S5n[[U55S:Xa"[[U5URS5nUb[U[5(dl[[U55nUS:XaOQUS:Xa[XpR5nO5US:Xa$[US/[UR5-5nO [S5e[!US5(a[U5S:XaOn[[U55[UR5:Xa [U[UR55nO#[US/[UR5-5n[#UU[%U5[%U5UcSO [US5UUUcSO URU4[%U 5[%U 5[%U 5[%U 5[%U 5UcSO [US/5S9Ulgs snf) Nr rzUnexpected shape of valueszOutput zKshap.Explanation does not yet support output_names of order greater than 3!__len__values base_valuesdata display_datainstance_names feature_names output_namesoutput_indexes lower_bounds upper_bounds error_std main_effectshierarchical_values clustering) op_history compute_time isinstancerVr\r]r^compute_output_dims output_dims_compute_shapelenranger listr ValueErrorhasattrr list_wrap_s)selfr\r]r^r_r`rarbrcrdrerfrgrhrirke values_shape num_namesioutput_names_orders r&__init__Explanation.__init__gs$02( fk * *AXXF--K66D.vDW%f-  C(8(8$9Q$>$T%5%5a%89I( F*F F(383CD3CagaSM3CLD }- .! 3< A%#m*< Q*O %d=&91 = \"a'C ,>,q/,Q %d=&91 =  |, - 2 l!3T5E5Ea5HIL  #J|U,K,K!$^L%A!B !Q&#q("<1A1AB #q(")1ts:s7K KEs*Lc.URR$z/Pass-through from the underlying slicer object.rvr\rws r&r\Explanation.valuessww~~r%c$XRlgr+r)rw new_valuess r&r\rs #r%c.URR$rrvr]rs r&r]Explanation.base_valuessww"""r%c$XRlgr+r)rwnew_base_valuess r&r]rs -r%c.URR$rrvr^rs r&r^Explanation.datasww||r%c$XRlgr+r)rwnew_datas r&r^rs  r%c.URR$r)rvr_rs r&r_Explanation.display_dataww###r%cz[U[R5(a URnXRlgr+)rlpd DataFramer\rvr_)rwnew_display_datas r&r_rs* & 5 5/66 /r%c.URR$r)rvr`rs r&r`Explanation.instance_namesww%%%r%c.URR$rrvrbrs r&rbExplanation.output_namesrr%c$XRlgr+r)rwnew_output_namess r&rbr /r%c.URR$r)rvrcrs r&rcExplanation.output_indexesrr%c.URR$rrvrars r&raExplanation.feature_namessww$$$r%c$XRlgr+r)rwnew_feature_namess r&rars 1r%c.URR$r)rvrdrs r&rdExplanation.lower_boundsrr%c.URR$r)rvrers r&reExplanation.upper_bounds rr%c.URR$r)rvrfrs r&rfExplanation.error_stdsww   r%c.URR$rrvrgrs r&rgExplanation.main_effectsrr%c$XRlgr+r)rwnew_main_effectss r&rgrrr%c.URR$rrvrhrs r&rhExplanation.hierarchical_valuessww***r%c$XRlgr+r)rwnew_hierarchical_valuess r&rhr!s &=#r%c.URR$rrvrirs r&riExplanation.clustering%sww!!!r%c$XRlgr+r)rwnew_clusterings r&rir*s +r%cSUR<3nURbUSUR<3- nURbUSUR<3- nU$)z6Display some basic printable info, but not everything.z .values = z .base_values = z .data = )r\r]r^)rwouts r&__repr__Explanation.__repr__/s[DKK?+    ' )$*:*:)=> >C 99 ]499-0 0C r%c Sn[U[5(dU4nSnUGH<nUS- nU[La&U[UR5[U5- - nM8Un[U[ 5(aUR U5n[U[R[R45(a [U5nGO&[U[R5(aUVs/sHn[U5PM nnGO[U[5(aURnGO[U[5(Ga/nSURR ;a$URR SR"nO=SURR$;a#URR$SR"nUS:wGa*X7;Ga$[U5S:Xa?[R&"[R("UR*5U:H5SSnGO[U5S:XGa/n/n /n [,R."U5n[1UR5Hup[1UR*U 5HupX:XdM UR3[R("USS2U 455 U R3[R("UR4U 55 U R3UR6U U 5 M M [[R("U5[R("U 5[R("U 5UR8UR:[R("U 5UUR<UR>UR@URBURDURFURHS9n[,R,"URJ5Ul%/nSURR ;a#URR SR"nUS:waX>;a[U5S:Xa/n/n [1UR5H^up[MURNU XR4U 5H/upnX:XdM UR3U5 U R3U5 M1 M` [,R."U5nXl XlXBl'SUl$[U[RP[RR[R[R45(a [U5nXELdGM![UU5nUUU'[U5nGM? [S U55n[U5S:XaU$Uc[,R,"U5nURRWU5UlURJR3[YS U4URS 95 U$s snf) z'This adds support for OpChain indexing.Nr rbrrY r]r^r_r`rarbrcrdrerfrgrhrirac3$# UHov M g7fr+r).0vs r& *Explanation.__getitem__..s%1Qsr-rrr)-rltupleEllipsisrpshaperapplynpint64int32intndarrayrVr\rrv_objectsdim_aliasesargwherearrayrbcopydeepcopy enumerateappendr^r]r_r`rcrdrerfrgrhrirjzipraint8int16rrr-r)rwr/new_selfpostorig_troutput_names_dimsrrrr{jsfeature_names_dimsval_idtmps r&r-Explanation.__getitem__8s$&&7DA 1HCH}s4::T22F!W%%GGDMa"((BHH!566AA2::..)*+AQA+A{++HHAs##$&!!TWW%5%55(,(8(8(H(L(L%#tww'7'77(,(8(8(H(L(L%!8 8,-2KK1B1B(Cq(HI!LQO./14%' *,#%#'==#6$-dkk$:DA(1$2C2CA2F(G#$6$.$5$5bhhqAw6G$H$,OOBHHTYYq\4J$K$3$:$:4;K;KA;Nq;Q$R )H%;$/HHZ0(*(A!#(!3)-):):+/+>+>*,((8*<)*+/+>+>)-):):)-):):&*nn)-):):040H0H'+$ /3ii.H+&(""dgg&6&66)-)9)9/)J)N)N&!8 9cBT>UYZ>Z!#J!H$-dkk$:'*4+=+=a+@%ST'VGA! v * 1 1! 4 ( 2(W%; $}}T2H&0O$,M-.**.H'!bggrxx288DEEF4jCSzsx%%% t9>O  yyHkk--d3 ""=m4'^b^h^h#ijm,sW-cX[URR5n[SU5$)z8Compute the shape over potentially complex data nesting.r)rorvr\r)rwshap_values_shapes r&rExplanation.shapes(+477>>:%'899r%c URS$Nr)rrs r&rZExplanation.__len__szz!}r%c[URURURURUR UR URURURURURURURURS9n[R"UR 5UlU$)Nr)rVr\r]r^r_r`rarbrcrdrerfrgrhrirrj)rwnew_exps r&__copy__Explanation.__copy__s KK((**..,,**..****nn** $ 8 8  "YYt7r%ctUR5nURR[X14URS95 [ U[ 5(aU"URUR5UlURb"U"URUR5UlURb"U"URUR5Ul U$U"URU5UlURbU"URU5UlURbU"URU5Ul U$)Nr) rrjrrrrlrVr\r^r])rwother binary_opop_namers r&_apply_binary_operator"Explanation._apply_binary_operators--/!!-W8X\XbXb"cd e[ ) )&w~~u||DGN||'(uzzB "".&/0C0CUEVEV&W# 'w~~u=GN||'(u= "".&/0C0CU&K#r%cDURU[RS5$N__add__roperatoraddrwrs r&rExplanation.__add__**5(,, JJr%cDURU[RS5$rrrs r&__radd__Explanation.__radd__rr%cDURU[RS5$N__sub__rrsubrs r&rExplanation.__sub__rr%cDURU[RS5$rr rs r&__rsub__Explanation.__rsub__rr%cDURU[RS5$N__mul__rrmulrs r&rExplanation.__mul__rr%cDURU[RS5$rrrs r&__rmul__Explanation.__rmul__rr%cDURU[RS5$)N __truediv__)rrtruedivrs r&rExplanation.__truediv__s**5(2B2BMRRr%c [R"U5nURSS5nUS;aX4nURSSUlURb[ UR5(dUS:XaUR 5n[ R"[UR555Ul[ R"UR5Vs/sHn[[ U5"US5PM sn5Ul SUl GO [[ U5"[ R"UR540UD6Ul URb;[[ U5"[ R"UR540UD6Ul URb_[!U["5(aJ[%URR&5U:a'[[ U5"UR40UD6UlO[!U["5(aSUlUS:XayURbl[%URR&5S:XaIURR)S5R+5S:aURSUl OSUl URR-[/UUUR&US:HS95 U$s snf![a SUl GNTf=f) z1Apply a numpy-style function to this Explanation.axisN)rr rYrrg:0yE>)rrrr)rgetrjrais_1d_flatten_feature_namesrrrrkeysr\getattrrir^ Exceptionr]rlrrprstdrArr)rwfnamerrrrrs r& _numpy_funcExplanation._numpy_funcsK99T?zz&$' 9 ~H"*"5"5cr":H     )%8J8J2K2KPTXYPY446J%'XXd:??3D.E%FH " hh*J[J[J]'^J]QE(:1a(@J]'^_HO"&H %b%0$++1FQ&QHO}}()$+B$6rxx 7J$Uf$UHM##/JtS4I4IcRVRbRbRhRhNilpNp'.r5'9$:J:J'Uf'U$D#&&'+$ 194T__=R=R9SWX9X""1%))+d2&*ooa&8#&*#"" ::$(AI   ;(_!)$(HM)s!K :KK%$K%c$URS5$)Nr2r'rs r&r2Explanation.abss&&r%cU$r+rrs r&r7Explanation.identitys r%c$URS5$)Nr:r*rs r&r:Explanation.argsort"s **r%c$URS5$)Nr=r*rs r&r=Explanation.flip&s''r%c"URSUS9$)Numpy-style mean function.rJrr*rwrs r&rJExplanation.mean*sT22r%c"URSUS9$)r3rDr4r*r5s r&rDExplanation.max.D11r%c"URSUS9$)r3rGr4r*r5s r&rGExplanation.min2r9r%cUcURSUS9$US:Xd[UR5S:Xa [X5$[ S5e)zNumpy-style sum function.rAr4r z4Only axis = 1 is supported for grouping right now...)r'rprgroup_featuresr)rwrgroupings r&rAExplanation.sum6sK  ##E#5 5 19DJJ1,!$1 1STTr%c [R"U5nURb[UR5(dUS:XaUR 5n[ R "[UR555Ul[ R "UR5Vs/sHn[ R"XQ5PM sn5Ul SUl OL[ R"URX5Ul [ R"URX5Ul URR[SU4UR US:HS95 U$s snf)Nr percentile)rrrr)rrrar r!rrrrr"r\rArir^rjrrr)rwqrrrrs r&rAExplanation.percentile>s==&    )%8J8J2K2KPTXYPY446J%'XXd:??3D.E%FH " hhZEVEVEX'YEX a(;EX'YZHO"&H  mmHOOQEHOMM(--AHM"" !W::$(AI   (Zs( Ec[RRU5nURSnUceUR U[ X5US9nU[ U5$)aRandomly samples the instances (rows) of the Explanation object. Parameters ---------- max_samples : int The number of rows to sample. Note that if ``replace=False``, then fewer than max_samples will be drawn if ``len(explanation) < max_samples``. replace : bool Sample with or without replacement. random_state : int Random seed to use for sampling, defaults to 0. r)sizereplace)rrandom RandomStaterchoicerGrr)rw max_samplesrF random_staternglengthindss r&rMExplanation.sampleSsY ii##L1A!!!zz&s;'?zQDJr%cURn[UR5S:wa [S5eUS:Xa URn[ X1S9$)zComputes an optimal leaf ordering sort order using hclustering. hclust(metric="sqeuclidean") Parameters ---------- metric : str A metric supported by scipy clustering. Defaults to "sqeuclidean". axis : int The axis to cluster along. rYz3The hclust order only supports 2D arrays right now!r )Xmetric)r\rprrTr )rwrRrr\s r&rQExplanation.hclustisE v||  ! !VW W 19XXF77r%cLURSURS:XdS5e[R"URURSS9(d [ S5e[ [R "URUR/5URURURURURURURURURUR UR"UR$UR&S9nU$)zStack two explanations column-wise. Parameters ---------- other : shap.Explanation The other Explanation object to stack with. Returns ------- exp : shap.Explanation A new Explanation object representing the stacked explanations. rz9Can't hstack explanations with different numbers of rows!gư>)atolz5Can't hstack explanations with different base values!r[)rrallcloser]rsrVhstackr\r^r_r`rarbrcrdrerfrgrhri)rwrrs r&rXExplanation.hstackszz!} A.k0kk.{{4++U->->TJTU U99dkk5<<89((**..,,**..****nn** $ 8 8  r%c URRS:a [S5e[U[5(a [ XS9$[U[ [[R45(aK[R"U5n[S0[R"U5Vs0sH o"XU:H_M snD6$[S5es snf)a0Split this explanation into several cohorts. Parameters ---------- cohorts : int or array If this is an integer then we auto build that many cohorts using a decision tree. If this is an array then we treat that as an array of cohort names/ids for each instance. Returns ------- Cohorts object rYzCohorts cannot be calculated on multiple outputs at once. Please make sure to specify the output index on which cohorts should be build, e.g. for a multi-class output shap_values[..., cohort_class].cohorts(2).) max_cohortszRThe given set of cohort indicators is not recognized! Please give an array or int.r)r\ndimrsrlr _auto_cohortsrrrrrrCohortsunique TypeError)rwcohortsrs r&raExplanation.cohortss ;;  a =  gs # # ; ; geRZZ8 9 9hhw'GZbiiPWFXYFXdDD$99FXYZ ZlmmZs#C c0n[[UR55HNn[URUURU5H!up4X1;a/X'XR U5 M# MP U$r+)rqrpr\rrarrwrr{rrs r&r!"Explanation._flatten_feature_namessk%' s4;;'(AD..q14;;q>B&$&JM $$Q'C) r%c0n[[UR55HNn[URUURU5H!up4X1;a/X'XR U5 M# MP U$r+)rqrpr\rr^rrds r&_use_data_as_feature_names&Explanation._use_data_as_feature_namessg%' s4;;'(ADIIaL$++a.9&$&JM $$Q':) r%)rvrkrjrn)NNNNNNNNNNNNNNrSrVrSr)rr)NN)rz int | Noner+)Fr)rJrrFrrKrrSrV) sqeuclideanr)rRrrr)rrVrSrV)raz)int | list[int] | tuple[int] | np.ndarrayrSr^)rSr#)4rrrr r!r}rTr\setterr]r^r_r`rbrcrardrerfrgrhrirr-rrZrrrrrr rrrr'r2r7r:r=rJrDrGrArArMrQrXrar!rgr$rr%r&rVrV[s!   !W v ]]$$##.. [[  $$00 &&$$00&&%%22$$$$!!$$00++> >"",,l\::,$KKKKKKS*X''++((322U* ,84"Hn6r%rV) metaclassc0nUH nURX/5U/-X!U'M" URn[R"U5n0nSn[ UR 5S:HnUGH8nURX35n X;aMSXi'URX35n URX/5n U V s/sHoR U 5PM n n U(aUURU R5URU'URU R5URU'OfURSS2U 4RS5URSS2U4'URSS2U 4RS5URSS2U4'XRU'US- nGM; [U(aURSUOURSS2SU24URU(aURSUOURSS2SU24URcSO0U(aURSS2SU24OURSS2SU24SURcSOURSUSSSSSSSSS9$s sn f)Nrr Tr) rrarrrprindexr\rAr^rVr]r_) shap_values feature_map reverse_mapr curr_namessv_newfoundr{rank1new_name cols_to_sumrold_indss r&r=r=sa(*K)49JB)OSWRX)X %&**J ]]; 'F E A  !! "a 'E??4.   ??4.!ooh ; 1<=A$$Q'= *11(;??AFMM! (--h7;;=FKKN"-"4"4Q["A"E"Ea"HFMM!Q$  + 0 0H = A A! DFKK1 "*Q Q#& " bq a!e(<&& %V[[!_6;;q"1"u+=    &,1f!!!RaR%(v7J7J1bqb57Q$22:d@T@TUWVW@X ! >s0I2c[U5nUb [U5nOUnUbI[U5nU[U5*SU:wa*U[U5*S-SUSS:XaUSUS:XaUSSnOUb[U5SSnO [5n[U5[U5- [U5- n[[U5U-[U55n[U5$)zPUses the passed data to infer which dimensions correspond to the model's output.Nr r)rorprrq) r\r]r^rbry data_shape output_shapeinteraction_orderrns r&rmrms!&)L #D) " %l3  #l++- ., >c,//!356,qr:JJQ<?2'+L  %k2126 w L)C O;c,>OOJ*;;S=NOK  r%cR[US[[R45(+$r)rlrrrr)vals r&r r )s3q6D"**#56 77r%c ,^Sn[US5(a[U[5(a [5$[R R U5(d+[U5S:a[U"U5[5(ag[U[5(a-[U54[U[[U555-$[[US[555S:a UR$[U5S:Xag[U5S:XaS[U"U55-$[U"U55mT[5:Xa [U54$[R"[T5[ S 9n[#S[U55H^n[X5n[U5[T5:XdS 5e[#[U55HnX%==XETU:H-ss'M M` [U54[U4S j[%U555-$) z-Computes the shape of a generic object ``x``.cUHnUs $ gr+r)iterabler/s r& _first_item#_compute_shape.._first_item0sDKr%rZrr+rr )r)r )dtypezDArrays in Explanation objects must have consistent inner dimensions!c3D># UHupU(aTUOSv M g7fr+r)rrmatch first_shapes r&r!_compute_shape..Ps bOa81u[^$>Oas )rtrlrrscipysparseissparserpr#ronextiterr#rronesrrqr)xrmatchesr{rrrs @r&roro-s 1i Jq#$6$6w <<  # #A z+a.RU7V7V!TAy>!DaM*:;;; 71guw '(1,ww 1v{ 1v{n[^444 Q0KegAyggc+&d3G 1c!f qt$5zS--u/uu-s5z"A J%(k!n4 4J# F9ubyY`Oabb bbr%c~\rSrSrSrS Sjr\S Sj5r\RS5rSSjr SSjr SSjr S r S r g )r^iSa'A collection of :class:`.Explanation` objects, typically each explaining a cluster of similar samples. Examples -------- A ``Cohorts`` object can be initialized in a variety of ways. By explicitly specifying the cohorts: >>> exp = Explanation( ... values=np.random.uniform(low=-1, high=1, size=(500, 5)), ... data=np.random.normal(loc=1, scale=3, size=(500, 5)), ... feature_names=list("abcde"), ... ) >>> cohorts = Cohorts( ... col_a_neg=exp[exp[:, "a"].data < 0], ... col_a_pos=exp[exp[:, "a"].data >= 0], ... ) >>> cohorts Or using the :meth:`.Explanation.cohorts` method: >>> cohorts2 = exp.cohorts(3) >>> cohorts2 Most of the :class:`.Explanation` interface is also exposed in ``Cohorts``. For example, to retrieve the SHAP values corresponding to column 'a' across all cohorts, you can use: >>> cohorts[..., 'a'].values To actually retrieve the values of a particular :class:`.Explanation`, you'll need to access it via the :meth:`.Cohorts.cohorts` property: >>> cohorts.cohorts["col_a_neg"][..., 'a'].values array([...]) # truncated c Xl0Ulgr+)ra _callables)rwrs r&r}Cohorts.__init__|s /1r%cUR$)z7Internal collection of cohorts, stored as a dictionary.)_cohortsrs r&raCohorts.cohortss}}r%c[U[5(d Sn[U5eUR5H1n[U[5(aMS[ U53n[U5e Xlg)Nz"self.cohorts must be a dictionary!zBArguments to a Cohorts set must be Explanation objects, but found )rlr#r`r\rVtyper)rwcvalemsgexps r&rars`$%%7DD/ !;;=Cc;//[\`ad\e[fgo%! 15 r%c0nURH#nURURU5X#'M% [S0UD6$)Nr)rr-r^)rwr/ new_cohortsks r&r-Cohorts.__getitem__s> A!]]1-99$?KN%%%r%c[5nURHJn[URUU5n[U5(aXBRU'M<XBRU'ML U$r+)r^rr#callabler)rwrrrresults r& __getattr__Cohorts.__getattr__s[i AT]]1-t4F,2&&q)*0$$Q'  r%cUR(d Sn[U5e0nURR5HupVU"U0UD6XE'M [S0UD6$)aCall the bound methods on the Explanation objects retrieved during attribute access. For example, ``Cohorts(...).mean(axis=0)`` would first run ``__getattr__("mean")`` and return a bound method ``Explanation.mean`` for all the :class:`Explanation` objects inside the ``Cohorts``, returned as a new ``Cohorts`` object. Then the ``(axis=0)`` call would be executed on that returned ``Cohorts`` object, which is why we need ``__call__`` defined. zNo methods to __call__!r)rrsitemsr^)rwrrrrr bound_methods r&__call__Cohorts.__call__sX,DT" " #446OA)4:6:KN 7%%%r%cS[UR5SURR5Vs/sHoRPM snS3$s snf)Nz')rprr\r)rwrs r&rCohorts.__repr__s{8T]]9K8LL_rvrrsGsGsIaJsImnahahsIaJ`KKLM MaJsA )rrraN)rrVrSNone)rSzdict[str, Explanation]rSr^)rrrSr^)rrrr r!r}rTrarlr-rrrr$rr%r&r^r^SsN&P2 ^^ 5 5& &$Mr%r^c8[RRUS9nURURUR 5 UR UR5R5n/n[URS5HnSn[[X555HnX5U4S:dMURRUnURRUn URXX4n US:dMYU[URU5- nX:aUS- nOUS- nU[U 5S-- nM UR!USS5 M ["R$"U5n 0n ["R&"U 5H nX U:HX'M [)S 0U D6$) zWThis uses a DecisionTreeRegressor to build a group of cohorts with similar SHAP values.)max_leaf_nodesrz < z >= z & Nr)sklearntreeDecisionTreeRegressorfitr^r\ decision_pathtoarrayrqrrptree_feature thresholdrrarrrr_r^) rpr[mpaths path_namesr{rrrrrpath_names_arrras r&r]r]s~  **+*FAEE+  K../ OOK,, - 5 5 7EJ;$$Q' (s58}%AT{Q''//!,GG--a0 !&&qz2a<C 9 9' BCCD C NU22D& $s)$)XXj)NG .)#d$:; *  W r%c[U[R5(aM[UR5S:Xa4[US[R5(aUVs/sHoPM sn$U$s snf)zfA helper to patch things since slicer doesn't handle arrays of arrays (it does handle lists of arrays)r r)rlrrrpr)rrs r&rurusS!RZZ  S\Q%6:adBJJ;W;W~1a1~s A/rirj)rSztuple[int | None, ...]r)* __future__rrr dataclassesrrtypingrrrnumpyrpandasr scipy.clusterr scipy.sparse scipy.spatialrslicerr r r utils._clusteringr utils._exceptionsrutils._generalrr,rrr(rVr=rmr ror^r]rurr%r&rs" (&&%%.-#*+  && &6$d6$rw Ow t/dD8#cLaMaMH!Hr%