Refactoring of coordinate spaces and atlases

[vinaysraghavan]

Currently, the naplib Brain object instantiates hemispheres with the default "atlas" set to FSAverage and loads the automatic parcellation a2009s (?h.aparc.a2009s) labels from the fsaverage subjects folder, which are Destrieux atlas labels.

If the appropriate surface files for fsaverage are not present, then the default behavior attempts to load a .mat file for the surface coordinates and faces, which is assumed to contain coordinates in MNI152 space. In this case, the default parcelation labels loaded are the FSL_MNI152.?h.aparc.split_STG_MTG labels. These appear to be customized Desikan-Killiany atlas labels that include additional splits of the STG and MTG.

The desired behavior is for the user to set both coordinate_space as either FSAverage or MNI152, defaulting to the former, and atlas as Destrieux or Desikan-Killiany, as these are the most commonly available automatic parcellations. By default, FSAverage will default to Destrieux atlas labels and MNI152 to Desikan-Killiany, to minimize change in the current behavior.

Additionally, atlas should be able to take an annotation file name such that the user can specify the annotation file stored as SUBJECT_DIR/SUBJECT/label/?h.{atlas}.annot. This is relevant so that users can control which atlas labels are used for functions such as paint_overlay and annotate_coords.

This is personally relevant so I can use Glasser labels :)
https://figshare.com/articles/dataset/HCP-MMP1_0_projected_on_fsaverage/3498446

[vinaysraghavan]

It appears the FSL_MNI152.?h.aparc.split_STG_MTG.annot files came from here and were additionally mapped to MNI152 with FSL.

These are custom annotations of the Desikan-Killiany, so they could be better handled by the customer atlas loader. However, I don't think MNI152 labels come with any FreeSurfer download. Since the average user probably won't use MNI coordinates on an FSAverage brain (and in the interest of not changing past behavior), I'll set the default use of the MNI152 coordinate space and Desikan-Killiany atlas to the aforementioned custom annotation file. Otherwise, I'll assume users will generally be working with FSAverage coordinates and will load atlas labels accordingly

[gavinmischler]

These are custom annotations of the Desikan-Killiany, so they could be better handled by the customer atlas loader. However, I don't think MNI152 labels come with any FreeSurfer download. Since the average user probably won't use MNI coordinates on an FSAverage brain (and in the interest of not changing past behavior), I'll set the default use of the MNI152 coordinate space and Desikan-Killiany atlas to the aforementioned custom annotation file. Otherwise, I'll assume users will generally be working with FSAverage coordinates and will load atlas labels accordingly

Sounds good. We can just assume the user generally knows what they're doing and won't mix coordinates in a bad way, and for anyone who doesn't have detailed knowledge, the defaults should hit their most general case.