class_docstr: Linear Mixed Effects Model
  
  Parameters
  ----------
  endog : 1d array_like
      The dependent variable
  exog : 2d array_like
      A matrix of covariates used to determine the
      mean structure (the "fixed effects" covariates).
  groups : 1d array_like
      A vector of labels determining the groups -- data from
      different groups are independent
  exog_re : 2d array_like
      A matrix of covariates used to determine the variance and
      covariance structure (the "random effects" covariates).  If
      None, defaults to a random intercept for each group.
  exog_vc : VCSpec instance or dict-like (deprecated)
      A VCSPec instance defines the structure of the variance
      components in the model.  Alternatively, see notes below
      for a dictionary-based format.  The dictionary format is
      deprecated and may be removed at some point in the future.
  use_sqrt : bool
      If True, optimization is carried out using the lower
      triangle of the square root of the random effects
      covariance matrix, otherwise it is carried out using the
      lower triangle of the random effects covariance matrix.
  missing : str
      The approach to missing data handling
  
  Notes
  -----
  If `exog_vc` is not a `VCSpec` instance, then it must be a
  dictionary of dictionaries.  Specifically, `exog_vc[a][g]` is a
  matrix whose columns are linearly combined using independent
  random coefficients.  This random term then contributes to the
  variance structure of the data for group `g`.  The random
  coefficients all have mean zero, and have the same variance.  The
  matrix must be `m x k`, where `m` is the number of observations in
  group `g`.  The number of columns may differ among the top-level
  groups.
  
  The covariates in `exog`, `exog_re` and `exog_vc` may (but need
  not) partially or wholly overlap.
  
  `use_sqrt` should almost always be set to True.  The main use case
  for use_sqrt=False is when complicated patterns of fixed values in
  the covariance structure are set (using the `free` argument to
  `fit`) that cannot be expressed in terms of the Cholesky factor L.
  
  Examples
  --------
  A basic mixed model with fixed effects for the columns of
  ``exog`` and a random intercept for each distinct value of
  ``group``:
  
  >>> model = sm.MixedLM(endog, exog, groups)
  >>> result = model.fit()
  
  A mixed model with fixed effects for the columns of ``exog`` and
  correlated random coefficients for the columns of ``exog_re``:
  
  >>> model = sm.MixedLM(endog, exog, groups, exog_re=exog_re)
  >>> result = model.fit()
  
  A mixed model with fixed effects for the columns of ``exog`` and
  independent random coefficients for the columns of ``exog_re``:
  
  >>> free = MixedLMParams.from_components(
                   fe_params=np.ones(exog.shape[1]),
                   cov_re=np.eye(exog_re.shape[1]))
  >>> model = sm.MixedLM(endog, exog, groups, exog_re=exog_re)
  >>> result = model.fit(free=free)
  
  A different way to specify independent random coefficients for the
  columns of ``exog_re``.  In this example ``groups`` must be a
  Pandas Series with compatible indexing with ``exog_re``, and
  ``exog_re`` has two columns.
  
  >>> g = pd.groupby(groups, by=groups).groups
  >>> vc = {}
  >>> vc['1'] = {k : exog_re.loc[g[k], 0] for k in g}
  >>> vc['2'] = {k : exog_re.loc[g[k], 1] for k in g}
  >>> model = sm.MixedLM(endog, exog, groups, vcomp=vc)
  >>> result = model.fit()
class_docstr_tok: ["Linear","Mixed","Effects","Model","Parameters","--","--","--","--","--","endog",":","1d","array_like","The","dependent","variable","exog",":","2d","array_like","A","matrix","of","covariates","used","to","determine","the","mean","structure","(","the","``","fixed","effects","''","covariates",")",".","groups",":","1d","array_like","A","vector","of","labels","determining","the","groups","--","data","from","different","groups","are","independent","exog_re",":","2d","array_like","A","matrix","of","covariates","used","to","determine","the","variance","and","covariance","structure","(","the","``","random","effects","''","covariates",")",".","If","None",",","defaults","to","a","random","intercept","for","each","group",".","exog_vc",":","VCSpec","instance","or","dict-like","(","deprecated",")","A","VCSPec","instance","defines","the","structure","of","the","variance","components","in","the","model",".","Alternatively",",","see","notes","below","for","a","dictionary-based","format",".","The","dictionary","format","is","deprecated","and","may","be","removed","at","some","point","in","the","future",".","use_sqrt",":","bool","If","True",",","optimization","is","carried","out","using","the","lower","triangle","of","the","square","root","of","the","random","effects","covariance","matrix",",","otherwise","it","is","carried","out","using","the","lower","triangle","of","the","random","effects","covariance","matrix",".","missing",":","str","The","approach","to","missing","data","handling","Notes","--","--","-","If","`","exog_vc","`","is","not","a","`","VCSpec","`","instance",",","then","it","must","be","a","dictionary","of","dictionaries",".","Specifically",",","`","exog_vc","[","a","]","[","g","]","`","is","a","matrix","whose","columns","are","linearly","combined","using","independent","random","coefficients",".","This","random","term","then","contributes","to","the","variance","structure","of","the","data","for","group","`","g","`",".","The","random","coefficients","all","have","mean","zero",",","and","have","the","same","variance",".","The","matrix","must","be","`","m","x","k","`",",","where","`","m","`","is","the","number","of","observations","in","group","`","g","`",".","The","number","of","columns","may","differ","among","the","top-level","groups",".","The","covariates","in","`","exog","`",",","`","exog_re","`","and","`","exog_vc","`","may","(","but","need","not",")","partially","or","wholly","overlap",".","`","use_sqrt","`","should","almost","always","be","set","to","True",".","The","main","use","case","for","use_sqrt=False","is","when","complicated","patterns","of","fixed","values","in","the","covariance","structure","are","set","(","using","the","`","free","`","argument","to","`","fit","`",")","that","can","not","be","expressed","in","terms","of","the","Cholesky","factor","L.","Examples","--","--","--","--","A","basic","mixed","model","with","fixed","effects","for","the","columns","of","``","exog","``","and","a","random","intercept","for","each","distinct","value","of","``","group","``",":",">",">",">","model","=","sm.MixedLM","(","endog",",","exog",",","groups",")",">",">",">","result","=","model.fit","(",")","A","mixed","model","with","fixed","effects","for","the","columns","of","``","exog","``","and","correlated","random","coefficients","for","the","columns","of","``","exog_re","``",":",">",">",">","model","=","sm.MixedLM","(","endog",",","exog",",","groups",",","exog_re=exog_re",")",">",">",">","result","=","model.fit","(",")","A","mixed","model","with","fixed","effects","for","the","columns","of","``","exog","``","and","independent","random","coefficients","for","the","columns","of","``","exog_re","``",":",">",">",">","free","=","MixedLMParams.from_components","(","fe_params=np.ones","(","exog.shape","[","1","]",")",",","cov_re=np.eye","(","exog_re.shape","[","1","]",")",")",">",">",">","model","=","sm.MixedLM","(","endog",",","exog",",","groups",",","exog_re=exog_re",")",">",">",">","result","=","model.fit","(","free=free",")","A","different","way","to","specify","independent","random","coefficients","for","the","columns","of","``","exog_re","``",".","In","this","example","``","groups","``","must","be","a","Pandas","Series","with","compatible","indexing","with","``","exog_re","``",",","and","``","exog_re","``","has","two","columns",".",">",">",">","g","=","pd.groupby","(","groups",",","by=groups",")",".groups",">",">",">","vc","=","{","}",">",">",">","vc","[","'","1","'","]","=","{","k",":","exog_re.loc","[","g","[","k","]",",","0","]","for","k","in","g","}",">",">",">","vc","[","'","2","'","]","=","{","k",":","exog_re.loc","[","g","[","k","]",",","1","]","for","k","in","g","}",">",">",">","model","=","sm.MixedLM","(","endog",",","exog",",","groups",",","vcomp=vc",")",">",">",">","result","=","model.fit","(",")"]
code: def __init__(
      self,
      endog,
      exog,
      groups,
      exog_re=None,
      exog_vc=None,
      use_sqrt=True,
      missing="none",
      **kwargs,
  ):
      _allowed_kwargs = ["missing_idx", "design_info", "formula"]
      for x in kwargs.keys():
          if x not in _allowed_kwargs:
              raise ValueError(
                  "argument %s not permitted for MixedLM initialization"
                  % x
              )
  
      self.use_sqrt = use_sqrt
  
      # Some defaults
      self.reml = True
      self.fe_pen = None
      self.re_pen = None
  
      if isinstance(exog_vc, dict):
          warnings.warn("Using deprecated variance components format")
          # Convert from old to new representation
          exog_vc = _convert_vc(exog_vc)
  
      if exog_vc is not None:
          self.k_vc = len(exog_vc.names)
          self.exog_vc = exog_vc
      else:
          self.k_vc = 0
          self.exog_vc = VCSpec([], [], [])
  
      # If there is one covariate, it may be passed in as a column
      # vector, convert these to 2d arrays.
      # TODO: Can this be moved up in the class hierarchy?
      #       yes, it should be done up the hierarchy
      if (
          exog is not None
          and data_tools._is_using_ndarray_type(exog, None)
          and exog.ndim == 1
      ):
          exog = exog[:, None]
      if (
          exog_re is not None
          and data_tools._is_using_ndarray_type(exog_re, None)
          and exog_re.ndim == 1
      ):
          exog_re = exog_re[:, None]
  
      # Calling super creates self.endog, etc. as ndarrays and the
      # original exog, endog, etc. are self.data.endog, etc.
      super().__init__(
          endog,
          exog,
          groups=groups,
          exog_re=exog_re,
          missing=missing,
          **kwargs,
      )
  
      self._init_keys.extend(["use_sqrt", "exog_vc"])
  
      # Number of fixed effects parameters
      self.k_fe = exog.shape[1]
  
      if exog_re is None and len(self.exog_vc.names) == 0:
          # Default random effects structure (random intercepts).
          self.k_re = 1
          self.k_re2 = 1
          self.exog_re = np.ones((len(endog), 1), dtype=np.float64)
          self.data.exog_re = self.exog_re
          names = ["Group Var"]
          self.data.param_names = self.exog_names + names
          self.data.exog_re_names = names
          self.data.exog_re_names_full = names
  
      elif exog_re is not None:
          # Process exog_re the same way that exog is handled
          # upstream
          # TODO: this is wrong and should be handled upstream wholly
          self.data.exog_re = exog_re
          self.exog_re = np.asarray(exog_re)
          if self.exog_re.ndim == 1:
              self.exog_re = self.exog_re[:, None]
          # Model dimensions
          # Number of random effect covariates
          self.k_re = self.exog_re.shape[1]
          # Number of covariance parameters
          self.k_re2 = self.k_re * (self.k_re + 1) // 2
  
      else:
          # All random effects are variance components
          self.k_re = 0
          self.k_re2 = 0
  
      if not self.data._param_names:
          # HACK: could have been set in from_formula already
          # needs refactor
          (
              param_names,
              exog_re_names,
              exog_re_names_full,
          ) = self._make_param_names(exog_re)
          self.data.param_names = param_names
          self.data.exog_re_names = exog_re_names
          self.data.exog_re_names_full = exog_re_names_full
  
      self.k_params = self.k_fe + self.k_re2
  
      # Convert the data to the internal representation, which is a
      # list of arrays, corresponding to the groups.
      group_labels = list(set(groups))
      group_labels.sort()
      row_indices = {s: [] for s in group_labels}
      for i, g in enumerate(groups):
          row_indices[g].append(i)
      self.row_indices = row_indices
      self.group_labels = group_labels
      self.n_groups = len(self.group_labels)
  
      # Split the data by groups
      self.endog_li = self.group_list(self.endog)
      self.exog_li = self.group_list(self.exog)
      self.exog_re_li = self.group_list(self.exog_re)
  
      # Precompute this.
      if self.exog_re is None:
          self.exog_re2_li = None
      else:
          self.exog_re2_li = [np.dot(x.T, x) for x in self.exog_re_li]
  
      # The total number of observations, summed over all groups
      self.nobs = len(self.endog)
      self.n_totobs = self.nobs
  
      # Set the fixed effects parameter names
      if self.exog_names is None:
          self.exog_names = [
              "FE%d" % (k + 1) for k in range(self.exog.shape[1])
          ]
  
      # Precompute this
      self._aex_r = []
      self._aex_r2 = []
      for i in range(self.n_groups):
          a = self._augment_exog(i)
          self._aex_r.append(a)
  
          ma = _dot(a.T, a)
          self._aex_r2.append(ma)
  
      # Precompute this
      self._lin, self._quad = self._reparam()
  
imports: import warnings
  import numpy
  import pandas
  import patsy
  from scipy import sparse
  from scipy.stats.distributions import norm
  from statsmodels.base._penalties import Penalty
  import statsmodels.base.model
  from statsmodels.tools import data
  from statsmodels.tools.decorators import cache_readonly
  from statsmodels.tools.sm_exceptions import ConvergenceWarning
label_desc: Use image node_id 1 to create a new MixedLM object from inherited base classes: base with example: obj = MixedLM(endog, exog, groups, exog_re, exog_vc, use_sqrt, missing)