class_docstr: Class for masking of Niimg-like objects.
  
  NiftiMapsMasker is useful when data from overlapping volumes should be
  extracted (contrarily to :class:`nilearn.maskers.NiftiLabelsMasker`).
  Use case: Summarize brain signals from large-scale networks obtained by
  prior PCA or :term:`ICA`.
  
  Note that, Inf or NaN present in the given input images are automatically
  put to zero rather than considered as missing data.
  
  Parameters
  ----------
  maps_img : 4D niimg-like object
      See :ref:`extracting_data`.
      Set of continuous maps. One representative time course per map is
      extracted using least square regression.
  
  mask_img : 3D niimg-like object, optional
      See :ref:`extracting_data`.
      Mask to apply to regions before extracting signals.
  
  allow_overlap : :obj:`bool`, default=True
      If False, an error is raised if the maps overlaps (ie at least two
      maps have a non-zero value for the same voxel).
  %(smoothing_fwhm)s
  %(standardize_maskers)s
  %(standardize_confounds)s
  high_variance_confounds : :obj:`bool`, default=False
      If True, high variance confounds are computed on provided image with
      :func:`nilearn.image.high_variance_confounds` and default parameters
      and regressed out.
  %(detrend)s
  %(low_pass)s
  %(high_pass)s
  %(t_r)s
  dtype : {dtype, "auto"}, optional
      Data type toward which the data should be converted. If "auto", the
      data will be converted to int32 if dtype is discrete and float32 if it
      is continuous.
  
  resampling_target : {"data", "mask", "maps", None}, default="data"
      Gives which image gives the final shape/size. For example, if
      `resampling_target` is "mask" then maps_img and images provided to
      fit() are resampled to the shape and affine of mask_img. "None" means
      no resampling: if shapes and affines do not match, a ValueError is
      raised.
  %(memory)s
  %(memory_level)s
  %(verbose0)s
  %(keep_masked_maps)s
  
  reports : :obj:`bool`, default=True
      If set to True, data is saved in order to produce a report.
  
  %(masker_kwargs)s
  
  Attributes
  ----------
  maps_img_ : :obj:`nibabel.nifti1.Nifti1Image`
      The maps mask of the data.
  
  n_elements_ : :obj:`int`
      The number of overlapping maps in the mask.
      This is equivalent to the number of volumes in the mask image.
  
      .. versionadded:: 0.9.2
  
  Notes
  -----
  If resampling_target is set to "maps", every 3D image processed by
  transform() will be resampled to the shape of maps_img. It may lead to a
  very large memory consumption if the voxel number in maps_img is large.
  
  See Also
  --------
  nilearn.maskers.NiftiMasker
  nilearn.maskers.NiftiLabelsMasker
class_docstr_tok: ["Class","for","masking","of","Niimg-like","objects",".","NiftiMapsMasker","is","useful","when","data","from","overlapping","volumes","should","be","extracted","(","contrarily","to",":","class",":","`","nilearn.maskers.NiftiLabelsMasker","`",")",".","Use","case",":","Summarize","brain","signals","from","large-scale","networks","obtained","by","prior","PCA","or",":","term",":","`","ICA","`",".","Note","that",",","Inf","or","NaN","present","in","the","given","input","images","are","automatically","put","to","zero","rather","than","considered","as","missing","data",".","Parameters","--","--","--","--","--","maps_img",":","4D","niimg-like","object","See",":","ref",":","`","extracting_data","`",".","Set","of","continuous","maps",".","One","representative","time","course","per","map","is","extracted","using","least","square","regression",".","mask_img",":","3D","niimg-like","object",",","optional","See",":","ref",":","`","extracting_data","`",".","Mask","to","apply","to","regions","before","extracting","signals",".","allow_overlap",":",":","obj",":","`","bool","`",",","default=True","If","False",",","an","error","is","raised","if","the","maps","overlaps","(","ie","at","least","two","maps","have","a","non-zero","value","for","the","same","voxel",")",".","%","(","smoothing_fwhm",")","s","%","(","standardize_maskers",")","s","%","(","standardize_confounds",")","s","high_variance_confounds",":",":","obj",":","`","bool","`",",","default=False","If","True",",","high","variance","confounds","are","computed","on","provided","image","with",":","func",":","`","nilearn.image.high_variance_confounds","`","and","default","parameters","and","regressed","out",".","%","(","detrend",")","s","%","(","low_pass",")","s","%","(","high_pass",")","s","%","(","t_r",")","s","dtype",":","{","dtype",",","``","auto","''","}",",","optional","Data","type","toward","which","the","data","should","be","converted",".","If","``","auto","''",",","the","data","will","be","converted","to","int32","if","dtype","is","discrete","and","float32","if","it","is","continuous",".","resampling_target",":","{","``","data","''",",","``","mask","''",",","``","maps","''",",","None","}",",","default=","''","data","''","Gives","which","image","gives","the","final","shape\/size",".","For","example",",","if","`","resampling_target","`","is","``","mask","''","then","maps_img","and","images","provided","to","fit","(",")","are","resampled","to","the","shape","and","affine","of","mask_img",".","``","None","''","means","no","resampling",":","if","shapes","and","affines","do","not","match",",","a","ValueError","is","raised",".","%","(","memory",")","s","%","(","memory_level",")","s","%","(","verbose0",")","s","%","(","keep_masked_maps",")","s","reports",":",":","obj",":","`","bool","`",",","default=True","If","set","to","True",",","data","is","saved","in","order","to","produce","a","report",".","%","(","masker_kwargs",")","s","Attributes","--","--","--","--","--","maps_img_",":",":","obj",":","`","nibabel.nifti1.Nifti1Image","`","The","maps","mask","of","the","data",".","n_elements_",":",":","obj",":","`","int","`","The","number","of","overlapping","maps","in","the","mask",".","This","is","equivalent","to","the","number","of","volumes","in","the","mask","image",".","..","versionadded",":",":","0.9.2","Notes","--","--","-","If","resampling_target","is","set","to","``","maps","''",",","every","3D","image","processed","by","transform","(",")","will","be","resampled","to","the","shape","of","maps_img",".","It","may","lead","to","a","very","large","memory","consumption","if","the","voxel","number","in","maps_img","is","large",".","See","Also","--","--","--","--","nilearn.maskers.NiftiMasker","nilearn.maskers.NiftiLabelsMasker"]
docstr: Prepare signal extraction from regions.
  
  Parameters
  ----------
  imgs : :obj:`list` of Niimg-like objects
      See :ref:`extracting_data`.
      Image data passed to the reporter.
  
  y : None
      This parameter is unused. It is solely included for scikit-learn
      compatibility.
docstr_tok: ["Prepare","signal","extraction","from","regions",".","Parameters","--","--","--","--","--","imgs",":",":","obj",":","`","list","`","of","Niimg-like","objects","See",":","ref",":","`","extracting_data","`",".","Image","data","passed","to","the","reporter",".","y",":","None","This","parameter","is","unused",".","It","is","solely","included","for","scikit-learn","compatibility","."]
code: def fit(self, imgs=None, y=None):
      """Prepare signal extraction from regions.
  
      Parameters
      ----------
      imgs : :obj:`list` of Niimg-like objects
          See :ref:`extracting_data`.
          Image data passed to the reporter.
  
      y : None
          This parameter is unused. It is solely included for scikit-learn
          compatibility.
      """
      # Load images
      repr = _utils._repr_niimgs(
          self.mask_img, shorten=(not self.verbose)
      )
      msg = f"loading regions from {repr}"
      _utils.logger.log(msg=msg, verbose=self.verbose)
      self.maps_img_ = _utils.check_niimg(
          self.maps_img, dtype=self.dtype, atleast_4d=True
      )
      self.maps_img_ = image.clean_img(
          self.maps_img_,
          detrend=False,
          standardize=False,
          ensure_finite=True,
      )
  
      if self.mask_img is not None:
          repr = _utils._repr_niimgs(
              self.mask_img, shorten=(not self.verbose)
          )
          msg = f"loading mask from {repr}"
          _utils.logger.log(msg=msg, verbose=self.verbose)
          self.mask_img_ = _utils.check_niimg_3d(self.mask_img)
      else:
          self.mask_img_ = None
  
      # Check shapes and affines or resample.
      if self.resampling_target is None and self.mask_img_ is not None:
          _utils.niimg_conversions.check_same_fov(
              mask=self.mask_img_,
              maps=self.maps_img_,
              raise_error=True,
          )
  
      elif (
          self.resampling_target == "mask"
          and self.mask_img_ is not None
      ):
          if self.verbose > 0:
              print("Resampling maps")
  
          self.maps_img_ = image.resample_img(
              self.maps_img_,
              target_affine=self.mask_img_.affine,
              target_shape=self.mask_img_.shape,
              interpolation="continuous",
              copy=True,
          )
  
      elif (
          self.resampling_target == "maps"
          and self.mask_img_ is not None
      ):
          if self.verbose > 0:
              print("Resampling mask")
  
          self.mask_img_ = image.resample_img(
              self.mask_img_,
              target_affine=self.maps_img_.affine,
              target_shape=self.maps_img_.shape[:3],
              interpolation="nearest",
              copy=True,
          )
  
      if self.reports:
          self._reporting_data = {
              "maps_image": self.maps_img_,
              "mask": self.mask_img_,
              "dim": None,
              "img": imgs,
          }
          if imgs is not None:
              imgs, dims = compute_middle_image(imgs)
              self._reporting_data["img"] = imgs
              self._reporting_data["dim"] = dims
      else:
          self._reporting_data = None
  
      # The number of elements is equal to the number of volumes
      self.n_elements_ = self.maps_img_.shape[3]
  
      return self
  
file_path: nilearn/nilearn/maskers/nifti_maps_masker.py
imports: import warnings
  import numpy
  from joblib import Memory
  from nilearn import _utils, image
  from nilearn.maskers._utils import compute_middle_image
  from nilearn.maskers.base_masker import BaseMasker, _filter_and_extract
label_desc: Use image node_id 4 for calling the NiftiMapsMasker obj's underlying member method code with example usage: obj.fit(imgs, y) and returns: self