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

A nested working dependence structure.

A working dependence structure that captures a nested hierarchy of groups. Each level of grouping contributes to the random error structure of the model.

When using this working covariance structure, dep_data of the GEE instance should contain a n_obs x k matrix of 0/1 indicators, corresponding to the k subgroups 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 value for column j of dep_data should also have the same value for all columns j’ < j (this only applies to observations in the same top-level cluster given by the groups argument to GEE).


The calculations for this dependence structure involve all pairs of observations within a group (that is, within the top level group structure passed to GEE). Large group sizes will result in slow iterations.

The variance components are estimated using least squares regression of the products r*r’, for standardized residuals r and r’ in the same group, on a matrix of indicators defining which variance components are shared by r and r’.


Suppose our data are student test scores, and the students are in classrooms, nested in schools, nested in school districts. The school district is the highest level of grouping, so the school district id would be provided to GEE as groups, and the school and classroom id’s would be provided to the Nested class as the dep_data argument, e.g.

0 0 # School 0, classroom 0, student 0 0 0 # School 0, classroom 0, student 1 0 1 # School 0, classroom 1, student 0 0 1 # School 0, classroom 1, student 1 1 0 # School 1, classroom 0, student 0 1 0 # School 1, classroom 0, student 1 1 1 # School 1, classroom 1, student 0 1 1 # School 1, classroom 1, student 1

Labels lower in the hierarchy are recycled, so that student 0 in classroom 0 is different fro student 0 in classroom 1, etc.


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.