code: def covariance_mest(
      X,
      m_estimator,
      *,
      init=None,
      tol=10e-3,
      n_iter_max=50,
      assume_centered=False,
      q=0.9,
      nu=5,
      norm="trace",
  ):
      r"""Robust M-estimators.
  
      Robust M-estimator based covariance matrix [1]_, computed by fixed point
      algorithm.
  
      For an input time series :math:`X \in \mathbb{R}^{c \times t}`, composed of
      :math:`c` channels and :math:`t` time samples,
  
      .. math::
          C = \frac{1}{t} \sum_i \varphi(X[:,i]^H C^{-1} X[:,i]) X[:,i] X[:,i]^H
  
      where :math:`\varphi()` is a function allowing to weight the squared
      Mahalanobis distance depending on the M-estimator type: Huber, Student-t or
      Tyler.
  
      Parameters
      ----------
      X : ndarray, shape (n_channels, n_times)
          Multi-channel time-series, real or complex-valued.
      m_estimator : {'hub', 'stu', 'tyl'}
          Type of M-estimator:
  
          - 'hub' for Huber's M-estimator [2]_;
          - 'stu' for Student-t's M-estimator [3]_;
          - 'tyl' for Tyler's M-estimator [4]_.
      init : None | ndarray, shape (n_channels, n_channels), default=None
          A matrix used to initialize the algorithm.
          If None, the sample covariance matrix is used.
      tol : float, default=10e-3
          The tolerance to stop the fixed point estimation.
      n_iter_max : int, default=50
          The maximum number of iterations.
      assume_centered : bool, default=False
          If `True`, data will not be centered before computation.
          Useful when working with data whose mean is almost, but not exactly
          zero. If `False`, data will be centered before computation.
      q : float, default=0.9
          Using Huber's M-estimator, q is the percentage in (0, 1] of inputs
          deemed uncorrupted, while (1-q) is the percentage of inputs treated as
          outliers w.r.t a Gaussian distribution.
          This estimator is a trade-off between Tyler's estimator (q=0) and the
          sample covariance matrix (q=1).
      nu : int, default=5
          Using Student-t's M-estimator, degree of freedom for t-distribution
          (strictly positive).
          This estimator is a trade-off between Tyler's estimator (nu->0) and the
          sample covariance matrix (nu->inf).
      norm : {"trace", "determinant"}, default="trace"
          Using Tyler's M-estimator, the type of normalization:
  
          * 'trace': trace of covariance matrix is ``n_channels``;
          * 'determinant': determinant of covariance matrix is 1.
  
      Returns
      -------
      cov : ndarray, shape (n_channels, n_channels)
          Robust M-estimator based covariance matrix.
  
      Notes
      -----
      .. versionadded:: 0.4
  
      References
      ----------
      .. [1] `Complex Elliptically Symmetric Distributions: Survey, New Results
          and Applications
          <https://www.researchgate.net/profile/H-Vincent-Poor/publication/258658018_Complex_Elliptically_Symmetric_Distributions_Survey_New_Results_and_Applications/links/550480100cf24cee3a0150e2/Complex-Elliptically-Symmetric-Distributions-Survey-New-Results-and-Applications.pdf>`_
          E. Ollila, D.E. Tyler, V. Koivunen, H.V. Poor. IEEE Transactions on
          Signal Processing, 2012.
      .. [2] `Robust antenna array processing using M-estimators of
          pseudo-covariance
          <http://lib.tkk.fi/Diss/2010/isbn9789526030319/article5.pdf>`_
          E. Ollila, V. Koivunen. PIMRC, 2003.
      .. [3] `Influence functions for array covariance matrix estimators
          <https://ieeexplore.ieee.org/abstract/document/1289447/>`_
          E. Ollila, V. Koivunen. IEEE SSP, 2003.
      .. [4] `A distribution-free M-estimator of multivariate scatter
          <https://projecteuclid.org/journals/annals-of-statistics/volume-15/issue-1/A-Distribution-Free-M-Estimator-of-Multivariate-Scatter/10.1214/aos/1176350263.full>`_
          D.E. Tyler. The Annals of Statistics, 1987.
      """  # noqa
      n_channels, n_times = X.shape
  
      if m_estimator == "hub":
          if not 0 < q <= 1:
              raise ValueError(
                  f"Value q must be included in (0, 1] (Got {q})"
              )
  
          def weight_func(x):  # Example 1, Section V-C in [1]
              c2 = chi2.ppf(q, n_channels) / 2
              b = (
                  chi2.cdf(2 * c2, n_channels + 1)
                  + c2 * (1 - q) / n_channels
              )
              return np.minimum(1, c2 / x) / b
  
      elif m_estimator == "stu":
          if nu <= 0:
              raise ValueError(
                  f"Value nu must be strictly positive (Got {nu})"
              )
  
          def weight_func(x):  # Eq.(42) in [1]
              return (2 * n_channels + nu) / (nu + 2 * x)
  
      elif m_estimator == "tyl":
  
          def weight_func(x):  # Example 2, Section V-C in [1]
              return n_channels / x
  
      else:
          raise ValueError(f"Unsupported m_estimator: {m_estimator}")
  
      if not assume_centered:
          X -= np.mean(X, axis=1, keepdims=True)
      if init is None:
          cov = X @ X.conj().T / n_times
      else:
          cov = init
  
      for _ in range(n_iter_max):
          dist2 = distance_mahalanobis(X, cov, squared=True)
          Xw = np.sqrt(weight_func(dist2)) * X
          cov_new = Xw @ Xw.conj().T / n_times
  
          norm_delta = np.linalg.norm(cov_new - cov, ord="fro")
          norm_cov = np.linalg.norm(cov, ord="fro")
          cov = cov_new
          if (norm_delta / norm_cov) <= tol:
              break
      else:
          warnings.warn("Convergence not reached")
  
      if m_estimator == "tyl":
          cov = normalize(cov, norm)
          if norm == "trace":
              cov *= n_channels
  
      return cov
  
imports: import warnings
  from functools import wraps
  import numpy
  from scipy.linalg import block_diag
  from scipy.stats import chi2
  from sklearn.covariance import oas, ledoit_wolf, fast_mcd
  from .distance import distance_mahalanobis
  from .test import is_square, is_real_type
label_desc: Use image node_id 8 for calling a global function with example usage: covariance_mest(X, m_estimator) and returns: cov, unknown, unknown, unknown