netneurotools.freesurfer.spin_data

netneurotools.freesurfer.spin_data(data, *, lhannot, rhannot, version='fsaverage', n_rotate=1000, spins=None, drop=None, verbose=False, **kwargs)[source]

Project parcellated data to surface, rotates, and re-parcellates.

Projection to the surface uses {lh,rh}annot files. Rotation uses vertex coordinates from the specified fsaverage version and relies on netneurotools.stats.gen_spinsamples(). Re-parcellated data will not be exactly identical to original values due to re-averaging process. Parcels subsumed by regions in drop will be listed as NaN.

Parameters:

  • data ((N,) numpy.ndarray) – Parcellated data to be rotated. Parcels should be ordered by [left, right] hemisphere; ordering within hemisphere should correspond to the provided {lh,rh}annot annotation files.

  • {lh (str) – Path to .annot file containing labels to parcels on the {left,right} hemisphere

  • rh}annot (str) – Path to .annot file containing labels to parcels on the {left,right} hemisphere

  • version (str, optional) – Specifies which version of fsaverage provided annotation files correspond to. Must be one of {‘fsaverage’, ‘fsaverage3’, ‘fsaverage4’, ‘fsaverage5’, ‘fsaverage6’}. Default: ‘fsaverage’

  • n_rotate (int, optional) – Number of rotations to generate. Default: 1000

  • spins (array_like, optional) – Pre-computed spins to use instead of generating them on the fly. If not provided will use other provided parameters to create them. Default: None

  • drop (list, optional) – Specifies regions in {lh,rh}annot that are not present in data. NaNs will be inserted in place of the these regions in the returned data. If not specified, parcels defined in netneurotools.freesurfer.FSIGNORE are assumed to not be present. Default: None

  • verbose (bool, optional) – Whether to print occasional status messages. Default: False

  • kwargs (key-value pairs) – Keyword arguments passed to netneurotools.stats.gen_spinsamples

Returns:

  • rotated ((N, n_rotate) numpy.ndarray) – Rotated `data

  • cost ((N, n_rotate,) numpy.ndarray) – Cost (specified as Euclidean distance) of re-assigning each coordinate for every rotation in spinsamples. Only provided if return_cost is True.