class_docstr: This is a class to represent multiple ROI objects, where the
  reference to a given domain is explicit.
  
  A multiple ROI object is a set of ROI defined on a given domain,
  each having its own 'region-level' characteristics (ROI features).
  
  Every voxel of the domain can have its own characteristics yet,
  defined at the 'voxel-level', but those features can only be accessed
  familywise (i.e. the values are grouped by ROI).
  
  Parameters
  ----------
  k : int
    Number of ROI in the SubDomains object
  label : array of shape (domain.size), dtype=np.int_
    An array use to define which voxel belongs to which ROI.
    The label values greater than -1 correspond to subregions
    labelling. The labels are recomputed so as to be consecutive
    integers.
    The labels should not be accessed outside this class. One has to
    use the API mapping methods instead.
  features : dict {str: list of object, length=self.k}
    Describe the voxels features, grouped by ROI
  roi_features : dict {str: array-like, shape=(self.k, roi_feature_dim)
    Describe the ROI features. A special feature, `id`, is read-only and
    is used to give an unique identifier for region, which is persistent
    through the MROI objects manipulations. On should access the different
    ROI's features using ids.
class_docstr_tok: ["This","is","a","class","to","represent","multiple","ROI","objects",",","where","the","reference","to","a","given","domain","is","explicit",".","A","multiple","ROI","object","is","a","set","of","ROI","defined","on","a","given","domain",",","each","having","its","own","'region-level","'","characteristics","(","ROI","features",")",".","Every","voxel","of","the","domain","can","have","its","own","characteristics","yet",",","defined","at","the","'voxel-level","'",",","but","those","features","can","only","be","accessed","familywise","(","i.e",".","the","values","are","grouped","by","ROI",")",".","Parameters","--","--","--","--","--","k",":","int","Number","of","ROI","in","the","SubDomains","object","label",":","array","of","shape","(","domain.size",")",",","dtype=np.int_","An","array","use","to","define","which","voxel","belongs","to","which","ROI",".","The","label","values","greater","than","-1","correspond","to","subregions","labelling",".","The","labels","are","recomputed","so","as","to","be","consecutive","integers",".","The","labels","should","not","be","accessed","outside","this","class",".","One","has","to","use","the","API","mapping","methods","instead",".","features",":","dict","{","str",":","list","of","object",",","length=self.k","}","Describe","the","voxels","features",",","grouped","by","ROI","roi_features",":","dict","{","str",":","array-like",",","shape=","(","self.k",",","roi_feature_dim",")","Describe","the","ROI","features",".","A","special","feature",",","`","id","`",",","is","read-only","and","is","used","to","give","an","unique","identifier","for","region",",","which","is","persistent","through","the","MROI","objects","manipulations",".","On","should","access","the","different","ROI","'s","features","using","ids","."]
docstr: Generates a label image that represents self.
  
  Parameters
  ----------
  fid: str,
    Feature to be represented. If None, a binary image of the MROI
    domain will be we created.
  roi: bool,
    Whether or not to write the desired feature as a ROI one.
    (i.e. a ROI feature corresponding to `fid` will be looked upon,
    and if not found, a representative feature will be computed from
    the `fid` feature).
  method: str,
    If a feature is written as a ROI feature, this keyword tweaks
    the way the representative feature is computed.
  descrip: str,
    Description of the image, to be written in its header.
  
  Notes
  -----
  Requires that self.dom is an ddom.NDGridDomain
  
  Returns
  -------
  nim : nibabel nifti image
    Nifti image corresponding to the ROI feature to be written.
docstr_tok: ["Generates","a","label","image","that","represents","self",".","Parameters","--","--","--","--","--","fid",":","str",",","Feature","to","be","represented",".","If","None",",","a","binary","image","of","the","MROI","domain","will","be","we","created",".","roi",":","bool",",","Whether","or","not","to","write","the","desired","feature","as","a","ROI","one",".","(","i.e",".","a","ROI","feature","corresponding","to","`","fid","`","will","be","looked","upon",",","and","if","not","found",",","a","representative","feature","will","be","computed","from","the","`","fid","`","feature",")",".","method",":","str",",","If","a","feature","is","written","as","a","ROI","feature",",","this","keyword","tweaks","the","way","the","representative","feature","is","computed",".","descrip",":","str",",","Description","of","the","image",",","to","be","written","in","its","header",".","Notes","--","--","-","Requires","that","self.dom","is","an","ddom.NDGridDomain","Returns","--","--","--","-","nim",":","nibabel","nifti","image","Nifti","image","corresponding","to","the","ROI","feature","to","be","written","."]
code: def to_image(self, fid=None, roi=False, method="mean", descrip=None):
      """Generates a label image that represents self.
  
      Parameters
      ----------
      fid: str,
        Feature to be represented. If None, a binary image of the MROI
        domain will be we created.
      roi: bool,
        Whether or not to write the desired feature as a ROI one.
        (i.e. a ROI feature corresponding to `fid` will be looked upon,
        and if not found, a representative feature will be computed from
        the `fid` feature).
      method: str,
        If a feature is written as a ROI feature, this keyword tweaks
        the way the representative feature is computed.
      descrip: str,
        Description of the image, to be written in its header.
  
      Notes
      -----
      Requires that self.dom is an ddom.NDGridDomain
  
      Returns
      -------
      nim : nibabel nifti image
        Nifti image corresponding to the ROI feature to be written.
  
      """
      if not isinstance(self.domain, ddom.NDGridDomain):
          print(
              "self.domain is not an NDGridDomain; nothing was written."
          )
          return None
  
      if fid is None:
          # write a binary representation of the domain if no fid provided
          nim = self.domain.to_image(
              data=(self.label != -1).astype(np.int32)
          )
          if descrip is None:
              descrip = "binary representation of MROI"
      else:
          data = -np.ones(self.label.size, dtype=np.int32)
          tmp_image = self.domain.to_image()
          mask = tmp_image.get_fdata().copy().astype(bool)
          if not roi:
              # write a feature
              if fid not in self.features:
                  raise ValueError(
                      f"`{fid}` feature could not be found"
                  )
              for i in self.get_id():
                  data[self.select_id(i, roi=False)] = self.get_feature(
                      fid, i
                  )
          else:
              # write a roi feature
              if fid in self.roi_features:
                  # write from existing roi feature
                  for i in self.get_id():
                      data[
                          self.select_id(i, roi=False)
                      ] = self.get_roi_feature(fid, i)
              elif fid in self.features:
                  # write from representative feature
                  summary_feature = self.representative_feature(
                      fid, method=method
                  )
                  for i in self.get_id():
                      data[
                          self.select_id(i, roi=False)
                      ] = summary_feature[self.select_id(i)]
          # MROI object was defined on a masked image: we square it back.
          wdata = -np.ones(mask.shape, data.dtype)
          wdata[mask] = data
          nim = Nifti1Image(wdata, get_affine(tmp_image))
      # set description of the image
      if descrip is not None:
          get_header(nim)["descrip"] = descrip
      return nim
  
imports: import numpy
  from nibabel import Nifti1Image, load
  from nipy.io.nibcompat import get_affine, get_header
  from .None import discrete_domain
label_desc: Use image node_id 21 for calling the SubDomains obj's underlying member method code with example usage: obj.to_image(fid, roi, method, descrip) and returns: nim, None