Let users easily fetch atlases

[khoffschlag]

This could be done via nilearn (https://nilearn.github.io/stable/modules/datasets.html?highlight=datasets#module-nilearn.datasets).

[spisakt]

An atlas can be defined usually by two things:

• labelmap: nifit file where intensity encodes the rois
• labels text file: the file assigning the region names (and optionally other infos) to intensities in the labelmap

PUMI will provide an extra, optional feature: atlas modularization

• module_labelmap: another labelmap with large scale modules (e.g. 7 resting state networks)
• module_labels: the label file for with the name of the modules
  This is just reordering the labels in the labelmap and the labels file so that subsequent regions belong to the same module.
  Now, in a specific case, this is solved like this:
  

  PUMI/PUMI/utils.py

  Line 728 in a41e43b

  def relabel_atlas(atlas_file, modules, labels):

  
  But we need a more general solution: computing the overlap between all regions and modules and assignining each region to the module with the highest overlap (dice coefficient?).

To implement all there, many designs are possible but a possible design could be that we have two small pumi moduels ( with @GroupPipeline decorator)

fetch_atlas:

• we specify (in decorator arguments) which atlas we need, which can be the name of a "built-in" atlas or (optionally) a path to a custom atlas labelmap and label text file
  "built-in" atlases:
  • PUMI-MIST-XXX where XXX is the number of regions. The whole MIST atlas is delivered with PUMI
  • NOTE: this actually might be liuterally the same atlas as 'basc_multiscale_2015'. If this is the case, we can fully rely on nilearn and do not have to deliver this atlas with PUMI.
  • all nilearn atlases: name is based on the nilearn function name (without fetch_atlas). It fetches the atlas and convert everything to a standard format if needed. Probbaly it writes out (sinks) the files.
  • all extra nilearn parameteres could be kwargs-like parameters or simply a decorator parameter of type dict, which provides the neccessary infos.
• output fields: labelmap, labels

modularize_atlas

• this is an optional step in the workflow, it has the following decorator inputs: labelmap, labels, module_labelmap, module_labels
• it is supposed to receive the outputs of two 'fetch_atlas'-es
• it does the modularization, i.e. the reordering of labels, so that they reflect the bigger modules

Example usages:

fetch_atlas -> extract_timeseries

fetch_atlas   \
                    modularize_atlas -> extract_timeseries
fetch_atlas   /

NOTE:

Now we use the pick_atlas pipeline. This will be substituted by the new functions., but it can be used as an example.

Step-by-step todo list:

• implement only 'fetch_atlas' in a file PUMI/pipelines/multimodel/atlas.py and an example scipt (in the folder 'examples'), with wich all nilearn atlases can be tested
• test it with various atlases
• see if 'basc_multiscale_2015' == MIST (as delivered in the data_in folder)
• test if the RPN-signature works if 'pick_atlas' is substituted with fetch_atlas
• implement modularize_atlas
• port RPN-signature to the new implementattion (fetch -> modularize), check if output stays the same
• remove the old 'pick_atlas' and all related functions