class statsmodels.genmod.cov_struct.Nested(cov_nearest_method='clipped')[source]

A nested working dependence structure.

A nested working dependence structure captures unique variance associated with each level in a hierarchy of partitions of the cases. For each level of the hierarchy, there is a set of iid random effects with mean zero, and with variance that is specific to the level. These variance parameters are estimated from the data using the method of moments.

The top level of the hierarchy is always defined by the required groups argument to GEE.

The dep_data argument used to create the GEE defines the remaining levels of the hierarchy. it should be either an array, or if using the formula interface, a string that contains a formula. If an array, it should contain a n_obs x k matrix of labels, corresponding to the k levels of partitioning that are nested under the top-level groups of the GEE instance. These subgroups should be nested from left to right, so that two observations with the same label for column j of dep_data should also have the same label for all columns j’ < j (this only applies to observations in the same top-level cluster given by the groups argument to GEE).

If dep_data is a formula, it should usually be of the form 0 + a + b + …, where a, b, etc. contain labels defining group membership. The 0 + ` should be included to prevent creation of an intercept. The variable values are interpreted as labels for group membership, but the variables should not be explicitly coded as categorical, i.e. use `0 + a not 0 + C(a).


The calculations for the nested structure involve all pairs of observations within the top level group passed to GEE. Large group sizes will result in slow iterations.


covariance_matrix(expval, index)

Returns the working covariance or correlation matrix for a given cluster of data.

covariance_matrix_solve(expval, index, …)

Solves matrix equations of the form covmat * soln = rhs and returns the values of soln, where covmat is the covariance matrix represented by this class.


Called on the first call to update


Returns a summary string describing the state of the dependence structure.


Update the association parameter values based on the current regression coefficients.