parameters: (source_subj, hemi, surface_type,
                              target_subj='fsaverage', subjects_dir=None,
                              n_neighbors=20, random_state=0,
                              n_test_images=40, coef_threshold=None,
                              renormalize=True)
return_statement: return matrix
docstring: Creates a matrix implementing freesurfer mri_surf2surf command.
      
      A surface-to-surface transform is a linear transform between vertex spaces.
      Such a transform must be highly localized in the sense that a vertex in the
      target surface only draws its values from very few source vertices.
      This function exploits the localization to create an inverse problem for 
      each vertex.
      The source neighborhoods for each target vertex are found by using
      mri_surf2surf to transform the three coordinate maps from the source 
      surface to the target surface, yielding three coordinate values for each
      target vertex, for which we find the nearest neighbors in the source space.
      A small number of test images is transformed from source surface to
      target surface.	
      For each target vertex in the transformed test images, a regression is 
      performed using only the corresponding source image neighborhood, yielding
      the entries for a sparse matrix encoding the transform.
      
      Parameters
      ==========
      
      source_subj: str
      	Freesurfer name of source subject
      
      hemi: str in ("lh", "rh")
      	Indicator for hemisphere
      
      surface_type: str in ("white", "pial", ...)
      	Indicator for surface layer
      
      target_subj: str, default "fsaverage"
      	Freesurfer name of target subject
      
      subjects_dir: str, default os.environ["SUBJECTS_DIR"]
      	The freesurfer subjects directory
      
      n_neighbors: int, default 20
      	The size of the neighborhood to take into account when estimating
      	the source support of a vertex
      
      random_state: int, default 0
      	Random number generator or seed for generating test images
      
      n_test_images: int, default 40
      	Number of test images transformed to compute inverse problem. This 
      	should be greater than n_neighbors or equal.
      
      coef_treshold: float, default 1 / (10 * n_neighbors)
      	Value under which to set a weight to zero in the inverse problem.
      
      renormalize: boolean, default True
      	Determines whether the rows of the output matrix should add to 1,
      	implementing what is sensible: a weighted averaging
      
      Notes
      =====
      It turns out that freesurfer seems to do the following: For each target
      vertex, find, on the sphere, the nearest source vertices, and average their
      values. Try to be as one-to-one as possible.
docstring_summary: Creates a matrix implementing freesurfer mri_surf2surf command.
      
      A surface-to-surface transform is a linear transform between vertex spaces.
      Such a transform must be highly localized in the sense that a vertex in the
      target surface only draws its values from very few source vertices.
      This function exploits the localization to create an inverse problem for 
      each vertex.
      The source neighborhoods for each target vertex are found by using
      mri_surf2surf to transform the three coordinate maps from the source 
      surface to the target surface, yielding three coordinate values for each
      target vertex, for which we find the nearest neighbors in the source space.
      A small number of test images is transformed from source surface to
      target surface.	
      For each target vertex in the transformed test images, a regression is 
      performed using only the corresponding source image neighborhood, yielding
      the entries for a sparse matrix encoding the transform.
      
      Parameters
      ==========
      
      source_subj: str
      	Freesurfer name of source subject
      
      hemi: str in ("lh", "rh")
      	Indicator for hemisphere
      
      surface_type: str in ("white", "pial", ...)
      	Indicator for surface layer
      
      target_subj: str, default "fsaverage"
      	Freesurfer name of target subject
      
      subjects_dir: str, default os.environ["SUBJECTS_DIR"]
      	The freesurfer subjects directory
      
      n_neighbors: int, default 20
      	The size of the neighborhood to take into account when estimating
      	the source support of a vertex
      
      random_state: int, default 0
      	Random number generator or seed for generating test images
      
      n_test_images: int, default 40
      	Number of test images transformed to compute inverse problem. This 
      	should be greater than n_neighbors or equal.
      
      coef_treshold: float, default 1 / (10 * n_neighbors)
      	Value under which to set a weight to zero in the inverse problem.
      
      renormalize: boolean, default True
      	Determines whether the rows of the output matrix should add to 1,
      	implementing what is sensible: a weighted averaging
      
      Notes
      =====
      It turns out that freesurfer seems to do the following: For each target
      vertex, find, on the sphere, the nearest source vertices, and average their
      values. Try to be as one-to-one as possible.
docstring_tokens: Creates a matrix implementing freesurfer mri_surf2surf command . A surface - to - surface transform is a linear transform between vertex spaces . Such a transform must be highly localized in the sense that a vertex in the target surface only draws its values from very few source vertices . This function exploits the localization to create an inverse problem for each vertex . The source neighborhoods for each target vertex are found by using mri_surf2surf to transform the three coordinate maps from the source surface to the target surface yielding three coordinate values for each target vertex for which we find the nearest neighbors in the source space . A small number of test images is transformed from source surface to target surface . For each target vertex in the transformed test images a regression is performed using only the corresponding source image neighborhood yielding the entries for a sparse matrix encoding the transform . Parameters ========== source_subj : str Freesurfer name of source subject hemi : str in ( lh rh ) Indicator for hemisphere surface_type : str in ( white pial ... ) Indicator for surface layer target_subj : str default fsaverage Freesurfer name of target subject subjects_dir : str default os . environ [ SUBJECTS_DIR ] The freesurfer subjects directory n_neighbors : int default 20 The size of the neighborhood to take into account when estimating the source support of a vertex random_state : int default 0 Random number generator or seed for generating test images n_test_images : int default 40 Number of test images transformed to compute inverse problem . This should be greater than n_neighbors or equal . coef_treshold : float default 1 / ( 10 * n_neighbors ) Value under which to set a weight to zero in the inverse problem . renormalize : boolean default True Determines whether the rows of the output matrix should add to 1 implementing what is sensible : a weighted averaging Notes ===== It turns out that freesurfer seems to do the following : For each target vertex find on the sphere the nearest source vertices and average their values . Try to be as one - to - one as possible .
function: def get_mri_surf2surf_matrix(source_subj, hemi, surface_type,
                              target_subj='fsaverage', subjects_dir=None,
                              n_neighbors=20, random_state=0,
                              n_test_images=40, coef_threshold=None,
                              renormalize=True):
  
      """Creates a matrix implementing freesurfer mri_surf2surf command.
      
      A surface-to-surface transform is a linear transform between vertex spaces.
      Such a transform must be highly localized in the sense that a vertex in the
      target surface only draws its values from very few source vertices.
      This function exploits the localization to create an inverse problem for 
      each vertex.
      The source neighborhoods for each target vertex are found by using
      mri_surf2surf to transform the three coordinate maps from the source 
      surface to the target surface, yielding three coordinate values for each
      target vertex, for which we find the nearest neighbors in the source space.
      A small number of test images is transformed from source surface to
      target surface.	
      For each target vertex in the transformed test images, a regression is 
      performed using only the corresponding source image neighborhood, yielding
      the entries for a sparse matrix encoding the transform.
      
      Parameters
      ==========
      
      source_subj: str
      	Freesurfer name of source subject
      
      hemi: str in ("lh", "rh")
      	Indicator for hemisphere
      
      surface_type: str in ("white", "pial", ...)
      	Indicator for surface layer
      
      target_subj: str, default "fsaverage"
      	Freesurfer name of target subject
      
      subjects_dir: str, default os.environ["SUBJECTS_DIR"]
      	The freesurfer subjects directory
      
      n_neighbors: int, default 20
      	The size of the neighborhood to take into account when estimating
      	the source support of a vertex
      
      random_state: int, default 0
      	Random number generator or seed for generating test images
      
      n_test_images: int, default 40
      	Number of test images transformed to compute inverse problem. This 
      	should be greater than n_neighbors or equal.
      
      coef_treshold: float, default 1 / (10 * n_neighbors)
      	Value under which to set a weight to zero in the inverse problem.
      
      renormalize: boolean, default True
      	Determines whether the rows of the output matrix should add to 1,
      	implementing what is sensible: a weighted averaging
      
      Notes
      =====
      It turns out that freesurfer seems to do the following: For each target
      vertex, find, on the sphere, the nearest source vertices, and average their
      values. Try to be as one-to-one as possible.
      """
  
      source_verts, _, _ = get_surf(source_subj, hemi, surface_type,
                                    freesurfer_subject_dir=subjects_dir)
  
      transformed_coords = mri_surf2surf(source_verts.T,
                                         source_subj, target_subj, hemi,
                                         subjects_dir=subjects_dir)
  
      kdt = KDTree(source_verts)
      print("Getting nearest neighbors")
      distances, indices = kdt.query(transformed_coords.T, k=n_neighbors)
      print("Done")
  
      rng = (np.random.RandomState(random_state) 
                            if isinstance(random_state, int) else random_state)
      test_images = rng.randn(n_test_images, len(source_verts))
      transformed_test_images = mri_surf2surf(test_images, source_subj,
                                              target_subj, hemi,
                                              subjects_dir=subjects_dir)
  
      # Solve linear problems to get coefficients
      all_coefs = []
      residuals = []
      print("Computing coefficients")
      i = 0
      for target_activation, source_inds in zip(
                                          transformed_test_images.T, indices):
          i += 1
          print("{i}".format(i=i), end="\r")
          source_values = test_images[:, source_inds]
          r = lstsq(source_values, target_activation,
                   overwrite_a=True, overwrite_b=True)
          all_coefs.append(r[0])
          residuals.append(r[1])
      print("Done")
  
      all_coefs = np.array(all_coefs)
  
      if coef_threshold is None:  # we know now that coefs are doing averages
          coef_threshold = (1 / 10. / n_neighbors )
      all_coefs[np.abs(all_coefs) < coef_threshold] = 0
      if renormalize:
          all_coefs /= np.abs(all_coefs).sum(axis=1)[:, np.newaxis] + 1e-10
  
      # there seem to be like 7 vertices that don't constitute an average over
      # 20 vertices or less, but all the others are such an average.
  
      # Let's make a matrix that does the transform:
      col_indices = indices.ravel()
      row_indices = (np.arange(indices.shape[0])[:, np.newaxis] *
                     np.ones(indices.shape[1], dtype='int')).ravel()
      data = all_coefs.ravel()
      shape = (transformed_coords.shape[1], source_verts.shape[0])
  
      matrix = coo_matrix((data, (row_indices, col_indices)), shape=shape)
  
      return matrix
function_tokens: def get_mri_surf2surf_matrix ( source_subj , hemi , surface_type , target_subj = 'fsaverage' , subjects_dir = None , n_neighbors = 20 , random_state = 0 , n_test_images = 40 , coef_threshold = None , renormalize = True ) : source_verts , _ , _ = get_surf ( source_subj , hemi , surface_type , freesurfer_subject_dir = subjects_dir ) transformed_coords = mri_surf2surf ( source_verts . T , source_subj , target_subj , hemi , subjects_dir = subjects_dir ) kdt = KDTree ( source_verts ) print ( "Getting nearest neighbors" ) distances , indices = kdt . query ( transformed_coords . T , k = n_neighbors ) print ( "Done" ) rng = ( np . random . RandomState ( random_state ) if isinstance ( random_state , int ) else random_state ) test_images = rng . randn ( n_test_images , len ( source_verts ) ) transformed_test_images = mri_surf2surf ( test_images , source_subj , target_subj , hemi , subjects_dir = subjects_dir ) # Solve linear problems to get coefficients all_coefs = [ ] residuals = [ ] print ( "Computing coefficients" ) i = 0 for target_activation , source_inds in zip ( transformed_test_images . T , indices ) : i += 1 print ( "{i}" . format ( i = i ) , end = "\r" ) source_values = test_images [ : , source_inds ] r = lstsq ( source_values , target_activation , overwrite_a = True , overwrite_b = True ) all_coefs . append ( r [ 0 ] ) residuals . append ( r [ 1 ] ) print ( "Done" ) all_coefs = np . array ( all_coefs ) if coef_threshold is None : # we know now that coefs are doing averages coef_threshold = ( 1 / 10. / n_neighbors ) all_coefs [ np . abs ( all_coefs ) < coef_threshold ] = 0 if renormalize : all_coefs /= np . abs ( all_coefs ) . sum ( axis = 1 ) [ : , np . newaxis ] + 1e-10 # there seem to be like 7 vertices that don't constitute an average over # 20 vertices or less, but all the others are such an average. # Let's make a matrix that does the transform: col_indices = indices . ravel ( ) row_indices = ( np . arange ( indices . shape [ 0 ] ) [ : , np . newaxis ] * np . ones ( indices . shape [ 1 ] , dtype = 'int' ) ) . ravel ( ) data = all_coefs . ravel ( ) shape = ( transformed_coords . shape [ 1 ] , source_verts . shape [ 0 ] ) matrix = coo_matrix ( ( data , ( row_indices , col_indices ) ) , shape = shape ) return matrix