[BUG] Improving brain atlases and standardize them

[mtorabi59]

Is there an existing issue for this?

• I have searched the existing issues

Operating system

• Linux
• Mac
• Windows

Operating system version

Mac OS Version 13.4

Python version

• 3.12
• 3.11
• 3.10
• 3.9
• 3.8

nilearn version

0.10.3

Expected behavior

Me and @Remi-Gau found out that a couple of nilearn atlases may benefit from some standardization and some of them even have inconsistencies.
Specifically:

• Schaefer atlas:
  1. the region names list is in byte string format, it'd be better if they were in string format
  2. labels_img is filled with float values instead of integers, i.e. region ids are float numbers.
• AAL atlas:
  1. the region ids (the numbers filling the labels_img) start from 2001 instead of 1 and are not consecutive numbers
• Destrieux atlas:
  1. The number of region names (151) does not match with the number of region ids (148), i.e. there are regions that do not exist in labels_img even without masking or resampling
  2. region names are a list of tuples like (id, name) instead of being only a string containing the name of the region.

Moreover, it seems the list of region names in all atlases includes "background" except AAL and Schaefer. For some atlases the name considered for background is different, e.g. "bg" or "Background"

@Remi-Gau feel free to add to the list

Current behavior & error messages

NA

Steps and code to reproduce bug

NA

[Remi-Gau]

from #4329

• ensuring that nilearn atlases have a "standardized" data structure
  (for example that each fetcher returns a list of labels as a list of strings)
• checking the label types passed to the constructor of NiftiLabelMasker
  and throw errors if they do not pass
  instead of warnings like they do here.

Originally posted by @Remi-Gau in #4289 (comment)

---

Even though working on this should fix #4330 and #4331, it will change what it returned by some of the fetchers (some even if not an API change, it would be a behavior change that should probably go through a deprecation cycle - not 100% about this).

For example, the Destrieux fetcher would return 'labels' as list of strings and not a numpy.recarray containing the names of the ROIs.

So this feels like a bit of an "invasive" change to include into 0.10.4 that should be a bug fix release. So I suggest making that change after 0.10.4 is out.

Note that the list of labels should also include "background" (or "Background")

Was checking on the templateFlow atlases and not all of them explicitly includes "background" in their list of labels so I would not make this required for Nilearn list of labels (for example by throwing an error if a user passed a list of labels to NiftiLabelMasker that did not include "background").

---

@bthirion said

Indeed, we need to go through deprecation cycles for that one.

---

@man-shu said

IIUC, going through the deprecation cycle would involve warning users about the changes for a few releases before actually inteoducing them?

[Remi-Gau]

going through the deprecation cycle would involve warning users about the changes for a few releases before actually introducing them

Yes exactly we usually have deprecation warnings for 2 releases before the deprecation comes in effect. So if the a "breaking" change appears in 0.11, people's code will still "work" until 0.13 but they will get a warning that should tell them what to do to not adapt their code.

[Remi-Gau]

See old issues / PRs about this:

• Harvard-Oxford atlas: some atlases have wrong number of labels #2036
• correspondance between atlas region labels and NiftiLabelsMasker's output dimensions #3085
• [FIX] Fix labels HarvardOxford fetcher #3080
• [wip] Harmonize datasets.fetch_atlas output attributes  #2037