OSCR

Siibra: a software tool suite for realizing a Multilevel Human Brain Atlas from complex data resources.

Code ↔ Paper

25 matches between paragraphs of the paper and lines of its authors' code, computed by the harvester (lexical-v1). Click a colored paragraph or line to see its counterpart.

18 blocks of code here have a permanent identifier (oscr:b:…), listed with the matches below: citable for good, with a page of its own. Select a match and press Cite to copy it. What a block identifier is.

The 25 matches
  1. [1] § Results › Multimodal comparison of brain areas ↔ examples/tutorials/2025-paper-fig5.py, lines 17 to 38 · score 0.98 · high resolution scans, underlying cloud resource, chosen position, oriented cortical, motor area, full resolution image · block oscr:b:XHYQCQD77PE0S-M · Report a mismatch
  2. [2] § Results › Anatomical evaluation of subcortical maps ↔ examples/tutorials/2025-paper-fig6.py, lines 16 to 49 · score 0.84 · ventral intermediate nucleus, subcortical maps, structural connectivity, thalamus, diffusion, Precentral · block oscr:b:E950W8GA36TAY-J · Report a mismatch
  3. [3] § Results › Multimodal comparison of brain areas ↔ siibra/livequeries/bigbrain.py, lines 253 to 394 · score 0.79 · intersected layer IV, cortical image patch, cortical layer surface, BigBrain, closest, oriented · block oscr:b:H901GFF9E2JE4-P · Report a mismatch
  4. [4] § Methods › Memory-efficient representation of sparse regional maps ↔ siibra/volumes/parcellationmap.py, lines 1142 to 1283 · score 0.77 · Statistical maps, region maps, image volume, parcellation maps, coordinate space, numerical · block oscr:b:YGT1P8AWM6PDN-0 · Report a mismatch
  5. [5] § Results › Anatomically guided reproducible extraction of microscopy data ↔ examples/tutorials/2025-paper-fig5.py, lines 17 to 38 · score 0.74 · high resolution image, siibra allows, full resolution, BigBrain, precomputed, microscopy · block oscr:b:XHYQCQD77PE0S-M · Report a mismatch
  6. [6] § Results › Design and architecture of siibra ↔ backend/app/bkwdcompat.py, lines 104 to 173 · score 0.74 · DiFuMo, MNI Colin, cytoarchitectonic maps, cortical layer, Julich Brain, bundle · block oscr:b:1KNXCR377C6CM-S · Report a mismatch
  7. [7] § Methods › Support of FAIR principles ↔ siibra/volumes/sparsemap.py, lines 489 to 545 · score 0.72 · NumPy, Nifti1Image, nibabel, nilearn, fetching, siibra · block oscr:b:HV3MKYG7YR2WS-O · Report a mismatch
  8. [8] § Methods › Modeling spatial entities in different reference coordinate systems ↔ siibra/livequeries/bigbrain.py, lines 253 to 394 · score 0.69 · cortical image patch, point clouds, BigBrain, vertices, probability, locations · block oscr:b:H901GFF9E2JE4-P · Report a mismatch
  9. [9] § Methods › Memory-efficient representation of sparse regional maps ↔ siibra/volumes/sparsemap.py, lines 338 to 468 · score 0.67 · bounding boxes, Statistical maps, image volume, sparse, weights, probabilistic · block oscr:b:9YPG6ZX9HNWC4-1 · Report a mismatch
  10. [10] § Methods › Separation of content from code › Live queries ↔ siibra/livequeries/ebrains.py, lines 34 to 145 · score 0.64 · EBRAINS Knowledge Graph, anatomically anchored, live queries, siibra, Atlas · block oscr:b:EK5EMZX0GXCKZ-Z · Report a mismatch
  11. [11] § Results › Anatomical characterization and multimodal profiling for regions of interest ↔ siibra/volumes/parcellationmap.py, lines 1142 to 1283 · score 0.63 · statistical maps, image volume, brain regions, reference space, correlation, assignment · block oscr:b:YGT1P8AWM6PDN-0 · Report a mismatch
  12. [12] § Methods › Modular software architecture ↔ siibra/core/space.py, lines 26 to 143 · score 0.61 · inflated surface, FreeSurfer, pial, volumetric, space, siibra · block oscr:b:SHNR28TA2DXY9-2 · Report a mismatch
  13. [13] § Methods › Modeling spatial entities in different reference coordinate systems ↔ hbp_spatial_backend/__init__.py, lines 150 to 224 · score 0.61 · folding patterns, transform coordinates, alignment, diffeomorphisms, Brain · block oscr:b:RYFR77265FXX0-N · Report a mismatch
  14. [14] § Results › Visually guided exploration from full brain networks to cells ↔ backend/app/bkwdcompat.py, lines 104 to 173 · score 0.61 · MNI Colin, cytoarchitectonic maps, cortical layer, Julich Brain, parcellation, space · block oscr:b:1KNXCR377C6CM-S · Report a mismatch
  15. [15] § Results › Expansion with new contents ↔ backend/app/bkwdcompat.py, lines 69 to 102 · score 0.61 · Allen Mouse Brain, Waxholm Space, Rat Brain, Brain Atlas, parcellation · block oscr:b:WC3M0ACQ90A66-0 · Report a mismatch
  16. [16] § Results › Anatomically guided reproducible extraction of microscopy data ↔ siibra/features/image/sections.py, lines 38 to 107 · score 0.59 · cortical patch, bounding box, BigBrain, fetch, resolutions, volume · block oscr:b:5R75VZ29ZEZJQ-W · Report a mismatch
  17. [17] § Results › Anatomical characterization and multimodal profiling for regions of interest ↔ siibra/volumes/parcellationmap.py, lines 1285 to 1383 · score 0.59 · Gaussian blob, uncertain coordinates, kernel, split, assignment, volume · block oscr:b:D85Z6YKTECA04-D · Report a mismatch
  18. [18] § Results › Anatomical characterization and multimodal profiling for regions of interest ↔ siibra/livequeries/allen.py, lines 69 to 120 · score 0.59 · Allen Human Brain, gene expression, Human Brain Atlas, microarray, tissue, connectivity · block oscr:b:H3ZR4V45GMST2-S · Report a mismatch
  19. [19] § Results › Anatomical characterization and multimodal profiling for regions of interest ↔ siibra/features/tabular/gene_expression.py, lines 30 to 170 · score 0.58 · gene expression, molecular, Human Brain Atlas, tabular, microarray, Allen · block oscr:b:VX5S6HVNFAJQK-C · Report a mismatch
  20. [20] § Methods › Linking data features to atlas elements ↔ siibra/features/tabular/tabular.py, lines 29 to 157 · score 0.57 · neurotransmitter receptor, tissue samples, properties, locations, anatomical, brain · block oscr:b:WPDA6A0HNVMF7-8 · Report a mismatch
  21. [21] § Methods › Separation of content from code › Live queries ↔ siibra/livequeries/allen.py, lines 69 to 120 · score 0.56 · Allen Human Brain, live queries, microarray, API, interfaces, connecting · block oscr:b:H3ZR4V45GMST2-S · Report a mismatch
  22. [22] § Methods › Linking data features to atlas elements ↔ examples/tutorials/2025-paper-fig6.py, lines 16 to 49 · score 0.55 · inter subject variability, reliable, histological, anatomical, maps · block oscr:b:E950W8GA36TAY-J · Report a mismatch
  23. [23] § Results › Anatomical characterization and multimodal profiling for regions of interest ↔ siibra/features/tabular/gene_expression.py, lines 30 to 170 · score 0.53 · gene expressions, Human Brain Atlas, tabular, Allen, co, retrieved · block oscr:b:VX5S6HVNFAJQK-C · Report a mismatch
  24. [24] § Results › Multimodal comparison of brain areas ↔ siibra/livequeries/allen.py, lines 142 to 200 · score 0.52 · microarray probe, tissue samples, donors, Allen, genes, MNI · block oscr:b:QGHPSTA5NXKV3-7 · Report a mismatch
  25. [25] § Methods › Modular software architecture ↔ src/viewerModule/nehuba/nehubaViewerGlue/nehubaViewerGlue.component.spec.ts, lines 1 to 66 · score 0.51 · user interactions, user interface, touch, reactive, Angular, viewer · block oscr:b:G7RQW8XD57VFY-1 · Report a mismatch

Paper

Loaded from Europe PMC by your browser; OSCR does not store it: doi.org · Europe PMC

The paper is loaded when this pane is shown.

The authors' code

Python · 1,860 lines · 73 KB · Apache-2.0 · 3 matches

  1. # Copyright 2018-2026
  2. # Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH
  3. # Licensed under the Apache License, Version 2.0 (the "License");
  4. # you may not use this file except in compliance with the License.
  5. # You may obtain a copy of the License at
  6. # http://www.apache.org/licenses/LICENSE-2.0
  7. # Unless required by applicable law or agreed to in writing, software
  8. # distributed under the License is distributed on an "AS IS" BASIS,
  9. # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  10. # See the License for the specific language governing permissions and
  11. # limitations under the License.
  12. """Provides spatial representations for parcellations and regions."""
  13. from collections import defaultdict
  14. from dataclasses import dataclass, asdict
  15. from typing import Union, Dict, List, TYPE_CHECKING, Iterable, Tuple, Literal, NamedTuple
  16. import numpy as np
  17. import pandas as pd
  18. from . import volume as _volume
  19. from .providers import provider
  20. from .. import exceptions
  21. from ..commons import (
  22. MapIndex,
  23. MapType,
  24. compare_arrays,
  25. resample_img_to_img,
  26. connected_components,
  27. clear_name,
  28. create_key,
  29. create_gaussian_kernel,
  30. siibra_tqdm,
  31. Species,
  32. CompareMapsResult,
  33. generate_uuid,
  34. logger,
  35. QUIET,
  36. )
  37. from ..core import concept, space, parcellation, region as _region
  38. from ..locations import location, point, pointcloud
  39. if TYPE_CHECKING:
  40. from ..core.region import Region
  41. from nilearn.maskers import NiftiLabelsMasker, SurfaceLabelsMasker
  42. import json
  43. from itertools import groupby
  44. from os import path, rename
  45. from ..retrieval.cache import CACHE
  46. @dataclass
  47. class MapAssignment:
  48. input_structure: int
  49. centroid: Union[Tuple[np.ndarray], point.Point]
  50. volume: int
  51. fragment: str
  52. map_value: np.ndarray
  53. time: Union[int, float, None]
  54. @dataclass
  55. class AssignImageResult(CompareMapsResult, MapAssignment):
  56. pass
  57. class _CompressedMapSpec(NamedTuple):
  58. """What a compression produces, before `compress()` wraps it as a Map."""
  59. volumes: List[_volume.Volume]
  60. indices: Dict[str, List[Dict]]
  61. class Map(concept.AtlasConcept, configuration_folder="maps"):
  62. def __init__(
  63. self,
  64. identifier: str,
  65. name: str,
  66. space_spec: dict,
  67. parcellation_spec: dict,
  68. indices: Dict[str, List[Dict]],
  69. volumes: list = [],
  70. shortname: str = "",
  71. description: str = "",
  72. modality: str = None,
  73. publications: list = [],
  74. datasets: list = [],
  75. prerelease: bool = False,
  76. ):
  77. """
  78. Constructs a new parcellation object.
  79. Parameters
  80. ----------
  81. identifier: str
  82. Unique identifier of the parcellation
  83. name: str
  84. Human-readable name of the parcellation
  85. space_spec: dict
  86. Specification of the space (use @id or name fields)
  87. parcellation_spec: str
  88. Specification of the parcellation (use @id or name fields)
  89. indices: dict
  90. Dictionary of indices for the brain regions.
  91. Keys are exact region names.
  92. Per region name, a list of dictionaries with fields "volume" and "label" is expected,
  93. where "volume" points to the index of the Volume object where this region is mapped,
  94. and optional "label" is the voxel label for that region.
  95. For continuous / probability maps, the "label" can be null or omitted.
  96. For single-volume labelled maps, the "volume" can be null or omitted.
  97. volumes: list[Volume]
  98. parcellation volumes
  99. shortname: str, optional
  100. Shortform of human-readable name
  101. description: str, optional
  102. Textual description of the parcellation
  103. modality: str, default: None
  104. Specification of the modality used for creating the parcellation
  105. publications: list
  106. List of associated publications, each a dictionary with "doi" and/or "citation" fields
  107. datasets : list
  108. datasets associated with this concept
  109. """
  110. concept.AtlasConcept.__init__(
  111. self,
  112. identifier=identifier,
  113. name=name,
  114. species=None, # inherits species from space
  115. shortname=shortname,
  116. description=description,
  117. publications=publications,
  118. datasets=datasets,
  119. modality=modality,
  120. prerelease=prerelease,
  121. )
  122. self._space_spec = space_spec
  123. self._parcellation_spec = parcellation_spec
  124. # Since the volumes might include 4D arrays, where the actual
  125. # volume index points to a z coordinate, we create subvolume
  126. # indexers from the given volume provider if 'z' is specified.
  127. self._indices: Dict[str, List[MapIndex]] = {}
  128. self.volumes: List[_volume.Volume] = []
  129. remap_volumes = {}
  130. # TODO: This assumes knowledge of the preconfigruation specs wrt. z.
  131. # z to subvolume conversion should probably go to the factory.
  132. for regionname, indexlist in indices.items():
  133. k = clear_name(regionname)
  134. self._indices[k] = []
  135. for index in indexlist:
  136. vol = index.get('volume', 0)
  137. assert vol in range(len(volumes))
  138. z = index.get('z')
  139. if (vol, z) not in remap_volumes:
  140. if z is None:
  141. self.volumes.append(volumes[vol])
  142. else:
  143. self.volumes.append(_volume.Subvolume(volumes[vol], z))
  144. remap_volumes[vol, z] = len(self.volumes) - 1
  145. self._indices[k].append(
  146. MapIndex(volume=remap_volumes[vol, z], label=index.get('label'), fragment=index.get('fragment'))
  147. )
  148. # make sure the indices are unique - each map/label pair should appear at most once
  149. all_indices = sum(self._indices.values(), [])
  150. seen = set()
  151. duplicates = {x for x in all_indices if x in seen or seen.add(x)}
  152. self._nonunique_indices = duplicates
  153. self._affine_cached = None
  154. self._compressed_cached: Dict[tuple, "Map"] = {}
  155. @property
  156. def key(self):
  157. _id = self.id
  158. return create_key(_id[len("siibra-map-v0.0.1"):])
  159. @property
  160. def species(self) -> Species:
  161. # lazy implementation
  162. if self._species_cached is None:
  163. self._species_cached = self.space.species
  164. return self.space._species_cached
  165. def get_index(self, region: Union[str, "Region"]):
  166. """
  167. Returns the unique index corresponding to the specified region.
  168. Tip
  169. ----
  170. Use find_indices() method for a less strict search returning all matches.
  171. Parameters
  172. ----------
  173. region: str or Region
  174. Returns
  175. -------
  176. MapIndex
  177. Raises
  178. ------
  179. NonUniqueIndexError
  180. If not unique or not defined in this parcellation map.
  181. """
  182. matches = self.find_indices(region)
  183. if len(matches) > 1:
  184. # if there is an exact match, we still use it. If not, we cannot proceed.
  185. regionname = region.name if isinstance(region, _region.Region) \
  186. else region
  187. for index, matched_name in matches.items():
  188. if matched_name == regionname:
  189. return index
  190. raise exceptions.NonUniqueIndexError(
  191. f"The specification '{region}' matches multiple mapped "
  192. f"structures in {str(self)}: {list(matches.values())}"
  193. )
  194. elif len(matches) == 0:
  195. raise exceptions.NonUniqueIndexError(
  196. f"The specification '{region}' does not match to any structure mapped in {self}"
  197. )
  198. else:
  199. return next(iter(matches))
  200. def find_indices(self, region: Union[str, "Region"]):
  201. """
  202. Returns the volume/label indices in this map which match the given
  203. region specification.
  204. Parameters
  205. ----------
  206. region: str or Region
  207. Returns
  208. -------
  209. dict
  210. - keys: MapIndex
  211. - values: region name
  212. """
  213. if region in self._indices:
  214. return {
  215. idx: region
  216. for idx in self._indices[region]
  217. }
  218. regionname = region.name if isinstance(region, _region.Region) else region
  219. matched_region_names = set(_.name for _ in (self.parcellation.find(regionname)))
  220. matches = matched_region_names & self._indices.keys()
  221. if len(matches) == 0:
  222. logger.warning(f"Region {regionname} not defined in {self}")
  223. return {
  224. idx: regionname
  225. for regionname in matches
  226. for idx in self._indices[regionname]
  227. }
  228. def get_region(self, label: int = None, volume: int = 0, index: MapIndex = None):
  229. """
  230. Returns the region mapped by the given index, if any.
  231. Tip
  232. ----
  233. Use get_index() or find_indices() methods to obtain the MapIndex.
  234. Parameters
  235. ----------
  236. label: int, default: None
  237. volume: int, default: 0
  238. index: MapIndex, default: None
  239. Returns
  240. -------
  241. Region
  242. A region object defined in the parcellation map.
  243. """
  244. if isinstance(label, MapIndex) and index is None:
  245. raise TypeError("Specify MapIndex with 'index' keyword.")
  246. if index is None:
  247. index = MapIndex(volume, label)
  248. matches = [
  249. regionname
  250. for regionname, indexlist in self._indices.items()
  251. if index in indexlist
  252. ]
  253. if len(matches) == 0:
  254. logger.warning(f"Index {index} not defined in {self}")
  255. return None
  256. elif len(matches) == 1:
  257. return self.parcellation.get_region(matches[0])
  258. else:
  259. # this should not happen, already tested in constructor
  260. raise RuntimeError(f"Index {index} is not unique in {self}")
  261. @property
  262. def space(self):
  263. for key in ["@id", "name"]:
  264. if key in self._space_spec:
  265. return space.Space.get_instance(self._space_spec[key])
  266. return space.Space(None, "Unspecified space", species=Species.UNSPECIFIED_SPECIES)
  267. @property
  268. def parcellation(self):
  269. for key in ["@id", "name"]:
  270. if key in self._parcellation_spec:
  271. return parcellation.Parcellation.get_instance(self._parcellation_spec[key])
  272. logger.warning(
  273. f"Cannot determine parcellation of {self.__class__.__name__} "
  274. f"{self.name} from {self._parcellation_spec}"
  275. )
  276. return None
  277. @property
  278. def labels(self):
  279. """
  280. The set of all label indices defined in this map, including "None" if
  281. not defined for one or more regions.
  282. """
  283. return {d.label for v in self._indices.values() for d in v}
  284. @property
  285. def has_unique_labels(self) -> bool:
  286. """
  287. True if every mapped region carries a distinct label across all volumes and
  288. fragments. Surface and fragmented volumetric maps are commonly labelled per
  289. hemisphere, so the same label may denote two different regions.
  290. """
  291. labels = [ix.label for ixs in self._indices.values() for ix in ixs]
  292. return None not in labels and len(labels) == len(set(labels))
  293. @property
  294. def maptype(self) -> MapType:
  295. if all(isinstance(_, int) for _ in self.labels):
  296. return MapType.LABELLED
  297. elif self.labels == {None}:
  298. return MapType.STATISTICAL
  299. else:
  300. raise RuntimeError(
  301. f"Inconsistent label indices encountered in {self}"
  302. )
  303. def __len__(self):
  304. return len(self.volumes)
  305. @property
  306. def regions(self):
  307. return list(self._indices)
  308. def get_volume(
  309. self,
  310. region: Union[str, "Region"] = None,
  311. *,
  312. index: MapIndex = None,
  313. **kwargs,
  314. ) -> Union[_volume.Volume, _volume.FilteredVolume, _volume.Subvolume]:
  315. try:
  316. length = len([arg for arg in [region, index] if arg is not None])
  317. assert length == 1
  318. except AssertionError:
  319. if length > 1:
  320. raise exceptions.ExcessiveArgumentException(
  321. "One and only one of region or index can be defined for `get_volume`."
  322. )
  323. mapindex = None
  324. if region is not None:
  325. try:
  326. assert isinstance(region, (str, _region.Region))
  327. except AssertionError:
  328. raise TypeError(f"Please provide a region name or region instance, not a {type(region)}")
  329. mapindex = self.get_index(region)
  330. if index is not None:
  331. assert isinstance(index, MapIndex)
  332. mapindex = index
  333. if mapindex is None:
  334. if len(self) == 1:
  335. mapindex = MapIndex(volume=0, label=None)
  336. elif len(self) > 1:
  337. assert self.maptype == MapType.LABELLED, f"Cannot merge multiple volumes of map type {self.maptype}. Please specify a region or index."
  338. logger.info(
  339. "Map provides multiple volumes and no region specification is"
  340. " provided. Reducing them to a single volume resampled to space template."
  341. )
  342. labels = list(range(1, len(self.volumes) + 1)) if self.labels == {1} else None
  343. merged_volume = _volume.ReducedVolume(self.volumes, labels)
  344. return merged_volume
  345. else:
  346. raise exceptions.NoVolumeFound("Map provides no volumes.")
  347. kwargs_fragment = kwargs.pop("fragment", None)
  348. if kwargs_fragment is not None:
  349. if (mapindex.fragment is not None) and (kwargs_fragment != mapindex.fragment):
  350. raise exceptions.ConflictingArgumentException(
  351. f"Conflicting specifications for fetching volume fragment{f' for region {region}'}: "
  352. f"supplied: {kwargs_fragment}, preconfigured: {mapindex.fragment}"
  353. )
  354. if mapindex.volume is None:
  355. mapindex.volume = 0
  356. if mapindex.volume >= len(self.volumes):
  357. raise IndexError(
  358. f"{self} provides {len(self)} mapped volumes, but #{mapindex.volume} was requested."
  359. )
  360. if mapindex.label is None and mapindex.fragment is None:
  361. return self.volumes[mapindex.volume]
  362. return _volume.FilteredVolume(
  363. parent_volume=self.volumes[mapindex.volume],
  364. label=mapindex.label,
  365. fragment=kwargs_fragment or mapindex.fragment,
  366. )
  367. def fetch(
  368. self,
  369. region: Union[str, "Region"] = None,
  370. *,
  371. index: MapIndex = None,
  372. **fetch_kwargs
  373. ):
  374. """
  375. Fetches one particular volume of this parcellation map.
  376. If there's only one volume, this is the default, otherwise further
  377. specification is requested:
  378. - the volume index,
  379. - the MapIndex (which results in a regional map being returned)
  380. You might also consider fetch_iter() to iterate the volumes, or
  381. compress() to produce a single-volume parcellation map.
  382. Parameters
  383. ----------
  384. region: str, Region
  385. Specification of a region name, resulting in a regional map
  386. (mask or statistical map) to be returned.
  387. index: MapIndex
  388. Explicit specification of the map index, typically resulting
  389. in a regional map (mask or statistical map) to be returned.
  390. Note that supplying 'region' will result in retrieving the map index of that region
  391. automatically.
  392. **fetch_kwargs
  393. - resolution_mm: resolution in millimeters as float or a tuple of floats
  394. - format: the format of the volume, like "mesh" or "nii"
  395. - voi: a BoundingBox of interest
  396. Note
  397. ----
  398. Not all keyword arguments are supported for volume formats. Format
  399. is restricted by available formats (check formats property).
  400. Returns
  401. -------
  402. An image or mesh
  403. """
  404. vol = self.get_volume(region=region, index=index, **fetch_kwargs)
  405. return vol.fetch(**fetch_kwargs)
  406. def fetch_iter(self, **kwargs):
  407. """
  408. Returns an iterator to fetch all mapped volumes sequentially.
  409. All arguments are passed on to function Map.fetch(). By default, it
  410. will go through all fragments as well.
  411. """
  412. fragments = {kwargs.pop('fragment', None)} or self.fragments or {None}
  413. return (
  414. self.fetch(
  415. index=MapIndex(volume=i, label=None, fragment=frag), **kwargs
  416. )
  417. for frag in fragments
  418. for i in range(len(self))
  419. )
  420. @property
  421. def provides_image(self):
  422. return any(v.provides_image for v in self.volumes)
  423. @property
  424. def fragments(self):
  425. return sorted({
  426. index.fragment
  427. for indices in self._indices.values()
  428. for index in indices
  429. if index.fragment is not None
  430. })
  431. @property
  432. def provides_mesh(self):
  433. return any(v.provides_mesh for v in self.volumes)
  434. @property
  435. def formats(self):
  436. return {f for v in self.volumes for f in v.formats}
  437. @property
  438. def is_labelled(self):
  439. return self.maptype == MapType.LABELLED
  440. @property
  441. def affine(self):
  442. if self._affine_cached is None:
  443. # we compute the affine from a volumetric volume provider
  444. for fmt in _volume.Volume.SUPPORTED_FORMATS:
  445. if fmt not in _volume.Volume.MESH_FORMATS:
  446. if fmt not in self.formats:
  447. continue
  448. try:
  449. self._affine_cached = self.fetch(index=MapIndex(volume=0), format=fmt).affine
  450. break
  451. except Exception:
  452. logger.debug("Caught exceptions:\n", exc_info=1)
  453. continue
  454. else:
  455. raise RuntimeError(f"No volumetric provider in {self} to derive the affine matrix.")
  456. if not isinstance(self._affine_cached, np.ndarray):
  457. logger.error("invalid affine:", self._affine_cached)
  458. return self._affine_cached
  459. def __iter__(self):
  460. return self.fetch_iter()
  461. def compress(self, **kwargs) -> "Map":
  462. """
  463. Convert this map into an equivalent map whose labels are unique across the
  464. whole image or surface, re-labelling regions sequentially from 1.
  465. Volumetric maps are merged into a single labelled volume on the grid of the
  466. space template. Surface maps keep their fragments, since a vertex belongs to
  467. exactly one of them, and are relabelled so that a label identifies one region
  468. rather than one region per hemisphere.
  469. The compressed image is built and kept as a memory-mapped array on disk, so
  470. neither building nor using it holds the full volume in RAM. Results are also
  471. cached per instance, keyed by the fetch arguments.
  472. Note
  473. ----
  474. Labels that no region claims are dropped to background. Surface maps
  475. sometimes carry such labels for technical reasons (e.g. a brainstem label
  476. so the map loads in freesurfer) and they have no name to report.
  477. Parameters
  478. ----------
  479. **kwargs
  480. Fetch arguments applied both to the space template, which defines the
  481. output grid, and to the mapped volumes, so that sources are read at the
  482. same resolution and resampling is usually unnecessary. `variant` is
  483. passed to the template only.
  484. Returns
  485. -------
  486. parcellationmap.Map
  487. Raises
  488. ------
  489. ValueError
  490. If this map is not labelled.
  491. RuntimeError
  492. If there is nothing to merge.
  493. """
  494. if not self.is_labelled:
  495. raise ValueError(f"Compression is not possible for {self.maptype} maps.")
  496. if len(self.volumes) == 1 and (not self.fragments or self.has_unique_labels):
  497. raise RuntimeError(
  498. "The map cannot be compressed: it is already a single, uniquely labelled volume."
  499. )
  500. key = tuple(sorted(kwargs.items()))
  501. try:
  502. hash(key)
  503. except TypeError: # an unhashable fetch argument, e.g. target_affine
  504. logger.debug(f"Cannot cache compression of {self} for {kwargs}.")
  505. key = None
  506. if key is not None and key in self._compressed_cached:
  507. return self._compressed_cached[key]
  508. entries = sorted(
  509. (index.volume, index.fragment or "", index.label, regionname)
  510. for regionname, indices in self._indices.items()
  511. for index in indices
  512. )
  513. relabelling_plan = [
  514. (MapIndex(volume=vol, fragment=frag or None, label=label), regionname, newlabel)
  515. for newlabel, (vol, frag, label, regionname) in enumerate(entries, start=1)
  516. ]
  517. # everything that shapes the result, so a changed configuration or changed
  518. # fetch arguments never reuse a stale artifact
  519. signature = json.dumps(
  520. {
  521. "map": self.id,
  522. "space": self.space.id,
  523. "kwargs": {k: str(v) for k, v in sorted(kwargs.items())},
  524. "indices": [
  525. [index.volume, index.fragment, index.label, regionname]
  526. for index, regionname, _ in relabelling_plan
  527. ],
  528. },
  529. sort_keys=True, # ensure_ascii=True by default: CACHE encodes as ascii
  530. )
  531. if self.provides_image:
  532. spec = self._compress_image_map(relabelling_plan, signature, **kwargs)
  533. elif self.provides_mesh:
  534. if kwargs:
  535. logger.info(f"Fetch arguments {list(kwargs)} are ignored when compressing a surface map.")
  536. spec = self._compress_surface_map(relabelling_plan, signature)
  537. else:
  538. raise NotImplementedError(f"{self} provides neither image nor mesh data to compress.")
  539. compressed = Map(
  540. identifier=f"{create_key(self.name)}_compressed",
  541. name=f"{self.name} compressed",
  542. space_spec=self._space_spec,
  543. parcellation_spec=self._parcellation_spec,
  544. indices=spec.indices,
  545. volumes=spec.volumes,
  546. )
  547. if key is not None:
  548. self._compressed_cached[key] = compressed
  549. return compressed
  550. def _compress_image_map(
  551. self, plan: List[Tuple[MapIndex, str, int]], signature: str, **kwargs
  552. ) -> "_CompressedMapSpec":
  553. """
  554. Merge the volumes and fragments of a volumetric map into a single labelled
  555. volume on the template grid. See `compress()`.
  556. Source volumes are streamed one at a time into a memory-mapped output array,
  557. so peak memory is one source volume rather than the whole map. Where regions
  558. overlap, the later entry of the relabelling plan wins; the number of
  559. contested voxels is reported.
  560. """
  561. cachefile = CACHE.build_filename(signature, suffix=".npy")
  562. metafile = f"{cachefile}.json"
  563. if path.isfile(cachefile) and path.isfile(metafile):
  564. try:
  565. with open(metafile) as f:
  566. meta = json.load(f)
  567. data = np.lib.format.open_memmap(cachefile, mode="r")
  568. logger.debug(f"Reusing the compressed {self} from {cachefile}")
  569. return _CompressedMapSpec(
  570. volumes=[_volume.from_array(
  571. data, np.array(meta["affine"]), self.space.id,
  572. name=self.name + " compressed", cache=False,
  573. )],
  574. indices=meta["indices"],
  575. )
  576. except (ValueError, OSError, KeyError):
  577. logger.debug(f"Discarding unreadable compression cache {cachefile}")
  578. # only the grid of the template is needed - never load its data, which for
  579. # large templates (e.g. BigBrain) dominates both time and memory
  580. variant = kwargs.pop("variant", None)
  581. template_img = self.space.get_template(variant=variant).fetch(**kwargs)
  582. shape, affine = tuple(template_img.shape[:3]), template_img.affine
  583. dtype = np.min_scalar_type(len(plan)) # sized by region count, not by the template
  584. nbytes = int(np.prod(shape)) * np.dtype(dtype).itemsize
  585. gib = nbytes / 1024**3
  586. logger.info(
  587. f"Compressing {self} into a {gib:.2f} GiB labelled volume "
  588. f"(shape {shape}, {np.dtype(dtype).name}) from {len(self.volumes)} volume(s)."
  589. )
  590. units = [(unit, list(entries)) for unit, entries in groupby(
  591. plan, key=lambda entry: (entry[0].volume, entry[0].fragment)
  592. )]
  593. tempfile = f"{cachefile}_temp"
  594. result = np.lib.format.open_memmap(tempfile, mode="w+", dtype=dtype, shape=shape)
  595. region_indices = defaultdict(list)
  596. contested, unmapped = 0, []
  597. try:
  598. with provider.SubvolumeProvider.UseCaching():
  599. for (volume, fragment), entries in siibra_tqdm(
  600. units, total=len(units), unit=" maps",
  601. desc=f"Compressing {len(self.volumes)} volume(s) and "
  602. f"{len(self.fragments) or 1} fragment(s) of {self.name}",
  603. disable=len(units) == 1,
  604. ):
  605. img = self.fetch(index=MapIndex(volume=volume, fragment=fragment), **kwargs)
  606. if tuple(img.shape[:3]) == shape and np.allclose(img.affine, affine):
  607. img_data = np.asanyarray(img.dataobj)
  608. else:
  609. logger.debug(f"Compression requires resampling volume {volume} (nearest)")
  610. img_data = np.asanyarray(resample_img_to_img(img, template_img).dataobj)
  611. observed = set(np.unique(img_data)) - {0}
  612. for index, regionname, newlabel in entries:
  613. update_voxels = img_data == index.label
  614. if not update_voxels.any():
  615. unmapped.append(regionname)
  616. contested += int(np.count_nonzero(result[update_voxels]))
  617. result[update_voxels] = newlabel
  618. region_indices[regionname].append({"volume": 0, "label": newlabel})
  619. observed.discard(index.label)
  620. if observed:
  621. logger.warning(
  622. f"Labels {sorted(observed)} are observed in volume {volume} "
  623. f"(fragment {fragment}) of {self}, but no region is defined for them."
  624. )
  625. del img_data
  626. result.flush()
  627. finally:
  628. del result # close the memmap before renaming, required on Windows
  629. rename(tempfile, cachefile)
  630. with open(metafile, "w") as f:
  631. json.dump({"affine": affine.tolist(), "indices": region_indices}, f)
  632. if contested:
  633. logger.info(
  634. f"{contested} voxel(s) are mapped by more than one region in {self}; "
  635. "the last entry of the relabelling order was kept for each."
  636. )
  637. if unmapped:
  638. logger.warning(f"{len(unmapped)} region(s) have no voxels after compression:\n{unmapped}")
  639. return _CompressedMapSpec(
  640. volumes=[_volume.from_array(
  641. np.lib.format.open_memmap(cachefile, mode="r"), affine, self.space.id,
  642. name=self.name + " compressed", cache=False,
  643. )],
  644. indices=region_indices,
  645. )
  646. def _compress_surface_map(
  647. self, plan: List[Tuple[MapIndex, str, int]], signature: str
  648. ) -> "_CompressedMapSpec":
  649. """
  650. Relabel the fragments of a surface map so that every region has a globally
  651. unique label. Fragments are preserved, since a vertex belongs to exactly one
  652. of them. See `compress()`.
  653. The label arrays are one per-vertex value per fragment, well under a megabyte
  654. even for the densest fsaverage mesh, so they are held in memory rather than
  655. memory-mapped, and written as GIFTI label files.
  656. Results are cached per fragment as GIFTI label files; a cache hit skips the
  657. relabelling and therefore also its warnings about unnamed labels and empty
  658. regions.
  659. """
  660. from nibabel import gifti
  661. from os import replace
  662. if len(self.volumes) > 1:
  663. raise NotImplementedError(
  664. f"{self} provides {len(self.volumes)} surface volumes; compression expects one."
  665. )
  666. prov = self.volumes[0]._providers["gii-label"]
  667. filemap, region_indices = {}, defaultdict(list)
  668. units = [(unit, list(entries)) for unit, entries in groupby(
  669. plan, key=lambda entry: (entry[0].volume, entry[0].fragment)
  670. )]
  671. for (_, fragment), entries in siibra_tqdm(
  672. units, total=len(units), unit=" fragments",
  673. desc=f"Relabelling {len(units)} surface fragment(s) of {self.name}",
  674. ):
  675. filename = CACHE.build_filename(f"{signature}-{fragment}", suffix=".label.gii")
  676. if not path.isfile(filename):
  677. # read from the provider: Volume.fetch() would also pull the template mesh
  678. data = prov.fetch(fragment=fragment)["labels"]
  679. # GIFTI data arrays support uint8, int32 and float32 only
  680. relabelled = np.zeros_like(data, dtype="int32")
  681. observed = set(np.unique(data)) - {0}
  682. unmapped = []
  683. for index, regionname, newlabel in entries:
  684. selection = data == index.label
  685. if not selection.any():
  686. unmapped.append(regionname)
  687. relabelled[selection] = newlabel
  688. observed.discard(index.label)
  689. if observed:
  690. logger.warning(
  691. f"Labels {sorted(observed)} are observed in fragment '{fragment}' of "
  692. f"{self}, but no region is defined for them."
  693. )
  694. if unmapped:
  695. logger.warning(
  696. f"{len(unmapped)} region(s) have no vertices in fragment "
  697. f"'{fragment}' of {self}:\n{unmapped}"
  698. )
  699. tempfile = CACHE.build_filename(f"{signature}-{fragment}-temp", suffix=".label.gii")
  700. gifti.GiftiImage(darrays=[
  701. gifti.GiftiDataArray(relabelled, intent="NIFTI_INTENT_LABEL")
  702. ]).to_filename(tempfile)
  703. replace(tempfile, filename)
  704. for index, regionname, newlabel in entries:
  705. region_indices[regionname].append(
  706. {"volume": 0, "fragment": fragment, "label": newlabel}
  707. )
  708. filemap[fragment] = filename
  709. return _CompressedMapSpec(
  710. volumes=[_volume.from_file(
  711. filemap, space=self.space.id, name=self.name + " compressed", format="gii-label",
  712. )],
  713. indices=region_indices,
  714. )
  715. def compute_centroids(self, split_components: bool = True, **fetch_kwargs) -> Dict[str, pointcloud.PointCloud]:
  716. """
  717. Compute a dictionary of all regions in this map to their centroids.
  718. By default, the regional masks will be split to connected components
  719. and each point in the PointCloud corresponds to a region component.
  720. Parameters
  721. ----------
  722. split_components: bool, default: True
  723. If True, finds the spatial properties for each connected component
  724. found by skimage.measure.label.
  725. Returns
  726. -------
  727. Dict[str, point.Point]
  728. Region names as keys and computed centroids as items.
  729. """
  730. assert self.provides_image, "Centroid computation for meshes is not supported yet."
  731. centroids = dict()
  732. for regionname, indexlist in siibra_tqdm(
  733. self._indices.items(), unit="regions", desc="Computing centroids"
  734. ):
  735. assert regionname not in centroids
  736. # get the mask of the region in this map
  737. with QUIET:
  738. if len(indexlist) >= 1:
  739. merged_volume = _volume.merge(
  740. [
  741. _volume.from_nifti(
  742. self.fetch(index=index, **fetch_kwargs),
  743. self.space,
  744. f"{self.name} - {index}"
  745. )
  746. for index in indexlist
  747. ],
  748. labels=[1] * len(indexlist)
  749. )
  750. mapimg = merged_volume.fetch()
  751. elif len(indexlist) == 1:
  752. index = indexlist[0]
  753. mapimg = self.fetch(index=index, **fetch_kwargs) # returns a mask of the region
  754. props = _volume.ComponentSpatialProperties.compute_from_image(
  755. img=mapimg,
  756. space=self.space,
  757. split_components=split_components,
  758. )
  759. try:
  760. centroids[regionname] = pointcloud.from_points([c.centroid for c in props])
  761. except exceptions.EmptyPointCloudError:
  762. centroids[regionname] = None
  763. return centroids
  764. def get_resampled_template(self, **fetch_kwargs) -> _volume.Volume:
  765. """
  766. Resample the reference space template to fetched map image. Uses
  767. nilearn.image.resample_to_img to resample the template.
  768. Parameters
  769. ----------
  770. **fetch_kwargs: takes the arguments of Map.fetch()
  771. Returns
  772. -------
  773. Volume
  774. """
  775. from nilearn.image import resample_to_img
  776. source_template = self.space.get_template().fetch()
  777. map_image = self.fetch(**fetch_kwargs)
  778. img = resample_to_img(source_template, map_image, interpolation='continuous')
  779. return _volume.from_array(
  780. data=img.dataobj,
  781. affine=img.affine,
  782. space=self.space,
  783. name=f"{source_template} resampled to coordinate system of {self}"
  784. )
  785. def colorize(
  786. self,
  787. values: Union[dict, "pd.Series", "pd.DataFrame"],
  788. background_label: Union[int, float] = 0,
  789. **masker_kwargs
  790. ):
  791. """Colorize the map with the provided regional values.
  792. Parameters
  793. ----------
  794. values : dict
  795. Dictionary mapping regions to values
  796. Return
  797. ------
  798. Nifti1Image
  799. """
  800. if not self.is_labelled:
  801. raise NotImplementedError("Since statistical maps can overlap, this is not yet implemented.")
  802. if isinstance(values, dict):
  803. resolved = {}
  804. for spec, value in values.items():
  805. matched = set(self.find_indices(spec).values()) # {MapIndex: regionname}
  806. if not matched:
  807. logger.warning(f"'{spec}' is not mapped in {self} - skipped in colorization.")
  808. continue
  809. for regionname in matched:
  810. resolved[regionname] = value
  811. if not resolved:
  812. raise ValueError(f"None of the {len(values)} provided keys are mapped in {self}.")
  813. values = pd.Series({r: resolved.get(r, background_label) for r in self.regions})
  814. masker_kwargs.setdefault("background_label", background_label)
  815. masker = self.as_nilearn_masker(**masker_kwargs)
  816. masker.fit()
  817. # ensure the order of columns follow the bids table used for masker
  818. values = values[masker.lut["name"]]
  819. return masker.inverse_transform(values)
  820. def get_colormap(self, region_specs: Iterable = None, *, fill_uncolored: bool = False):
  821. """
  822. Generate a matplotlib colormap from known rgb values of label indices.
  823. Parameters
  824. ----------
  825. region_specs: iterable(regions), optional
  826. Optional parameter to only color the desired regions.
  827. fill_uncolored: bool , optional
  828. If a region has no preconfigured color, a color will be randomly (reproducible) created.
  829. Returns
  830. -------
  831. ListedColormap
  832. """
  833. try:
  834. from matplotlib.colors import ListedColormap
  835. except ImportError as e:
  836. logger.error(
  837. "matplotlib not available. Please install matplotlib to create a matplotlib colormap."
  838. )
  839. raise e
  840. if fill_uncolored:
  841. seed = len(self.regions)
  842. np.random.seed(seed)
  843. logger.info(f"Random colors are allowed for regions without preconfgirued colors. Random seed: {seed}.")
  844. colors = {}
  845. if region_specs is not None:
  846. include_region_names = {
  847. self.parcellation.get_region(region_spec).name for region_spec in region_specs
  848. }
  849. else:
  850. include_region_names = None
  851. use_volindx = False
  852. if len(self.volumes) > 1 and self.labels == {1}:
  853. use_volindx = True
  854. logger.info("Using sequential relabling determined by the order of volumes.")
  855. no_predefined_color = []
  856. for regionname, indices in self._indices.items():
  857. for index in indices:
  858. if index.label is None:
  859. continue
  860. if (include_region_names is not None) and (regionname not in include_region_names):
  861. continue
  862. else:
  863. region = self.get_region(index=index)
  864. if region.rgb is not None:
  865. if use_volindx:
  866. colors[index.volume + 1] = region.rgb
  867. else:
  868. colors[index.label] = region.rgb
  869. elif fill_uncolored:
  870. random_clr = [np.random.randint(0, 255) for r in range(3)]
  871. while random_clr in list(colors.values()):
  872. random_clr = [np.random.randint(0, 255) for r in range(3)]
  873. colors[index.label] = random_clr
  874. else:
  875. no_predefined_color.append(region.name)
  876. if len(colors) == 0:
  877. raise exceptions.NoPredifinedColormapException(
  878. f"There is no predefined/preconfigured colormap for '{self}'."
  879. "Set `fill_uncolored=True` to get a reproducible colormap."
  880. )
  881. if no_predefined_color:
  882. logger.info(
  883. f"No preconfigured color found for the following regions."
  884. "Use `fill_uncolored=True` to display with a non-background color.\n"
  885. f"{no_predefined_color}"
  886. )
  887. max_label_index = max(colors.keys())
  888. palette = np.array(
  889. [
  890. list(colors[i]) + [1] if i in colors else [0, 0, 0, 0]
  891. for i in range(max_label_index + 1)
  892. ]
  893. ) / [255, 255, 255, 1]
  894. return ListedColormap(palette)
  895. def sample_locations(self, regionspec, numpoints: int):
  896. """ Sample 3D locations inside a given region.
  897. The probability distribution is approximated from the region mask based
  898. on the squared distance transform.
  899. Parameters
  900. ----------
  901. regionspec: Region or str
  902. Region to be used
  903. numpoints: int
  904. Number of samples to draw
  905. Returns
  906. -------
  907. PointCloud
  908. Sample points in physical coordinates corresponding to this
  909. parcellationmap
  910. """
  911. from scipy.ndimage import distance_transform_edt
  912. index = self.get_index(regionspec)
  913. mask = self.fetch(index=index)
  914. arr = np.asanyarray(mask.dataobj)
  915. if arr.dtype.char in np.typecodes['AllInteger']:
  916. # a binary mask - use distance transform to get sampling weights
  917. W = distance_transform_edt(np.asanyarray(mask.dataobj))**2
  918. else:
  919. # a statistical map - interpret directly as weights
  920. W = arr
  921. p = (W / W.sum()).ravel()
  922. XYZ_ = np.array(
  923. np.unravel_index(np.random.choice(len(p), numpoints, p=p), W.shape)
  924. ).T
  925. XYZ = np.dot(mask.affine, np.c_[XYZ_, np.ones(numpoints)].T)[:3, :].T
  926. return pointcloud.PointCloud(XYZ, space=self.space)
  927. def to_sparse(self):
  928. """
  929. Creates a SparseMap object from this parcellation map object.
  930. Returns
  931. -------
  932. SparseMap
  933. """
  934. from .sparsemap import SparseMap
  935. indices = {
  936. regionname: [
  937. {'volume': idx.volume, 'label': idx.label, 'fragment': idx.fragment}
  938. for idx in indexlist
  939. ]
  940. for regionname, indexlist in self._indices.items()
  941. }
  942. return SparseMap(
  943. identifier=self.id,
  944. name=self.name,
  945. space_spec={'@id': self.space.id},
  946. parcellation_spec={'@id': self.parcellation.id},
  947. indices=indices,
  948. volumes=self.volumes,
  949. shortname=self.shortname,
  950. description=self.description,
  951. modality=self.modality,
  952. publications=self.publications,
  953. datasets=self.datasets
  954. )
  955. def _read_voxel(
  956. self,
  957. x: Union[int, np.ndarray, List],
  958. y: Union[int, np.ndarray, List],
  959. z: Union[int, np.ndarray, List]
  960. ):
  961. def _read_voxels_from_volume(xyz, volimg):
  962. xyz = np.stack(xyz, axis=1)
  963. valid_points_mask = np.all([(0 <= di) & (di < vol_size) for vol_size, di in zip(volimg.shape, xyz.T)], axis=0)
  964. x, y, z = xyz[valid_points_mask].T
  965. valid_points_indices, *_ = np.where(valid_points_mask)
  966. valid_data_points = np.asanyarray(volimg.dataobj)[x, y, z]
  967. return zip(valid_points_indices, valid_data_points)
  968. # integers are just single-element arrays, cast to avoid an extra code branch for integers
  969. x, y, z = [np.array(di) for di in (x, y, z)]
  970. fragments = self.fragments or {None}
  971. return [
  972. (pointindex, volume, fragment, data_point)
  973. for fragment in fragments
  974. for volume, volimg in enumerate(self.fetch_iter(fragment=fragment))
  975. # transformations or user input might produce points outside the volume, filter these out.
  976. for (pointindex, data_point) in _read_voxels_from_volume((x, y, z), volimg)
  977. ]
  978. def _assign(
  979. self,
  980. item: location.Location,
  981. minsize_voxel=1,
  982. lower_threshold=0.0,
  983. **kwargs
  984. ) -> List[Union[MapAssignment, AssignImageResult]]:
  985. """
  986. For internal use only. Returns a dataclass, which provides better static type checking.
  987. """
  988. if isinstance(item, point.Point):
  989. return self._assign_points(
  990. pointcloud.PointCloud([item], item.space, sigma_mm=item.sigma),
  991. lower_threshold
  992. )
  993. if isinstance(item, pointcloud.PointCloud):
  994. return self._assign_points(item, lower_threshold)
  995. if isinstance(item, _volume.Volume):
  996. if isinstance(item, _volume.TimeSeriesVolume):
  997. return self._assign_timeseries_volume(
  998. queryvolume=item,
  999. lower_threshold=lower_threshold,
  1000. minsize_voxel=minsize_voxel,
  1001. **kwargs
  1002. )
  1003. else:
  1004. return self._assign_volume(
  1005. queryvolume=item,
  1006. lower_threshold=lower_threshold,
  1007. minsize_voxel=minsize_voxel,
  1008. **kwargs
  1009. )
  1010. raise RuntimeError(
  1011. f"Items of type {item.__class__.__name__} cannot be used for region assignment."
  1012. )
  1013. def assign(
  1014. self,
  1015. item: location.Location,
  1016. minsize_voxel=1,
  1017. lower_threshold=0.0,
  1018. **kwargs
  1019. ) -> "pd.DataFrame":
  1020. """Assign an input Location to brain regions.
  1021. The input is assumed to be defined in the same coordinate space
  1022. as this parcellation map.
  1023. Parameters
  1024. ----------
  1025. item: Location
  1026. A spatial object defined in the same physical reference space as
  1027. this parcellation map, which could be a point, set of points, or
  1028. image volume. If it is an image, it will be resampled to the same voxel
  1029. space if its affine transformation differs from that of the
  1030. parcellation map. Resampling will use linear interpolation for float
  1031. image types, otherwise nearest neighbor.
  1032. minsize_voxel: int, default: 1
  1033. Minimum voxel size of image components to be taken into account.
  1034. lower_threshold: float, default: 0
  1035. Lower threshold on values in the statistical map. Values smaller
  1036. than this threshold will be excluded from the assignment computation.
  1037. Returns
  1038. -------
  1039. pandas.DataFrame
  1040. A table of associated regions and their scores per component found
  1041. in the input image, or per coordinate provided. The scores are:
  1042. - Value: Maximum value of the voxels in the map covered by an
  1043. input coordinate or input image signal component.
  1044. - Pearson correlation coefficient between the brain region map
  1045. and an input image signal component (NaN for exact coordinates)
  1046. - Contains: Percentage of the brain region map contained in an
  1047. input image signal component, measured from their binarized
  1048. masks as the ratio between the volume of their intersection
  1049. and the volume of the brain region (NaN for exact coordinates)
  1050. - Contained: Percentage of an input image signal component
  1051. contained in the brain region map, measured from their binary
  1052. masks as the ratio between the volume of their intersection and
  1053. the volume of the input image signal component (NaN for exact
  1054. coordinates)
  1055. """
  1056. assignments = self._assign(item, minsize_voxel, lower_threshold, **kwargs)
  1057. # format assignments as pandas dataframe
  1058. columns = [
  1059. "input structure",
  1060. "time",
  1061. "centroid",
  1062. "volume",
  1063. "fragment",
  1064. "region",
  1065. "correlation",
  1066. "intersection over union",
  1067. "map value",
  1068. "map weighted mean",
  1069. "map containedness",
  1070. "input weighted mean",
  1071. "input containedness"
  1072. ]
  1073. if len(assignments) == 0:
  1074. return pd.DataFrame(columns=columns).dropna(axis='columns', how='all')
  1075. # determine the unique set of observed indices in order to do region lookups
  1076. # only once for each map index occurring in the point list
  1077. labelled = self.is_labelled # avoid calling this in a loop
  1078. observed_indices = { # unique set of observed map indices. NOTE: len(observed_indices) << len(assignments)
  1079. (
  1080. a.volume,
  1081. a.fragment,
  1082. a.map_value if labelled else None
  1083. )
  1084. for a in assignments
  1085. }
  1086. region_lut = { # lookup table of observed region objects
  1087. (v, f, l): self.get_region(
  1088. index=MapIndex(
  1089. volume=int(v),
  1090. label=l if l is None else int(l),
  1091. fragment=f
  1092. )
  1093. )
  1094. for v, f, l in observed_indices
  1095. }
  1096. dataframe_list = []
  1097. for a in assignments:
  1098. item_to_append = {
  1099. "input structure": a.input_structure,
  1100. "time": a.time,
  1101. "centroid": a.centroid,
  1102. "volume": a.volume,
  1103. "fragment": a.fragment,
  1104. "region": region_lut[
  1105. a.volume,
  1106. a.fragment,
  1107. a.map_value if labelled else None
  1108. ],
  1109. }
  1110. # because AssignImageResult is a subclass of Assignment
  1111. # need to check for isinstance AssignImageResult first
  1112. if isinstance(a, AssignImageResult):
  1113. item_to_append = {
  1114. **item_to_append,
  1115. **{
  1116. "correlation": a.correlation,
  1117. "intersection over union": a.intersection_over_union,
  1118. "map value": a.map_value,
  1119. "map weighted mean": a.weighted_mean_of_first,
  1120. "map containedness": a.intersection_over_first,
  1121. "input weighted mean": a.weighted_mean_of_second,
  1122. "input containedness": a.intersection_over_second,
  1123. }
  1124. }
  1125. elif isinstance(a, MapAssignment):
  1126. item_to_append = {
  1127. **item_to_append,
  1128. **{
  1129. "correlation": None,
  1130. "intersection over union": None,
  1131. "map value": a.map_value,
  1132. "map weighted mean": None,
  1133. "map containedness": None,
  1134. "input weighted mean": None,
  1135. "input containedness": None,
  1136. }
  1137. }
  1138. else:
  1139. raise RuntimeError("assignments must be of type Assignment or AssignImageResult!")
  1140. dataframe_list.append(item_to_append)
  1141. return (
  1142. pd.DataFrame(dataframe_list)
  1143. .convert_dtypes() # convert will guess numeric column types
  1144. .reindex(columns=columns)
  1145. .dropna(axis='columns', how='all')
  1146. )
  1147. def _assign_points(self, points: pointcloud.PointCloud, lower_threshold: float) -> List[MapAssignment]:
  1148. """
  1149. assign a PointCloud to this parcellation map.
  1150. Parameters
  1151. -----------
  1152. lower_threshold: float, default: 0
  1153. Lower threshold on values in the statistical map. Values smaller than
  1154. this threshold will be excluded from the assignment computation.
  1155. """
  1156. assignments = []
  1157. if points.space != self.space:
  1158. logger.info(
  1159. f"Coordinates will be converted from {points.space.name} "
  1160. f"to {self.space.name} space for assignment."
  1161. )
  1162. # convert sigma to voxel coordinates
  1163. scaling = np.array(
  1164. [np.linalg.norm(self.affine[:, i]) for i in range(3)]
  1165. ).mean()
  1166. phys2vox = np.linalg.inv(self.affine)
  1167. # if all points have the same sigma, and lead to a standard deviation
  1168. # below 3 voxels, we are much faster with a multi-coordinate readout.
  1169. if points.has_constant_sigma:
  1170. sigma_vox = points.sigma[0] / scaling
  1171. if sigma_vox < 3:
  1172. pts_warped = points.warp(self.space.id)
  1173. X, Y, Z = (np.dot(phys2vox, pts_warped.homogeneous.T) + 0.5).astype("int")[:3]
  1174. for pointindex, vol, frag, value in self._read_voxel(X, Y, Z):
  1175. if value > lower_threshold:
  1176. position = pts_warped[pointindex].coordinate
  1177. assignments.append(
  1178. MapAssignment(
  1179. input_structure=pointindex,
  1180. centroid=tuple(position),
  1181. volume=vol,
  1182. fragment=frag,
  1183. map_value=value,
  1184. time=None,
  1185. )
  1186. )
  1187. return assignments
  1188. # if we get here, we need to handle each point independently.
  1189. # This is much slower but more precise in dealing with the uncertainties
  1190. # of the coordinates.
  1191. for pointindex, pt in siibra_tqdm(
  1192. enumerate(points.warp(self.space.id)),
  1193. total=len(points), desc="Assigning points",
  1194. ):
  1195. sigma_vox = pt.sigma / scaling
  1196. if sigma_vox < 3:
  1197. # voxel-precise - just read out the value in the maps
  1198. N = len(self)
  1199. logger.debug(f"Assigning coordinate {tuple(pt)} to {N} maps")
  1200. x, y, z = (np.dot(phys2vox, pt.homogeneous) + 0.5).astype("int")[:3]
  1201. values = self._read_voxel(x, y, z)
  1202. for _, vol, frag, value in values:
  1203. if value > lower_threshold:
  1204. assignments.append(
  1205. MapAssignment(
  1206. input_structure=pointindex,
  1207. centroid=tuple(pt),
  1208. volume=vol,
  1209. fragment=frag,
  1210. map_value=value,
  1211. time=None,
  1212. )
  1213. )
  1214. else:
  1215. logger.debug(
  1216. f"Assigning uncertain coordinate {tuple(pt)} to {len(self)} maps."
  1217. )
  1218. kernel = create_gaussian_kernel(sigma_vox, 3)
  1219. r = int(kernel.shape[0] / 2) # effective radius
  1220. assert pt.homogeneous.shape[0] == 1
  1221. xyz_vox = (np.dot(phys2vox, pt.homogeneous.T) + 0.5).astype("int")
  1222. shift = np.identity(4)
  1223. shift[:3, -1] = xyz_vox[:3, 0] - r
  1224. # build niftiimage with the Gaussian blob,
  1225. # then recurse into this method with the image input
  1226. gaussian_kernel = _volume.from_array(
  1227. data=kernel,
  1228. affine=np.dot(self.affine, shift),
  1229. space=self.space,
  1230. name=f"Gaussian kernel of {pt}",
  1231. cache=False,
  1232. )
  1233. for entry in self._assign(
  1234. item=gaussian_kernel,
  1235. lower_threshold=lower_threshold,
  1236. split_components=False
  1237. ):
  1238. entry.input_structure = pointindex
  1239. entry.centroid = tuple(pt)
  1240. assignments.append(entry)
  1241. return assignments
  1242. def _assign_volume(
  1243. self,
  1244. queryvolume: "_volume.Volume",
  1245. lower_threshold: float,
  1246. split_components: bool = True,
  1247. time: int = None,
  1248. **kwargs,
  1249. ) -> List[AssignImageResult]:
  1250. """
  1251. Assign an image volume to this parcellation map.
  1252. Parameters
  1253. -----------
  1254. queryvolume: Volume
  1255. the volume to be compared with maps
  1256. minsize_voxel: int, default: 1
  1257. Minimum voxel size of image components to be taken into account.
  1258. lower_threshold: float, default: 0
  1259. Lower threshold on values in the statistical map. Values smaller than
  1260. this threshold will be excluded from the assignment computation.
  1261. split_components: bool, default: True
  1262. Whether to split the query volume into disjoint components.
  1263. """
  1264. # TODO: split_components is not known to `assign`
  1265. # TODO: `minsize_voxel` is not used here. Consider the implementation of `assign` again.
  1266. if kwargs:
  1267. logger.info(f"The keywords {[k for k in kwargs]} are not passed on during volume assignment.")
  1268. if queryvolume.space != self.space:
  1269. raise ValueError("Assigned volume must be in the same space as the map.")
  1270. if split_components:
  1271. iter_components = lambda arr: connected_components(arr)
  1272. else:
  1273. iter_components = lambda arr: [(0, arr)]
  1274. queryimg = queryvolume.fetch()
  1275. assignments = []
  1276. all_indices = [
  1277. index
  1278. for regionindices in self._indices.values()
  1279. for index in regionindices
  1280. ]
  1281. with QUIET and provider.SubvolumeProvider.UseCaching():
  1282. for index in siibra_tqdm(
  1283. all_indices,
  1284. desc=f"Assigning {queryvolume} to {self}",
  1285. disable=len(all_indices) < 5,
  1286. unit="map",
  1287. leave=False
  1288. ):
  1289. region_map = self.fetch(index=index)
  1290. region_map_arr = np.asanyarray(region_map.dataobj)
  1291. # the shape and affine are checked by `nilearn.image.resample_to_img()`
  1292. # and returns the original data if resampling is not necessary.
  1293. queryimgarr_res = np.asanyarray(
  1294. resample_img_to_img(queryimg, region_map).dataobj
  1295. )
  1296. for compmode, voxelmask in iter_components(queryimgarr_res):
  1297. scores = compare_arrays(
  1298. voxelmask,
  1299. region_map.affine, # after resampling, both should have the same affine
  1300. region_map_arr,
  1301. region_map.affine
  1302. )
  1303. component_position = np.array(np.where(voxelmask)).T.mean(0)
  1304. if scores.intersection_over_union > lower_threshold:
  1305. assignments.append(
  1306. AssignImageResult(
  1307. input_structure=compmode,
  1308. centroid=tuple(component_position.round(2)),
  1309. volume=index.volume,
  1310. fragment=index.fragment,
  1311. map_value=index.label,
  1312. time=time,
  1313. **asdict(scores)
  1314. )
  1315. )
  1316. return assignments
  1317. def _assign_timeseries_volume(
  1318. self,
  1319. queryvolume: "_volume.TimeSeriesVolume",
  1320. lower_threshold: float,
  1321. split_components: bool = True,
  1322. **kwargs
  1323. ) -> List[AssignImageResult]:
  1324. assignments = []
  1325. for v_t in siibra_tqdm(queryvolume, unit='time point'):
  1326. assignments_t = self._assign_volume(
  1327. v_t,
  1328. lower_threshold=lower_threshold,
  1329. split_components=split_components,
  1330. time=v_t.timepoint,
  1331. **kwargs
  1332. )
  1333. assignments.extend(assignments_t)
  1334. return assignments
  1335. def to_BIDS_lookup_table(self) -> pd.DataFrame:
  1336. """
  1337. Generate a BIDS-compatible lookup table for the labelled map.
  1338. The lookup table associates voxel labels with region names and optional
  1339. RGB colors derived from the corresponding parcellation regions.
  1340. If the map consists of multiple fragments, the fragments are first
  1341. compressed into a single labelled image and relabelled to ensure BIDS
  1342. compatibility.
  1343. Parameters
  1344. ----------
  1345. filepath : str, optional
  1346. Path to a ``.tsv`` file where the lookup table should be written.
  1347. If provided, the table is saved in tab-separated format.
  1348. Returns
  1349. -------
  1350. pandas.DataFrame
  1351. A lookup table with the following columns:
  1352. - ``index``: Integer label value in the image.
  1353. - ``name``: Name of the corresponding brain region.
  1354. - ``color``: Hexadecimal RGB color code associated with the region,
  1355. or ``None`` if no color is defined.
  1356. Raises
  1357. ------
  1358. Exception
  1359. If the map contains more than one volume.
  1360. AssertionError
  1361. If ``filepath`` does not end with ``.tsv``.
  1362. Notes
  1363. -----
  1364. BIDS lookup tables require a single labelled volume. Maps distributed
  1365. across multiple fragments are therefore compressed and relabelled before
  1366. generating the table.
  1367. """
  1368. if not self.is_labelled:
  1369. raise NotImplementedError("Currently, there is not LUT standard defined by BIDS for statistical maps.")
  1370. if len(self.volumes) > 1 or not self.has_unique_labels:
  1371. logger.info(
  1372. f"{self} has {len(self.volumes)} volume(s)/{len(self.fragments)} fragment(s); "
  1373. "siibra will compress and reindex it for BIDS compatibility."
  1374. )
  1375. mp = self.compress()
  1376. else:
  1377. mp = self
  1378. def to_record(regionname: str, index: MapIndex) -> List[Dict]:
  1379. rgb = mp.parcellation.get_region(regionname).rgb
  1380. color = "#{:02x}{:02x}{:02x}".format(*rgb) if rgb else None
  1381. return {
  1382. "index": index.label,
  1383. "name": regionname,
  1384. "color": color,
  1385. }
  1386. table = pd.DataFrame(
  1387. [
  1388. to_record(r, indices[0])
  1389. for r, indices in mp._indices.items()
  1390. ]
  1391. )
  1392. if "gii-label" in mp.formats:
  1393. # read from the provider: mp.fetch() would also pull the template mesh
  1394. prov = mp.volumes[0]._providers["gii-label"]
  1395. observed = set()
  1396. for fragment in (mp.fragments or [None]):
  1397. observed |= set(np.unique(prov.fetch(fragment=fragment)["labels"]))
  1398. for xl in sorted(observed - set(table["index"]) - {0}): # 0 is background
  1399. table.loc[len(table)] = {"name": f"{xl} (unnamed)", "index": xl, "color": None}
  1400. if not table["index"].is_unique:
  1401. duplicated = sorted(table.loc[table["index"].duplicated(), "index"])
  1402. raise RuntimeError(
  1403. f"Labels {duplicated} are assigned to more than one region in {mp}. "
  1404. "A BIDS lookup table requires unique indices."
  1405. )
  1406. return table
  1407. def _as_surfaceimage(self, variant: str = None):
  1408. from nilearn.surface import SurfaceImage, PolyData
  1409. if "gii-label" not in self.formats:
  1410. raise ValueError("`SurfaceImage` representation is only possible for 'gii-label' maps.")
  1411. if len(self.volumes) > 1:
  1412. raise ValueError("`SurfaceImage` representation is only possible for maps with single and hemisphere fragemented maps.")
  1413. giilabel_filemap = {}
  1414. for frag in self.fragments:
  1415. loader = self.volumes[0]._providers["gii-label"]._loaders[frag]
  1416. loader._retrieve()
  1417. giilabel_filemap[frag.replace(' hemisphere', "")] = loader.cachefile
  1418. return SurfaceImage(mesh=self.space._as_polymesh(variant=variant), data=PolyData(**giilabel_filemap))
  1419. def as_nilearn_masker(
  1420. self,
  1421. strategy: Literal[
  1422. "mean",
  1423. "median",
  1424. "sum",
  1425. "minimum",
  1426. "maximum",
  1427. "standard_deviation",
  1428. "variance",
  1429. ] = "mean",
  1430. surface_variant: str = None,
  1431. **masker_kwargs,
  1432. ) -> Union["NiftiLabelsMasker", "SurfaceLabelsMasker"]:
  1433. from nilearn import maskers
  1434. try:
  1435. from ..retrieval.cache import jobmemory_path
  1436. masker_kwargs.setdefault("memory", jobmemory_path)
  1437. except ImportError:
  1438. ...
  1439. if not self.is_labelled:
  1440. raise NotImplementedError(
  1441. f"Nilearn maskers for {self.maptype} maps are provided by SparseMap, "
  1442. "which projects the data onto the maps instead of summarizing labelled "
  1443. "regions. Convert this map with `to_sparse()` first."
  1444. )
  1445. mp = self.compress() if (len(self.volumes) > 1 or self.fragments) else self
  1446. if "lut" in masker_kwargs:
  1447. raise ValueError("siibra handles `lut` parameter based on the map.")
  1448. masker_kwargs.setdefault("verbose", 1)
  1449. masker_kwargs.setdefault("strategy", strategy)
  1450. masker_kwargs["lut"] = mp.to_BIDS_lookup_table()
  1451. if self.provides_image:
  1452. masker = maskers.NiftiLabelsMasker(mp.fetch(), **masker_kwargs)
  1453. else:
  1454. masker = maskers.SurfaceLabelsMasker(
  1455. mp._as_surfaceimage(variant=surface_variant),
  1456. **masker_kwargs,
  1457. )
  1458. return masker
  1459. def extract_signals_with_nilearn(
  1460. self,
  1461. volume: _volume.Volume,
  1462. strategy: Literal[
  1463. "mean",
  1464. "median",
  1465. "sum",
  1466. "minimum",
  1467. "maximum",
  1468. "standard_deviation",
  1469. "variance",
  1470. ] = "mean",
  1471. confounds: np.ndarray = None,
  1472. sample_mask: np.ndarray = None,
  1473. surface_variant: str = None,
  1474. **masker_kwargs,
  1475. ) -> pd.DataFrame:
  1476. """
  1477. Extract region-wise signals from a 3D/4D volume using `nilearn`.
  1478. The regions defined in this map are used to summarize the input volume
  1479. with :class:`nilearn.maskers.NiftiLabelsMasker` (labelled volumetric maps),
  1480. :class:`nilearn.maskers.SurfaceLabelsMasker` (labelled surface maps), or
  1481. :class:`nilearn.maskers.NiftiMapsMasker` (statistical maps). Maps with
  1482. several volumes or fragments are compressed into a single labelled map first.
  1483. Parameters
  1484. ----------
  1485. volume: Volume
  1486. Input 3D or 4D volume from which signals should be extracted, typically
  1487. an fMRI image. Both NIfTI and timeseries GIFTI sources are supported.
  1488. strategy: str, default: "mean"
  1489. How voxels or vertices are summarized within each region. Only applies
  1490. to labelled maps; it is ignored for statistical maps, since
  1491. `NiftiMapsMasker` projects the data onto the (overlapping, continuous)
  1492. maps by least squares instead of summarizing discrete regions.
  1493. confounds: array-like, optional
  1494. Confounds to regress out during extraction.
  1495. See `nilearn.maskers.BaseMasker.transform`.
  1496. sample_mask: array-like, optional
  1497. Mask of samples to include when extracting signals.
  1498. See `nilearn.maskers.BaseMasker.transform`.
  1499. surface_variant: str, optional
  1500. Template surface variant to use for surface maps, e.g. "inflated".
  1501. **masker_kwargs
  1502. Passed on to the nilearn masker constructor.
  1503. Returns
  1504. -------
  1505. pandas.DataFrame
  1506. One column per region mapped in this map, one row per sample. The index
  1507. is the time axis of `volume` when it has one and no `sample_mask` was
  1508. given, otherwise a range index.
  1509. Notes
  1510. -----
  1511. Region names are taken from the BIDS lookup table generated by
  1512. `to_BIDS_lookup_table()`. Regions that disappear when the map is resampled
  1513. onto the input volume are reported and filled with zeros; nilearn's
  1514. `keep_masked_labels` does not prevent them from being dropped, and it is
  1515. deprecated since nilearn 0.14.
  1516. """
  1517. masker = self.as_nilearn_masker(
  1518. strategy=strategy if self.is_labelled else None,
  1519. surface_variant=surface_variant,
  1520. **masker_kwargs
  1521. )
  1522. if self.provides_image and volume.provides_image:
  1523. source = volume.fetch()
  1524. elif "gii-label" in self.formats and "gii-timeseries" in volume.formats:
  1525. source = volume._as_surfaceimage(variant=surface_variant)
  1526. else:
  1527. raise ValueError(
  1528. f"Cannot extract signals from {volume} with {self}: no common representation. "
  1529. f"The map provides {sorted(self.formats)}, the input provides {sorted(volume.formats)}."
  1530. )
  1531. # np.asarray normalizes plain and pandas output alike. (set_output(transform="pandas")
  1532. # raises NotImplementedError before nilearn 0.13, and the column names it
  1533. # produces are the ones we assign below anyway.)
  1534. signals = np.atleast_2d(np.asarray(
  1535. masker.fit_transform(source, confounds=confounds, sample_mask=sample_mask)
  1536. ))
  1537. if self.is_labelled:
  1538. # region_names_ maps output column index -> region name. It is available on
  1539. # both Nifti and Surface labels maskers since nilearn 0.10.4.
  1540. # (masker.labels_ cannot be used here: it includes the background label.
  1541. # get_feature_names_out() is equivalent but only exists from nilearn 0.13.)
  1542. extracted = [name for _, name in sorted(masker.region_names_.items())]
  1543. all_regions = masker.lut["name"].tolist()
  1544. else:
  1545. # NiftiMapsMasker names its columns positionally, so column i corresponds
  1546. # to volume i of the array stacked by _stack_maps().
  1547. extracted = all_regions = [
  1548. regionname for regionname, indices
  1549. in sorted(self._indices.items(), key=lambda kv: kv[1][0].volume)
  1550. ]
  1551. if signals.shape[1] != len(extracted):
  1552. raise RuntimeError(
  1553. f"nilearn returned {signals.shape[1]} signals but {len(extracted)} "
  1554. f"regions were expected for {self}."
  1555. )
  1556. result = pd.DataFrame(signals, columns=extracted)
  1557. missing = [r for r in all_regions if r not in set(extracted)]
  1558. if missing:
  1559. logger.info(
  1560. f"{len(missing)} region(s) were removed when resampling {self} to the "
  1561. f"input volume and are filled with zeros:\n{missing}"
  1562. )
  1563. result[missing] = 0
  1564. result = result[all_regions]
  1565. result.columns.name = "region"
  1566. # sample_mask drops samples, so the time axis would no longer align
  1567. time = getattr(volume, "time", None)
  1568. if time is not None and sample_mask is None and len(time) == len(result):
  1569. result.index = pd.Index(time, name="time")
  1570. return result
  1571. def from_volume(
  1572. name: str,
  1573. volume: Union[_volume.Volume, List[_volume.Volume]],
  1574. regionnames: List[str],
  1575. regionlabels: List[int],
  1576. parcellation_spec: Union[str, "parcellation.Parcellation"] = None
  1577. ) -> 'Map':
  1578. """
  1579. Add a custom labelled parcellation map to siibra from a labelled NIfTI file.
  1580. Parameters
  1581. ------------
  1582. name: str
  1583. Human-readable name of the parcellation.
  1584. volume: Volume, or a list of Volumes.
  1585. space_spec: str, Space
  1586. Specification of the reference space (space object, name, keyword, or id - e.g. 'mni152').
  1587. regionnames: list[str]
  1588. List of human-readable names of the mapped regions.
  1589. regionlabels: list[int]
  1590. List of integer labels in the nifti file corresponding to the list of regions.
  1591. parcellation: str or Parcellation. Optional.
  1592. If the related parcellation already defined or preconfigured in siibra.
  1593. """
  1594. # providers and map indices
  1595. providers = []
  1596. volumes = volume if isinstance(volume, list) else [volume]
  1597. map_space = volumes[0].space
  1598. assert all(v.space == map_space for v in volumes), "Volumes have to be in the same space"
  1599. for vol_idx, vol in enumerate(volumes):
  1600. image = vol.fetch()
  1601. arr = np.asanyarray(image.dataobj)
  1602. labels_in_volume = np.unique(arr)[1:].astype('int')
  1603. # populate region indices from given name/label lists
  1604. indices = dict()
  1605. for label, regionname in zip(regionlabels, regionnames):
  1606. if label not in labels_in_volume:
  1607. logger.warning(
  1608. f"Label {label} not mapped in the provided NIfTI volume -> "
  1609. f"region '{regionname} will not be in the map."
  1610. )
  1611. elif label in [v[0]['label'] for v in indices.values() if v[0]['volume'] == vol_idx]:
  1612. logger.warning(f"Label {label} already defined in the same volume; will not map it to '{regionname}'.")
  1613. else:
  1614. assert regionname not in indices, f"'{regionname}' must be unique in `regionnames`."
  1615. indices[regionname] = [{'volume': vol_idx, 'label': label}]
  1616. # check for any remaining labels in the NIfTI volume
  1617. unnamed_labels = list(set(labels_in_volume) - set(regionlabels))
  1618. if unnamed_labels:
  1619. logger.warning(
  1620. f"The following labels appear in the NIfTI volume {vol_idx}, but not in "
  1621. f"the specified regions: {', '.join(str(lb) for lb in unnamed_labels)}. "
  1622. "They will be removed from the nifti volume."
  1623. )
  1624. for label in unnamed_labels:
  1625. arr[arr == label] = 0
  1626. providers.extend(vol._providers.values())
  1627. # parcellation
  1628. if parcellation_spec is None:
  1629. parcellation_spec = name
  1630. try:
  1631. parcobj = parcellation.Parcellation.registry().get(parcellation_spec)
  1632. logger.info(f"Using '{parcellation_spec}', siibra decoded the parcellation as '{parcobj}'")
  1633. except Exception:
  1634. logger.info(
  1635. f"Using '{parcellation_spec}', siibra could not decode the "
  1636. " parcellation. Building a new parcellation."
  1637. )
  1638. # build a new parcellation
  1639. parcobj = parcellation.Parcellation(
  1640. identifier=generate_uuid(','.join(regionnames)),
  1641. name=name,
  1642. species=vol.space.species,
  1643. regions=list(map(_region.Region, regionnames)),
  1644. )
  1645. if parcobj.key not in list(parcellation.Parcellation.registry()):
  1646. parcellation.Parcellation.registry().add(parcobj.key, parcobj)
  1647. for region in siibra_tqdm(
  1648. indices.keys(),
  1649. desc="Checking if provided regions are defined in the parcellation."
  1650. ):
  1651. try:
  1652. _ = parcobj.get_region(region)
  1653. except Exception:
  1654. logger.warning(f"'{region}' is missing in the parcellation.")
  1655. # build the parcellation map object
  1656. parcmap = Map(
  1657. identifier=generate_uuid(name),
  1658. name=f"{name} map in {map_space.name}",
  1659. space_spec={"@id": map_space.id},
  1660. parcellation_spec={'name': parcobj.name},
  1661. indices=indices,
  1662. volumes=volumes
  1663. )
  1664. # add it to siibra's registry
  1665. Map.registry().add(parcmap.key, parcmap)
  1666. # return the map - note that it has a pointer to the parcellation
  1667. return parcmap

parcellationmap.py at commit f6636aa, under Apache-2.0 · at the source

Overview

Authors: Timo Dickscheid1,2,3, Xiaoyun Gui1, Ahmet N Simsek1, Christian Schiffer1,3, Jean-Francois Mangin4, Yann Leprince4, Viktor Jirsa5, Jan G Bjaalie6, Trygve B Leergaard6, Sebastian Bludau1, Katrin Amunts1,7
  1. Institute of Neuroscience and Medicine (INM-1), Research Centre Jülich, Jülich, Germany
  2. Institute of Computational Visualistics, University of Koblenz, Koblenz, Germany
  3. Helmholtz AI, Research Centre Jülich, Jülich, Germany
  4. NeuroSpin, CEA, Université Paris-Saclay, Gif-sur-Yvette, France
  5. Institut de Neurosciences des Systèmes, INSERM, Aix-Marseille University, Marseille, France
  6. Institute of Basic Medical Sciences, University of Oslo, Oslo, Norway
  7. Medical Faculty & University Hospital Düsseldorf - Cécile & Oskar Vogt Institute of Brain Research, Heinrich Heine University, Düsseldorf, Germany
Journal: Nature methods, volume 23, issue 8, pages 1647-1658
Dates: received 18 March 2025; accepted 15 June 2026; published online 20 July 2026; in print 2026
Type: Research article · Language: English
License: CC BY
Identifiers: DOI 10.1038/s41592-026-03159-x · PMID 42477446 · PMCID PMC13441889 · OpenAlex W4410759675
Open access: hybrid, a free copy (OpenAlex)
Status: code verified (how the code is found and verified)
Categories: structural MRI / diffusion (modality), human (organism), methods / tools (subfield)
Methods: Spectral & time-frequency, fMRI & imaging
Keywords: Computational neuroscience, Data integration, Software, Neuroscience
MeSH: Atlases as Topic*, Brain*, Brain Mapping*, Software*, Humans, Image Processing, Computer-Assisted, Internet, Magnetic Resonance Imaging, User-Computer Interface (* major topic)
Topic: Functional Brain Connectivity Studies (Cognitive Neuroscience, Neuroscience), according to OpenAlex
Funding: EC | Horizon 2020 Framework Programme (EU Framework Programme for Research and Innovation H2020) (945539, 101058516); Helmholtz Association (InterLabs-0015, Portfolio Theme SMHB, ZT-I-PF-4-061); Deutsche Forschungsgemeinschaft (German Research Foundation) (501864659, SPP2041)
Citations: cited by 1 paper (Europe PMC); 76 references in the paper
Research resources: RRID:SCR_001362, RRID:SCR_002498, RRID:SCR_002577, Matplotlib RRID:SCR_008624, as NumPy RRID:SCR_008633, stored in the EBRAINS Knowledge Graph RRID:SCR_017612, fetched tabular data as pandas RRID:SCR_018214, napari RRID:SCR_022765, RRID:SCR_023173, RRID:SCR_023498

Abstract

Computational technology opens new possibilities toward understanding the complexity of the human brain, but it requires integrating measurements from different modalities and scales in an anatomical context and exposing them in an interoperable, actionable form. Especially with growing big data resources, accessing information from different scales and modalities coherently for visual exploration, reproducible analysis and application development remains challenging. Here we present siibra, a tool suite that connects diverse data from cloud resources to reference atlases and coordinate spaces. It supports different use cases by making contents accessible through a web viewer, Python library and HTTP application programming interface. Using siibra we implemented a Multilevel Human Brain Atlas linking macro-anatomical concepts and their inter-subject variability with measurements of the microstructural composition and intrinsic variance of brain regions, building on cytoarchitecture as a reference and supporting MRI-based and microscopic templates. The atlas is integrated with the EBRAINS research infrastructure. All software and content are openly accessible.

Reproduced under the paper's license (CC BY), from the paper cited above.

Repositories

Its files are read in the Code ↔ Paper reader above, with 25 matches between paragraphs and lines of code.

siibra-python.readthedocs.io

License: none: the authors keep all their rights
State: the link answers, verified on 27 September 2026
Evidence: the link answers
Software Heritage: not checked
Found in: “Code availability”
Not found: README, license file, CITATION.cff, environment file, tests, continuous integration, documentation
Availability: 1 check, the latest on 27 September 2026: the link answers (HTTP 200)
  • 27 September 2026: the link answers (HTTP 200)

HumanBrainProject/hbp-spatial-backend

License: Apache-2.0
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Commit: 0acac3bc230fb8a65e6cf1a3f9196648606da65f, 1 April 2025
Languages: Python (13), Shell (2)
Size: 54 files, 15 scripts
Software Heritage: not archived
Found in: the text, “Modeling spatial entities in different reference”
Holds: README, license file, environment (Dockerfile, Dockerfile.server, setup.cfg, setup.py, docker-aims/Dockerfile), tests, continuous integration
Not found: CITATION.cff, documentation
Availability: 1 check, the latest on 27 September 2026: the link answers
  • 27 September 2026: the link answers
17 files

FZJ-INM1-BDA/siibra-tutorials

License: Apache-2.0
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Commit: 88580425bf6815235725df94c5246e7f05583787, 22 June 2026
Languages: Jupyter (12)
Size: 20 files, 12 scripts
Software Heritage: not archived
Found in: “Code availability”
Holds: README, license file, environment (requirements.txt, runtime.txt), continuous integration, 12 notebooks
Not found: CITATION.cff, tests, documentation
Tools: Nilearn (12 files), Matplotlib (10 files), NumPy (2 files), pandas (2 files)
Availability: 1 check, the latest on 27 September 2026: the link answers
  • 27 September 2026: the link answers
14 files

FZJ-INM1-BDA/siibra-python

License: Apache-2.0
State: the link answers, verified on 2 November 2026
Evidence: files inventoried
Commit: f6636aa84bf1b15ce395945670f666510978ee42, 2 November 2026
Languages: Python (172)
Size: 270 files, 172 scripts
Software Heritage: archived
Found in: “Code availability”
Holds: README, license file, CITATION.cff, environment (pyproject.toml, requirements-test.txt, .github/requirements-build.txt, config_schema/requirements.txt, docs/requirements-doc.txt), tests, continuous integration, documentation
Tools: NumPy (47 files), Nilearn (28 files), pandas (19 files), NiBabel (15 files), Matplotlib (14 files), Plotly (6 files), scikit-image (5 files), tifffile (3 files), SciPy (2 files), seaborn (2 files), h5py (1 file), scikit-learn (1 file)
Availability: 2 checks, the latest on 2 November 2026: the link answers
  • 2 November 2026: the link answers
  • 27 September 2026: the link answers
174 files

FZJ-INM1-BDA/siibra-explorer

License: Apache-2.0
State: the link answers, verified on 2 November 2026
Evidence: files inventoried
Commit: a1b93e091f2457ff8d683dab27001b89332e29f9, 26 July 2026
Languages: TypeScript (574), JavaScript (23), Python (22), Shell (2)
Size: 1,304 files, 621 scripts
Software Heritage: archived
Found in: “Code availability”
Holds: README, license file, environment (Dockerfile, backend/requirements.txt, docs/Dockerfile, docs/requirements.txt, docs/develop/docker-compose.yml), tests, continuous integration, documentation
Not found: CITATION.cff
Availability: 2 checks, the latest on 2 November 2026: the link answers
  • 2 November 2026: the link answers
  • 27 September 2026: the link answers
623 files

FZJ-INM1-BDA/siibra-api

License: Apache-2.0
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Commit: 3af86fe2c1f9b7532203d05f47eb4f682b8108b7, 23 September 2026
Languages: Python (489), Shell (2)
Size: 549 files, 491 scripts
Software Heritage: not archived
Found in: “Code availability”
Holds: README, license file, environment (docker-compose.yml, Dockerfile, server.dockerfile, worker-v4.dockerfile, worker.dockerfile, .docker/docker-compose.yaml, requirements/all.txt, requirements/docs.txt, requirements/partial-all.txt, requirements/partial-worker.txt, requirements/server.txt, requirements/siibra.txt), tests, continuous integration, documentation
Not found: CITATION.cff
Tools: NumPy (7 files), NiBabel (2 files), pandas (2 files), Plotly (1 file)
Availability: 1 check, the latest on 27 September 2026: the link answers
  • 27 September 2026: the link answers
493 files

apache.org/licenses

License: none: the authors keep all their rights
State: the link answers, verified on 27 September 2026
Evidence: the link answers
Software Heritage: not checked
Found in: “Code availability”
Not found: README, license file, CITATION.cff, environment file, tests, continuous integration, documentation
Availability: 1 check, the latest on 27 September 2026: the link answers (HTTP 200)
  • 27 September 2026: the link answers (HTTP 200)
At the source: apache.org/licenses/

Zenodo 21127648

License: CC-BY-4.0
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Size: 1 file, 0 scripts
Software Heritage: not checked
Found in: the references
Not found: README, license file, CITATION.cff, environment file, tests, continuous integration, documentation
Availability: 1 check, the latest on 27 September 2026: the link answers (HTTP 200)
  • 27 September 2026: the link answers (HTTP 200)

Code availability

Source codes for siibra are available on GitHub (https://github.com/FZJ-INM1-BDA/siibra-python; https://github.com/FZJ-INM1-BDA/siibra-explorer and https://github.com/FZJ-INM1-BDA/siibra-api) and provided under the Apache 2.0 license (http://www.apache.org/licenses/). We have integrated all components of siibra with Zenodo, which generates unique DOIs for each new release of the tool suite. An installation of the interactive viewer is publicly accessible at https://atlases.ebrains.eu/viewer as a core component of the brain atlas services in the research infrastructure EBRAINS. The web API can be accessed at https://siibra-api.apps.ebrains.eu/v3_0/docs. Researchers can install siibra-python through the Python Package Index from https://pypi.org/project/siibra. Comprehensive online documentation, including executable codes to reproduce all figures can be accessed via https://siibra-python.readthedocs.io/en/v1. More detailed tutorials notebooks are provided at https://github.com/FZJ-INM1-BDA/siibra-tutorials.

Reproduced under the paper's license (CC BY), from the paper cited above.

Tracing map

Proposed by the machine: these links were found in the paper and verified at the source, without human review. The map will receive a Zenodo DOI once one of the paper's authors has validated it with their ORCID.

What the map holds:

  • 8 repositories of the authors' code, each at its verified commit, with its license and how the link was found in the paper;
  • 1,311 scripts, each with its path and the digest of its content;
  • 25 matches between paragraphs of the paper and lines of the code (method lexical-v1);
  • neither the text of the paper nor the code itself.

Its JSON (tracing-map.json) is deposited on Zenodo with its DOI once the map is validated.

Data

Datasets cited

Data Availability Statement

All data used in this work are publicly available via the URLs and references provided with the respective figures. Most contents are published as curated datasets with permanent identifiers on the EBRAINS platform (https://ebrains.eu). Gene expression levels were retrieved from the Allen Human Brain microarray data18,19. The current foundational content linked with the atlas is defined and maintained at https://github.com/FZJ-INM1-BDA/siibra-configurations/tree/v1. An overview is provided as Extended Data Table 2.

Source codes for siibra are available on GitHub (https://github.com/FZJ-INM1-BDA/siibra-python; https://github.com/FZJ-INM1-BDA/siibra-explorer and https://github.com/FZJ-INM1-BDA/siibra-api) and provided under the Apache 2.0 license (http://www.apache.org/licenses/). We have integrated all components of siibra with Zenodo, which generates unique DOIs for each new release of the tool suite. An installation of the interactive viewer is publicly accessible at https://atlases.ebrains.eu/viewer as a core component of the brain atlas services in the research infrastructure EBRAINS. The web API can be accessed at https://siibra-api.apps.ebrains.eu/v3_0/docs. Researchers can install siibra-python through the Python Package Index from https://pypi.org/project/siibra. Comprehensive online documentation, including executable codes to reproduce all figures can be accessed via https://siibra-python.readthedocs.io/en/v1. More detailed tutorials notebooks are provided at https://github.com/FZJ-INM1-BDA/siibra-tutorials.

Reproduced under the paper's license (CC BY), from the paper cited above.

Versions

The history of this record: each version stored by the harvester or made by a correction of its authors or of the maintainers of its code, and what changed in its facts. The texts of the paper (its abstract, its availability statements) are not part of it; versions that changed only those are not listed.

Version 2, 28 September 2026

  • Publisher: n/a → Nature Portfolio

Version 1, 27 September 2026: the first record

Recorded: type, language, journal, volume, issue, pages, dates, 11 authors, 4 keywords, 9 MeSH terms, 3 funders, 60 references, 10 RRIDs.

Cite

This paper

Dickscheid, T., Gui, X., Simsek, A. N., Schiffer, C., Mangin, J.-F., Leprince, Y., Jirsa, V., Bjaalie, J. G., Leergaard, T. B., Bludau, S., & Amunts, K. (2026). Siibra: a software tool suite for realizing a Multilevel Human Brain Atlas from complex data resources. Nature methods, 23(8), 1647-1658. https://doi.org/10.1038/s41592-026-03159-x

BibTeX

@article{dickscheid2026siibra,
author = {Dickscheid, Timo and Gui, Xiaoyun and Simsek, Ahmet N and Schiffer, Christian and Mangin, Jean-Francois and Leprince, Yann and Jirsa, Viktor and Bjaalie, Jan G and Leergaard, Trygve B and Bludau, Sebastian and Amunts, Katrin},
title = {{Siibra: a software tool suite for realizing a Multilevel Human Brain Atlas from complex data resources}},
journal = {Nature methods},
year = {2026},
month = jul,
volume = {23},
number = {8},
pages = {1647--1658},
publisher = {Nature Portfolio},
issn = {1548-7091},
doi = {10.1038/s41592-026-03159-x},
url = {https://doi.org/10.1038/s41592-026-03159-x},
pmid = {42477446},
pmcid = {PMC13441889}
}

RIS

TY - JOUR
AU - Dickscheid, Timo
AU - Gui, Xiaoyun
AU - Simsek, Ahmet N
AU - Schiffer, Christian
AU - Mangin, Jean-Francois
AU - Leprince, Yann
AU - Jirsa, Viktor
AU - Bjaalie, Jan G
AU - Leergaard, Trygve B
AU - Bludau, Sebastian
AU - Amunts, Katrin
TI - Siibra: a software tool suite for realizing a Multilevel Human Brain Atlas from complex data resources
T2 - Nature methods
J2 - Nat Methods
PY - 2026
DA - 2026/07/20
VL - 23
IS - 8
SP - 1647
EP - 1658
SN - 1548-7091
PB - Nature Portfolio
DO - 10.1038/s41592-026-03159-x
UR - https://doi.org/10.1038/s41592-026-03159-x
LA - en
ER -

CSL-JSON

{
"id": "10.1038/s41592-026-03159-x",
"type": "article-journal",
"title": "Siibra: a software tool suite for realizing a Multilevel Human Brain Atlas from complex data resources",
"container-title": "Nature methods",
"author": [
{
"family": "Dickscheid",
"given": "Timo"
},
{
"family": "Gui",
"given": "Xiaoyun"
},
{
"family": "Simsek",
"given": "Ahmet N"
},
{
"family": "Schiffer",
"given": "Christian"
},
{
"family": "Mangin",
"given": "Jean-Francois"
},
{
"family": "Leprince",
"given": "Yann"
},
{
"family": "Jirsa",
"given": "Viktor"
},
{
"family": "Bjaalie",
"given": "Jan G"
},
{
"family": "Leergaard",
"given": "Trygve B"
},
{
"family": "Bludau",
"given": "Sebastian"
},
{
"family": "Amunts",
"given": "Katrin"
}
],
"container-title-short": "Nat Methods",
"volume": "23",
"issue": "8",
"page": "1647-1658",
"DOI": "10.1038/s41592-026-03159-x",
"PMID": "42477446",
"PMCID": "PMC13441889",
"ISSN": "1548-7091",
"publisher": "Nature Portfolio",
"URL": "https://doi.org/10.1038/s41592-026-03159-x",
"language": "en",
"issued": {
"date-parts": [
[
2026,
7,
20
]
]
}
}

The tracing map gets a citation of its own once an author has validated it and it has a DOI.

Similar papers

The papers with a page that share the most with this one: the tools found in their code, their categories, datasets, cited references and authors, the rarest counting most.

[1] doi:10.1038/s41597-023-02389-4 [code]
AtOM, an ontology model to standardize use of brain atlases in tools, workflows, and data infrastructures.
Journal: Scientific data
In common: tifffile, Nilearn, Plotly, 9 other tools, methods / tools, 14 references, 2 authors
[2] doi:10.1126/sciadv.abq7547 [code]
Characterization of regional differences in resting-state fMRI with a data-driven network model of brain dynamics.
Journal: Science advances
In common: NiBabel, seaborn, scikit-learn, 4 other tools, 5 references, 3 authors
[3] doi:10.1162/imag.a.1079 [code]
From fibers to cells: Fourier-based registration enables virtual Cresyl violet staining from 3D polarized light imaging.
Journal: Imaging neuroscience (Cambridge, Mass.)
In common: tifffile, scikit-image, h5py, 6 other tools, 4 references, 2 authors
[4] doi:10.1038/s42003-025-08267-6 [code]
Brainbuilder: a software pipeline for 3D reconstruction of cortical maps from multi-modal 2D data sets.
Journal: Communications biology
In common: scikit-image, h5py, NiBabel, 6 other tools, methods / tools, 8 references, author Katrin Amunts
[5] doi:10.3389/fninf.2022.803934 [code]
Browsing Multiple Subjects When the Atlas Adaptation Cannot Be Achieved <i>via</i> a Warping Strategy.
Journal: Frontiers in neuroinformatics
In common: Nilearn, Matplotlib, NumPy, methods / tools, 7 references, author Yann Leprince
[6] doi:10.1038/s41597-023-02527-y
The efferent connections of the orbitofrontal, posterior parietal, and insular cortex of the rat brain.
Journal: Scientific data
In common: methods / tools, 6 references, 2 authors
[7] doi:10.1038/s41592-023-02034-3
Waxholm Space atlas of the rat brain: a 3D atlas supporting data analysis and integration.
Journal: Nature methods
In common: methods / tools, 5 references, 2 authors
[8] doi:10.1038/s41597-024-03863-3 [code]
Comparison of basal ganglia regions across murine brain atlases using metadata models and the Waxholm Space.
Journal: Scientific data
In common: pandas, Matplotlib, NumPy, methods / tools, 7 references, author Trygve B Leergaard
[9] doi:10.1016/j.neuroimage.2022.119623 [code]
Open and reproducible neuroimaging: From study inception to publication.
Journal: NeuroImage
In common: Nilearn, h5py, NiBabel, 5 other tools, 8 references
[10] doi:10.1038/s41467-025-63177-9 [code]
DeMBA: a developmental atlas for navigating the mouse brain in space and time.
Journal: Nature communications
In common: scikit-image, NiBabel, seaborn, 4 other tools, 1 reference, 2 authors

Contribute

The authors of this paper can claim it, correct its record and validate its tracing map, and the maintainers of its code (its owner, or a public member of its organization) correct what it says of their repository; anyone signed in can ask for its removal. Every request goes to OSCR's own machine, which answers it; your account page follows them.

Sign in with ORCID to claim this paper as one of its authors, correct its record or validate its tracing map: when the paper's metadata lists your ORCID iD, you are recognized at once. Maintainers of its code: sign in with GitHub, then claim the repository on your account page.

Add the badge to the code's README

OSCR: the badge of this paper

If you are an author or a maintainer of this paper's code, you can add this badge. It says what OSCR knows of the paper (its code, its validated tracing map) and links the code to this page. Paste one of these snippets under the README's title. Keep the two marks around it, so that the badge can be replaced in place and is never added twice. OSCR changes nothing in your repository.

Markdown
<!-- oscr-badge:start -->
[![OSCR](https://openscicode.org/badge/doi/10.1038/s41592-026-03159-x.svg)](https://openscicode.org/badge/doi/10.1038/s41592-026-03159-x)
<!-- oscr-badge:end -->
reStructuredText
.. oscr-badge:start

.. image:: https://openscicode.org/badge/doi/10.1038/s41592-026-03159-x.svg
   :target: https://openscicode.org/badge/doi/10.1038/s41592-026-03159-x
   :alt: OSCR

.. oscr-badge:end
HTML
<!-- oscr-badge:start -->
<a href="https://openscicode.org/badge/doi/10.1038/s41592-026-03159-x"><img src="https://openscicode.org/badge/doi/10.1038/s41592-026-03159-x.svg" alt="OSCR"></a>
<!-- oscr-badge:end -->

On GitHub, open the README, choose Edit (the pencil), paste the snippet under the title, then "Commit changes".

If you choose to, you can have the badge kept up to date for you, with oscr badge --write from the command line or with the GitHub Action in your repository's workflows. Every other form and option (a card, AsciiDoc, LaTeX, shields.io) is on the badge page.

Request its removal

To ask OSCR to remove this record, the copies of its authors' scripts or its tracing map, use the removal request page: signed in, you say who you are, what to remove and why, then review and confirm the request. Published rules decide every request (how).

Discussion, reproductions, activity

Discussion: code errors and mismatches between the code and the paper about this paper and its code, from readers and its authors, beside the paper and its tracing map.

Report a mismatch between the code and the paper · Report a code error (signed in)

Reproductions: reports from readers who ran the authors' code and did not get the paper's result, what they ran, with which environment, commit and data.

Report a reproduction failure (signed in)

Versions of its code: the releases of its code tied to a version of this paper (the preprint, the accepted manuscript, the version of record…), each with the tracing map versioned with it.

Activity: what happens around this paper: new versions of its record, its map's validation, discussions and reproductions. It opens with sign-in.