docs: def pvc_iyang(
          petin,
          mridct,
          Cnt,
          pvcroi,
          krnl,
          itr=5,
          tool='niftyreg',
          faff='',
          outpath='',
          fcomment='',
          store_img=False,
          store_rois=False,
      ):
      ''' Perform partial volume (PVC) correction of PET data (petin) using MRI data (mridct).
          The PVC method uses iterative Yang method.
          GPU based convolution is the key routine of the PVC. 
          Input:
          -------
          petin:  either a dictionary containing image data, file name and affine transform,
                  or a string of the path to the NIfTI file of the PET data.
          mridct: a dictionary of MRI data, including the T1w image, which can be given
                  in DICOM (field 'T1DCM') or NIfTI (field 'T1nii').  The T1w image data
                  is needed for co-registration to PET if affine is not given in the text
                  file with its path in faff.
          Cnt:    a dictionary of paths for third-party tools:
                  * dcm2niix: Cnt['DCM2NIIX']
                  * niftyreg, resample: Cnt['RESPATH']
                  * niftyreg, rigid-reg: Cnt['REGPATH']
                  * verbose mode on/off: Cnt['VERBOSE'] = True/False
          pvcroi: list of regions (also a list) with number label to distinguish
                  the parcellations.  The numbers correspond to the image values
                  of the parcellated T1w image.  E.g.:
                  pvcroi = [
                      [36], # ROI 1 (single parcellation region)
                      [35], # ROI 2
                      [39, 40, 72, 73, 74], # ROI 3 (region consisting of multiple parcellation regions)
                      ...
                  ]
          kernel: the point spread function (PSF) specific for the camera and the object.  
                  It is given as a 3x17 matrix, a 17-element kernel for each dimension (x,y,z).
                  It is used in the GPU-based convolution using separable kernels.
          outpath:path to the output of the resulting PVC images
          faff:   a text file of the affine transformations needed to get the MRI into PET space.
                  If not provided, it will be obtained from the performed rigid transformation.
                  For this the MR T1w image is required.  If faff and T1w image are not provided,
                  it will results in exception/error.
          fcomment:a string used in naming the produced files, helpful for distinguishing them.
          tool:   co-registration tool.  By default it is NiftyReg, but SPM is also 
                  possible (needs Matlab engine and more validation)
          itr:    number of iterations used by the PVC.  5-10 should be enough (5 default)
      '''
  
      # get all the input image properties
      if isinstance(petin, dict):
          im = imdic['im']
          fpet = imdic['fpet']
          B = imdic['affine']
      elif isinstance(petin, basestring) and os.path.isfile(petin):
          imdct = imio.getnii(petin, output='all')
          im = imdct['im']
          B = imdct['affine']
          fpet = petin
      
      if im.ndim!=3:
          raise IndexError('Only 3D images are expected in this method of partial volume correction.')
  
      # check if brain parcellations exist in NIfTI format
      if not os.path.isfile(mridct['T1lbl']):
          raise NameError('MissingLabels')
  
      #> output dictionary
      outdct = {}
  
      # establish the output folder
      if outpath=='':        
          prcl_dir = os.path.dirname(mridct['T1lbl'])
          pvc_dir =  os.path.join(os.path.dirname(fpet), 'PVC')
      else:
          prcl_dir = outpath
          pvc_dir =  os.path.join(os.path.dirname(fpet), 'PVC')
  
      #> create folders
      imio.create_dir(prcl_dir)
      imio.create_dir(pvc_dir)
  
      #==================================================================
      #if affine transf. (faff) is given then take the T1 and resample it too.
      if isinstance(faff, basestring) and not os.path.isfile(faff):
          # faff is not given; get it by running the affine; get T1w to PET space
  
          ft1w = imio.pick_t1w(mridct)
  
          if tool=='spm':
              regdct = regseg.coreg_spm(
                  fpet,
                  ft1w,
                  fcomment = fcomment,
                  outpath=os.path.join(outpath,'PET', 'positioning')
              )
          elif tool=='niftyreg':
              regdct = regseg.affine_niftyreg(
                  fpet,
                  ft1w,
                  outpath=os.path.join(outpath,'PET', 'positioning'),
                  fcomment = fcomment,
                  executable = Cnt['REGPATH'],
                  omp = multiprocessing.cpu_count()/2,
                  rigOnly = True,
                  affDirect = False,
                  maxit=5,
                  speed=True,
                  pi=50, pv=50,
                  smof=0, smor=0,
                  rmsk=True,
                  fmsk=True,
                  rfwhm=15., #millilitres
                  rthrsh=0.05,
                  ffwhm = 15., #millilitres
                  fthrsh=0.05,
                  verbose=Cnt['VERBOSE']
              )
          faff = regdct['faff']
  
      # resample the GIF T1/labels to upsampled PET
      # file name of the parcellation (GIF-based) upsampled to PET
      fgt1u = os.path.join(
              prcl_dir,
              os.path.basename(mridct['T1lbl']).split('.')[0]\
              +'_registered_trimmed'+fcomment+'.nii.gz')
          
      if tool=='niftyreg':
          if os.path.isfile( Cnt['RESPATH'] ):
              cmd = [Cnt['RESPATH'],  '-ref', fpet,  '-flo', mridct['T1lbl'],
                     '-trans', faff, '-res', fgt1u, '-inter', '0']
              if not Cnt['VERBOSE']: cmd.append('-voff')
              call(cmd)
          else:
              raise IOError('e> path to resampling executable is incorrect!')
          
      elif tool=='spm':
          fout = regseg.resample_spm(
                      fpet,
                      mridct['T1lbl'],
                      faff,
                      fimout = fgt1u,
                      matlab_eng = regdct['matlab_eng'],
                      intrp = 0.,
                      del_ref_uncmpr = True,
                      del_flo_uncmpr = True,
                      del_out_uncmpr = True,
              )
  
      #==================================================================
  
      # Get the parcellation labels in the upsampled PET space
      dprcl = imio.getnii(fgt1u, output='all')
      prcl = dprcl['im']
  
      #> path to parcellations in NIfTI format
      prcl_pth = os.path.split(mridct['T1lbl'])
  
      #---------------------------------------------------------------------------
      #> get the parcellation specific for PVC based on the current parcellations
      imgroi = prcl.copy();  imgroi[:] = 0
      
      #> number of segments, without the background
      nSeg = len(pvcroi)
      
      #> create the image of numbered parcellations
      for k in range(nSeg):
          for m in pvcroi[k]:
              imgroi[prcl==m] = k+1
  
      #> save the PCV ROIs to a new NIfTI file
      if store_rois:
          froi = os.path.join(prcl_dir, prcl_pth[1].split('.nii')[0]+'_PVC-ROIs-inPET.nii.gz')
          imio.array2nii(
              imgroi,
              dprcl['affine'],
              froi,
              trnsp = (dprcl['transpose'].index(0),
                       dprcl['transpose'].index(1),
                       dprcl['transpose'].index(2)),
              flip = dprcl['flip'])
          outdct['froi'] = froi
      #---------------------------------------------------------------------------
  
  
      #---------------------------------------------------------------------------
      # run iterative Yang PVC
      imgpvc, m_a = iyang(im, krnl, imgroi, Cnt, itr=itr)
      #---------------------------------------------------------------------------
  
      outdct['im'] = imgpvc
      outdct['imroi'] = imgroi
      outdct['faff'] = faff
  
      if store_img:
          fpvc = os.path.join( pvc_dir,
                               os.path.split(fpet)[1].split('.nii')[0]+'_PVC'+fcomment+'.nii.gz')
          imio.array2nii( imgpvc[::-1,::-1,:], B, fpvc, descrip='pvc=iY')
          outdct['fpet'] = fpvc
  
      return outdct