Skip to content

neuroscales/nextbrain-utils

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

16 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

NextBrain utils

NextBrain is a probabilistic atlas of the entire human brain derived from histology images.

Casamitjana, A., Mancini, M., Robinson, E., Peter, L. et al. A probabilistic histological atlas of the human brain for MRI segmentation. Nature (2025). https://doi.org/10.1038/s41586-025-09708-2

It can be used by an accompanying software to segment any brain scan into more than 300 anatomical regions at sub-millimeter resolution.

Puonti, O., Nolan, J., Dicamillo, R., Balbastre, Y., et al. Fast segmentation with the NextBrain histological atlas. bioRxiv (2025). https://doi.org/10.1101/2025.09.22.673638

The NextBrain subcortical labels follow the Allen Brain ontology. The Allen Human Brain Atlas is a reference anatomical atlas of the human brain drawn on a single specimen.

Ding, S.-L., Royall, J.J., Sunkin, S.M., Ng, L. et al. Comprehensive cellular-resolution atlas of the adult human brain. The Journal of Comparative Neurology (2016). https://doi.org/10.1002/cne.24080

The tools provided in this package allow NextBrain label maps to be converted to Allen Brain label maps. It also allows Allen Brain label maps to be simplified by collapsing labels along levels of its ontology.

Combine both NextBrain hemispheres into a single file

nextbrain-utils combine \
    -l seg.left.nii.gz  \
    -r seg.right.nii.gz \
    -o seg.both.nii.gz  \
    -m sides.nii.gz
image

Convert NextBrain labels to Allen labels

nextbrain-utils allen  \
    -i seg.both.nii.gz \
    -o seg.allen.nii.gz

Note that some of the Allen Brain labels are pretty large and cannot be encoded in a 16 bit integer. This means that Freeview does not properly display them, even if an appropriate lookup table is used. As a workaround, "large" Allen labels can be mapped to a lower range. Specifically, we

  • map the range [146035001, 146035199] to [1, 199]
  • map the range [146034600, 146034999] to [600, 999]
  • map the range [266441000, 266441999] to [3000, 3999]
  • map the range [267499000, 267499999] to [9000, 9999]
nextbrain-utils allen   \
    -i seg.both.nii.gz  \
    -o seg.allen.nii.gz \
    -s16
image

By default, this function approximately maps the Desikan-Killiany cortical labels generated by Freesurfer/NextBrain to Allen's gyral labels. It uses the following mapping:


2000  ctx-unknown                   ->     12112  cerebral gyri and lobules
2001  ctx-bankssts                  ->     12112  cerebral gyri and lobules
2002  ctx-caudalanteriorcingulate   ->     12158  cingulate gyrus, caudal (posterior) part
2003  ctx-caudalmiddlefrontal       ->     12116  middle frontal gyrus
2005  ctx-cuneus                    ->     12150  cuneus
2006  ctx-entorhinal                ->     12163  anterior parahippocampal gyrus
2007  ctx-fusiform                  ->     12152  occipitotemporal (fusiform) gyrus, occipital part
2008  ctx-inferiorparietal          ->     12134  inferior parietal lobule
2009  ctx-inferiortemporal          ->     12142  inferior temporal gyrus
2010  ctx-isthmuscingulate          ->     12158  cingulate gyrus, caudal (posterior) part
2011  ctx-lateraloccipital          ->     12148  occipital lobe
2012  ctx-lateralorbitofrontal      ->     12125  lateral orbital gyrus
2013  ctx-lingual                   ->     12151  lingual gyrus
2014  ctx-medialorbitofrontal       ->     12121  gyrus rectus (straight gyrus)
2015  ctx-middletemporal            ->     12141  middle temporal gyrus
2016  ctx-parahippocampal           ->     12164  posterior parahippocampal gyrus
2017  ctx-paracentral               ->     12138  paracentral lobule, rostral part
2018  ctx-parsopercularis           ->     12119  inferior frontal gyrus, opercular part
2019  ctx-parsorbitalis             ->     12120  inferior frontal gyrus, orbital part
2020  ctx-parstriangularis          ->     12118  inferior frontal gyrus, triangular part
2021  ctx-pericalcarine             ->     12148  occipital lobe
2022  ctx-postcentral               ->     12132  postcentral gyrus
2023  ctx-posteriorcingulate        ->     12158  cingulate gyrus, caudal (posterior) part
2024  ctx-precentral                ->     12114  precentral gyrus
2025  ctx-precuneus                 ->     12137  precuneus
2026  ctx-rostralanteriorcingulate  ->     12157  cingulate gyrus, rostral (anterior) part
2027  ctx-rostralmiddlefrontal      ->     12116  middle frontal gyrus
2028  ctx-superiorfrontal           ->     12115  superior frontal gyrus
2029  ctx-superiorparietal          ->     12133  supraparietal lobule
2030  ctx-superiortemporal          ->     12140  superior temporal gyrus
2031  ctx-supramarginal             ->     12135  supramarginal gyrus
2032  ctx-frontalpole               -> 146034888  frontal pole
2033  ctx-temporalpole              ->     12146  temporal pole
2034  ctx-transversetemporal        ->     12144  transverse temporal gyrus (Heschl's gyrus)
2035  ctx-insula                    ->     12176  insular lobe

This mapping is imperfect and cannot be totally trusted. It is possible to preserve the Desikan-Killiany labels (IDs in range [2000, 2035]).

nextbrain-utils allen   \
    -i seg.both.nii.gz  \
    -o seg.allen.nii.gz \
    -c dk
image

Alternatively, the Desikan-Killiany labels can be collapsed into coarse "developmental" cortical regions.

nextbrain-utils allen   \
    -i seg.both.nii.gz  \
    -o seg.allen.nii.gz \
    -c dev
image

This uses the following mapping:

10160   neocortex (isocortex)   <- 2000  ctx-unknown

10161   frontal neocortex       <- 2003  ctx-caudalmiddlefrontal
                                <- 2012  ctx-lateralorbitofrontal
                                <- 2014  ctx-medialorbitofrontal
                                <- 2017  ctx-paracentral
                                <- 2018  ctx-parsopercularis
                                <- 2019  ctx-parsorbitalis
                                <- 2020  ctx-parstriangularis
                                <- 2024  ctx-precentral
                                <- 2027  ctx-rostralmiddlefrontal
                                <- 2028  ctx-superiorfrontal
                                <- 2032  ctx-frontalpole

10208   parietal neocortex      <- 2008  ctx-inferiorparietal
                                <- 2022  ctx-postcentral
                                <- 2025  ctx-precuneus
                                <- 2029  ctx-superiorparietal
                                <- 2031  ctx-supramarginal

10235   temporal neocortex      <- 2001  ctx-bankssts
                                <- 2007  ctx-fusiform
                                <- 2009  ctx-inferiortemporal
                                <- 2015  ctx-middletemporal
                                <- 2030  ctx-superiortemporal
                                <- 2033  ctx-temporalpole
                                <- 2034  ctx-transversetemporal

10268   occipital neocortex     <- 2005  ctx-cuneus
                                <- 2011  ctx-lateraloccipital
                                <- 2013  ctx-lingual
                                <- 2021  ctx-pericalcarine

10288   insular neocortex       <- 2035  ctx-insula

10314   periarchicortex         <- 2006  ctx-entorhinal
                                <- 2016  ctx-parahippocampal

Simplify an Allen segmentation map

nextbrain-utils simplify \
    -i seg.allen.nii.gz  \
    -o seg.simple.nii.gz \
    -l AMY ATA EXA Ca Pu NAC GP Cla BF THM SubTH HTH HIP

The list of labels to collapse can be long names, acronyms or IDs from the Allen ontology. If the Allen map uses S16-compatible labels, please use the -s16 option here as well.

Then Allen ontology can br browsed online:

image

Convert NextBrain labels to ASeg+AParc labels

nextbrain-utils aseg         \
    -i seg.both.nii.gz       \
    -o seg.aseg.aparc.nii.gz \
    -s sides.nii.gz
image

An ASeg label map contains the following labels (+ the AParc/Desikan-Killiany labels):

0   Unknown                                 0   0   0   0
2   Left-Cerebral-White-Matter              245 245 245 0
3   Left-Cerebral-Cortex                    205 62  78  0
4   Left-Lateral-Ventricle                  120 18  134 0
5   Left-Inf-Lat-Vent                       196 58  250 0
7   Left-Cerebellum-White-Matter            220 248 164 0
8   Left-Cerebellum-Cortex                  230 148 34  0
10  Left-Thalamus                           0   118 14  0
11  Left-Caudate                            122 186 220 0
12  Left-Putamen                            236 13  176 0
13  Left-Pallidum                           12  48  255 0
14  3rd-Ventricle                           204 182 142 0
15  4th-Ventricle                           42  204 164 0
16  Brain-Stem                              119 159 176 0
17  Left-Hippocampus                        220 216 20  0
18  Left-Amygdala                           103 255 255 0
24  CSF                                     60  60  60  0
26  Left-Accumbens-area                     255 165 0   0
28  Left-VentralDC                          145 42  42  0
41  Right-Cerebral-White-Matter             245 245 245 0
42  Right-Cerebral-Cortex                   205 62  78  0
43  Right-Lateral-Ventricle                 120 18  134 0
44  Right-Inf-Lat-Vent                      196 58  250 0
46  Right-Cerebellum-White-Matter           220 248 164 0
47  Right-Cerebellum-Cortex                 230 148 34  0
49  Right-Thalamus                          0   118 14  0
50  Right-Caudate                           122 186 220 0
51  Right-Putamen                           236 13  176 0
52  Right-Pallidum                          13  48  255 0
53  Right-Hippocampus                       220 216 20  0
54  Right-Amygdala                          103 255 255 0
58  Right-Accumbens-area                    255 165 0   0
60  Right-VentralDC                         165 42  42  0

Convert NextBrain labels to SuperSynth labels

nextbrain-utils supersynth   \
    -i seg.both.nii.gz       \
    -o seg.supersynth.nii.gz \
    -s sides.nii.gz
image

A SuperSynth label map contains the following labels:

0       Unknown                                 0   0   0   0
2       Left-Cerebral-White-Matter              245 245 245 0
3       Left-Cerebral-Cortex                    205 62  78  0
4       Left-Lateral-Ventricle                  120 18  134 0
5       Left-Inf-Lat-Vent                       196 58  250 0
7       Left-Cerebellum-White-Matter            220 248 164 0
8       Left-Cerebellum-Cortex                  230 148 34  0
10      Left-Thalamus                           0   118 14  0
11      Left-Caudate                            122 186 220 0
12      Left-Putamen                            236 13  176 0
13      Left-Pallidum                           12  48  255 0
14      3rd-Ventricle                           204 182 142 0
15      4th-Ventricle                           42  204 164 0
16      Brain-Stem                              119 159 176 0
17      Left-Hippocampus                        220 216 20  0
18      Left-Amygdala                           103 255 255 0
26      Left-Accumbens-area                     255 165 0   0
41      Right-Cerebral-White-Matter             245 245 245 0
42      Right-Cerebral-Cortex                   205 62  78  0
43      Right-Lateral-Ventricle                 120 18  134 0
44      Right-Inf-Lat-Vent                      196 58  250 0
46      Right-Cerebellum-White-Matter           220 248 164 0
47      Right-Cerebellum-Cortex                 230 148 34  0
49      Right-Thalamus                          0   118 14  0
50      Right-Caudate                           122 186 220 0
51      Right-Putamen                           236 13  176 0
52      Right-Pallidum                          13  48  255 0
53      Right-Hippocampus                       220 216 20  0
54      Right-Amygdala                          103 255 255 0
58      Right-Accumbens-area                    255 165 0   0
77      WM-hypointensities                      200 70  255 0
85      Optic-Chiasm                            234 169  30 0
99      Lesion                                  255 165 0   0
# sclimbic
819     Left-HypoThal-noMB                      0   80  0   0   2
820     Right-HypoThal-noMB                     15  165 15  0   2
821     Left-Fornix                             0   255 255 0   3
822     Right-Fornix                            27  187 253 0   3
843     Left-MammillaryBody                     178 255 80  0   2
844     Right-MammillaryBody                    25  246 80  0   2
865     Left-Basal-Forebrain                    170 85  0   0   2
866     Right-Basal-Forebrain                   139 69  19  0   2
869     Left-SeptalNuc                          255 170 255 0   2
870     Right-SeptalNuc                         191 127 191 0   2

Generate an Allen lookup table compatible with Freesurfer

nextbrain-utils lut      \
    -o AllenBrainLUT.txt \
    -l allen+dk

By default, this lookup table uses long names for each region. Acronyms can be used instead.

nextbrain-utils lut      \
    -o AllenBrainLUT.txt \
    -l allen+dk          \
    -a

If S16-compatible labels are used, use the -s16 option here as well.

nextbrain-utils lut      \
    -o AllenBrainLUT.txt \
    -l allen+dk          \
    -s16

The ASeg and SuperSynth label maps can be displayed using the default freesurfer lookup table. Nonetheless, compact lookup tables that only contain labels present in a ASeg+AParc or SuperSynth label map can be generated. Possible LUT options are

  • allen : Labels from the Allen Brain developmental ontology
  • allen+dk : Allen + append Desikan-Killiany cortical labels
  • nextbrain : NextBrain
  • aseg : ASeg+AParc/SynthSeg
  • supersynth : SuperSynth
  • supersynth-cerebrum : SuperSynth (cerebrum mode)
  • supersynth-exvivo : SuperSynth (exvivo mode)
  • freesurfer : Complete FreeSurfer colormap

About

A few utility tools to work with NextBrain segmentations

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages