class_docstr: Whitening, and optional unsupervised dimension reduction.
  
  Implementation of the whitening, and an optional unsupervised dimension
  reduction, with SPD matrices as inputs.
  
  Parameters
  ----------
  metric : str, default='euclid'
      The metric for the estimation of mean matrix used for whitening and
      dimension reduction.
  dim_red : None | dict, default=None
      If ``None`` :
          no dimension reduction during whitening.
      If ``{'n_components': val}`` :
          dimension reduction defining the number of components;
          ``val`` must be an integer superior to 1.
      If ``{'expl_var': val}`` :
          dimension reduction selecting the number of components such that
          the amount of variance that needs to be explained is greater than
          the percentage specified by ``val``.
          ``val`` must be a float in (0,1], typically ``0.99``.
      If ``{'max_cond': val}`` :
          dimension reduction selecting the number of components such that
          the condition number of the mean matrix is lower than ``val``.
          This threshold has a physiological interpretation, because it can
          be viewed as the ratio between the power of the strongest component
          (usually, eye-blink source) and the power of the lowest component
          you don't want to keep (acquisition sensor noise).
          ``val`` must be a float strictly superior to 1, typically 100.
  verbose : bool, default=False
      Verbose flag.
  
  Attributes
  ----------
  n_components_ : int
      If fit, the number of components after dimension reduction.
  filters_ : ndarray, shape ``(n_channels_, n_components_)``
      If fit, the spatial filters to whiten SPD matrices.
  inv_filters_ : ndarray, shape ``(n_components_, n_channels_)``
      If fit, the spatial filters to unwhiten SPD matrices.
  
  Notes
  -----
  .. versionadded:: 0.2.7
class_docstr_tok: ["Whitening",",","and","optional","unsupervised","dimension","reduction",".","Implementation","of","the","whitening",",","and","an","optional","unsupervised","dimension","reduction",",","with","SPD","matrices","as","inputs",".","Parameters","--","--","--","--","--","metric",":","str",",","default='euclid'","The","metric","for","the","estimation","of","mean","matrix","used","for","whitening","and","dimension","reduction",".","dim_red",":","None","|","dict",",","default=None","If","``","None","``",":","no","dimension","reduction","during","whitening",".","If","``","{","'n_components","'",":","val","}","``",":","dimension","reduction","defining","the","number","of","components",";","``","val","``","must","be","an","integer","superior","to","1",".","If","``","{","'expl_var","'",":","val","}","``",":","dimension","reduction","selecting","the","number","of","components","such","that","the","amount","of","variance","that","needs","to","be","explained","is","greater","than","the","percentage","specified","by","``","val","``",".","``","val","``","must","be","a","float","in","(","0,1","]",",","typically","``","0.99","``",".","If","``","{","'max_cond","'",":","val","}","``",":","dimension","reduction","selecting","the","number","of","components","such","that","the","condition","number","of","the","mean","matrix","is","lower","than","``","val","``",".","This","threshold","has","a","physiological","interpretation",",","because","it","can","be","viewed","as","the","ratio","between","the","power","of","the","strongest","component","(","usually",",","eye-blink","source",")","and","the","power","of","the","lowest","component","you","do","n't","want","to","keep","(","acquisition","sensor","noise",")",".","``","val","``","must","be","a","float","strictly","superior","to","1",",","typically","100.","verbose",":","bool",",","default=False","Verbose","flag",".","Attributes","--","--","--","--","--","n_components_",":","int","If","fit",",","the","number","of","components","after","dimension","reduction",".","filters_",":","ndarray",",","shape","``","(","n_channels_",",","n_components_",")","``","If","fit",",","the","spatial","filters","to","whiten","SPD","matrices",".","inv_filters_",":","ndarray",",","shape","``","(","n_components_",",","n_channels_",")","``","If","fit",",","the","spatial","filters","to","unwhiten","SPD","matrices",".","Notes","--","--","-","..","versionadded",":",":","0.2.7"]
docstr: Train whitening spatial filters.
  
  Parameters
  ----------
  X : ndarray, shape (n_matrices, n_channels, n_channels)
      Set of SPD matrices.
  y : None
      Ignored as unsupervised.
  sample_weight : None | ndarray, shape (n_matrices,), default=None
      Weight of each matrix, to compute the weighted mean matrix used for
      whitening and dimension reduction. If None, it uses equal weights.
  
  Returns
  -------
  self : Whitening instance
      The Whitening instance.
docstr_tok: ["Train","whitening","spatial","filters",".","Parameters","--","--","--","--","--","X",":","ndarray",",","shape","(","n_matrices",",","n_channels",",","n_channels",")","Set","of","SPD","matrices",".","y",":","None","Ignored","as","unsupervised",".","sample_weight",":","None","|","ndarray",",","shape","(","n_matrices",",",")",",","default=None","Weight","of","each","matrix",",","to","compute","the","weighted","mean","matrix","used","for","whitening","and","dimension","reduction",".","If","None",",","it","uses","equal","weights",".","Returns","--","--","--","-","self",":","Whitening","instance","The","Whitening","instance","."]
code: def fit(self, X, y=None, sample_weight=None):
      """Train whitening spatial filters.
  
      Parameters
      ----------
      X : ndarray, shape (n_matrices, n_channels, n_channels)
          Set of SPD matrices.
      y : None
          Ignored as unsupervised.
      sample_weight : None | ndarray, shape (n_matrices,), default=None
          Weight of each matrix, to compute the weighted mean matrix used for
          whitening and dimension reduction. If None, it uses equal weights.
  
      Returns
      -------
      self : Whitening instance
          The Whitening instance.
      """
      # weighted mean of input SPD matrices
      Xm = mean_covariance(
          X, metric=self.metric, sample_weight=sample_weight
      )
  
      # whitening without dimension reduction
      if self.dim_red is None:
          self.n_components_ = X.shape[-1]
          self.filters_ = invsqrtm(Xm)
          self.inv_filters_ = sqrtm(Xm)
  
      # whitening with dimension reduction
      elif isinstance(self.dim_red, dict):
          eigvals, eigvecs = self._prepare_dimension_reduction(X, Xm)
  
          # dimension reduction
          if self.verbose:
              print(
                  "Dimension reduction of Whitening on %d components"
                  % self.n_components_
              )
          pca_filters = eigvecs[:, : self.n_components_]
          pca_sqrtvals = np.sqrt(eigvals[: self.n_components_])
          # whitening
          self.filters_ = pca_filters @ np.diag(1.0 / pca_sqrtvals)
          self.inv_filters_ = np.diag(pca_sqrtvals).T @ pca_filters.T
  
      else:
          raise ValueError(
              "Unknown type for parameter dim_red: %r"
              % type(self.dim_red)
          )
  
      return self
  
file_path: pyRiemann/pyriemann/preprocessing.py
imports: import numbers
  import numpy
  from scipy.linalg import eigh
  from sklearn.base import BaseEstimator, TransformerMixin
  from sklearn.utils.extmath import stable_cumsum
  from .utils.mean import mean_covariance
  from .utils.base import sqrtm, invsqrtm
label_desc: Use image node_id 2 for calling the Whitening obj's underlying member method code with example usage: obj.fit(X, y, sample_weight) and returns: self