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 model in which the fixed effects parameters are
  penalized.  The dependence parameters are held fixed at their
  estimated values in the unpenalized model.
  
  Parameters
  ----------
  method : str of Penalty object
      Method for regularization.  If a string, must be 'l1'.
  alpha : array_like
      Scalar or vector of penalty weights.  If a scalar, the
      same weight is applied to all coefficients; if a vector,
      it contains a weight for each coefficient.  If method is a
      Penalty object, the weights are scaled by alpha.  For L1
      regularization, the weights are used directly.
  ceps : positive real scalar
      Fixed effects parameters smaller than this value
      in magnitude are treated as being zero.
  ptol : positive real scalar
      Convergence occurs when the sup norm difference
      between successive values of `fe_params` is less than
      `ptol`.
  maxit : int
      The maximum number of iterations.
  **fit_kwargs
      Additional keyword arguments passed to fit.
  
  Returns
  -------
  A MixedLMResults instance containing the results.
  
  Notes
  -----
  The covariance structure is not updated as the fixed effects
  parameters are varied.
  
  The algorithm used here for L1 regularization is a"shooting"
  or cyclic coordinate descent algorithm.
  
  If method is 'l1', then `fe_pen` and `cov_pen` are used to
  obtain the covariance structure, but are ignored during the
  L1-penalized fitting.
  
  References
  ----------
  Friedman, J. H., Hastie, T. and Tibshirani, R. Regularized
  Paths for Generalized Linear Models via Coordinate
  Descent. Journal of Statistical Software, 33(1) (2008)
  http://www.jstatsoft.org/v33/i01/paper
  
  http://statweb.stanford.edu/~tibs/stat315a/Supplements/fuse.pdf
docstr_tok: ["Fit","a","model","in","which","the","fixed","effects","parameters","are","penalized",".","The","dependence","parameters","are","held","fixed","at","their","estimated","values","in","the","unpenalized","model",".","Parameters","--","--","--","--","--","method",":","str","of","Penalty","object","Method","for","regularization",".","If","a","string",",","must","be","'l1","'",".","alpha",":","array_like","Scalar","or","vector","of","penalty","weights",".","If","a","scalar",",","the","same","weight","is","applied","to","all","coefficients",";","if","a","vector",",","it","contains","a","weight","for","each","coefficient",".","If","method","is","a","Penalty","object",",","the","weights","are","scaled","by","alpha",".","For","L1","regularization",",","the","weights","are","used","directly",".","ceps",":","positive","real","scalar","Fixed","effects","parameters","smaller","than","this","value","in","magnitude","are","treated","as","being","zero",".","ptol",":","positive","real","scalar","Convergence","occurs","when","the","sup","norm","difference","between","successive","values","of","`","fe_params","`","is","less","than","`","ptol","`",".","maxit",":","int","The","maximum","number","of","iterations",".","*","*","fit_kwargs","Additional","keyword","arguments","passed","to","fit",".","Returns","--","--","--","-","A","MixedLMResults","instance","containing","the","results",".","Notes","--","--","-","The","covariance","structure","is","not","updated","as","the","fixed","effects","parameters","are","varied",".","The","algorithm","used","here","for","L1","regularization","is","a","''","shooting","''","or","cyclic","coordinate","descent","algorithm",".","If","method","is","'l1","'",",","then","`","fe_pen","`","and","`","cov_pen","`","are","used","to","obtain","the","covariance","structure",",","but","are","ignored","during","the","L1-penalized","fitting",".","References","--","--","--","--","--","Friedman",",","J.","H.",",","Hastie",",","T.","and","Tibshirani",",","R.","Regularized","Paths","for","Generalized","Linear","Models","via","Coordinate","Descent",".","Journal","of","Statistical","Software",",","33","(","1",")","(","2008",")","http",":","\/\/www.jstatsoft.org\/v33\/i01\/paper","http",":","\/\/statweb.stanford.edu\/~tibs\/stat315a\/Supplements\/fuse.pdf"]
code: def fit_regularized(
      self,
      start_params=None,
      method="l1",
      alpha=0,
      ceps=1e-4,
      ptol=1e-6,
      maxit=200,
      **fit_kwargs,
  ):
      """
      Fit a model in which the fixed effects parameters are
      penalized.  The dependence parameters are held fixed at their
      estimated values in the unpenalized model.
  
      Parameters
      ----------
      method : str of Penalty object
          Method for regularization.  If a string, must be 'l1'.
      alpha : array_like
          Scalar or vector of penalty weights.  If a scalar, the
          same weight is applied to all coefficients; if a vector,
          it contains a weight for each coefficient.  If method is a
          Penalty object, the weights are scaled by alpha.  For L1
          regularization, the weights are used directly.
      ceps : positive real scalar
          Fixed effects parameters smaller than this value
          in magnitude are treated as being zero.
      ptol : positive real scalar
          Convergence occurs when the sup norm difference
          between successive values of `fe_params` is less than
          `ptol`.
      maxit : int
          The maximum number of iterations.
      **fit_kwargs
          Additional keyword arguments passed to fit.
  
      Returns
      -------
      A MixedLMResults instance containing the results.
  
      Notes
      -----
      The covariance structure is not updated as the fixed effects
      parameters are varied.
  
      The algorithm used here for L1 regularization is a"shooting"
      or cyclic coordinate descent algorithm.
  
      If method is 'l1', then `fe_pen` and `cov_pen` are used to
      obtain the covariance structure, but are ignored during the
      L1-penalized fitting.
  
      References
      ----------
      Friedman, J. H., Hastie, T. and Tibshirani, R. Regularized
      Paths for Generalized Linear Models via Coordinate
      Descent. Journal of Statistical Software, 33(1) (2008)
      http://www.jstatsoft.org/v33/i01/paper
  
      http://statweb.stanford.edu/~tibs/stat315a/Supplements/fuse.pdf
      """
  
      if isinstance(method, str) and (method.lower() != "l1"):
          raise ValueError("Invalid regularization method")
  
      # If method is a smooth penalty just optimize directly.
      if isinstance(method, Penalty):
          # Scale the penalty weights by alpha
          method.alpha = alpha
          fit_kwargs.update({"fe_pen": method})
          return self.fit(**fit_kwargs)
  
      if np.isscalar(alpha):
          alpha = alpha * np.ones(self.k_fe, dtype=np.float64)
  
      # Fit the unpenalized model to get the dependence structure.
      mdf = self.fit(**fit_kwargs)
      fe_params = mdf.fe_params
      cov_re = mdf.cov_re
      vcomp = mdf.vcomp
      scale = mdf.scale
      try:
          cov_re_inv = np.linalg.inv(cov_re)
      except np.linalg.LinAlgError:
          cov_re_inv = None
  
      for itr in range(maxit):
          fe_params_s = fe_params.copy()
          for j in range(self.k_fe):
              if abs(fe_params[j]) < ceps:
                  continue
  
              # The residuals
              fe_params[j] = 0.0
              expval = np.dot(self.exog, fe_params)
              resid_all = self.endog - expval
  
              # The loss function has the form
              # a*x^2 + b*x + pwt*|x|
              a, b = 0.0, 0.0
              for group_ix, group in enumerate(self.group_labels):
                  vc_var = self._expand_vcomp(vcomp, group_ix)
  
                  exog = self.exog_li[group_ix]
                  ex_r, ex2_r = (
                      self._aex_r[group_ix],
                      self._aex_r2[group_ix],
                  )
  
                  resid = resid_all[self.row_indices[group]]
                  solver = _smw_solver(
                      scale, ex_r, ex2_r, cov_re_inv, 1 / vc_var
                  )
  
                  x = exog[:, j]
                  u = solver(x)
                  a += np.dot(u, x)
                  b -= 2 * np.dot(u, resid)
  
              pwt1 = alpha[j]
              if b > pwt1:
                  fe_params[j] = -(b - pwt1) / (2 * a)
              elif b < -pwt1:
                  fe_params[j] = -(b + pwt1) / (2 * a)
  
          if np.abs(fe_params_s - fe_params).max() < ptol:
              break
  
      # Replace the fixed effects estimates with their penalized
      # values, leave the dependence parameters in their unpenalized
      # state.
      params_prof = mdf.params.copy()
      params_prof[0 : self.k_fe] = fe_params
  
      scale = self.get_scale(fe_params, mdf.cov_re_unscaled, mdf.vcomp)
  
      # Get the Hessian including only the nonzero fixed effects,
      # then blow back up to the full size after inverting.
      hess, sing = self.hessian(params_prof)
      if sing:
          warnings.warn(_warn_cov_sing)
  
      pcov = np.nan * np.ones_like(hess)
      ii = np.abs(params_prof) > ceps
      ii[self.k_fe :] = True
      ii = np.flatnonzero(ii)
      hess1 = hess[ii, :][:, ii]
      pcov[np.ix_(ii, ii)] = np.linalg.inv(-hess1)
  
      params_object = MixedLMParams.from_components(
          fe_params, cov_re=cov_re
      )
  
      results = MixedLMResults(self, params_prof, pcov / scale)
      results.params_object = params_object
      results.fe_params = fe_params
      results.cov_re = cov_re
      results.vcomp = vcomp
      results.scale = scale
      results.cov_re_unscaled = mdf.cov_re_unscaled
      results.method = mdf.method
      results.converged = True
      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
  
      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 6 for calling the MixedLM obj's underlying member method code with example usage: obj.fit_regularized(start_params, method, alpha, ceps, ptol, maxit) and returns: MixedLMResultsWrapper, self