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","(",")"]
docstr: Fit a linear mixed model to the data.
  
  Parameters
  ----------
  start_params : array_like or MixedLMParams
      Starting values for the profile log-likelihood.  If not a
      `MixedLMParams` instance, this should be an array
      containing the packed parameters for the profile
      log-likelihood, including the fixed effects
      parameters.
  reml : bool
      If true, fit according to the REML likelihood, else
      fit the standard likelihood using ML.
  niter_sa : int
      Currently this argument is ignored and has no effect
      on the results.
  cov_pen : CovariancePenalty object
      A penalty for the random effects covariance matrix
  do_cg : bool, defaults to True
      If False, the optimization is skipped and a results
      object at the given (or default) starting values is
      returned.
  fe_pen : Penalty object
      A penalty on the fixed effects
  free : MixedLMParams object
      If not `None`, this is a mask that allows parameters to be
      held fixed at specified values.  A 1 indicates that the
      corresponding parameter is estimated, a 0 indicates that
      it is fixed at its starting value.  Setting the `cov_re`
      component to the identity matrix fits a model with
      independent random effects.  Note that some optimization
      methods do not respect this constraint (bfgs and lbfgs both
      work).
  full_output : bool
      If true, attach iteration history to results
  method : str
      Optimization method.  Can be a scipy.optimize method name,
      or a list of such names to be tried in sequence.
  **fit_kwargs
      Additional keyword arguments passed to fit.
  
  Returns
  -------
  A MixedLMResults instance.
docstr_tok: ["Fit","a","linear","mixed","model","to","the","data",".","Parameters","--","--","--","--","--","start_params",":","array_like","or","MixedLMParams","Starting","values","for","the","profile","log-likelihood",".","If","not","a","`","MixedLMParams","`","instance",",","this","should","be","an","array","containing","the","packed","parameters","for","the","profile","log-likelihood",",","including","the","fixed","effects","parameters",".","reml",":","bool","If","true",",","fit","according","to","the","REML","likelihood",",","else","fit","the","standard","likelihood","using","ML",".","niter_sa",":","int","Currently","this","argument","is","ignored","and","has","no","effect","on","the","results",".","cov_pen",":","CovariancePenalty","object","A","penalty","for","the","random","effects","covariance","matrix","do_cg",":","bool",",","defaults","to","True","If","False",",","the","optimization","is","skipped","and","a","results","object","at","the","given","(","or","default",")","starting","values","is","returned",".","fe_pen",":","Penalty","object","A","penalty","on","the","fixed","effects","free",":","MixedLMParams","object","If","not","`","None","`",",","this","is","a","mask","that","allows","parameters","to","be","held","fixed","at","specified","values",".","A","1","indicates","that","the","corresponding","parameter","is","estimated",",","a","0","indicates","that","it","is","fixed","at","its","starting","value",".","Setting","the","`","cov_re","`","component","to","the","identity","matrix","fits","a","model","with","independent","random","effects",".","Note","that","some","optimization","methods","do","not","respect","this","constraint","(","bfgs","and","lbfgs","both","work",")",".","full_output",":","bool","If","true",",","attach","iteration","history","to","results","method",":","str","Optimization","method",".","Can","be","a","scipy.optimize","method","name",",","or","a","list","of","such","names","to","be","tried","in","sequence",".","*","*","fit_kwargs","Additional","keyword","arguments","passed","to","fit",".","Returns","--","--","--","-","A","MixedLMResults","instance","."]
code: def fit(
      self,
      start_params=None,
      reml=True,
      niter_sa=0,
      do_cg=True,
      fe_pen=None,
      cov_pen=None,
      free=None,
      full_output=False,
      method=None,
      **fit_kwargs,
  ):
      """
      Fit a linear mixed model to the data.
  
      Parameters
      ----------
      start_params : array_like or MixedLMParams
          Starting values for the profile log-likelihood.  If not a
          `MixedLMParams` instance, this should be an array
          containing the packed parameters for the profile
          log-likelihood, including the fixed effects
          parameters.
      reml : bool
          If true, fit according to the REML likelihood, else
          fit the standard likelihood using ML.
      niter_sa : int
          Currently this argument is ignored and has no effect
          on the results.
      cov_pen : CovariancePenalty object
          A penalty for the random effects covariance matrix
      do_cg : bool, defaults to True
          If False, the optimization is skipped and a results
          object at the given (or default) starting values is
          returned.
      fe_pen : Penalty object
          A penalty on the fixed effects
      free : MixedLMParams object
          If not `None`, this is a mask that allows parameters to be
          held fixed at specified values.  A 1 indicates that the
          corresponding parameter is estimated, a 0 indicates that
          it is fixed at its starting value.  Setting the `cov_re`
          component to the identity matrix fits a model with
          independent random effects.  Note that some optimization
          methods do not respect this constraint (bfgs and lbfgs both
          work).
      full_output : bool
          If true, attach iteration history to results
      method : str
          Optimization method.  Can be a scipy.optimize method name,
          or a list of such names to be tried in sequence.
      **fit_kwargs
          Additional keyword arguments passed to fit.
  
      Returns
      -------
      A MixedLMResults instance.
      """
  
      _allowed_kwargs = [
          "gtol",
          "maxiter",
          "eps",
          "maxcor",
          "ftol",
          "tol",
          "disp",
          "maxls",
      ]
      for x in fit_kwargs.keys():
          if x not in _allowed_kwargs:
              warnings.warn("Argument %s not used by MixedLM.fit" % x)
  
      if method is None:
          method = ["bfgs", "lbfgs", "cg"]
      elif isinstance(method, str):
          method = [method]
  
      for meth in method:
          if meth.lower() in ["newton", "ncg"]:
              raise ValueError(
                  "method %s not available for MixedLM" % meth
              )
  
      self.reml = reml
      self.cov_pen = cov_pen
      self.fe_pen = fe_pen
      self._cov_sing = 0
      self._freepat = free
  
      if full_output:
          hist = []
      else:
          hist = None
  
      if start_params is None:
          params = MixedLMParams(self.k_fe, self.k_re, self.k_vc)
          params.fe_params = np.zeros(self.k_fe)
          params.cov_re = np.eye(self.k_re)
          params.vcomp = np.ones(self.k_vc)
      else:
          if isinstance(start_params, MixedLMParams):
              params = start_params
          else:
              # It's a packed array
              if (
                  len(start_params)
                  == self.k_fe + self.k_re2 + self.k_vc
              ):
                  params = MixedLMParams.from_packed(
                      start_params,
                      self.k_fe,
                      self.k_re,
                      self.use_sqrt,
                      has_fe=True,
                  )
              elif len(start_params) == self.k_re2 + self.k_vc:
                  params = MixedLMParams.from_packed(
                      start_params,
                      self.k_fe,
                      self.k_re,
                      self.use_sqrt,
                      has_fe=False,
                  )
              else:
                  raise ValueError("invalid start_params")
  
      if do_cg:
          fit_kwargs["retall"] = hist is not None
          if "disp" not in fit_kwargs:
              fit_kwargs["disp"] = False
          packed = params.get_packed(
              use_sqrt=self.use_sqrt, has_fe=False
          )
  
          if niter_sa > 0:
              warnings.warn("niter_sa is currently ignored")
  
          # Try optimizing one or more times
          for j in range(len(method)):
              rslt = super().fit(
                  start_params=packed,
                  skip_hessian=True,
                  method=method[j],
                  **fit_kwargs,
              )
              if rslt.mle_retvals["converged"]:
                  break
              packed = rslt.params
              if j + 1 < len(method):
                  next_method = method[j + 1]
                  warnings.warn(
                      "Retrying MixedLM optimization with %s"
                      % next_method,
                      ConvergenceWarning,
                  )
              else:
                  msg = (
                      "MixedLM optimization failed, "
                      + "trying a different optimizer may help."
                  )
                  warnings.warn(msg, ConvergenceWarning)
  
          # The optimization succeeded
          params = np.atleast_1d(rslt.params)
          if hist is not None:
              hist.append(rslt.mle_retvals)
  
      converged = rslt.mle_retvals["converged"]
      if not converged:
          gn = self.score(rslt.params)
          gn = np.sqrt(np.sum(gn**2))
          msg = "Gradient optimization failed, |grad| = %f" % gn
          warnings.warn(msg, ConvergenceWarning)
  
      # Convert to the final parameterization (i.e. undo the square
      # root transform of the covariance matrix, and the profiling
      # over the error variance).
      params = MixedLMParams.from_packed(
          params,
          self.k_fe,
          self.k_re,
          use_sqrt=self.use_sqrt,
          has_fe=False,
      )
      cov_re_unscaled = params.cov_re
      vcomp_unscaled = params.vcomp
      fe_params, sing = self.get_fe_params(
          cov_re_unscaled, vcomp_unscaled
      )
      params.fe_params = fe_params
      scale = self.get_scale(fe_params, cov_re_unscaled, vcomp_unscaled)
      cov_re = scale * cov_re_unscaled
      vcomp = scale * vcomp_unscaled
  
      f1 = (self.k_re > 0) and (np.min(np.abs(np.diag(cov_re))) < 0.01)
      f2 = (self.k_vc > 0) and (np.min(np.abs(vcomp)) < 0.01)
      if f1 or f2:
          msg = "The MLE may be on the boundary of the parameter space."
          warnings.warn(msg, ConvergenceWarning)
  
      # Compute the Hessian at the MLE.  Note that this is the
      # Hessian with respect to the random effects covariance matrix
      # (not its square root).  It is used for obtaining standard
      # errors, not for optimization.
      hess, sing = self.hessian(params)
      if sing:
          warnings.warn(_warn_cov_sing)
  
      hess_diag = np.diag(hess)
      if free is not None:
          pcov = np.zeros_like(hess)
          pat = self._freepat.get_packed(use_sqrt=False, has_fe=True)
          ii = np.flatnonzero(pat)
          hess_diag = hess_diag[ii]
          if len(ii) > 0:
              hess1 = hess[np.ix_(ii, ii)]
              pcov[np.ix_(ii, ii)] = np.linalg.inv(-hess1)
      else:
          pcov = np.linalg.inv(-hess)
      if np.any(hess_diag >= 0):
          msg = (
              "The Hessian matrix at the estimated parameter values "
              + "is not positive definite."
          )
          warnings.warn(msg, ConvergenceWarning)
  
      # Prepare a results class instance
      params_packed = params.get_packed(use_sqrt=False, has_fe=True)
      results = MixedLMResults(self, params_packed, pcov / scale)
      results.params_object = params
      results.fe_params = fe_params
      results.cov_re = cov_re
      results.vcomp = vcomp
      results.scale = scale
      results.cov_re_unscaled = cov_re_unscaled
      results.method = "REML" if self.reml else "ML"
      results.converged = converged
      results.hist = hist
      results.reml = self.reml
      results.cov_pen = self.cov_pen
      results.k_fe = self.k_fe
      results.k_re = self.k_re
      results.k_re2 = self.k_re2
      results.k_vc = self.k_vc
      results.use_sqrt = self.use_sqrt
      results.freepat = self._freepat
  
      return MixedLMResultsWrapper(results)
  
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 18 for calling the MixedLM obj's underlying member method code with example usage: obj.fit(start_params, reml, niter_sa, do_cg, fe_pen, cov_pen, free, full_output, method) and returns: MixedLMResultsWrapper