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 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
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