class_docstr: Morph source space data from one subject to another.
  
  .. note::
      This class should not be instantiated directly via
      ``mne.SourceMorph(...)``. Instead, use one of the functions
      listed in the See Also section below.
  
  Parameters
  ----------
  subject_from : str | None
      Name of the subject from which to morph as named in the SUBJECTS_DIR.
  subject_to : str | array | list of array
      Name of the subject on which to morph as named in the SUBJECTS_DIR.
      The default is 'fsaverage'. If morphing a volume source space,
      subject_to can be the path to a MRI volume. Can also be a list of
      two arrays if morphing to hemisphere surfaces.
  kind : str | None
      Kind of source estimate. E.g. ``'volume'`` or ``'surface'``.
  zooms : float | tuple
      See :func:`mne.compute_source_morph`.
  niter_affine : tuple of int
      Number of levels (``len(niter_affine)``) and number of
      iterations per level - for each successive stage of iterative
      refinement - to perform the affine transform.
  niter_sdr : tuple of int
      Number of levels (``len(niter_sdr)``) and number of
      iterations per level - for each successive stage of iterative
      refinement - to perform the Symmetric Diffeomorphic Registration (sdr)
      transform :footcite:`AvantsEtAl2008`.
  spacing : int | list | None
      See :func:`mne.compute_source_morph`.
  smooth : int | str | None
      See :func:`mne.compute_source_morph`.
  xhemi : bool
      Morph across hemisphere.
  morph_mat : scipy.sparse.csr_matrix
      The sparse surface morphing matrix for spherical surface
      based morphing :footcite:`GreveEtAl2013`.
  vertices_to : list of ndarray
      The destination surface vertices.
  shape : tuple
      The volume MRI shape.
  affine : ndarray
      The volume MRI affine.
  pre_affine : instance of dipy.align.AffineMap
      The transformation that is applied before the before ``sdr_morph``.
  sdr_morph : instance of dipy.align.DiffeomorphicMap
      The class that applies the the symmetric diffeomorphic registration
      (SDR) morph.
  src_data : dict
      Additional source data necessary to perform morphing.
  vol_morph_mat : scipy.sparse.csr_matrix | None
      The volumetric morph matrix, if :meth:`compute_vol_morph_mat`
      was used.
  %(verbose)s
  
  See Also
  --------
  compute_source_morph
  read_source_morph
  
  Notes
  -----
  .. versionadded:: 0.17
  
  References
  ----------
  .. footbibliography::
class_docstr_tok: ["Morph","source","space","data","from","one","subject","to","another",".","..","note",":",":","This","class","should","not","be","instantiated","directly","via","``","mne.SourceMorph","(","...",")","``",".","Instead",",","use","one","of","the","functions","listed","in","the","See","Also","section","below",".","Parameters","--","--","--","--","--","subject_from",":","str","|","None","Name","of","the","subject","from","which","to","morph","as","named","in","the","SUBJECTS_DIR",".","subject_to",":","str","|","array","|","list","of","array","Name","of","the","subject","on","which","to","morph","as","named","in","the","SUBJECTS_DIR",".","The","default","is","'fsaverage","'",".","If","morphing","a","volume","source","space",",","subject_to","can","be","the","path","to","a","MRI","volume",".","Can","also","be","a","list","of","two","arrays","if","morphing","to","hemisphere","surfaces",".","kind",":","str","|","None","Kind","of","source","estimate",".","E.g",".","``","'volume","'","``","or","``","'surface","'","``",".","zooms",":","float","|","tuple","See",":","func",":","`","mne.compute_source_morph","`",".","niter_affine",":","tuple","of","int","Number","of","levels","(","``","len","(","niter_affine",")","``",")","and","number","of","iterations","per","level","-","for","each","successive","stage","of","iterative","refinement","-","to","perform","the","affine","transform",".","niter_sdr",":","tuple","of","int","Number","of","levels","(","``","len","(","niter_sdr",")","``",")","and","number","of","iterations","per","level","-","for","each","successive","stage","of","iterative","refinement","-","to","perform","the","Symmetric","Diffeomorphic","Registration","(","sdr",")","transform",":","footcite",":","`","AvantsEtAl2008","`",".","spacing",":","int","|","list","|","None","See",":","func",":","`","mne.compute_source_morph","`",".","smooth",":","int","|","str","|","None","See",":","func",":","`","mne.compute_source_morph","`",".","xhemi",":","bool","Morph","across","hemisphere",".","morph_mat",":","scipy.sparse.csr_matrix","The","sparse","surface","morphing","matrix","for","spherical","surface","based","morphing",":","footcite",":","`","GreveEtAl2013","`",".","vertices_to",":","list","of","ndarray","The","destination","surface","vertices",".","shape",":","tuple","The","volume","MRI","shape",".","affine",":","ndarray","The","volume","MRI","affine",".","pre_affine",":","instance","of","dipy.align.AffineMap","The","transformation","that","is","applied","before","the","before","``","sdr_morph","``",".","sdr_morph",":","instance","of","dipy.align.DiffeomorphicMap","The","class","that","applies","the","the","symmetric","diffeomorphic","registration","(","SDR",")","morph",".","src_data",":","dict","Additional","source","data","necessary","to","perform","morphing",".","vol_morph_mat",":","scipy.sparse.csr_matrix","|","None","The","volumetric","morph","matrix",",","if",":","meth",":","`","compute_vol_morph_mat","`","was","used",".","%","(","verbose",")","s","See","Also","--","--","--","--","compute_source_morph","read_source_morph","Notes","--","--","-","..","versionadded",":",":","0.17","References","--","--","--","--","--","..","footbibliography",":",":"]
docstr: Compute the sparse matrix representation of the volumetric morph.
  
  Parameters
  ----------
  %(verbose)s
  
  Returns
  -------
  morph : instance of SourceMorph
      The instance (modified in-place).
  
  Notes
  -----
  For a volumetric morph, this will compute the morph for an identity
  source volume, i.e., with one source vertex active at a time, and store
  the result as a :class:`sparse <scipy.sparse.csr_matrix>`
  morphing matrix. This takes a long time (minutes) to compute initially,
  but drastically speeds up :meth:`apply` for STCs, so it can be
  beneficial when many time points or many morphs (i.e., greater than
  the number of volumetric ``src_from`` vertices) will be performed.
  
  When calling :meth:`save`, this sparse morphing matrix is saved with
  the instance, so this only needs to be called once. This function does
  nothing if the morph matrix has already been computed, or if there is
  no volume morphing necessary.
  
  .. versionadded:: 0.22
docstr_tok: ["Compute","the","sparse","matrix","representation","of","the","volumetric","morph",".","Parameters","--","--","--","--","--","%","(","verbose",")","s","Returns","--","--","--","-","morph",":","instance","of","SourceMorph","The","instance","(","modified","in-place",")",".","Notes","--","--","-","For","a","volumetric","morph",",","this","will","compute","the","morph","for","an","identity","source","volume",",","i.e.",",","with","one","source","vertex","active","at","a","time",",","and","store","the","result","as","a",":","class",":","`","sparse","<","scipy.sparse.csr_matrix",">","`","morphing","matrix",".","This","takes","a","long","time","(","minutes",")","to","compute","initially",",","but","drastically","speeds","up",":","meth",":","`","apply","`","for","STCs",",","so","it","can","be","beneficial","when","many","time","points","or","many","morphs","(","i.e.",",","greater","than","the","number","of","volumetric","``","src_from","``","vertices",")","will","be","performed",".","When","calling",":","meth",":","`","save","`",",","this","sparse","morphing","matrix","is","saved","with","the","instance",",","so","this","only","needs","to","be","called","once",".","This","function","does","nothing","if","the","morph","matrix","has","already","been","computed",",","or","if","there","is","no","volume","morphing","necessary",".","..","versionadded",":",":","0.22"]
code: def compute_vol_morph_mat(self, *, verbose=None):
      """Compute the sparse matrix representation of the volumetric morph.
  
      Parameters
      ----------
      %(verbose)s
  
      Returns
      -------
      morph : instance of SourceMorph
          The instance (modified in-place).
  
      Notes
      -----
      For a volumetric morph, this will compute the morph for an identity
      source volume, i.e., with one source vertex active at a time, and store
      the result as a :class:`sparse <scipy.sparse.csr_matrix>`
      morphing matrix. This takes a long time (minutes) to compute initially,
      but drastically speeds up :meth:`apply` for STCs, so it can be
      beneficial when many time points or many morphs (i.e., greater than
      the number of volumetric ``src_from`` vertices) will be performed.
  
      When calling :meth:`save`, this sparse morphing matrix is saved with
      the instance, so this only needs to be called once. This function does
      nothing if the morph matrix has already been computed, or if there is
      no volume morphing necessary.
  
      .. versionadded:: 0.22
      """
      if self.affine is None or self.vol_morph_mat is not None:
          return
      logger.info(
          "Computing sparse volumetric morph matrix "
          "(will take some time...)"
      )
      self.vol_morph_mat = self._morph_vols(None, "Vertex")
      return self
  
imports: import copy
  import os.path
  import warnings
  import numpy
  from scipy import sparse
  from .fixes import _get_img_fdata
  from .morph_map import read_morph_map
  from .parallel import parallel_func
  from .source_estimate import _BaseSourceEstimate, _BaseSurfaceSourceEstimate, _BaseVolSourceEstimate, _get_ico_tris
  from .source_space._source_space import SourceSpaces, _ensure_src, _grid_interp
  from .surface import _compute_nearest, mesh_edges, read_surface
  from .utils import BunchConst, ProgressBar, _check_fname, _check_option, _custom_lru_cache, _ensure_int, _import_h5io_funcs, _import_nibabel, _validate_type, check_version, fill_doc, get_subjects_dir, logger, use_log_level, verbose, warn
  from .utils import warn
label_desc: Use image node_id 6 for calling the SourceMorph obj's underlying member method code with example usage: obj.compute_vol_morph_mat() and returns: self