Skip to content

Utilities API

yabplot.get_atlas_regions(atlas, category, custom_atlas_path=None)

Returns the list of region names for a given atlas in the specific order used for mapping data arrays.

Parameters:

Name Type Description Default
atlas str

Name of the atlas (e.g., 'aparc', 'aseg').

 required
category str

'cortical', 'subcortical', or 'tracts'.

 required
custom_atlas_path str

Path to custom atlas directory.

 None

Returns:

Type Description
list

List of strings containing region names. - If input data is a LIST, it must match this order. - If input data is a DICT, keys must match these names.
Source code in yabplot/data/__init__.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def get_atlas_regions(atlas, category, custom_atlas_path=None):
    """
    Returns the list of region names for a given atlas in the specific order 
    used for mapping data arrays.

    Parameters
    ----------
    atlas : str
        Name of the atlas (e.g., 'aparc', 'aseg').
    category : str
        'cortical', 'subcortical', or 'tracts'.
    custom_atlas_path : str, optional
        Path to custom atlas directory.

    Returns
    -------
    list
        List of strings containing region names. 
        - If input data is a LIST, it must match this order.
        - If input data is a DICT, keys must match these names.
    """

    # resolve the directory path
    try:
        atlas_dir = _resolve_resource_path(atlas, category, custom_path=custom_atlas_path)
    except Exception as e:
        print(f"Error resolving atlas: {e}")
        return []

    # --- case 1: cortical ---
    if category == 'cortical':
        check_name = None if custom_atlas_path else atlas
        try:
            _, lut_path = _find_cortical_files(atlas_dir, strict_name=check_name)

            # use parse_lut to get the IDs and the full names list
            ids, _, names_list, _ = parse_lut(lut_path)

            # return only the names corresponding to the explicit IDs in the file.
            return [names_list[i] for i in ids]

        except Exception as e:
            print(f"Error parsing cortical atlas: {e}")
            return []

    # --- case 2: subcortical ---
    elif category == 'subcortical':
        try:
            file_map = _find_subcortical_files(atlas_dir)
            # the plotting function sorts keys alphabetically
            return sorted(list(file_map.keys()))
        except Exception as e:
            print(f"Error listing subcortical regions: {e}")
            return []

    # --- case 3: tracts ---
    elif category == 'tracts':
        try:
            file_map = _find_tract_files(atlas_dir)
            # the plotting function sorts keys alphabetically
            return sorted(list(file_map.keys()))
        except Exception as e:
            print(f"Error listing tracts: {e}")
            return []

    else:
        raise ValueError("Category must be 'cortical', 'subcortical', or 'tracts'")

yabplot.get_available_resources(category=None)

Returns available resources from the registry.

Parameters:

Name Type Description Default
category str or None

If provided (e.g., 'cortical', 'subcortical', 'tracts', 'bmesh'), returns a list of available names for that specific category. If None, returns a dictionary containing all categories and their options.

 None
Source code in yabplot/data/__init__.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def get_available_resources(category=None):
    """
    Returns available resources from the registry.

    Parameters
    ----------
    category : str or None
        If provided (e.g., 'cortical', 'subcortical', 'tracts', 'bmesh'), returns a list of available names 
        for that specific category.
        If None, returns a dictionary containing all categories and their options.
    """
    if not GOODBOY.registry:
        return [] if category else {}

    # helper to clean names: e.g., "cortical-aparc.zip" -> ("cortical", "aparc")
    def _parse_key(key):
        if "-" not in key: return None, None
        prefix, remainder = key.split("-", 1)
        name = remainder.replace(".zip", "")
        return prefix, name

    # mode 1: specific category
    if category:
        available = []
        for key in GOODBOY.registry.keys():
            prefix, name = _parse_key(key)
            if prefix == category:
                available.append(name)
        return sorted(available)

    # mode 2: all categories
    all_resources = {}
    for key in GOODBOY.registry.keys():
        prefix, name = _parse_key(key)
        if prefix and name:
            if prefix not in all_resources:
                all_resources[prefix] = []
            all_resources[prefix].append(name)

    for k in all_resources:
        all_resources[k].sort()

    return all_resources