Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

GitHub issues GitHub pull-requests GitHub contributors GitHub Commits GitHub size GitHub HitCount

Parcellation Fragmenter

Fragments FreeSurfer parcellation annotation in N-equal sized parcels. Besides looking beautiful, such surface parcellation could be used as feature extract for machine learning approaches or similar.

The current version takes either the whole FreeSurfer surface and devides it into N equal sized parcels or it takes a predefined region of interest (ROI), specified by FreeSurfer's aparc.annot file and fragments this region in N equal sized parcels.

The parcellation can be done by using a Gaussian Mixed Model, a Ward or a K-Means approach.

The following figure shows an example of a whole surface fragmentation for 16, 64, 256, 1024, 4096 parcels using a Gaussian Mixed Models approach:

The following figure shows an example of a fragmentation of the superior temporal cortex for 4, 16, 64, 256, 1024 using a K-Means approach:

How to install it

git clone
cd ./parcellation_fragmenter
pip install -e .

How to run it

Note: For a detailed walk-through of how to use the code, see ./notebooks/Demo.ipynb.

import nibabel as nb # for loading surfaces
from fragmenter import RegionExtractor # for extracting regional indices
from fragmenter import Fragment # main fragmentation class
from fragmenter import colormaps # for generating new colormaps

# Define surface file and annotation file.
# If you are using Gifti-structured data, use ```nb.load()``` instead,
# the vertices and faces will exists as GiftiDataArrays objects
verts, faces =

# Extract region-specific indices
# Likewise, you can also specific an HCP-styped Gifti Label object
# with extension .label.gii.
E = RegionExtractor.Extractor(
parcels = E.map_regions()

# Define set of regions of interest.  These region names are dependent
# on the region IDs in the original annotation / label file.
  'superiortemporal', 'transversetemporal','bankssts',
# Instantiate the fragmentation object and generate the sub-regions.
temporal = Fragment.Fragment(n_clusters=75), faces=faces,
  parcels=parcel_maps, rois=rois, size=15)

# If you want to generate pretty color-scheme with a gradient along the
# inferior-superior axis, do the following:
[_, ctab, names, remapped] = colormaps.get_ctab_and_names(verts,
plotting.view_surf([verts, faces],
  remapped, threshold=0.1, cmap='plasma')

# We can then save the map with:
annot_name = '../data/freesurfer/fsaverage/label/lh.temporal.annot'

How to help with it

There are still many things that can be changed/adapted/added. So please feel free to check-out the issues section for what can be done, fork the project, send me a PR or give us a feedback!


This project is licensed under BSD 3-Clause License.



Fragments FreeSurfer parcellation annotation in N-equal sized parcels







No releases published


No packages published