M/PhldZddlZddlmZmZddlmZgdZ dZ dZ dZ d Z d Z d!d Zd ZdZdZdZeedZdefdZdZdefdZdZdZd"dZd#dZd"dZdedfdZeZdZdZedfdZ edfd Z!dS)$uWSandwich covariance estimators Created on Sun Nov 27 14:10:57 2011 Author: Josef Perktold Author: Skipper Seabold for HCxxx in linear_model.RegressionResults License: BSD-3 Notes ----- for calculating it, we have two versions version 1: use pinv pinv(x) scale pinv(x) used currently in linear_model, with scale is 1d (or diagonal matrix) (x'x)^(-1) x' scale x (x'x)^(-1), scale in general is (nobs, nobs) so pretty large general formulas for scale in cluster case are in [4], which can be found (as of 2017-05-20) at http://www.tandfonline.com/doi/abs/10.1198/jbes.2010.07136 This paper also has the second version. version 2: (x'x)^(-1) S (x'x)^(-1) with S = x' scale x, S is (kvar,kvars), (x'x)^(-1) is available as normalized_covparams. S = sum (x*u) dot (x*u)' = sum x*u*u'*x' where sum here can aggregate over observations or groups. u is regression residual. x is (nobs, k_var) u is (nobs, 1) x*u is (nobs, k_var) For cluster robust standard errors, we first sum (x*w) over other groups (including time) and then take the dot product (sum of outer products) S = sum_g(x*u)' dot sum_g(x*u) For HAC by clusters, we first sum over groups for each time period, and then use HAC on the group sums of (x*w). If we have several groups, we have to sum first over all relevant groups, and then take the outer product sum. This can be done by summing using indicator functions or matrices or with explicit loops. Alternatively we calculate separate covariance matrices for each group, sum them and subtract the duplicate counted intersection. Not checked in details yet: degrees of freedom or small sample correction factors, see (two) references (?) This is the general case for MLE and GMM also in MLE hessian H, outerproduct of jacobian S, cov_hjjh = HJJH, which reduces to the above in the linear case, but can be used generally, e.g. in discrete, and is misnomed in GenericLikelihoodModel in GMM it's similar but I would have to look up the details, (it comes out in sandwich form by default, it's in the sandbox), standard Newey West or similar are on the covariance matrix of the moment conditions quasi-MLE: MLE with mis-specified model where parameter estimates are fine (consistent ?) but cov_params needs to be adjusted similar or same as in sandwiches. (I did not go through any details yet.) TODO ---- * small sample correction factors, Done for cluster, not yet for HAC * automatic lag-length selection for Newey-West HAC, -> added: nlag = floor[4(T/100)^(2/9)] Reference: xtscc paper, Newey-West note this will not be optimal in the panel context, see Peterson * HAC should maybe return the chosen nlags * get consistent notation, varies by paper, S, scale, sigma? * replace diag(hat_matrix) calculations in cov_hc2, cov_hc3 References ---------- [1] John C. Driscoll and Aart C. Kraay, “Consistent Covariance Matrix Estimation with Spatially Dependent Panel Data,” Review of Economics and Statistics 80, no. 4 (1998): 549-560. [2] Daniel Hoechle, "Robust Standard Errors for Panel Regressions with Cross-Sectional Dependence", The Stata Journal [3] Mitchell A. Petersen, “Estimating Standard Errors in Finance Panel Data Sets: Comparing Approaches,” Review of Financial Studies 22, no. 1 (January 1, 2009): 435 -480. [4] A. Colin Cameron, Jonah B. Gelbach, and Douglas L. Miller, “Robust Inference With Multiway Clustering,” Journal of Business and Economic Statistics 29 (April 2011): 238-249. not used yet: A.C. Cameron, J.B. Gelbach, and D.L. Miller, “Bootstrap-based improvements for inference with clustered errors,” The Review of Economics and Statistics 90, no. 3 (2008): 414–427. N)combine_indices group_sums)se_cov) cov_clustercov_cluster_2groupscov_hac cov_nw_panelcov_white_simplecov_hc0cov_hc1cov_hc2cov_hc3rweights_bartlettweights_uniformc|tj|jj|dddf|jjjz}|S)zt sandwich with pinv(x) * diag(scale) * pinv(x).T where pinv(x) = (X'X)^(-1) X and scale is (nobs,) N)npdotmodel pinv_wexogTresultsscaleHs e/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/statsmodels/stats/sandwich_covariance.py_HCCMrs= w}' aaaf gm.00 2 2A Hc:|jdz}t||}|S+ See statsmodels.RegressionResults )residr)r het_scaler s rr r s$  q IGY''G NrcZ|j|jz |jdzz}t||}|Sr)nobsdf_residr"r)rr#r s rr r s3  g./1ABIGY''G Nrc tjtj|jjtj|j|jjj}|jdzd|z z }t||}|S)r r! rdiagrrexognormalized_cov_paramsrr"r)rhr#cov_hc2_s rr r st w})&!>!-,.0011 2 2A q !A#&IWi((H Orc tjtj|jjtj|j|jjj}|jd|z z dz}t||}|S)r r(r!r))rr-r#cov_hc3_s rrrst w})&!>!-,.0011 2 2A}ac"Q&IWi((H Orct|tr1|\}}tj|x}}tj|}nt |drt |dr|j}t |jdr\|j|j}tj |j |j}nt |jdr\|j |j}tj |j |j}n7|jj |jdddfz}tj|j}t |jdrC|dks=|tjtj|jjdddfz}nt%d||fS) z?Helper function to get scores from results Parameters r_resultsjac score_obsN freq_weightscluz:need either tuple of (jac, hessian_inv) or resultsinstance) isinstancetuplerasarrayhasattrr3rr4paramslinalginvhessianr5wexogwresidr,sqrtr6 ValueError)rcov_typer4 hessian_invxus r_get_sandwich_arraysrGs '5!!%"[:c??"Sj-- ' " "% 7J ' ' '&G 7=% ( ( D""7>22B)-- (=(=gn(M(MNNKK W]K 0 0 D((88B)-- (=(=gn(M(MNNKK$w~aaag'>>B*W%BCCK 7=. 1 1 K(e:K:K "'"*W]%?@@DIJJ JB$%% % {?rc|jdkr > Hrc|jdkr |dddf}|}tjtj|||j}|S)a sandwich with (X'X)^(-1) * scale * (X'X)^(-1) scale is (kvars, kvars) this uses results.normalized_cov_params for (X'X)^(-1) Parameters ---------- results : result instance need to contain regression results, uses results.normalized_cov_params scale : ndarray (k_vars, k_vars) scale matrix Returns ------- H : ndarray (k_vars, k_vars) robust covariance matrix for the parameter estimates r(NrIrrr)rErxxirs r_HCCM2rN sI( zQaaaf  C rvc5!!35))A HrcBdtj|dz|dzz z S)a!Bartlett weights for HAC this will be moved to another module Parameters ---------- nlags : int highest lag in the kernel window, this does not include the zero lag Returns ------- kernel : ndarray, (nlags+1,) weights for Bartlett kernel r(?)rarangenlagss rrr<s&$ ryq!!58, ,,rc0tj|dzS)auniform weights for HAC this will be moved to another module Parameters ---------- nlags : int highest lag in the kernel window, this does not include the zero lag Returns ------- kernel : ndarray, (nlags+1,) weights for uniform kernel r()ronesrRs rrrPs$ 757  r)bartlettuniformc|jdkr |dddf}|jd}|*ttjd|dz dzz}||}|dtj|j|z}td|dzD]C}tj||dj|d| }|||||jzzz }D|S)ainner covariance matrix for HAC (Newey, West) sandwich assumes we have a single time series with zero axis consecutive, equal spaced time periods Parameters ---------- x : ndarray (nobs,) or (nobs, k_var) data, for HAC this is array of x_i * u_i nlags : int or None highest lag to include in kernel window. If None, then nlags = floor(4(T/100)^(2/9)) is used. weights_func : callable weights_func is called with nlags as argument to get the kernel weights. default are Bartlett weights Returns ------- S : ndarray, (k_vars, k_vars) inner covariance matrix for sandwich Notes ----- used by cov_hac_simple options might change when other kernels besides Bartlett are available. r(NrgY@gqq?)rIshapeintrfloorrrrange)xrS weights_func n_periodsweightsSlagss r S_hac_simplereis> v{{ aaafI I }BHQ)d"2e!<<==>>l5!!G RVAC^^#AQa  && F1STT79a#h ' ' WS\QW %% Hrcd|jdkr |dddf}tj|j|S)aXinner covariance matrix for White heteroscedastistity sandwich Parameters ---------- x : ndarray (nobs,) or (nobs, k_var) data, for HAC this is array of x_i * u_i Returns ------- S : ndarray, (k_vars, k_vars) inner covariance matrix for sandwich Notes ----- this is just dot(X.T, X) r(NrL)r^s rS_white_simplergs2& v{{ aaafI 6!#q>>rcPt||j}t|||S)a\inner covariance matrix for HAC over group sums sandwich This assumes we have complete equal spaced time periods. The number of time periods per group need not be the same, but we need at least one observation for each time period For a single categorical group only, or a everything else but time dimension. This first aggregates x over groups for each time period, then applies HAC on the sum per period. Parameters ---------- x : ndarray (nobs,) or (nobs, k_var) data, for HAC this is array of x_i * u_i time : ndarray, (nobs,) timeindes, assumed to be integers range(n_periods) nlags : int or None highest lag to include in kernel window. If None, then nlags = floor[4(T/100)^(2/9)] is used. weights_func : callable weights_func is called with nlags as argument to get the kernel weights. default are Bartlett weights Returns ------- S : ndarray, (k_vars, k_vars) inner covariance matrix for sandwich References ---------- Daniel Hoechle, xtscc paper Driscoll and Kraay rSr_)rrre)r^timerSr_ x_group_sumss rS_hac_groupsumrls,Ja&&(L  E M M MMrcJt||j}t|S)zinner covariance matrix for White on group sums sandwich I guess for a single categorical group only, categorical group, can also be the product/intersection of groups This is used by cov_cluster and indirectly verified )rrrg)r^grouprks rS_crosssectionros$a'')L , ' ''rct|jdddf|}tj|}t ||}|S)z0this one is still wrong, use cov_cluster insteadN)ror"rsqueezerJ)rrnrcovs rcov_crosssection_0rssE 7=40% 8 8E Ju  E % C JrTct|d\}}t|dr|jtjdkrtj|d\}}ntj|}t ||}|j\}}t|} t||} |r$| | | dz z |dz t||z z zz} | S)ajcluster robust covariance matrix Calculates sandwich covariance matrix for a single cluster, i.e. grouped variables. Parameters ---------- results : result instance result of a regression, uses results.model.exog and results.resid TODO: this should use wexog instead use_correction : bool If true (default), then the small sample correction factor is used. Returns ------- cov : ndarray, (k_vars, k_vars) cluster robust covariance matrix for parameter estimates Notes ----- same result as Stata in UCLA example and same as Peterson r7)rDdtyper[T)return_inverserP) rGr;ruruniquerorZlenrNfloat) rrnuse_correctionrFrEclustersrr%k_paramsn_groupscov_cs rrrs2+7UCCCOB 5' " "$ekRXe__&D&D)E$???%%9U## 2u % %EXND(8}}H ; & &E8 (hm,GuTH_5557 8 LrcJ|D|jdks|jddkrtd|dddf}|dddf}n|}|}||f}t|||}t|||}t|t |d|}||z|z } | ||fS)aMcluster robust covariance matrix for two groups/clusters Parameters ---------- results : result instance result of a regression, uses results.model.exog and results.resid TODO: this should use wexog instead use_correction : bool If true (default), then the small sample correction factor is used. Returns ------- cov_both : ndarray, (k_vars, k_vars) cluster robust covariance matrix for parameter estimates, for both clusters cov_0 : ndarray, (k_vars, k_vars) cluster robust covariance matrix for parameter estimates for first cluster cov_1 : ndarray, (k_vars, k_vars) cluster robust covariance matrix for parameter estimates for second cluster Notes ----- verified against Peterson's table, (4 decimal print precision) Nr!r(zIif group2 is not given, then groups needs to be an array with two columnsr)rz)rIrZrCrr) rrngroup2rzgroup0group1cov0cov1cov01cov_boths rrrs:~ :>>U[^q009:: :qqq!tqqq!t  w~ F F FD w~ F F FD '..q1'5 7 7 7E d{U"H T4 rct|\}}t|}t||}|r"|j\}}||t ||z z z}|S)a heteroscedasticity robust covariance matrix (White) Parameters ---------- results : result instance result of a regression, uses results.model.exog and results.resid TODO: this should use wexog instead Returns ------- cov : ndarray, (k_vars, k_vars) heteroscedasticity robust covariance matrix for parameter estimates Notes ----- This produces the same result as cov_hc0, and does not include any small sample correction. verified (against LinearRegressionResults and Peterson) See Also -------- cov_hc1, cov_hc2, cov_hc3 : heteroscedasticity robust covariance matrices with small sample corrections )rGrgrNrZry)rrzrFrEsigmacov_wr%r|s rr r Xsd8+733OB 2  E ; & &E/h dXo.... Lrct|\}}t|||}t||}|r"|j\}} ||t || z z z}|S)a heteroscedasticity and autocorrelation robust covariance matrix (Newey-West) Assumes we have a single time series with zero axis consecutive, equal spaced time periods Parameters ---------- results : result instance result of a regression, uses results.model.exog and results.resid TODO: this should use wexog instead nlags : int or None highest lag to include in kernel window. If None, then nlags = floor[4(T/100)^(2/9)] is used. weights_func : callable weights_func is called with nlags as argument to get the kernel weights. default are Bartlett weights Returns ------- cov : ndarray, (k_vars, k_vars) HAC robust covariance matrix for parameter estimates Notes ----- verified only for nlags=0, which is just White just guessing on correction factor, need reference options might change when other kernels besides Bartlett are available. ri)rGrerNrZry) rrSr_rzrFrErrr%r|s rcov_hac_simplerslD+733OB 5| D D DE[%((G1h4%x0000 Nrc&g}g}|D]N\}}||z|kr@||||z||||||z O|gkrtdtj|tj|fS)z assumes sorted by time, groupidx is tuple of start and end values not optimized, just to get a working version, loop over groups z all groups are empty taking lags)appendrCrvstack)r^rcgroupidxout0 out_laggedlus r lagged_groupsrs DJ**! S5199 KK!C%' # # #   a!C%j ) ) ) rzz;<<< 9T??BIj11 11rc$t|dz }|dtj|j|z}t d|dzD]F}t |||\}}tj|j|}|||||jzzz }G|S)zinner covariance matrix for HAC for panel data no denominator nobs used no reference for this, just accounting for time indices r(r)rxrrrr]r) xwrarrSrbrcxw0xwlagrds r S_nw_panelrs LLNE RVBD"%%%AQa  &&"2sH55 U F35%  WS\QW %% Hrhacc`|dkrddg}n ||}t|\}}t|||}t||} |rb|j\} } |dkr| | t | | z z z} n9|dvr5t |} | | | dz z z} | | dz t | | z z z} | S)aPanel HAC robust covariance matrix Assumes we have a panel of time series with consecutive, equal spaced time periods. Data is assumed to be in long format with time series of each individual stacked into one array. Panel can be unbalanced. Parameters ---------- results : result instance result of a regression, uses results.model.exog and results.resid TODO: this should use wexog instead nlags : int or None Highest lag to include in kernel window. Currently, no default because the optimal length will depend on the number of observations per cross-sectional unit. groupidx : list of tuple each tuple should contain the start and end index for an individual. (groupidx might change in future). weights_func : callable weights_func is called with nlags as argument to get the kernel weights. default are Bartlett weights use_correction : 'cluster' or 'hac' or False If False, then no small sample correction is used. If 'cluster' (default), then the same correction as in cov_cluster is used. If 'hac', then the same correction as in single time series, cov_hac is used. Returns ------- cov : ndarray, (k_vars, k_vars) HAC robust covariance matrix for parameter estimates Notes ----- For nlags=0, this is just White covariance, cov_white. If kernel is uniform, `weights_uniform`, with nlags equal to the number of observations per unit in a balance panel, then cov_cluster and cov_hac_panel are identical. Tested against STATA `newey` command with same defaults. Options might change when other kernels besides Bartlett and uniform are available. rr(r)cr7clusterrP)rGrrNrZryrx) rrSrr_rzrarFrES_hacrr%r|r}s rr r sb zza&,u%%*733OB r7H - -E[%((G<h U " " teD8O444 4GG 6 6 68}}H x8b=1 1G bE$/$:$:: ;G Nrc\t|\}}t||||}t||}|rt|j\} } |dkr|| t | | z z z}nK|dvrGt t j|} || | dz z z}|| dz t | | z z z}|S)a-Driscoll and Kraay Panel robust covariance matrix Robust covariance matrix for panel data of Driscoll and Kraay. Assumes we have a panel of time series where the time index is available. The time index is assumed to represent equal spaced periods. At least one observation per period is required. Parameters ---------- results : result instance result of a regression, uses results.model.exog and results.resid TODO: this should use wexog instead nlags : int or None Highest lag to include in kernel window. Currently, no default because the optimal length will depend on the number of observations per cross-sectional unit. time : ndarray of int this should contain the coding for the time period of each observation. time periods should be integers in range(maxT) where maxT is obs of i weights_func : callable weights_func is called with nlags as argument to get the kernel weights. default are Bartlett weights use_correction : 'cluster' or 'hac' or False If False, then no small sample correction is used. If 'hac' (default), then the same correction as in single time series, cov_hac is used. If 'cluster', then the same correction as in cov_cluster is used. Returns ------- cov : ndarray, (k_vars, k_vars) HAC robust covariance matrix for parameter estimates Notes ----- Tested against STATA xtscc package, which uses no small sample correction This first averages relevant variables for each time period over all individuals/groups, and then applies the same kernel weighted averaging over time as in HAC. Warning: In the example with a short panel (few time periods and many individuals) with mainly across individual variation this estimator did not produce reasonable results. Options might change when other kernels besides Bartlett and uniform are available. References ---------- Daniel Hoechle, xtscc paper Driscoll and Kraay rir)rrrP)rGrlrNrZryrxrrw) rrSrjr_rzrFrErrr%r|r}s rcov_nw_groupsumr sx+733OB  2t5| L L LE[%((G<h U " " teD8O444 4GG / / /29T??++H x8b=1 1G bE$/$:$:: ;G Nr)r1)T)NT)"__doc__numpyrstatsmodels.tools.grouputilsrr statsmodels.stats.moment_helpersr__all__rr r r rrGrJrNrr kernel_dictrergrlrorsrrr rrrrr rrrrsOeeLDDDDDDDD333333 < < <(V          ''''T   8   8---(*,)++ -=- - - - ^2#'5E'N'N'N'NT ( ( (++++Z6 6 6 6 r%%%%P#'5E"&++++Z 222&   "9I %CCCCL8H !JJJJJJr