class_docstr: Object for Epoch/Evoked filtering.
docstr: Compute analytic signal or envelope for a subset of channels.
  
  Parameters
  ----------
  %(picks_all_data_noref)s
  envelope : bool
      Compute the envelope signal of each channel. Default False.
      See Notes.
  %(n_jobs)s
  n_fft : int | None | str
      Points to use in the FFT for Hilbert transformation. The signal
      will be padded with zeros before computing Hilbert, then cut back
      to original length. If None, n == self.n_times. If 'auto',
      the next highest fast FFT length will be use.
  %(verbose)s
  
  Returns
  -------
  self : instance of Raw, Epochs, or Evoked
      The raw object with transformed data.
  
  Notes
  -----
  **Parameters**
  
  If ``envelope=False``, the analytic signal for the channels defined in
  ``picks`` is computed and the data of the Raw object is converted to
  a complex representation (the analytic signal is complex valued).
  
  If ``envelope=True``, the absolute value of the analytic signal for the
  channels defined in ``picks`` is computed, resulting in the envelope
  signal.
  
  .. warning: Do not use ``envelope=True`` if you intend to compute
              an inverse solution from the raw data. If you want to
              compute the envelope in source space, use
              ``envelope=False`` and compute the envelope after the
              inverse solution has been obtained.
  
  If envelope=False, more memory is required since the original raw data
  as well as the analytic signal have temporarily to be stored in memory.
  If n_jobs > 1, more memory is required as ``len(picks) * n_times``
  additional time points need to be temporarily stored in memory.
  
  Also note that the ``n_fft`` parameter will allow you to pad the signal
  with zeros before performing the Hilbert transform. This padding
  is cut off, but it may result in a slightly different result
  (particularly around the edges). Use at your own risk.
  
  **Analytic signal**
  
  The analytic signal "x_a(t)" of "x(t)" is::
  
      x_a = F^{-1}(F(x) 2U) = x + i y
  
  where "F" is the Fourier transform, "U" the unit step function,
  and "y" the Hilbert transform of "x". One usage of the analytic
  signal is the computation of the envelope signal, which is given by
  "e(t) = abs(x_a(t))". Due to the linearity of Hilbert transform and the
  MNE inverse solution, the enevlope in source space can be obtained
  by computing the analytic signal in sensor space, applying the MNE
  inverse, and computing the envelope in source space.
docstr_tok: ["Compute","analytic","signal","or","envelope","for","a","subset","of","channels",".","Parameters","--","--","--","--","--","%","(","picks_all_data_noref",")","s","envelope",":","bool","Compute","the","envelope","signal","of","each","channel",".","Default","False",".","See","Notes",".","%","(","n_jobs",")","s","n_fft",":","int","|","None","|","str","Points","to","use","in","the","FFT","for","Hilbert","transformation",".","The","signal","will","be","padded","with","zeros","before","computing","Hilbert",",","then","cut","back","to","original","length",".","If","None",",","n","==","self.n_times",".","If","'auto","'",",","the","next","highest","fast","FFT","length","will","be","use",".","%","(","verbose",")","s","Returns","--","--","--","-","self",":","instance","of","Raw",",","Epochs",",","or","Evoked","The","raw","object","with","transformed","data",".","Notes","--","--","-","*","*","Parameters","*","*","If","``","envelope=False","``",",","the","analytic","signal","for","the","channels","defined","in","``","picks","``","is","computed","and","the","data","of","the","Raw","object","is","converted","to","a","complex","representation","(","the","analytic","signal","is","complex","valued",")",".","If","``","envelope=True","``",",","the","absolute","value","of","the","analytic","signal","for","the","channels","defined","in","``","picks","``","is","computed",",","resulting","in","the","envelope","signal",".","..","warning",":","Do","not","use","``","envelope=True","``","if","you","intend","to","compute","an","inverse","solution","from","the","raw","data",".","If","you","want","to","compute","the","envelope","in","source","space",",","use","``","envelope=False","``","and","compute","the","envelope","after","the","inverse","solution","has","been","obtained",".","If","envelope=False",",","more","memory","is","required","since","the","original","raw","data","as","well","as","the","analytic","signal","have","temporarily","to","be","stored","in","memory",".","If","n_jobs",">","1",",","more","memory","is","required","as","``","len","(","picks",")","*","n_times","``","additional","time","points","need","to","be","temporarily","stored","in","memory",".","Also","note","that","the","``","n_fft","``","parameter","will","allow","you","to","pad","the","signal","with","zeros","before","performing","the","Hilbert","transform",".","This","padding","is","cut","off",",","but","it","may","result","in","a","slightly","different","result","(","particularly","around","the","edges",")",".","Use","at","your","own","risk",".","*","*","Analytic","signal","*","*","The","analytic","signal","``","x_a","(","t",")","''","of","``","x","(","t",")","''","is",":",":","x_a","=","F^","{","-1","}","(","F","(","x",")","2U",")","=","x","+","i","y","where","``","F","''","is","the","Fourier","transform",",","``","U","''","the","unit","step","function",",","and","``","y","''","the","Hilbert","transform","of","``","x","''",".","One","usage","of","the","analytic","signal","is","the","computation","of","the","envelope","signal",",","which","is","given","by","''","e","(","t",")","=","abs","(","x_a","(","t",")",")","''",".","Due","to","the","linearity","of","Hilbert","transform","and","the","MNE","inverse","solution",",","the","enevlope","in","source","space","can","be","obtained","by","computing","the","analytic","signal","in","sensor","space",",","applying","the","MNE","inverse",",","and","computing","the","envelope","in","source","space","."]
code: def apply_hilbert(
      self,
      picks=None,
      envelope=False,
      n_jobs=None,
      n_fft="auto",
      *,
      verbose=None,
  ):
      """Compute analytic signal or envelope for a subset of channels.
  
      Parameters
      ----------
      %(picks_all_data_noref)s
      envelope : bool
          Compute the envelope signal of each channel. Default False.
          See Notes.
      %(n_jobs)s
      n_fft : int | None | str
          Points to use in the FFT for Hilbert transformation. The signal
          will be padded with zeros before computing Hilbert, then cut back
          to original length. If None, n == self.n_times. If 'auto',
          the next highest fast FFT length will be use.
      %(verbose)s
  
      Returns
      -------
      self : instance of Raw, Epochs, or Evoked
          The raw object with transformed data.
  
      Notes
      -----
      **Parameters**
  
      If ``envelope=False``, the analytic signal for the channels defined in
      ``picks`` is computed and the data of the Raw object is converted to
      a complex representation (the analytic signal is complex valued).
  
      If ``envelope=True``, the absolute value of the analytic signal for the
      channels defined in ``picks`` is computed, resulting in the envelope
      signal.
  
      .. warning: Do not use ``envelope=True`` if you intend to compute
                  an inverse solution from the raw data. If you want to
                  compute the envelope in source space, use
                  ``envelope=False`` and compute the envelope after the
                  inverse solution has been obtained.
  
      If envelope=False, more memory is required since the original raw data
      as well as the analytic signal have temporarily to be stored in memory.
      If n_jobs > 1, more memory is required as ``len(picks) * n_times``
      additional time points need to be temporarily stored in memory.
  
      Also note that the ``n_fft`` parameter will allow you to pad the signal
      with zeros before performing the Hilbert transform. This padding
      is cut off, but it may result in a slightly different result
      (particularly around the edges). Use at your own risk.
  
      **Analytic signal**
  
      The analytic signal "x_a(t)" of "x(t)" is::
  
          x_a = F^{-1}(F(x) 2U) = x + i y
  
      where "F" is the Fourier transform, "U" the unit step function,
      and "y" the Hilbert transform of "x". One usage of the analytic
      signal is the computation of the envelope signal, which is given by
      "e(t) = abs(x_a(t))". Due to the linearity of Hilbert transform and the
      MNE inverse solution, the enevlope in source space can be obtained
      by computing the analytic signal in sensor space, applying the MNE
      inverse, and computing the envelope in source space.
      """
      _check_preload(self, "inst.apply_hilbert")
      if n_fft is None:
          n_fft = len(self.times)
      elif isinstance(n_fft, str):
          if n_fft != "auto":
              raise ValueError(
                  f"n_fft must be an integer, string, or None, got {type(n_fft)}"
              )
          n_fft = next_fast_len(len(self.times))
      n_fft = int(n_fft)
      if n_fft < len(self.times):
          raise ValueError(
              f"n_fft ({n_fft}) must be at least the number of time points ("
              f"{len(self.times)})"
          )
      dtype = None if envelope else np.complex128
      picks = _picks_to_idx(
          self.info, picks, exclude=(), with_ref_meg=False
      )
      args, kwargs = (), dict(n_fft=n_fft, envelope=envelope)
  
      data_in = self._data
      if dtype is not None and dtype != self._data.dtype:
          self._data = self._data.astype(dtype)
  
      parallel, p_fun, n_jobs = parallel_func(_check_fun, n_jobs)
      if n_jobs == 1:
          # modify data inplace to save memory
          for idx in picks:
              self._data[..., idx, :] = _check_fun(
                  _my_hilbert, data_in[..., idx, :], *args, **kwargs
              )
      else:
          # use parallel function
          data_picks_new = parallel(
              p_fun(_my_hilbert, data_in[..., p, :], *args, **kwargs)
              for p in picks
          )
          for pp, p in enumerate(picks):
              self._data[..., p, :] = data_picks_new[pp]
      return self
  
imports: from collections import Counter
  from copy import deepcopy
  from functools import partial
  from math import gcd
  import numpy
  from scipy import fft, signal
  from scipy.stats import f
  from ._fiff.pick import _picks_to_idx
  from ._ola import _COLA
  from .cuda import _fft_multiply_repeated, _fft_resample, _setup_cuda_fft_multiply_repeated, _setup_cuda_fft_resample, _smart_pad
  from .parallel import parallel_func
  from .utils import _check_option, _check_preload, _ensure_int, _pl, _validate_type, logger, sum_squared, verbose, warn
label_desc: Use image node_id 4 for calling the FilterMixin obj's underlying member method code with example usage: obj.apply_hilbert(picks, envelope, n_jobs, n_fft) and returns: self