Skip to content

api.common.data_handlers

compounds

download

download_all(space_id, parcellation_id, region_id=None, feature_id=None)

Create a download bundle (zip) for the provided specification

Parameters:

Name Type Description Default
space_id str

lookup id of the space requested

 required
parcellation_id str

lookup_id of the parcellation requested

 required
region_id str

lookup_id of the region requested

 None

Returns:

Type Description
str

Path to the zip file
Source code in api/common/data_handlers/compounds/download.py 
 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
 72
 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
@data_decorator(ROLE)
def download_all(space_id: str, parcellation_id: str, region_id: str=None, feature_id: str=None) -> str:
    """Create a download bundle (zip) for the provided specification

    Args:
        space_id: lookup id of the space requested
        parcellation_id: lookup_id of the parcellation requested
        region_id: lookup_id of the region requested

    Returns:
        Path to the zip file

    """
    zipfilename = Path(SIIBRA_API_SHARED_DIR, f"atlas-download-{str(uuid4())}.zip")

    import siibra
    from api.serialization.util import instance_to_model
    from siibra.core import space as _space, parcellation as _parcellation, concept as _concept

    with ZipFile(zipfilename, "w") as zipfile:

        if feature_id:
            try:
                path_to_feature_export = Path(SIIBRA_API_SHARED_DIR, f"export-{feature_id}.zip")
                if not path_to_feature_export.exists():
                    feature = siibra.features.Feature._get_instance_by_id(feature_id)
                    feature.to_zip(path_to_feature_export)
                zipfile.write(path_to_feature_export, f"export-{feature_id}.zip")
            except Exception as e:
                zipfile.writestr(f"{feature_id}.error.txt", f"Feature exporting failed: {str(e)}")

        def write_model(filename, obj, **kwargs):
            try:
                zipfile.writestr(filename, instance_to_model(obj, **kwargs).json(indent=2))
            except Exception as e:
                zipfile.writestr(f"{filename}.error.txt", str(e))

        def write_desc(filename, obj, **kwargs):
            if isinstance(obj, _concept.AtlasConcept):
                try:
                    publications = "\n\n".join([f"[{p.get('citation', 'url')}]({p.get('url')})"
                                                if p.get('url')
                                                else p.get("citation", "CITATION")
                                                for p in obj.publications])
                    desc_str = DESC.format(name=obj.name, description=obj.description, citations=publications)
                    zipfile.writestr(filename, desc_str)
                except Exception as e:
                    zipfile.writestr(f"{filename}.error.txt", str(e))


        readme_txt = README.format(siibra_api_version=__version__,
                                   timestamp=str(datetime.now()),
                                   injected_content=f"space_id={space_id}, parcellation_id={parcellation_id}, region_id={region_id}")
        zipfile.writestr("README.md", readme_txt)
        zipfile.writestr("LICENCE.txt", LICENSE)
        try:
            space_filename = None

            space: _space.Space = siibra.spaces[space_id]
            space_filename = f"{space.key}.nii.gz"

            # this should fetch anything (surface, nifti, ng precomputed)
            space_vol = space.get_template().fetch()
            zipfile.writestr(space_filename, gzip.compress(space_vol.to_bytes()))
            write_desc(f'{space_filename}.info.md', space)
        except Exception as e:
            zipfile.writestr(f"{space_filename or 'UNKNOWN_SPACE'}.error.txt", str(e))


        if not region_id:
            try:
                parc_filename = None
                space: _space.Space = siibra.spaces[space_id]
                parcellation: _parcellation.Parcellation = siibra.parcellations[parcellation_id]
                parc_filename = f"{parcellation.key}.nii.gz"

                parc_vol = parcellation.get_map(space, siibra.MapType.LABELLED).fetch()
                zipfile.writestr(parc_filename, gzip.compress(parc_vol.to_bytes()))
                write_desc(f'{parc_filename}.info.md', parcellation)
            except Exception as e:
                zipfile.writestr(f"{parc_filename or 'UNKNOWN_PARCELLATION'}.error.txt", str(e))


        if region_id:
            try:
                region_filename = None
                space: _space.Space = siibra.spaces[space_id]
                region = siibra.get_region(parcellation_id, region_id)
                region_filename = f"{region.key}.nii.gz"
                regional_map = region.get_regional_map(space, siibra.MapType.STATISTICAL).fetch()
                zipfile.writestr(region_filename, gzip.compress(regional_map.to_bytes()))
                write_desc(f'{region_filename}.info.md', region)
            except Exception as e:
                zipfile.writestr(f"{region_filename or 'UNKNOWN_REGION'}.error.txt", str(e))


    return str(zipfilename)

core

atlas

all_atlases()

Get all atlases

Returns:

Type Description
List[Dict]

List of all serialized atlases.
Source code in api/common/data_handlers/core/atlas.py 
 5
 6
 7
 8
 9
10
11
12
13
@data_decorator(ROLE)
def all_atlases() -> List[Dict]:
    """Get all atlases

    Returns:
        List of all serialized atlases."""
    import siibra
    from api.serialization.util import instance_to_model
    return [instance_to_model(atlas).dict() for atlas in siibra.atlases]

single_atlas(atlas_id)

Get a single atlas

Parameters:

Name Type Description Default
atlas_id str

id of the atlas

 required

Returns:

Type Description
Dict

The atlas specified by the provided id, serialized into dict
Source code in api/common/data_handlers/core/atlas.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@data_decorator(ROLE)
def single_atlas(atlas_id: str) -> Dict:
    """Get a single atlas

    Args:
        atlas_id: id of the atlas

    Returns:
        The atlas specified by the provided id, serialized into dict
    """
    import siibra
    from api.serialization.util import instance_to_model
    atlas = siibra.atlases[atlas_id]
    return instance_to_model(atlas).dict()

parcellation

all_parcellations()

Get all parcellations

Returns:

Type Description

List of all serialized parcellations
Source code in api/common/data_handlers/core/parcellation.py 
 4
 5
 6
 7
 8
 9
10
11
12
@data_decorator(ROLE)
def all_parcellations():
    """Get all parcellations

    Returns:
        List of all serialized parcellations"""
    import siibra
    from api.serialization.util import instance_to_model
    return [instance_to_model(parc).dict() for parc in siibra.parcellations]

single_parcellation(parc_id)

Get a single parcellation

Parameters:

Name Type Description Default
parc_id str

id of the parcellation

 required

Returns:

Type Description

The parcellation specified by the provided id, serialized into dict
Source code in api/common/data_handlers/core/parcellation.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@data_decorator(ROLE)
def single_parcellation(parc_id: str):
    """Get a single parcellation

    Args:
        parc_id: id of the parcellation

    Returns:
        The parcellation specified by the provided id, serialized into dict
    """
    import siibra
    from api.serialization.util import instance_to_model
    return instance_to_model(
        siibra.parcellations[parc_id]
    ).dict()

region

all_regions(parcellation_id, find=None)

Get all regions, categorised under the parcellation specified by parcellation_id, optionally filtered by find.

Parameters:

Name Type Description Default
parcellation_id str

id of the parcellation, under which regions will be fetched

 required
find str

string to search for

 None

Returns:

Type Description
List

List of all serialized regions
Source code in api/common/data_handlers/core/region.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
@data_decorator(ROLE)
def all_regions(parcellation_id: str, find:str=None) -> List:
    """Get all regions, categorised under the parcellation specified by `parcellation_id`, optionally filtered by find.

    Args:
        parcellation_id: id of the parcellation, under which regions will be fetched
        find: string to search for

    Returns:
        List of all serialized regions"""
    import siibra
    from api.serialization.util import instance_to_model
    parc = siibra.parcellations[parcellation_id]
    regions = [r for r in (parc.find(find) if find else parc) ]
    return [instance_to_model(r).dict() for r in regions if r is not parc]

Get related regions, including the relationship qualification.

Parameters:

Name Type Description Default
parcellation_id str

id of the parcellation, under which the regions will be fetched

 required
region_id str

lookup id of the region

 required

Returns:

Type Description

List of RegionalRelationshipAssessments, serialized
Source code in api/common/data_handlers/core/region.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
@data_decorator(ROLE)
def get_related_regions(parcellation_id: str, region_id: str):
    """Get related regions, including the relationship qualification.

    Args:
        parcellation_id: id of the parcellation, under which the regions will be fetched
        region_id: lookup id of the region

    Returns:
        List of RegionalRelationshipAssessments, serialized"""
    import siibra
    from api.serialization.util import instance_to_model

    region = siibra.get_region(parcellation_id, region_id)
    all_assessments = [ass for ass in region.get_related_regions()]
    return [instance_to_model(ass).dict() for ass in all_assessments]

single_region(parcellation_id, region_id, space_id=None)

Get a single region, categorised under parcellation specified by parcellation_id, defined by region_id.

If space_id optional parameter is supplied, additional information about the region in the space will also be returned.

Parameters:

Name Type Description Default
parcellation_id str

id of the parcellation, under which the regions will be fetched

 required
region_id str

lookup id of the region

 required
space_id str

additional information about the region in the provided space

 None

Returns:

Type Description

The region, specified by the criteria, serialized.
Source code in api/common/data_handlers/core/region.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
@data_decorator(ROLE)
def single_region(parcellation_id: str, region_id: str, space_id: str=None):
    """Get a single region, categorised under parcellation specified by `parcellation_id`, defined by `region_id`.

    If space_id optional parameter is supplied, additional information about the region in the space will also be returned.

    Args:
        parcellation_id: id of the parcellation, under which the regions will be fetched
        region_id: lookup id of the region
        space_id: additional information about the region in the provided space

    Returns:
        The region, specified by the criteria, serialized."""
    import siibra
    from api.serialization.util import instance_to_model

    space = siibra.spaces[space_id] if space_id else None
    return instance_to_model(
        siibra.get_region(parcellation_id, region_id),
        space=space
    ).dict()

space

all_spaces()

Get all spaces

Returns:

Type Description
List

List of all serialized spaces.
Source code in api/common/data_handlers/core/space.py 
 5
 6
 7
 8
 9
10
11
12
13
@data_decorator(ROLE)
def all_spaces() -> List:
    """Get all spaces

    Returns:
        List of all serialized spaces."""
    import siibra
    from api.serialization.util import instance_to_model
    return [instance_to_model(space).dict() for space in siibra.spaces]

single_space(space_id)

Get a single space

Parameters:

Name Type Description Default
space_id str

lookup id of the space

 required

Returns:

Type Description
Dict

The space specified by the provided id, serialized into Dict
Source code in api/common/data_handlers/core/space.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@data_decorator(ROLE)
def single_space(space_id: str) -> Dict:
    """Get a single space

    Args:
        space_id: lookup id of the space

    Returns:
        The space specified by the provided id, serialized into Dict"""
    import siibra
    from api.serialization.util import instance_to_model
    return instance_to_model(
        siibra.spaces[space_id]
    ).dict()

features

types

all_feature_types()

Get all feature types

Returns:

Type Description
List[Dict[str, str]]

List of all features, including their name, and inheritance from Feature
Source code in api/common/data_handlers/features/types.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
@data_decorator(ROLE)
def all_feature_types() -> List[Dict[str, str]]:
    """Get all feature types

    Returns:
        List of all features, including their name, and inheritance from Feature"""
    from siibra.features import Feature


    def get_hierarchy_type(Cls: Type[Any]) -> str:
        """Get inherited class in the form of `Feature.{LessGenericCls}.{SpecificCls}.{Cls}`

        Args:
            Cls: subclass of Feature

        Returns:
            string representing class hierarchy"""
        return ".".join([
            BaseCls.__name__
            for BaseCls in Cls.__mro__
            if issubclass(BaseCls, Feature)
        ][::-1])

    return [
        {
            'name': get_hierarchy_type(Cls),
            'category': Cls.category,
        } for Cls in Feature._SUBCLASSES
    ]

vocabularies

gene

get_genes(find=None)

Get all genes

Returns:

Type Description

List of the genes.
Source code in api/common/data_handlers/vocabularies/gene.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
@data_decorator(ROLE)
def get_genes(find:str=None):
    """Get all genes

    Args:
        string to find in vocabularies

    Returns:
        List of the genes."""
    from api.serialization.util.siibra import GENE_NAMES

    if find == None:
        return_list = [v for v in GENE_NAMES]
    else:
        return_list = GENE_NAMES.find(find)

    return [GeneModel(
        symbol=v.get("symbol"),
        description=v.get("description")
        ).dict() for v in return_list]

volumes

parcellationmap

cache_region_statistic_map(parcellation_id, region_id, space_id)

Retrieve and save regional statistical map (if necessary), and then return the path of the map.

Parameters:

Name Type Description Default
parcellation_id str

lookup id of the parcellation of the map

 required
region_id str

lookup id of the region of the map

 required
space_id str

lookup id of the space of the map

 required

Returns:

Type Description
Tuple[str, bool]

path to statistical map, if a cached file is returned
Source code in api/common/data_handlers/volumes/parcellationmap.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def cache_region_statistic_map(parcellation_id: str, region_id: str, space_id: str) -> Tuple[str, bool]:
    """Retrieve and save regional statistical map (if necessary), and then return the path of the map.

    Args:
        parcellation_id: lookup id of the parcellation of the map
        region_id: lookup id of the region of the map
        space_id: lookup id of the space of the map

    Returns:
        path to statistical map, if a cached file is returned
    """
    import os
    full_filename = get_filename("statistical_map", parcellation_id, region_id, space_id, ext=".nii.gz")
    if os.path.isfile(full_filename):
        return full_filename, True

    import siibra
    import nibabel as nib
    error_text = f"Map with parc id '{parcellation_id}', space id '{space_id}'"

    stat_map = siibra.get_map(parcellation_id, space_id, siibra.MapType.STATISTICAL)
    assert stat_map is not None, f"{error_text} returns None"

    volume_data = stat_map.fetch(region=region_id)

    error_text = f"{error_text}, with region_id '{region_id}'"
    assert isinstance(volume_data, nib.Nifti1Image), f"{error_text}, volume provided is not of type Nifti1Image"

    nib.save(volume_data, full_filename)
    import json
    import time
    with open(f"{full_filename}.{str(int(time.time()))}.json", "w") as fp:
        json.dump({
            "prefix": "statistical_map",
            "parcellation_id": parcellation_id,
            "region_id": region_id,
            "space_id": space_id,
        }, fp=fp, indent="\t")
    return full_filename, False

get_map(parcellation_id, space_id, maptype)

Get a map instance, based on specification

Parameters:

Name Type Description Default
parcellation_id str

lookup id of the parcellation of the map

 required
space_id str

lookup id of the space of the map

 required
maptype Union[MapType, str]

maptype, either LABELLED or STATISTICAL

 required

Returns:

Type Description
Dict

Requested map instance, serialized into dict

Raises:

Type Description
AssertionError

if the supplied maptype is invalid type
NotFound

Map with the specification not found
Source code in api/common/data_handlers/volumes/parcellationmap.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
@data_decorator(ROLE)
def get_map(parcellation_id: str, space_id: str, maptype: Union[MapType, str]) -> Dict:
    """Get a map instance, based on specification

    Args:
        parcellation_id: lookup id of the parcellation of the map
        space_id: lookup id of the space of the map
        maptype: maptype, either LABELLED or STATISTICAL

    Returns:
        Requested map instance, serialized into dict

    Raises:
        AssertionError: if the supplied maptype is invalid type
        NotFound: Map with the specification not found
    """
    import siibra
    from api.serialization.util import instance_to_model

    maptype_string = None
    # check maptype name and value both matches
    if isinstance(maptype, MapType):
        assert maptype.name == maptype.value, f"str enum, expecting .name and .value to equal"
        maptype_string = maptype.name
    if isinstance(maptype, str):
        maptype_string = maptype

    assert maptype_string is not None, f"maptype is neither MapType nor str"

    siibra_maptype = siibra.MapType[maptype_string]
    assert siibra_maptype.name == maptype_string, f"Expecting maptype.name to match"

    returned_map = siibra.get_map(parcellation_id, space_id, siibra_maptype)

    if returned_map is None:
        raise NotFound

    return instance_to_model(
        returned_map
    ).dict()

get_parcellation_labelled_map(parcellation_id, space_id, region_id=None)

Retrieve and save labelled map / regional mask (if necessary), and then return the path of the map.

Parameters:

Name Type Description Default
parcellation_id str

lookup id of the parcellation of the map

 required
region_id str

lookup id of the region of the map

 None
space_id str

lookup id of the space of the map

 required

Returns:

Type Description

path to labelled map/regional mask, if a cached file is returned
Source code in api/common/data_handlers/volumes/parcellationmap.py 
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
@data_decorator(ROLE)
def get_parcellation_labelled_map(parcellation_id: str, space_id: str, region_id:str=None):
    """Retrieve and save labelled map / regional mask (if necessary), and then return the path of the map.

    Args:
        parcellation_id: lookup id of the parcellation of the map
        region_id: lookup id of the region of the map
        space_id: lookup id of the space of the map

    Returns:
        path to labelled map/regional mask, if a cached file is returned
    """
    import os
    full_filename = get_filename("labelled_map", parcellation_id, space_id, region_id if region_id else "", ext=".nii.gz")
    if os.path.isfile(full_filename):
        return full_filename, True

    import siibra
    import nibabel as nib
    error_text = f"Map with parc id '{parcellation_id}', space id '{space_id}'"

    volume_data = None
    if region_id is not None:
        region = siibra.get_region(parcellation_id, region_id)
        volume_data = region.get_regional_map(space_id, siibra.MapType.LABELLED).fetch()
    else:
        labelled_map = siibra.get_map(parcellation_id, space_id, siibra.MapType.LABELLED)
        assert labelled_map is not None, f"{error_text} returns None"
        volume_data = labelled_map.fetch()

    assert isinstance(volume_data, nib.Nifti1Image), f"{error_text}, volume provided is not of type Nifti1Image"

    nib.save(volume_data, full_filename)
    import json
    import time
    with open(f"{full_filename}.{str(int(time.time()))}.json", "w") as fp:
        json.dump({
            "prefix": "labelled_map",
            "parcellation_id": parcellation_id,
            "space_id": space_id,
            "region_id": region_id,
        }, fp=fp, indent="\t")
    return full_filename, False

get_region_statistic_map(parcellation_id, region_id, space_id)

Retrieve and save regional statistical map (if necessary), and then return the path of the map.

Parameters:

Name Type Description Default
parcellation_id str

lookup id of the parcellation of the map

 required
region_id str

lookup id of the region of the map

 required
space_id str

lookup id of the space of the map

 required

Returns:

Type Description

path to statistical map, if a cached file is returned
Source code in api/common/data_handlers/volumes/parcellationmap.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@data_decorator(ROLE)
def get_region_statistic_map(parcellation_id: str, region_id: str, space_id: str):
    """Retrieve and save regional statistical map (if necessary), and then return the path of the map.

    Args:
        parcellation_id: lookup id of the parcellation of the map
        region_id: lookup id of the region of the map
        space_id: lookup id of the space of the map

    Returns:
        path to statistical map, if a cached file is returned
    """
    return cache_region_statistic_map(parcellation_id, region_id, space_id)

get_region_statistic_map_info(parcellation_id, region_id, space_id)

Retrieve and save regional statistical map (if necessary), and then return the path of the map.

Parameters:

Name Type Description Default
parcellation_id str

lookup id of the parcellation of the map

 required
region_id str

lookup id of the region of the map

 required
space_id str

lookup id of the space of the map

 required

Returns:

Type Description

dict of min an max of the statistical map
Source code in api/common/data_handlers/volumes/parcellationmap.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
@data_decorator(ROLE)
def get_region_statistic_map_info(parcellation_id: str, region_id: str, space_id: str):
    """Retrieve and save regional statistical map (if necessary), and then return the path of the map.

    Args:
        parcellation_id: lookup id of the parcellation of the map
        region_id: lookup id of the region of the map
        space_id: lookup id of the space of the map

    Returns:
        dict of min an max of the statistical map
    """
    full_filename, _cache_flag = cache_region_statistic_map(parcellation_id, region_id, space_id)

    import nibabel as nib
    import numpy as np

    nii = nib.load(full_filename)
    data = nii.get_fdata()
    return {
        "min": np.min(data),
        "max": np.max(data),
    }

get_resampled_map(parcellation_id, space_id)

Retrieve and save a labelled map, resampled in space (if necessary), and then return the path of the map.

Parameters:

Name Type Description Default
parcellation_id str

lookup id of the parcellation of the map

 required
space_id str

lookup id of the target space of the sampled map

 required

Returns:

Type Description

path to statistical map, if a cached file is returned
Source code in api/common/data_handlers/volumes/parcellationmap.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
@data_decorator(ROLE)
def get_resampled_map(parcellation_id: str, space_id: str):
    """Retrieve and save a labelled map, resampled in space (if necessary), and then return the path of the map.

    Args:
        parcellation_id: lookup id of the parcellation of the map
        space_id: lookup id of the target space of the sampled map

    Returns:
        path to statistical map, if a cached file is returned
    """
    import os
    full_filename = get_filename("resampled_map", parcellation_id, space_id, ext=".nii.gz")
    if os.path.isfile(full_filename):
        return full_filename, True

    import siibra
    import nibabel as nib
    parcellation: siibra.core.parcellation.Parcellation = siibra.parcellations[parcellation_id]
    parcellation_map = parcellation.get_map(siibra.spaces[space_id], siibra.MapType.LABELLED)
    nii = parcellation_map.get_resampled_template()

    assert isinstance(nii, nib.Nifti1Image), f"resample failed... returned not of type nii"

    import time
    import json
    nib.save(nii, full_filename)
    with open(f"{full_filename}.{str(int(time.time()))}.json", "w") as fp:
        json.dump({
            "prefix": "resampled_map",
            "parcellation_id": parcellation_id,
            "space_id": space_id,
        }, indent="\t", fp=fp)
    return full_filename, False