OSCR

NeuroMArVL: An interactive and collaborative web-based tool for visualizing brain networks.

Code ↔ Paper

4 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.

The 4 matches
  1. [1] § IMPLEMENTATION DETAILS › 2D Visualizations ↔ brain-app-server/brain-app/graph2d.ts, lines 266–321 · score 0.67 · node overlaps, COSE bilkent, Compound, nesting, fast
  2. [2] § USAGE DETAILS › Demonstrating NeuroMArVL’s Features ↔ netneurotools/datasets/fetch_template.py, lines 1449–1558 · score 0.56 · diffusion tractography, cortical surface, anatomically, strength, connectomes
  3. [3] § IMPLEMENTATION DETAILS › Included Data ↔ netneurotools/datasets/fetch_template.py, lines 684–744 · score 0.55 · fsLR, spherical, pial, smoothing, midthickness, inflated
  4. [4] § USAGE DETAILS › Data Inputs ↔ netneurotools/datasets/fetch_template.py, lines 1449–1558 · score 0.53 · connection strength, cortical surface, template, inflated, anatomical, human

Paper

Loaded from Europe PMC by your browser, not stored by OSCR: doi.org · Europe PMC

The paper is loaded when this pane is shown.

The authors' code

Python · 1,581 lines · 67 KB · BSD-3-Clause · 3 matches

  1. """Functions for fetching template data."""
  3. import json
  5. from sklearn.utils import Bunch
  7. from .datasets_utils import (
  8. SURFACE,
  9. _get_reference_info,
  10. _check_freesurfer_subjid,
  11. fetch_file,
  12. )
  15. def fetch_fsaverage(
  16. version="fsaverage", use_local=False, force=False, data_dir=None, verbose=1
  17. ):
  18. """
  19. Download files for fsaverage FreeSurfer template.
  21. This dataset contains surface files for the fsaverage template including
  22. original, white matter, pial, inflated, and spherical surfaces for both
  23. left and right hemispheres.
  25. If you used this data, please cite 1_, 2_, 3_.
  27. Parameters
  28. ----------
  29. version : str, optional
  30. One of {'fsaverage', 'fsaverage3', 'fsaverage4', 'fsaverage5',
  31. 'fsaverage6'}. Default: 'fsaverage'
  32. use_local : bool, optional
  33. If True, will attempt to use local FreeSurfer data. Default: False
  35. Returns
  36. -------
  37. filenames : :class:`sklearn.utils.Bunch`
  38. Dictionary-like object with keys ['orig', 'white', 'smoothwm', 'pial',
  39. 'inflated', 'sphere'], where corresponding values are Surface
  40. namedtuples containing filepaths for the left (L) and right (R)
  41. hemisphere surface files.
  43. Other Parameters
  44. ----------------
  45. force : bool, optional
  46. If True, will overwrite existing dataset. Default: False
  47. data_dir : str, optional
  48. Path to use as data directory. If not specified, will check for
  49. environmental variable 'NNT_DATA'; if that is not set, will use
  50. `~/nnt-data` instead. Default: None
  51. verbose : int, optional
  52. Modifies verbosity of download, where higher numbers mean more updates.
  53. Default: 1
  55. Notes
  56. -----
  57. The returned surfaces represent different stages of cortical surface
  58. reconstruction and transformations:
  60. - **orig**: Original surface extracted from the brain volume, representing
  61. the initial estimate of the cortical boundary before topology correction.
  62. - **white**: White matter surface, representing the boundary between white
  63. matter and gray matter (inner cortical surface).
  64. - **smoothwm**: Smoothed white matter surface, created by applying
  65. smoothing to the white surface for improved visualization and analysis.
  66. - **pial**: Pial surface, representing the outer boundary of the cortex
  67. (gray matter/CSF interface). This is commonly used for cortical thickness
  68. calculations and surface-based registration.
  69. - **inflated**: Inflated surface, where sulci and gyri are smoothed to
  70. make visualization of the entire cortical surface easier while preserving
  71. topology. Useful for visualizing data across the cortex without occlusion
  72. by folding patterns.
  73. - **sphere**: Spherical surface, where the cortical surface is mapped to a
  74. sphere. This is essential for surface-based registration, inter-subject
  75. alignment, and applying parcellations.
  77. Each surface can be loaded with neuroimaging tools like nibabel and used
  78. for surface-based analyses, visualization, or spatial transformations.
  80. In a typical FreeSurfer installation, these template surfaces can be found
  81. in the subjects directory under ``$FREESURFER_HOME/subjects/`` (e.g.,
  82. ``$FREESURFER_HOME/subjects/fsaverage/surf/``). When ``use_local=True``,
  83. this function will attempt to locate and use these local files instead of
  84. downloading them.
  86. Example directory tree:
  88. ::
  90. ~/nnt-data/tpl-fsaverage
  91. ├── fsaverage
  92. │ ├── LICENSE
  93. │ └── surf
  94. │ ├── lh.curv
  95. │ ├── lh.inflated
  96. │ ├── lh.inflated_avg
  97. │ ├── lh.orig
  98. │ ├── lh.orig_avg
  99. │ ├── lh.pial
  100. │ ├── lh.pial_avg
  101. │ ├── lh.smoothwm
  102. │ ├── lh.sphere
  103. │ ├── lh.sphere.reg.avg
  104. │ ├── lh.white
  105. │ ├── lh.white_avg
  106. │ ├── rh.curv
  107. │ ├── rh.inflated
  108. │ ├── rh.inflated_avg
  109. │ ├── rh.orig
  110. │ ├── rh.orig_avg
  111. │ ├── rh.pial
  112. │ ├── rh.pial_avg
  113. │ ├── rh.smoothwm
  114. │ ├── rh.sphere
  115. │ ├── rh.sphere.reg.avg
  116. │ ├── rh.white
  117. │ └── rh.white_avg
  118. ├── fsaverage3
  119. │ ├── LICENSE
  120. │ └── surf
  121. │ ├── lh.curv
  122. │ ├── lh.inflated
  123. │ ├── lh.inflated_avg
  124. │ ├── lh.orig
  125. │ ├── lh.orig_avg
  126. │ ├── lh.pial
  127. │ ├── lh.pial_avg
  128. │ ├── lh.smoothwm
  129. │ ├── lh.sphere
  130. │ ├── lh.sphere.reg.avg
  131. │ ├── lh.white
  132. │ ├── lh.white_avg
  133. │ ├── rh.curv
  134. │ ├── rh.inflated
  135. │ ├── rh.inflated_avg
  136. │ ├── rh.orig
  137. │ ├── rh.orig_avg
  138. │ ├── rh.pial
  139. │ ├── rh.pial_avg
  140. │ ├── rh.smoothwm
  141. │ ├── rh.sphere
  142. │ ├── rh.sphere.reg.avg
  143. │ ├── rh.white
  144. │ └── rh.white_avg
  145. ├── fsaverage4
  146. │ ├── LICENSE
  147. │ └── surf
  148. │ ├── lh.curv
  149. │ ├── lh.inflated
  150. │ ├── lh.inflated_avg
  151. │ ├── lh.orig
  152. │ ├── lh.orig_avg
  153. │ ├── lh.pial
  154. │ ├── lh.pial_avg
  155. │ ├── lh.smoothwm
  156. │ ├── lh.sphere
  157. │ ├── lh.sphere.reg.avg
  158. │ ├── lh.white
  159. │ ├── lh.white_avg
  160. │ ├── rh.curv
  161. │ ├── rh.inflated
  162. │ ├── rh.inflated_avg
  163. │ ├── rh.orig
  164. │ ├── rh.orig_avg
  165. │ ├── rh.pial
  166. │ ├── rh.pial_avg
  167. │ ├── rh.smoothwm
  168. │ ├── rh.sphere
  169. │ ├── rh.sphere.reg.avg
  170. │ ├── rh.white
  171. │ └── rh.white_avg
  172. ├── fsaverage5
  173. │ ├── LICENSE
  174. │ └── surf
  175. │ ├── lh.curv
  176. │ ├── lh.inflated
  177. │ ├── lh.inflated_avg
  178. │ ├── lh.orig
  179. │ ├── lh.orig_avg
  180. │ ├── lh.pial
  181. │ ├── lh.pial_avg
  182. │ ├── lh.smoothwm
  183. │ ├── lh.sphere
  184. │ ├── lh.sphere.reg.avg
  185. │ ├── lh.white
  186. │ ├── lh.white_avg
  187. │ ├── rh.curv
  188. │ ├── rh.inflated
  189. │ ├── rh.inflated_avg
  190. │ ├── rh.orig
  191. │ ├── rh.orig_avg
  192. │ ├── rh.pial
  193. │ ├── rh.pial_avg
  194. │ ├── rh.smoothwm
  195. │ ├── rh.sphere
  196. │ ├── rh.sphere.reg.avg
  197. │ ├── rh.white
  198. │ └── rh.white_avg
  199. └── fsaverage6
  200. ├── LICENSE
  201. └── surf
  202. ├── lh.curv
  203. ├── lh.inflated
  204. ├── lh.inflated_avg
  205. ├── lh.orig
  206. ├── lh.orig_avg
  207. ├── lh.pial
  208. ├── lh.pial_avg
  209. ├── lh.smoothwm
  210. ├── lh.sphere
  211. ├── lh.sphere.reg.avg
  212. ├── lh.white
  213. ├── lh.white_avg
  214. ├── rh.curv
  215. ├── rh.inflated
  216. ├── rh.inflated_avg
  217. ├── rh.orig
  218. ├── rh.orig_avg
  219. ├── rh.pial
  220. ├── rh.pial_avg
  221. ├── rh.smoothwm
  222. ├── rh.sphere
  223. ├── rh.sphere.reg.avg
  224. ├── rh.white
  225. └── rh.white_avg
  227. 10 directories, 125 files
  229. References
  230. ----------
  231. .. [1] Anders M Dale, Bruce Fischl, and Martin I Sereno. Cortical
  232. surface-based analysis: i. segmentation and surface reconstruction.
  233. Neuroimage, 9(2):179\u2013194, 1999.
  234. .. [2] Bruce Fischl, Martin I Sereno, and Anders M Dale. Cortical
  235. surface-based analysis: ii: inflation, flattening, and a surface-based
  236. coordinate system. Neuroimage, 9(2):195\u2013207, 1999.
  237. .. [3] Bruce Fischl, Martin I Sereno, Roger BH Tootell, and Anders M Dale.
  238. High-resolution intersubject averaging and a coordinate system for the
  239. cortical surface. Human brain mapping, 8(4):272\u2013284, 1999.
  241. Examples
  242. --------
  243. Load the fsaverage template surfaces:
  245. >>> surfaces = fetch_fsaverage(version='fsaverage') # doctest: +SKIP
  246. >>> surfaces.keys() # doctest: +SKIP
  247. dict_keys(['orig', 'white', 'smoothwm', 'pial', 'inflated', 'sphere'])
  249. Access the pial surface paths for left and right hemispheres:
  251. >>> surfaces.pial # doctest: +SKIP
  252. Surface(L=PosixPath('~/nnt-data/tpl-fsaverage/fsaverage/surf/lh.pial'),
  253. R=PosixPath('~/nnt-data/tpl-fsaverage/fsaverage/surf/rh.pial'))
  255. Load the left pial surface with nibabel to examine its structure:
  257. >>> import nibabel as nib # doctest: +SKIP
  258. >>> pial_left = nib.freesurfer.read_geometry(surfaces.pial.L) # doctest: +SKIP
  259. >>> vertices, faces = pial_left # doctest: +SKIP
  260. >>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}") # doctest: +SKIP
  261. Vertices: (163842, 3), Faces: (327680, 3)
  262. """
  263. versions = ["fsaverage", "fsaverage3", "fsaverage4", "fsaverage5", "fsaverage6"]
  264. if version not in versions:
  265. raise ValueError(
  266. f"The version of fsaverage requested {version} does not "
  267. f"exist. Must be one of {versions}"
  268. )
  270. dataset_name = "tpl-fsaverage"
  271. _get_reference_info(dataset_name, verbose=verbose)
  273. keys = ["orig", "white", "smoothwm", "pial", "inflated", "sphere"]
  275. if use_local:
  276. try:
  277. data_dir = _check_freesurfer_subjid(version)[1]
  278. data = {
  279. k: SURFACE(
  280. data_dir / f"{version}/surf/lh.{k}",
  281. data_dir / f"{version}/surf/rh.{k}",
  282. )
  283. for k in keys
  284. }
  285. except FileNotFoundError:
  286. raise FileNotFoundError(
  287. f"Local FreeSurfer data for {version} not found. "
  288. "Please ensure FreeSurfer is installed and properly set up."
  289. ) from None
  290. else:
  291. fetched = fetch_file(
  292. dataset_name, keys=version, force=force, data_dir=data_dir, verbose=verbose
  293. )
  295. data = {
  296. k: SURFACE(
  297. fetched / f"surf/lh.{k}",
  298. fetched / f"surf/rh.{k}",
  299. )
  300. for k in keys
  301. }
  303. return Bunch(**data)
  306. def fetch_fsaverage_curated(version="fsaverage", force=False, data_dir=None, verbose=1):
  307. """
  308. Download files for fsaverage FreeSurfer template.
  310. This dataset contains surface geometry files (white, pial, inflated,
  311. sphere), medial wall labels, and surface shape files (sulcal depth and
  312. vertex area) in GIFTI format for the fsaverage template at various
  313. densities.
  315. If you used this data, please cite 1_, 2_, 3_, 4_.
  317. Parameters
  318. ----------
  319. version : str, optional
  320. One of {'fsaverage', 'fsaverage4', 'fsaverage5', 'fsaverage6'}.
  321. Default: 'fsaverage'
  323. Returns
  324. -------
  325. filenames : :class:`sklearn.utils.Bunch`
  326. Dictionary-like object with keys ['white', 'pial', 'inflated',
  327. 'sphere', 'medial', 'sulc', 'vaavg'], where corresponding values are
  328. Surface namedtuples containing filepaths for the left (L) and right
  329. (R) hemisphere files in GIFTI format.
  331. Other Parameters
  332. ----------------
  333. force : bool, optional
  334. If True, will overwrite existing dataset. Default: False
  335. data_dir : str, optional
  336. Path to use as data directory. If not specified, will check for
  337. environmental variable 'NNT_DATA'; if that is not set, will use
  338. `~/nnt-data` instead. Default: None
  339. verbose : int, optional
  340. Modifies verbosity of download, where higher numbers mean more updates.
  341. Default: 1
  343. Notes
  344. -----
  345. This function fetches curated fsaverage surfaces from the neuromaps
  346. package (see `neuromaps.datasets.fetch_fsaverage <https://netneurolab.github.io/neuromaps/generated/neuromaps.datasets.fetch_fsaverage.html>`_).
  347. All files are provided in GIFTI format (.gii) rather than FreeSurfer's
  348. native format.
  350. The returned files include:
  352. - **white**: White matter surface geometry (.surf.gii), representing the
  353. boundary between white matter and gray matter. Corresponds to FreeSurfer
  354. surfaces 'lh.white' and 'rh.white'.
  355. - **pial**: Pial surface geometry (.surf.gii), representing the outer
  356. cortical boundary. Corresponds to FreeSurfer surfaces 'lh.pial' and
  357. 'rh.pial'.
  358. - **inflated**: Inflated surface geometry (.surf.gii) for improved
  359. visualization of sulci and gyri. Corresponds to FreeSurfer surfaces
  360. 'lh.inflated' and 'rh.inflated'.
  361. - **sphere**: Spherical surface geometry (.surf.gii) used for surface-based
  362. registration and applying parcellations. Corresponds to FreeSurfer
  363. surfaces 'lh.sphere' and 'rh.sphere'.
  364. - **medial**: Medial wall mask (.label.gii) indicating vertices to exclude
  365. from analyses (vertices with no cortex). Not a standard FreeSurfer
  366. output; derived by neuromaps to mark the no-medial-wall vertices.
  367. - **sulc**: Sulcal depth map (.shape.gii) providing sulcal/gyral patterns
  368. on the midthickness surface. Corresponds to FreeSurfer 'lh.sulc' and
  369. 'rh.sulc' values resampled to the midthickness surface.
  370. - **vaavg**: Vertex area map (.shape.gii) representing the average vertex
  371. area on the midthickness surface. Not a standard FreeSurfer output;
  372. computed from mesh triangle areas and averaged per vertex.
  374. The vertex density varies by version: fsaverage (164k vertices),
  375. fsaverage6 (41k), fsaverage5 (10k), and fsaverage4 (3k).
  377. Example directory tree:
  379. ::
  381. ~/nnt-data/tpl-fsaverage_curated
  382. ├── fsaverage
  383. │ ├── tpl-fsaverage_den-164k_hemi-L_desc-nomedialwall_dparc.label.gii
  384. │ ├── tpl-fsaverage_den-164k_hemi-L_desc-sulc_midthickness.shape.gii
  385. │ ├── tpl-fsaverage_den-164k_hemi-L_desc-vaavg_midthickness.shape.gii
  386. │ ├── tpl-fsaverage_den-164k_hemi-L_inflated.surf.gii
  387. │ ├── tpl-fsaverage_den-164k_hemi-L_pial.surf.gii
  388. │ ├── tpl-fsaverage_den-164k_hemi-L_sphere.surf.gii
  389. │ ├── tpl-fsaverage_den-164k_hemi-L_white.surf.gii
  390. │ ├── tpl-fsaverage_den-164k_hemi-R_desc-nomedialwall_dparc.label.gii
  391. │ ├── tpl-fsaverage_den-164k_hemi-R_desc-sulc_midthickness.shape.gii
  392. │ ├── tpl-fsaverage_den-164k_hemi-R_desc-vaavg_midthickness.shape.gii
  393. │ ├── tpl-fsaverage_den-164k_hemi-R_inflated.surf.gii
  394. │ ├── tpl-fsaverage_den-164k_hemi-R_pial.surf.gii
  395. │ ├── tpl-fsaverage_den-164k_hemi-R_sphere.surf.gii
  396. │ └── tpl-fsaverage_den-164k_hemi-R_white.surf.gii
  397. ├── fsaverage4
  398. │ ├── tpl-fsaverage_den-3k_hemi-L_desc-nomedialwall_dparc.label.gii
  399. │ ├── tpl-fsaverage_den-3k_hemi-L_desc-sulc_midthickness.shape.gii
  400. │ ├── tpl-fsaverage_den-3k_hemi-L_desc-vaavg_midthickness.shape.gii
  401. │ ├── tpl-fsaverage_den-3k_hemi-L_inflated.surf.gii
  402. │ ├── tpl-fsaverage_den-3k_hemi-L_pial.surf.gii
  403. │ ├── tpl-fsaverage_den-3k_hemi-L_sphere.surf.gii
  404. │ ├── tpl-fsaverage_den-3k_hemi-L_white.surf.gii
  405. │ ├── tpl-fsaverage_den-3k_hemi-R_desc-nomedialwall_dparc.label.gii
  406. │ ├── tpl-fsaverage_den-3k_hemi-R_desc-sulc_midthickness.shape.gii
  407. │ ├── tpl-fsaverage_den-3k_hemi-R_desc-vaavg_midthickness.shape.gii
  408. │ ├── tpl-fsaverage_den-3k_hemi-R_inflated.surf.gii
  409. │ ├── tpl-fsaverage_den-3k_hemi-R_pial.surf.gii
  410. │ ├── tpl-fsaverage_den-3k_hemi-R_sphere.surf.gii
  411. │ └── tpl-fsaverage_den-3k_hemi-R_white.surf.gii
  412. ├── fsaverage5
  413. │ ├── tpl-fsaverage_den-10k_hemi-L_desc-nomedialwall_dparc.label.gii
  414. │ ├── tpl-fsaverage_den-10k_hemi-L_desc-sulc_midthickness.shape.gii
  415. │ ├── tpl-fsaverage_den-10k_hemi-L_desc-vaavg_midthickness.shape.gii
  416. │ ├── tpl-fsaverage_den-10k_hemi-L_inflated.surf.gii
  417. │ ├── tpl-fsaverage_den-10k_hemi-L_pial.surf.gii
  418. │ ├── tpl-fsaverage_den-10k_hemi-L_sphere.surf.gii
  419. │ ├── tpl-fsaverage_den-10k_hemi-L_white.surf.gii
  420. │ ├── tpl-fsaverage_den-10k_hemi-R_desc-nomedialwall_dparc.label.gii
  421. │ ├── tpl-fsaverage_den-10k_hemi-R_desc-sulc_midthickness.shape.gii
  422. │ ├── tpl-fsaverage_den-10k_hemi-R_desc-vaavg_midthickness.shape.gii
  423. │ ├── tpl-fsaverage_den-10k_hemi-R_inflated.surf.gii
  424. │ ├── tpl-fsaverage_den-10k_hemi-R_pial.surf.gii
  425. │ ├── tpl-fsaverage_den-10k_hemi-R_sphere.surf.gii
  426. │ └── tpl-fsaverage_den-10k_hemi-R_white.surf.gii
  427. └── fsaverage6
  428. ├── tpl-fsaverage_den-41k_hemi-L_desc-nomedialwall_dparc.label.gii
  429. ├── tpl-fsaverage_den-41k_hemi-L_desc-sulc_midthickness.shape.gii
  430. ├── tpl-fsaverage_den-41k_hemi-L_desc-vaavg_midthickness.shape.gii
  431. ├── tpl-fsaverage_den-41k_hemi-L_inflated.surf.gii
  432. ├── tpl-fsaverage_den-41k_hemi-L_pial.surf.gii
  433. ├── tpl-fsaverage_den-41k_hemi-L_sphere.surf.gii
  434. ├── tpl-fsaverage_den-41k_hemi-L_white.surf.gii
  435. ├── tpl-fsaverage_den-41k_hemi-R_desc-nomedialwall_dparc.label.gii
  436. ├── tpl-fsaverage_den-41k_hemi-R_desc-sulc_midthickness.shape.gii
  437. ├── tpl-fsaverage_den-41k_hemi-R_desc-vaavg_midthickness.shape.gii
  438. ├── tpl-fsaverage_den-41k_hemi-R_inflated.surf.gii
  439. ├── tpl-fsaverage_den-41k_hemi-R_pial.surf.gii
  440. ├── tpl-fsaverage_den-41k_hemi-R_sphere.surf.gii
  441. └── tpl-fsaverage_den-41k_hemi-R_white.surf.gii
  443. 4 directories, 56 files
  445. References
  446. ----------
  447. .. [1] Anders M Dale, Bruce Fischl, and Martin I Sereno. Cortical
  448. surface-based analysis: i. segmentation and surface reconstruction.
  449. Neuroimage, 9(2):179\u2013194, 1999.
  450. .. [2] Bruce Fischl, Martin I Sereno, and Anders M Dale. Cortical
  451. surface-based analysis: ii: inflation, flattening, and a surface-based
  452. coordinate system. Neuroimage, 9(2):195\u2013207, 1999.
  453. .. [3] Bruce Fischl, Martin I Sereno, Roger BH Tootell, and Anders M Dale.
  454. High-resolution intersubject averaging and a coordinate system for the
  455. cortical surface. Human brain mapping, 8(4):272\u2013284, 1999.
  456. .. [4] Ross D Markello, Justine Y Hansen, Zhen-Qi Liu, Vincent Bazinet,
  457. Golia Shafiei, Laura E Su\u00e1rez, Nadia Blostein, Jakob Seidlitz,
  458. Sylvain Baillet, Theodore D Satterthwaite, and others. Neuromaps:
  459. structural and functional interpretation of brain maps. Nature Methods,
  460. 19(11):1472\u20131479, 2022.
  462. Examples
  463. --------
  464. Load the fsaverage curated template surfaces:
  466. >>> surfaces = fetch_fsaverage_curated(version='fsaverage') # doctest: +SKIP
  467. >>> surfaces.keys() # doctest: +SKIP
  468. dict_keys(['white', 'pial', 'inflated', 'sphere', 'medial', 'sulc', 'vaavg'])
  470. Access the pial surface GIFTI files:
  472. >>> surfaces.pial # doctest: +SKIP
  473. Surface(L=PosixPath('~/nnt-data/tpl-fsaverage_curated/fsaverage/tpl-fsaverage_den-164k_hemi-L_pial.surf.gii'),
  474. R=PosixPath('~/nnt-data/tpl-fsaverage_curated/fsaverage/tpl-fsaverage_den-164k_hemi-R_pial.surf.gii'))
  476. Load the left pial surface with nibabel:
  478. >>> import nibabel as nib # doctest: +SKIP
  479. >>> pial_left = nib.load(surfaces.pial.L) # doctest: +SKIP
  480. >>> vertices = pial_left.agg_data('pointset') # doctest: +SKIP
  481. >>> faces = pial_left.agg_data('triangle') # doctest: +SKIP
  482. >>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}") # doctest: +SKIP
  483. Vertices: (163842, 3), Faces: (327680, 3)
  485. Load and examine the sulcal depth data:
  487. >>> sulc_left = nib.load(surfaces.sulc.L) # doctest: +SKIP
  488. >>> sulc_data = sulc_left.agg_data() # doctest: +SKIP
  489. >>> sulc_min, sulc_max = sulc_data.min(), sulc_data.max() # doctest: +SKIP
  490. >>> print(f"Sulcal depth range: {sulc_min:.2f} to {sulc_max:.2f}") # doctest: +SKIP
  491. Sulcal depth range: -1.78 to 1.88
  492. """
  493. versions = ["fsaverage", "fsaverage6", "fsaverage5", "fsaverage4"]
  494. if version not in versions:
  495. raise ValueError(
  496. f"The version of fsaverage requested {version} does not "
  497. f"exist. Must be one of {versions}"
  498. )
  500. dataset_name = "tpl-fsaverage_curated"
  501. _get_reference_info("tpl-fsaverage_curated", verbose=verbose)
  503. keys = ["white", "pial", "inflated", "sphere", "medial", "sulc", "vaavg"]
  504. keys_suffix = {
  505. "white": "white.surf",
  506. "pial": "pial.surf",
  507. "inflated": "inflated.surf",
  508. "sphere": "sphere.surf",
  509. "medial": "desc-nomedialwall_dparc.label",
  510. "sulc": "desc-sulc_midthickness.shape",
  511. "vaavg": "desc-vaavg_midthickness.shape",
  512. }
  513. version_density = {
  514. "fsaverage": "164k",
  515. "fsaverage6": "41k",
  516. "fsaverage5": "10k",
  517. "fsaverage4": "3k",
  518. }
  519. density = version_density[version]
  521. fetched = fetch_file(
  522. dataset_name, keys=version, force=force, data_dir=data_dir, verbose=verbose
  523. )
  525. # deal with default neuromaps directory structure in the archive
  526. if not fetched.exists():
  527. import shutil
  529. shutil.move(fetched.parent / "atlases/fsaverage", fetched)
  530. shutil.rmtree(fetched.parent / "atlases")
  532. data = {
  533. k: SURFACE(
  534. fetched / f"tpl-fsaverage_den-{density}_hemi-L_{keys_suffix[k]}.gii",
  535. fetched / f"tpl-fsaverage_den-{density}_hemi-R_{keys_suffix[k]}.gii",
  536. )
  537. for k in keys
  538. }
  540. return Bunch(**data)
  543. def fetch_hcp_standards(force=False, data_dir=None, verbose=1):
  544. """
  545. Fetch HCP standard mesh atlases for converting between FreeSurfer and HCP.
  547. This dataset contains standard mesh atlases used by Connectome Workbench
  548. to convert and register data between FreeSurfer fsaverage space and HCP
  549. fsLR space. It includes spherical templates for fsaverage and fsLR at
  550. multiple vertex densities (e.g., 164k, 59k, 32k), mapping spheres between
  551. fs (hemisphere-specific) and fsLR, and midthickness vertex area averages
  552. (``va_avg``) for resampling and area-preserving operations.
  554. The original file was from 3_, but is no longer available. The archived
  555. file is available from 4_.
  557. If you used this data, please cite 1_, 2_.
  559. Returns
  560. -------
  561. standards : str
  562. Filepath to standard_mesh_atlases directory
  564. Other Parameters
  565. ----------------
  566. force : bool, optional
  567. If True, will overwrite existing dataset. Default: False
  568. data_dir : str, optional
  569. Path to use as data directory. If not specified, will check for
  570. environmental variable 'NNT_DATA'; if that is not set, will use
  571. `~/nnt-data` instead. Default: None
  572. verbose : int, optional
  573. Modifies verbosity of download, where higher numbers mean more updates.
  574. Default: 1
  576. Notes
  577. -----
  578. Returns the path to the `standard_mesh_atlases` directory containing
  579. curated GIFTI files used for conversions between FreeSurfer fsaverage and
  580. HCP fsLR spaces, including spherical templates and midthickness vertex-area
  581. maps at multiple densities.
  583. Example directory tree:
  585. ::
  587. ~/nnt-data/tpl-hcp_standards/standard_mesh_atlases
  588. ├── fsaverage.L_LR.spherical_std.164k_fs_LR.surf.gii
  589. ├── fsaverage.R_LR.spherical_std.164k_fs_LR.surf.gii
  590. ├── fs_L
  591. │ ├── fsaverage.L.sphere.164k_fs_L.surf.gii
  592. │ └── fs_L-to-fs_LR_fsaverage.L_LR.spherical_std.164k_fs_L.surf.gii
  593. ├── fs_R
  594. │ ├── fsaverage.R.sphere.164k_fs_R.surf.gii
  595. │ └── fs_R-to-fs_LR_fsaverage.R_LR.spherical_std.164k_fs_R.surf.gii
  596. ├── L.sphere.32k_fs_LR.surf.gii
  597. ├── L.sphere.59k_fs_LR.surf.gii
  598. ├── resample_fsaverage
  599. │ ├── fsaverage4.L.midthickness_va_avg.3k_fsavg_L.shape.gii
  600. │ ├── fsaverage4.R.midthickness_va_avg.3k_fsavg_R.shape.gii
  601. │ ├── fsaverage4_std_sphere.L.3k_fsavg_L.surf.gii
  602. │ ├── fsaverage4_std_sphere.R.3k_fsavg_R.surf.gii
  603. │ ├── fsaverage5.L.midthickness_va_avg.10k_fsavg_L.shape.gii
  604. │ ├── fsaverage5.R.midthickness_va_avg.10k_fsavg_R.shape.gii
  605. │ ├── fsaverage5_std_sphere.L.10k_fsavg_L.surf.gii
  606. │ ├── fsaverage5_std_sphere.R.10k_fsavg_R.surf.gii
  607. │ ├── fsaverage6.L.midthickness_va_avg.41k_fsavg_L.shape.gii
  608. │ ├── fsaverage6.R.midthickness_va_avg.41k_fsavg_R.shape.gii
  609. │ ├── fsaverage6_std_sphere.L.41k_fsavg_L.surf.gii
  610. │ ├── fsaverage6_std_sphere.R.41k_fsavg_R.surf.gii
  611. │ ├── fsaverage.L.midthickness_va_avg.164k_fsavg_L.shape.gii
  612. │ ├── fsaverage.R.midthickness_va_avg.164k_fsavg_R.shape.gii
  613. │ ├── fsaverage_std_sphere.L.164k_fsavg_L.surf.gii
  614. │ ├── fsaverage_std_sphere.R.164k_fsavg_R.surf.gii
  615. │ ├── fs_LR-deformed_to-fsaverage.L.sphere.164k_fs_LR.surf.gii
  616. │ ├── fs_LR-deformed_to-fsaverage.L.sphere.32k_fs_LR.surf.gii
  617. │ ├── fs_LR-deformed_to-fsaverage.L.sphere.59k_fs_LR.surf.gii
  618. │ ├── fs_LR-deformed_to-fsaverage.R.sphere.164k_fs_LR.surf.gii
  619. │ ├── fs_LR-deformed_to-fsaverage.R.sphere.32k_fs_LR.surf.gii
  620. │ ├── fs_LR-deformed_to-fsaverage.R.sphere.59k_fs_LR.surf.gii
  621. │ ├── fs_LR.L.midthickness_va_avg.164k_fs_LR.shape.gii
  622. │ ├── fs_LR.L.midthickness_va_avg.32k_fs_LR.shape.gii
  623. │ ├── fs_LR.L.midthickness_va_avg.59k_fs_LR.shape.gii
  624. │ ├── fs_LR.R.midthickness_va_avg.164k_fs_LR.shape.gii
  625. │ ├── fs_LR.R.midthickness_va_avg.32k_fs_LR.shape.gii
  626. │ └── fs_LR.R.midthickness_va_avg.59k_fs_LR.shape.gii
  627. ├── R.sphere.32k_fs_LR.surf.gii
  628. └── R.sphere.59k_fs_LR.surf.gii
  630. 3 directories, 38 files
  632. References
  633. ----------
  634. .. [1] David C Van Essen, Kamil Ugurbil, Edward Auerbach, Deanna
  635. Barch,Timothy EJ Behrens, Richard Bucholz, Acer Chang, Liyong Chen,
  636. Maurizio Corbetta, Sandra W Curtiss, and others. The human connectome
  637. project: a data acquisition perspective. Neuroimage,
  638. 62(4):2222\u20132231, 2012.
  639. .. [2] Matthew F Glasser, Stamatios N Sotiropoulos, J Anthony Wilson,
  640. Timothy S Coalson, Bruce Fischl, Jesper L Andersson, Junqian Xu, Saad
  641. Jbabdi, Matthew Webster, Jonathan R Polimeni, and others. The minimal
  642. preprocessing pipelines for the human connectome project. Neuroimage,
  643. 80:105\u2013124, 2013.
  644. .. [3] http://brainvis.wustl.edu/workbench/standard_mesh_atlases.zip
  645. .. [4] https://web.archive.org/web/20220121035833/http://brainvis.wustl.edu/workbench/standard_mesh_atlases.zip
  647. Examples
  648. --------
  649. Load the standards directory and inspect contents:
  651. >>> standards = fetch_hcp_standards() # doctest: +SKIP
  652. >>> print(standards) # doctest: +SKIP
  653. PosixPath('~/nnt-data/tpl-hcp_standards/standard_mesh_atlases')
  655. List the fsLR 32k spherical templates:
  657. >>> import pathlib # doctest: +SKIP
  658. >>> list((standards).glob('L.sphere.32k_fs_LR.surf.gii')) # doctest: +SKIP
  659. [PosixPath('~/nnt-data/tpl-hcp_standards/standard_mesh_atlases/L.sphere.32k_fs_LR.surf.gii')]
  661. Load a sphere surface with nibabel and examine geometry:
  663. >>> import nibabel as nib # doctest: +SKIP
  664. >>> gii = nib.load(standards / 'L.sphere.32k_fs_LR.surf.gii') # doctest: +SKIP
  665. >>> vertices = gii.agg_data('pointset') # doctest: +SKIP
  666. >>> faces = gii.agg_data('triangle') # doctest: +SKIP
  667. >>> vertices.shape, faces.shape # doctest: +SKIP
  668. ((32492, 3), (64980, 3))
  669. """
  670. dataset_name = "tpl-hcp_standards"
  671. _get_reference_info(dataset_name, verbose=verbose)
  673. fetched = fetch_file(
  674. dataset_name,
  675. keys="standard_mesh_atlases",
  676. force=force,
  677. data_dir=data_dir,
  678. verbose=verbose,
  679. )
  681. return fetched
  684. def fetch_fslr_curated(version="fslr32k", force=False, data_dir=None, verbose=1):
  685. """
  686. Download files for HCP fsLR template.
  688. This dataset contains surface geometry files (midthickness, inflated,
  689. veryinflated [where available], sphere), medial wall labels, and surface
  690. shape files (sulcal depth and vertex area) in GIFTI format for the HCP fsLR
  691. template at various densities.
  693. If you used this data, please cite 1_, 2_, 3_.
  695. Parameters
  696. ----------
  697. version : str, optional
  698. One of {"fslr4k", "fslr8k", "fslr32k", "fslr164k"}. Default: 'fslr32k'
  700. Returns
  701. -------
  702. filenames : :class:`sklearn.utils.Bunch`
  703. Dictionary-like object with keys ['midthickness', 'inflated',
  704. 'veryinflated' (except for 'fslr4k'/'fslr8k'), 'sphere', 'medial',
  705. 'sulc', 'vaavg'], where corresponding values are Surface namedtuples
  706. containing filepaths for the left (L) and right (R) hemisphere files
  707. in GIFTI format.
  709. Other Parameters
  710. ----------------
  711. force : bool, optional
  712. If True, will overwrite existing dataset. Default: False
  713. data_dir : str, optional
  714. Path to use as data directory. If not specified, will check for
  715. environmental variable 'NNT_DATA'; if that is not set, will use
  716. `~/nnt-data` instead. Default: None
  717. verbose : int, optional
  718. Modifies verbosity of download, where higher numbers mean more updates.
  719. Default: 1
  721. Notes
  722. -----
  723. This function fetches curated fsLR surfaces from the neuromaps
  724. package (see `neuromaps.datasets.fetch_fslr <https://netneurolab.github.io/neuromaps/generated/neuromaps.datasets.fetch_fslr.html>`_).
  725. All files are provided in GIFTI format (.gii). The fsLR template is the
  726. HCP standard mesh used for group analyses and cross-subject alignment.
  729. The returned files include:
  731. - **midthickness**: Midthickness surface geometry (.surf.gii), halfway
  732. between white and pial surfaces; often preferred for data mapping.
  733. - **inflated**: Inflated surface geometry (.surf.gii) for improved
  734. visualization of sulci and gyri.
  735. - **veryinflated**: Very inflated surface geometry (.surf.gii) providing
  736. additional smoothing; not available for 'fslr4k'/'fslr8k'.
  737. - **sphere**: Spherical surface geometry (.surf.gii) used for surface-based
  738. registration and applying parcellations.
  739. - **medial**: Medial wall mask (.label.gii) indicating vertices to exclude
  740. from analyses (vertices with no cortex).
  741. - **sulc**: Sulcal depth map (.shape.gii) providing sulcal/gyral patterns
  742. on the midthickness surface.
  743. - **vaavg**: Vertex area map (.shape.gii) representing the average vertex
  744. area on the midthickness surface.
  746. The vertex density varies by version: fslr4k (≈4k vertices), fslr8k (≈8k),
  747. fslr32k (≈32k), and fslr164k (≈164k) per hemisphere.
  749. Example directory tree:
  751. ::
  753. ~/nnt-data/tpl-fslr_curated
  754. ├── fslr164k
  755. │ ├── README.md
  756. │ ├── tpl-fsLR_den-164k_hemi-L_desc-nomedialwall_dparc.label.gii
  757. │ ├── tpl-fsLR_den-164k_hemi-L_desc-sulc_midthickness.shape.gii
  758. │ ├── tpl-fsLR_den-164k_hemi-L_desc-vaavg_midthickness.shape.gii
  759. │ ├── tpl-fsLR_den-164k_hemi-L_inflated.surf.gii
  760. │ ├── tpl-fsLR_den-164k_hemi-L_midthickness.surf.gii
  761. │ ├── tpl-fsLR_den-164k_hemi-L_sphere.surf.gii
  762. │ ├── tpl-fsLR_den-164k_hemi-L_veryinflated.surf.gii
  763. │ ├── tpl-fsLR_den-164k_hemi-R_desc-nomedialwall_dparc.label.gii
  764. │ ├── tpl-fsLR_den-164k_hemi-R_desc-sulc_midthickness.shape.gii
  765. │ ├── tpl-fsLR_den-164k_hemi-R_desc-vaavg_midthickness.shape.gii
  766. │ ├── tpl-fsLR_den-164k_hemi-R_inflated.surf.gii
  767. │ ├── tpl-fsLR_den-164k_hemi-R_midthickness.surf.gii
  768. │ ├── tpl-fsLR_den-164k_hemi-R_sphere.surf.gii
  769. │ ├── tpl-fsLR_den-164k_hemi-R_veryinflated.surf.gii
  770. │ ├── tpl-fsLR_space-fsaverage_den-164k_hemi-L_sphere.surf.gii
  771. │ └── tpl-fsLR_space-fsaverage_den-164k_hemi-R_sphere.surf.gii
  772. ├── fslr32k
  773. │ ├── README.md
  774. │ ├── tpl-fsLR_den-32k_hemi-L_desc-nomedialwall_dparc.label.gii
  775. │ ├── tpl-fsLR_den-32k_hemi-L_desc-sulc_midthickness.shape.gii
  776. │ ├── tpl-fsLR_den-32k_hemi-L_desc-vaavg_midthickness.shape.gii
  777. │ ├── tpl-fsLR_den-32k_hemi-L_inflated.surf.gii
  778. │ ├── tpl-fsLR_den-32k_hemi-L_midthickness.surf.gii
  779. │ ├── tpl-fsLR_den-32k_hemi-L_sphere.surf.gii
  780. │ ├── tpl-fsLR_den-32k_hemi-L_veryinflated.surf.gii
  781. │ ├── tpl-fsLR_den-32k_hemi-R_desc-nomedialwall_dparc.label.gii
  782. │ ├── tpl-fsLR_den-32k_hemi-R_desc-sulc_midthickness.shape.gii
  783. │ ├── tpl-fsLR_den-32k_hemi-R_desc-vaavg_midthickness.shape.gii
  784. │ ├── tpl-fsLR_den-32k_hemi-R_inflated.surf.gii
  785. │ ├── tpl-fsLR_den-32k_hemi-R_midthickness.surf.gii
  786. │ ├── tpl-fsLR_den-32k_hemi-R_sphere.surf.gii
  787. │ ├── tpl-fsLR_den-32k_hemi-R_veryinflated.surf.gii
  788. │ ├── tpl-fsLR_space-fsaverage_den-32k_hemi-L_sphere.surf.gii
  789. │ └── tpl-fsLR_space-fsaverage_den-32k_hemi-R_sphere.surf.gii
  790. ├── fslr4k
  791. │ ├── tpl-fsLR_den-4k_hemi-L_desc-nomedialwall_dparc.label.gii
  792. │ ├── tpl-fsLR_den-4k_hemi-L_desc-sulc_midthickness.shape.gii
  793. │ ├── tpl-fsLR_den-4k_hemi-L_desc-vaavg_midthickness.shape.gii
  794. │ ├── tpl-fsLR_den-4k_hemi-L_inflated.surf.gii
  795. │ ├── tpl-fsLR_den-4k_hemi-L_midthickness.surf.gii
  796. │ ├── tpl-fsLR_den-4k_hemi-L_sphere.surf.gii
  797. │ ├── tpl-fsLR_den-4k_hemi-R_desc-nomedialwall_dparc.label.gii
  798. │ ├── tpl-fsLR_den-4k_hemi-R_desc-sulc_midthickness.shape.gii
  799. │ ├── tpl-fsLR_den-4k_hemi-R_desc-vaavg_midthickness.shape.gii
  800. │ ├── tpl-fsLR_den-4k_hemi-R_inflated.surf.gii
  801. │ ├── tpl-fsLR_den-4k_hemi-R_midthickness.surf.gii
  802. │ ├── tpl-fsLR_den-4k_hemi-R_sphere.surf.gii
  803. │ ├── tpl-fsLR_space-fsaverage_den-4k_hemi-L_sphere.surf.gii
  804. │ └── tpl-fsLR_space-fsaverage_den-4k_hemi-R_sphere.surf.gii
  805. └── fslr8k
  806. ├── tpl-fsLR_den-8k_hemi-L_desc-nomedialwall_dparc.label.gii
  807. ├── tpl-fsLR_den-8k_hemi-L_desc-sulc_midthickness.shape.gii
  808. ├── tpl-fsLR_den-8k_hemi-L_desc-vaavg_midthickness.shape.gii
  809. ├── tpl-fsLR_den-8k_hemi-L_inflated.surf.gii
  810. ├── tpl-fsLR_den-8k_hemi-L_midthickness.surf.gii
  811. ├── tpl-fsLR_den-8k_hemi-L_sphere.surf.gii
  812. ├── tpl-fsLR_den-8k_hemi-R_desc-nomedialwall_dparc.label.gii
  813. ├── tpl-fsLR_den-8k_hemi-R_desc-sulc_midthickness.shape.gii
  814. ├── tpl-fsLR_den-8k_hemi-R_desc-vaavg_midthickness.shape.gii
  815. ├── tpl-fsLR_den-8k_hemi-R_inflated.surf.gii
  816. ├── tpl-fsLR_den-8k_hemi-R_midthickness.surf.gii
  817. ├── tpl-fsLR_den-8k_hemi-R_sphere.surf.gii
  818. ├── tpl-fsLR_space-fsaverage_den-8k_hemi-L_sphere.surf.gii
  819. └── tpl-fsLR_space-fsaverage_den-8k_hemi-R_sphere.surf.gii
  821. 4 directories, 62 files
  823. References
  824. ----------
  825. .. [1] David C Van Essen, Kamil Ugurbil, Edward Auerbach, Deanna
  826. Barch,Timothy EJ Behrens, Richard Bucholz, Acer Chang, Liyong Chen,
  827. Maurizio Corbetta, Sandra W Curtiss, and others. The human connectome
  828. project: a data acquisition perspective. Neuroimage,
  829. 62(4):2222\u20132231, 2012.
  830. .. [2] Matthew F Glasser, Stamatios N Sotiropoulos, J Anthony Wilson,
  831. Timothy S Coalson, Bruce Fischl, Jesper L Andersson, Junqian Xu, Saad
  832. Jbabdi, Matthew Webster, Jonathan R Polimeni, and others. The minimal
  833. preprocessing pipelines for the human connectome project. Neuroimage,
  834. 80:105\u2013124, 2013.
  835. .. [3] Ross D Markello, Justine Y Hansen, Zhen-Qi Liu, Vincent Bazinet,
  836. Golia Shafiei, Laura E Su\u00e1rez, Nadia Blostein, Jakob Seidlitz,
  837. Sylvain Baillet, Theodore D Satterthwaite, and others. Neuromaps:
  838. structural and functional interpretation of brain maps. Nature Methods,
  839. 19(11):1472\u20131479, 2022.
  841. Examples
  842. --------
  843. Load the fsLR curated template surfaces:
  845. >>> surfaces = fetch_fslr_curated(version='fslr32k') # doctest: +SKIP
  846. >>> surfaces.keys() # doctest: +SKIP
  847. dict_keys(['midthickness', 'inflated', 'veryinflated', 'sphere', 'medial',
  848. 'sulc', 'vaavg'])
  850. Access the midthickness surface GIFTI files:
  852. >>> surfaces.midthickness # doctest: +SKIP
  853. Surface(L=PosixPath('~/nnt-data/tpl-fslr_curated/fslr32k/tpl-fsLR_den-32k_hemi-L_midthickness.surf.gii'),
  854. R=PosixPath('~/nnt-data/tpl-fslr_curated/fslr32k/tpl-fsLR_den-32k_hemi-R_midthickness.surf.gii'))
  856. Load the left midthickness surface with nibabel:
  858. >>> import nibabel as nib # doctest: +SKIP
  859. >>> gii = nib.load(surfaces.midthickness.L) # doctest: +SKIP
  860. >>> vertices = gii.agg_data('pointset') # doctest: +SKIP
  861. >>> faces = gii.agg_data('triangle') # doctest: +SKIP
  862. >>> print(vertices.shape, faces.shape) # doctest: +SKIP
  863. (32492, 3) (64980, 3)
  865. Load and examine the sulcal depth data:
  867. >>> sulc_left = nib.load(surfaces.sulc.L) # doctest: +SKIP
  868. >>> sulc_data = sulc_left.agg_data() # doctest: +SKIP
  869. >>> float(sulc_data.min()), float(sulc_data.max()) # doctest: +SKIP
  870. (-1.6234848499298096, 1.1611071825027466)
  871. """
  872. versions = ["fslr4k", "fslr8k", "fslr32k", "fslr164k"]
  873. if version not in versions:
  874. raise ValueError(
  875. f"The version of fsaverage requested {version} does not "
  876. f"exist. Must be one of {versions}"
  877. )
  879. dataset_name = "tpl-fslr_curated"
  880. _get_reference_info("tpl-fslr_curated", verbose=verbose)
  882. keys = [
  883. "midthickness",
  884. "inflated",
  885. "veryinflated",
  886. "sphere",
  887. "medial",
  888. "sulc",
  889. "vaavg",
  890. ]
  891. if version in ["fslr4k", "fslr8k"]:
  892. keys.remove("veryinflated")
  893. keys_suffix = {
  894. "midthickness": "midthickness.surf",
  895. "inflated": "inflated.surf",
  896. "veryinflated": "veryinflated.surf",
  897. "sphere": "sphere.surf",
  898. "medial": "desc-nomedialwall_dparc.label",
  899. "sulc": "desc-sulc_midthickness.shape",
  900. "vaavg": "desc-vaavg_midthickness.shape",
  901. }
  902. version_density = {
  903. "fslr4k": "4k",
  904. "fslr8k": "8k",
  905. "fslr32k": "32k",
  906. "fslr164k": "164k",
  907. }
  908. density = version_density[version]
  910. fetched = fetch_file(
  911. dataset_name, keys=version, force=force, data_dir=data_dir, verbose=verbose
  912. )
  914. # deal with default neuromaps directory structure in the archive
  915. if not fetched.exists():
  916. import shutil
  918. shutil.move(fetched.parent / "atlases/fsLR", fetched)
  919. shutil.rmtree(fetched.parent / "atlases")
  921. data = {
  922. k: SURFACE(
  923. fetched / f"tpl-fsLR_den-{density}_hemi-L_{keys_suffix[k]}.gii",
  924. fetched / f"tpl-fsLR_den-{density}_hemi-R_{keys_suffix[k]}.gii",
  925. )
  926. for k in keys
  927. }
  929. return Bunch(**data)
  932. def fetch_civet(density="41k", version="v1", force=False, data_dir=None, verbose=1):
  933. """
  934. Fetch CIVET surface files.
  936. This dataset contains midthickness and white matter surface files for the
  937. CIVET template in OBJ format, registered to ICBM152 space. CIVET is a
  938. fully automated structural image processing pipeline developed at the
  939. Montreal Neurological Institute.
  941. If you used this data, please cite 1_, 2_, 3_.
  943. Parameters
  944. ----------
  945. density : {'41k', '164k'}, optional
  946. Which density of the CIVET-space geometry files to fetch. The
  947. high-resolution '164k' surface only exists for version 'v2'
  948. version : {'v1, 'v2'}, optional
  949. Which version of the CIVET surfaces to use. Default: 'v2'
  951. Returns
  952. -------
  953. filenames : :class:`sklearn.utils.Bunch`
  954. Dictionary-like object with keys ['mid', 'white'], where corresponding
  955. values are Surface namedtuples containing filepaths for the left (L)
  956. and right (R) hemisphere surface files in OBJ format. Note: for version
  957. 'v1', the 'mid' and 'white' files are identical.
  959. Other Parameters
  960. ----------------
  961. force : bool, optional
  962. If True, will overwrite existing dataset. Default: False
  963. data_dir : str, optional
  964. Path to use as data directory. If not specified, will check for
  965. environmental variable 'NNT_DATA'; if that is not set, will use
  966. `~/nnt-data` instead. Default: None
  967. verbose : int, optional
  968. Modifies verbosity of download, where higher numbers mean more updates.
  969. Default: 1
  971. Notes
  972. -----
  973. The CIVET template surfaces are provided in OBJ format and registered to
  974. ICBM152 stereotaxic space.
  976. The returned files include:
  978. - **mid**: Midthickness surface (.obj), representing the surface halfway
  979. between white and gray matter boundaries. For version 'v1', this is
  980. identical to the white surface.
  981. - **white**: White matter surface (.obj), representing the boundary between
  982. white matter and gray matter.
  984. The vertex density varies by option: 41k (≈41k vertices) or 164k (≈164k)
  985. per hemisphere. The high-resolution 164k surface is only available for
  986. version 'v2'.
  988. Example directory tree:
  990. ::
  992. ~/nnt-data/tpl-civet
  993. ├── v1
  994. │ └── civet41k
  995. │ ├── tpl-civet_space-ICBM152_hemi-L_den-41k_mid.obj
  996. │ ├── tpl-civet_space-ICBM152_hemi-L_den-41k_white.obj
  997. │ ├── tpl-civet_space-ICBM152_hemi-R_den-41k_mid.obj
  998. │ └── tpl-civet_space-ICBM152_hemi-R_den-41k_white.obj
  999. └── v2
  1000. ├── civet164k
  1001. │ ├── tpl-civet_space-ICBM152_hemi-L_den-164k_mid.obj
  1002. │ ├── tpl-civet_space-ICBM152_hemi-L_den-164k_white.obj
  1003. │ ├── tpl-civet_space-ICBM152_hemi-R_den-164k_mid.obj
  1004. │ └── tpl-civet_space-ICBM152_hemi-R_den-164k_white.obj
  1005. └── civet41k
  1006. ├── tpl-civet_space-ICBM152_hemi-L_den-41k_mid.obj
  1007. ├── tpl-civet_space-ICBM152_hemi-L_den-41k_white.obj
  1008. ├── tpl-civet_space-ICBM152_hemi-R_den-41k_mid.obj
  1009. └── tpl-civet_space-ICBM152_hemi-R_den-41k_white.obj
  1011. 5 directories, 12 files
  1013. License: https://github.com/aces/CIVET_Full_Project/blob/master/LICENSE
  1015. References
  1016. ----------
  1017. .. [1] Oliver Lyttelton, Maxime Boucher, Steven Robbins, and Alan Evans. An
  1018. unbiased iterative group registration template for cortical surface
  1019. analysis. Neuroimage, 34(4):1535\u20131544, 2007.
  1020. .. [2] Vladimir S Fonov, Alan C Evans, Robert C McKinstry, C Robert Almli,
  1021. and DL Collins. Unbiased nonlinear average age-appropriate brain
  1022. templates from birth to adulthood. NeuroImage, 47:S102, 2009.
  1023. .. [3] Y Ad-Dab'bagh, O Lyttelton, J Muehlboeck, C Lepage, D Einarson, K
  1024. Mok, O Ivanov, R Vincent, J Lerch, and E Fombonne. The civet
  1025. image-processing environment: a fully automated comprehensive pipeline
  1026. for anatomical neuroimaging research. proceedings of the 12th annual
  1027. meeting of the organization for human brain mapping. Florence, Italy,
  1028. pages 2266, 2006.
  1030. Examples
  1031. --------
  1032. Load the CIVET template surfaces:
  1034. >>> surfaces = fetch_civet(density='41k', version='v2') # doctest: +SKIP
  1035. >>> surfaces.keys() # doctest: +SKIP
  1036. dict_keys(['mid', 'white'])
  1038. Access the midthickness surface paths:
  1040. >>> surfaces.mid # doctest: +SKIP
  1041. Surface(L=PosixPath('~/nnt-data/tpl-civet/v2/civet41k/tpl-civet_space-ICBM152_hemi-L_den-41k_mid.obj'),
  1042. R=PosixPath('~/nnt-data/tpl-civet/v2/civet41k/tpl-civet_space-ICBM152_hemi-R_den-41k_mid.obj'))
  1044. Load the left midthickness surface with nibabel:
  1046. >>> import nibabel as nib # doctest: +SKIP
  1047. >>> vertices, faces = nib.freesurfer.read_geometry(surfaces.mid.L) # doctest: +SKIP
  1048. >>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}") # doctest: +SKIP
  1049. Vertices: (40962, 3), Faces: (81920, 3)
  1050. """
  1051. densities = ["41k", "164k"]
  1052. if density not in densities:
  1053. raise ValueError(
  1054. f'The density of CIVET requested "{density}" does not exist. '
  1055. f"Must be one of {densities}"
  1056. )
  1057. versions = ["v1", "v2"]
  1058. if version not in versions:
  1059. raise ValueError(
  1060. f'The version of CIVET requested "{version}" does not exist. '
  1061. f"Must be one of {versions}"
  1062. )
  1064. if version == "v1" and density == "164k":
  1065. raise ValueError(
  1066. 'The "164k" density CIVET surface only exists for ' 'version "v2"'
  1067. )
  1069. dataset_name = "tpl-civet"
  1070. _get_reference_info(dataset_name, verbose=verbose)
  1072. keys = ["mid", "white"]
  1074. fetched = fetch_file(
  1075. dataset_name,
  1076. keys=[version, "civet" + density],
  1077. force=force,
  1078. data_dir=data_dir,
  1079. verbose=verbose,
  1080. )
  1082. data = {
  1083. k: SURFACE(
  1084. fetched / f"tpl-civet_space-ICBM152_hemi-L_den-{density}_{k}.obj",
  1085. fetched / f"tpl-civet_space-ICBM152_hemi-R_den-{density}_{k}.obj",
  1086. )
  1087. for k in keys
  1088. }
  1089. return Bunch(**data)
  1092. def fetch_civet_curated(version="civet41k", force=False, data_dir=None, verbose=1):
  1093. """
  1094. Download files for CIVET template.
  1096. This dataset contains surface geometry files (white, midthickness, inflated,
  1097. veryinflated, sphere), medial wall labels, and surface shape files (sulcal
  1098. depth and vertex area) in GIFTI format for the CIVET template at multiple
  1099. densities.
  1101. If you used this data, please cite 1_, 2_, 3_, 4_.
  1103. Parameters
  1104. ----------
  1105. version : {'civet41k', 'civet164k'}, optional
  1106. Which density of the CIVET-space geometry files to fetch.
  1108. Returns
  1109. -------
  1110. filenames : :class:`sklearn.utils.Bunch`
  1111. Dictionary-like object with keys ['white', 'midthickness', 'inflated',
  1112. 'veryinflated', 'sphere', 'medial', 'sulc', 'vaavg'], where
  1113. corresponding values are Surface namedtuples containing filepaths for
  1114. the left (L) and right (R) hemisphere files in GIFTI format.
  1116. Other Parameters
  1117. ----------------
  1118. force : bool, optional
  1119. If True, will overwrite existing dataset. Default: False
  1120. data_dir : str, optional
  1121. Path to use as data directory. If not specified, will check for
  1122. environmental variable 'NNT_DATA'; if that is not set, will use
  1123. `~/nnt-data` instead. Default: None
  1124. verbose : int, optional
  1125. Modifies verbosity of download, where higher numbers mean more updates.
  1126. Default: 1
  1128. Notes
  1129. -----
  1130. This function fetches curated CIVET surfaces from the neuromaps
  1131. package (see `neuromaps.datasets.fetch_civet <https://netneurolab.github.io/neuromaps/generated/neuromaps.datasets.fetch_civet.html>`_).
  1132. All files are provided in GIFTI format (.gii). The CIVET template is
  1133. registered to ICBM152 stereotaxic space.
  1135. The returned files include:
  1137. - **white**: White matter surface geometry (.surf.gii), representing the
  1138. boundary between white matter and gray matter.
  1139. - **midthickness**: Midthickness surface geometry (.surf.gii), halfway
  1140. between white and pial surfaces.
  1141. - **inflated**: Inflated surface geometry (.surf.gii) for improved
  1142. visualization of sulci and gyri.
  1143. - **veryinflated**: Very inflated surface geometry (.surf.gii) providing
  1144. additional smoothing for visualization.
  1145. - **sphere**: Spherical surface geometry (.surf.gii) used for surface-based
  1146. registration and applying parcellations.
  1147. - **medial**: Medial wall mask (.label.gii) indicating vertices to exclude
  1148. from analyses (vertices with no cortex).
  1149. - **sulc**: Sulcal depth map (.shape.gii) providing sulcal/gyral patterns
  1150. on the midthickness surface.
  1151. - **vaavg**: Vertex area map (.shape.gii) representing the average vertex
  1152. area on the midthickness surface.
  1154. The vertex density varies by version: civet41k (≈41k vertices) and
  1155. civet164k (≈164k) per hemisphere.
  1157. Example directory tree:
  1159. ::
  1161. ~/nnt-data/tpl-civet_curated
  1162. └── v2
  1163. ├── civet164k
  1164. │ ├── tpl-civet_den-164k_hemi-L_desc-nomedialwall_dparc.label.gii
  1165. │ ├── tpl-civet_den-164k_hemi-L_desc-sulc_midthickness.shape.gii
  1166. │ ├── tpl-civet_den-164k_hemi-L_desc-vaavg_midthickness.shape.gii
  1167. │ ├── tpl-civet_den-164k_hemi-L_inflated.surf.gii
  1168. │ ├── tpl-civet_den-164k_hemi-L_midthickness.surf.gii
  1169. │ ├── tpl-civet_den-164k_hemi-L_sphere.surf.gii
  1170. │ ├── tpl-civet_den-164k_hemi-L_veryinflated.surf.gii
  1171. │ ├── tpl-civet_den-164k_hemi-L_white.surf.gii
  1172. │ ├── tpl-civet_den-164k_hemi-R_desc-nomedialwall_dparc.label.gii
  1173. │ ├── tpl-civet_den-164k_hemi-R_desc-sulc_midthickness.shape.gii
  1174. │ ├── tpl-civet_den-164k_hemi-R_desc-vaavg_midthickness.shape.gii
  1175. │ ├── tpl-civet_den-164k_hemi-R_inflated.surf.gii
  1176. │ ├── tpl-civet_den-164k_hemi-R_midthickness.surf.gii
  1177. │ ├── tpl-civet_den-164k_hemi-R_sphere.surf.gii
  1178. │ ├── tpl-civet_den-164k_hemi-R_veryinflated.surf.gii
  1179. │ ├── tpl-civet_den-164k_hemi-R_white.surf.gii
  1180. │ ├── tpl-civet_space-fsaverage_den-164k_hemi-L_sphere.surf.gii
  1181. │ ├── tpl-civet_space-fsaverage_den-164k_hemi-R_sphere.surf.gii
  1182. │ ├── tpl-civet_space-fsLR_den-164k_hemi-L_sphere.surf.gii
  1183. │ └── tpl-civet_space-fsLR_den-164k_hemi-R_sphere.surf.gii
  1184. └── civet41k
  1185. ├── README.md
  1186. ├── tpl-civet_den-41k_hemi-L_desc-nomedialwall_dparc.label.gii
  1187. ├── tpl-civet_den-41k_hemi-L_desc-sulc_midthickness.shape.gii
  1188. ├── tpl-civet_den-41k_hemi-L_desc-vaavg_midthickness.shape.gii
  1189. ├── tpl-civet_den-41k_hemi-L_inflated.surf.gii
  1190. ├── tpl-civet_den-41k_hemi-L_midthickness.surf.gii
  1191. ├── tpl-civet_den-41k_hemi-L_sphere.surf.gii
  1192. ├── tpl-civet_den-41k_hemi-L_veryinflated.surf.gii
  1193. ├── tpl-civet_den-41k_hemi-L_white.surf.gii
  1194. ├── tpl-civet_den-41k_hemi-R_desc-nomedialwall_dparc.label.gii
  1195. ├── tpl-civet_den-41k_hemi-R_desc-sulc_midthickness.shape.gii
  1196. ├── tpl-civet_den-41k_hemi-R_desc-vaavg_midthickness.shape.gii
  1197. ├── tpl-civet_den-41k_hemi-R_inflated.surf.gii
  1198. ├── tpl-civet_den-41k_hemi-R_midthickness.surf.gii
  1199. ├── tpl-civet_den-41k_hemi-R_sphere.surf.gii
  1200. ├── tpl-civet_den-41k_hemi-R_veryinflated.surf.gii
  1201. ├── tpl-civet_den-41k_hemi-R_white.surf.gii
  1202. ├── tpl-civet_space-fsaverage_den-41k_hemi-L_sphere.surf.gii
  1203. ├── tpl-civet_space-fsaverage_den-41k_hemi-R_sphere.surf.gii
  1204. ├── tpl-civet_space-fsLR_den-41k_hemi-L_sphere.surf.gii
  1205. └── tpl-civet_space-fsLR_den-41k_hemi-R_sphere.surf.gii
  1207. 3 directories, 41 files
  1209. License: https://github.com/aces/CIVET_Full_Project/blob/master/LICENSE
  1211. References
  1212. ----------
  1213. .. [1] Oliver Lyttelton, Maxime Boucher, Steven Robbins, and Alan Evans. An
  1214. unbiased iterative group registration template for cortical surface
  1215. analysis. Neuroimage, 34(4):1535\u20131544, 2007.
  1216. .. [2] Vladimir S Fonov, Alan C Evans, Robert C McKinstry, C Robert Almli,
  1217. and DL Collins. Unbiased nonlinear average age-appropriate brain
  1218. templates from birth to adulthood. NeuroImage, 47:S102, 2009.
  1219. .. [3] Y Ad-Dab'bagh, O Lyttelton, J Muehlboeck, C Lepage, D Einarson, K
  1220. Mok, O Ivanov, R Vincent, J Lerch, and E Fombonne. The civet
  1221. image-processing environment: a fully automated comprehensive pipeline
  1222. for anatomical neuroimaging research. proceedings of the 12th annual
  1223. meeting of the organization for human brain mapping. Florence, Italy,
  1224. pages 2266, 2006.
  1225. .. [4] Ross D Markello, Justine Y Hansen, Zhen-Qi Liu, Vincent Bazinet,
  1226. Golia Shafiei, Laura E Su\u00e1rez, Nadia Blostein, Jakob Seidlitz,
  1227. Sylvain Baillet, Theodore D Satterthwaite, and others. Neuromaps:
  1228. structural and functional interpretation of brain maps. Nature Methods,
  1229. 19(11):1472\u20131479, 2022.
  1231. Examples
  1232. --------
  1233. Load the CIVET curated template surfaces:
  1235. >>> surfaces = fetch_civet_curated(version='civet41k') # doctest: +SKIP
  1236. >>> surfaces.keys() # doctest: +SKIP
  1237. dict_keys([
  1238. 'white', 'midthickness', 'inflated', 'veryinflated',
  1239. 'sphere', 'medial', 'sulc', 'vaavg'
  1240. ])
  1242. Access the midthickness surface GIFTI files:
  1244. >>> surfaces.midthickness # doctest: +SKIP
  1245. Surface(L=PosixPath('~/nnt-data/tpl-civet_curated/v2/civet41k/tpl-civet_den-41k_hemi-L_midthickness.surf.gii'),
  1246. R=PosixPath('~/nnt-data/tpl-civet_curated/v2/civet41k/tpl-civet_den-41k_hemi-R_midthickness.surf.gii'))
  1248. Load the left midthickness surface with nibabel:
  1250. >>> import nibabel as nib # doctest: +SKIP
  1251. >>> gii = nib.load(surfaces.midthickness.L) # doctest: +SKIP
  1252. >>> vertices = gii.agg_data('pointset') # doctest: +SKIP
  1253. >>> faces = gii.agg_data('triangle') # doctest: +SKIP
  1254. >>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}") # doctest: +SKIP
  1255. Vertices: (40962, 3), Faces: (81920, 3)
  1257. Load and examine the sulcal depth data:
  1259. >>> sulc_left = nib.load(surfaces.sulc.L) # doctest: +SKIP
  1260. >>> sulc_data = sulc_left.agg_data() # doctest: +SKIP
  1261. >>> float(sulc_data.min()), float(sulc_data.max()) # doctest: +SKIP
  1262. (-27.601072311401367, 20.54990005493164)
  1263. """
  1264. versions = ["civet41k", "civet164k"]
  1265. if version not in versions:
  1266. raise ValueError(
  1267. f"The version of fsaverage requested {version} does not "
  1268. f"exist. Must be one of {versions}"
  1269. )
  1271. dataset_name = "tpl-civet_curated"
  1272. _get_reference_info("tpl-civet_curated", verbose=verbose)
  1274. keys = [
  1275. "white",
  1276. "midthickness",
  1277. "inflated",
  1278. "veryinflated",
  1279. "sphere",
  1280. "medial",
  1281. "sulc",
  1282. "vaavg",
  1283. ]
  1284. keys_suffix = {
  1285. "white": "white.surf",
  1286. "midthickness": "midthickness.surf",
  1287. "inflated": "inflated.surf",
  1288. "veryinflated": "veryinflated.surf",
  1289. "sphere": "sphere.surf",
  1290. "medial": "desc-nomedialwall_dparc.label",
  1291. "sulc": "desc-sulc_midthickness.shape",
  1292. "vaavg": "desc-vaavg_midthickness.shape",
  1293. }
  1294. version_density = {
  1295. "civet41k": "41k",
  1296. "civet164k": "164k",
  1297. }
  1298. density = version_density[version]
  1300. fetched = fetch_file(
  1301. dataset_name,
  1302. keys=["v2", version],
  1303. force=force,
  1304. data_dir=data_dir,
  1305. verbose=verbose,
  1306. )
  1308. # deal with default neuromaps directory structure in the archive
  1309. if not fetched.exists():
  1310. import shutil
  1312. shutil.move(fetched.parent / "atlases/civet", fetched)
  1313. shutil.rmtree(fetched.parent / "atlases")
  1315. data = {
  1316. k: SURFACE(
  1317. fetched / f"tpl-civet_den-{density}_hemi-L_{keys_suffix[k]}.gii",
  1318. fetched / f"tpl-civet_den-{density}_hemi-R_{keys_suffix[k]}.gii",
  1319. )
  1320. for k in keys
  1321. }
  1323. return Bunch(**data)
  1326. def fetch_conte69(force=False, data_dir=None, verbose=1):
  1327. """
  1328. Download files for Van Essen et al., 2012 Conte69 template.
  1330. This dataset contains midthickness, inflated, and very inflated surface
  1331. files in GIFTI format for the Conte69 atlas, a population-average surface
  1332. template in fsLR32k space registered to MNI305 volumetric space.
  1334. If you used this data, please cite 1_, 2_.
  1336. Returns
  1337. -------
  1338. filenames : :class:`sklearn.utils.Bunch`
  1339. Dictionary-like object with keys ['midthickness', 'inflated',
  1340. 'vinflated', 'info'], where 'midthickness', 'inflated', and
  1341. 'vinflated' are Surface namedtuples containing filepaths for the left
  1342. (L) and right (R) hemisphere GIFTI files, and 'info' is a dictionary
  1343. containing template metadata from template_description.json.
  1345. Other Parameters
  1346. ----------------
  1347. force : bool, optional
  1348. If True, will overwrite existing dataset. Default: False
  1349. data_dir : str, optional
  1350. Path to use as data directory. If not specified, will check for
  1351. environmental variable 'NNT_DATA'; if that is not set, will use
  1352. `~/nnt-data` instead. Default: None
  1353. verbose : int, optional
  1354. Modifies verbosity of download, where higher numbers mean more updates.
  1355. Default: 1
  1357. Notes
  1358. -----
  1359. The Conte69 template is a population-average surface atlas registered to
  1360. MNI305 volumetric space using the fsLR32k mesh (approximately 32k vertices
  1361. per hemisphere).
  1363. The returned files include:
  1365. - **midthickness**: Midthickness surface geometry (.surf.gii), halfway
  1366. between white and pial surfaces.
  1367. - **inflated**: Inflated surface geometry (.surf.gii) for improved
  1368. visualization of sulci and gyri.
  1369. - **vinflated**: Very inflated surface geometry (.surf.gii) providing
  1370. additional smoothing for visualization.
  1371. - **info**: Metadata dictionary containing template name, BIDS version,
  1372. and references.
  1374. Example directory tree:
  1376. ::
  1378. ~/nnt-data/tpl-conte69
  1379. ├── CHANGES
  1380. ├── template_description.json
  1381. ├── tpl-conte69_space-MNI305_variant-fsLR32k_inflated.L.surf.gii
  1382. ├── tpl-conte69_space-MNI305_variant-fsLR32k_inflated.R.surf.gii
  1383. ├── tpl-conte69_space-MNI305_variant-fsLR32k_midthickness.L.surf.gii
  1384. ├── tpl-conte69_space-MNI305_variant-fsLR32k_midthickness.R.surf.gii
  1385. ├── tpl-conte69_space-MNI305_variant-fsLR32k_vinflated.L.surf.gii
  1386. └── tpl-conte69_space-MNI305_variant-fsLR32k_vinflated.R.surf.gii
  1388. 0 directories, 8 files
  1390. References
  1391. ----------
  1392. .. [1] David C Van Essen, Kamil Ugurbil, Edward Auerbach, Deanna Barch,
  1393. Timothy EJ Behrens, Richard Bucholz, Acer Chang, Liyong Chen, Maurizio
  1394. Corbetta, Sandra W Curtiss, and others. The human connectome project: a
  1395. data acquisition perspective. Neuroimage, 62(4):2222\u20132231, 2012.
  1396. .. [2] David C Van Essen, Matthew F Glasser, Donna L Dierker, John Harwell,
  1397. and Timothy Coalson. Parcellations and hemispheric asymmetries of human
  1398. cerebral cortex analyzed on surface-based atlases. Cerebral cortex,
  1399. 22(10):2241\u20132262, 2012.
  1400. .. [3] http://brainvis.wustl.edu/wiki/index.php//Caret:Atlases/Conte69_Atlas
  1402. Examples
  1403. --------
  1404. Load the Conte69 template surfaces:
  1406. >>> surfaces = fetch_conte69() # doctest: +SKIP
  1407. >>> surfaces.keys() # doctest: +SKIP
  1408. dict_keys(['midthickness', 'inflated', 'vinflated', 'info'])
  1410. Access the midthickness surface GIFTI files:
  1412. >>> surfaces.midthickness # doctest: +SKIP
  1413. Surface(L=PosixPath('~/nnt-data/tpl-conte69/tpl-conte69_space-MNI305_variant-fsLR32k_midthickness.L.surf.gii'),
  1414. R=PosixPath('~/nnt-data/tpl-conte69/tpl-conte69_space-MNI305_variant-fsLR32k_midthickness.R.surf.gii'))
  1416. Load the left midthickness surface with nibabel:
  1418. >>> import nibabel as nib # doctest: +SKIP
  1419. >>> gii = nib.load(surfaces.midthickness.L) # doctest: +SKIP
  1420. >>> vertices = gii.agg_data('pointset') # doctest: +SKIP
  1421. >>> faces = gii.agg_data('triangle') # doctest: +SKIP
  1422. >>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}") # doctest: +SKIP
  1423. Vertices: (32492, 3), Faces: (64980, 3)
  1425. Examine template metadata:
  1427. >>> surfaces.info['Name'] # doctest: +SKIP
  1428. "The 'Conte-69' template"
  1429. """
  1430. dataset_name = "tpl-conte69"
  1431. _get_reference_info(dataset_name, verbose=verbose)
  1433. keys = ["midthickness", "inflated", "vinflated"]
  1435. fetched = fetch_file(dataset_name, force=force, data_dir=data_dir, verbose=verbose)
  1437. data = {
  1438. k: SURFACE(
  1439. fetched / f"tpl-conte69_space-MNI305_variant-fsLR32k_{k}.L.surf.gii",
  1440. fetched / f"tpl-conte69_space-MNI305_variant-fsLR32k_{k}.R.surf.gii",
  1441. )
  1442. for k in keys
  1443. }
  1444. data["info"] = json.load(open(fetched / "template_description.json", "r"))
  1446. return Bunch(**data)
  1449. def fetch_yerkes19(force=False, data_dir=None, verbose=1):
  1450. """
  1451. Download files for Donahue et al., 2016 Yerkes19 template.
  1453. This dataset contains midthickness, inflated, and very inflated surface
  1454. files in GIFTI format for the Yerkes19 macaque template in fsLR32k space.
  1455. The Yerkes19 atlas is a population-average surface template for macaque
  1456. monkeys derived from high-resolution anatomical scans.
  1458. If you used this data, please cite 1_.
  1460. Returns
  1461. -------
  1462. filenames : :class:`sklearn.utils.Bunch`
  1463. Dictionary-like object with keys ['midthickness', 'inflated',
  1464. 'vinflated'], where corresponding values are Surface namedtuples
  1465. containing filepaths for the left (L) and right (R) hemisphere GIFTI
  1466. surface files.
  1468. Other Parameters
  1469. ----------------
  1470. force : bool, optional
  1471. If True, will overwrite existing dataset. Default: False
  1472. data_dir : str, optional
  1473. Path to use as data directory. If not specified, will check for
  1474. environmental variable 'NNT_DATA'; if that is not set, will use
  1475. `~/nnt-data` instead. Default: None
  1476. verbose : int, optional
  1477. Modifies verbosity of download, where higher numbers mean more updates.
  1478. Default: 1
  1480. Notes
  1481. -----
  1482. The Yerkes19 template is a macaque cortical surface atlas using the fsLR32k
  1483. mesh (approximately 32k vertices per hemisphere). It was developed to
  1484. facilitate comparative neuroanatomy studies between human and non-human
  1485. primates.
  1487. The returned files include:
  1489. - **midthickness**: Midthickness surface geometry (.surf.gii), halfway
  1490. between white and pial surfaces.
  1491. - **inflated**: Inflated surface geometry (.surf.gii) for improved
  1492. visualization of sulci and gyri.
  1493. - **vinflated**: Very inflated surface geometry (.surf.gii) providing
  1494. additional smoothing for visualization.
  1496. Example directory tree:
  1498. ::
  1500. ~/nnt-data/tpl-yerkes19
  1501. ├── tpl-yerkes19_space-fsLR32k_inflated.L.surf.gii
  1502. ├── tpl-yerkes19_space-fsLR32k_inflated.R.surf.gii
  1503. ├── tpl-yerkes19_space-fsLR32k_midthickness.L.surf.gii
  1504. ├── tpl-yerkes19_space-fsLR32k_midthickness.R.surf.gii
  1505. ├── tpl-yerkes19_space-fsLR32k_vinflated.L.surf.gii
  1506. └── tpl-yerkes19_space-fsLR32k_vinflated.R.surf.gii
  1508. 0 directories, 6 files
  1510. References
  1511. ----------
  1512. .. [1] Chad J Donahue, Stamatios N Sotiropoulos, Saad Jbabdi, Moises
  1513. Hernandez-Fernandez, Timothy E Behrens, Tim B Dyrby, Timothy Coalson,
  1514. Henry Kennedy, Kenneth Knoblauch, David C Van Essen, and others. Using
  1515. diffusion tractography to predict cortical connection strength and
  1516. distance: a quantitative comparison with tracers in the monkey. Journal
  1517. of Neuroscience, 36(25):6758\u20136770, 2016.
  1518. .. [2] https://balsa.wustl.edu/reference/show/976nz
  1520. Examples
  1521. --------
  1522. Load the Yerkes19 template surfaces:
  1524. >>> surfaces = fetch_yerkes19() # doctest: +SKIP
  1525. >>> surfaces.keys() # doctest: +SKIP
  1526. dict_keys(['midthickness', 'inflated', 'vinflated'])
  1528. Access the midthickness surface GIFTI files:
  1530. >>> surfaces.midthickness # doctest: +SKIP
  1531. Surface(L=PosixPath('~/nnt-data/tpl-yerkes19/tpl-yerkes19_space-fsLR32k_midthickness.L.surf.gii'),
  1532. R=PosixPath('~/nnt-data/tpl-yerkes19/tpl-yerkes19_space-fsLR32k_midthickness.R.surf.gii'))
  1534. Load the left midthickness surface with nibabel:
  1536. >>> import nibabel as nib # doctest: +SKIP
  1537. >>> gii = nib.load(surfaces.midthickness.L) # doctest: +SKIP
  1538. >>> vertices = gii.agg_data('pointset') # doctest: +SKIP
  1539. >>> faces = gii.agg_data('triangle') # doctest: +SKIP
  1540. >>> print(f"Vertices: {vertices.shape}, Faces: {faces.shape}") # doctest: +SKIP
  1541. Vertices: (32492, 3), Faces: (64980, 3)
  1542. """
  1543. dataset_name = "tpl-yerkes19"
  1544. _get_reference_info(dataset_name, verbose=verbose)
  1546. keys = ["midthickness", "inflated", "vinflated"]
  1548. fetched = fetch_file(dataset_name, force=force, data_dir=data_dir, verbose=verbose)
  1550. data = {
  1551. k: SURFACE(
  1552. fetched / f"tpl-yerkes19_space-fsLR32k_{k}.L.surf.gii",
  1553. fetched / f"tpl-yerkes19_space-fsLR32k_{k}.R.surf.gii",
  1554. )
  1555. for k in keys
  1556. }
  1558. return Bunch(**data)
  1561. def _fetch_subcortex_surface(
  1562. force=False, data_dir=None, verbose=1
  1563. ):
  1564. dataset_name = "tpl-subcortex_surface"
  1565. _get_reference_info(dataset_name, verbose=verbose)
  1567. fetched = fetch_file(
  1568. dataset_name,
  1569. force=force,
  1570. data_dir=data_dir,
  1571. verbose=verbose,
  1572. )
  1574. data = {
  1575. k: fetched / f"{k}_surfaces.vtm"
  1576. for k in [
  1577. "aseg", "tianS1", "tianS2", "tianS3", "tianS4"
  1578. ]
  1579. }
  1581. return data

fetch_template.py at commit 49f83c0, under BSD-3-Clause · at the source

Overview

Authors: Christopher Leslie Adamson1, Mehul Gajwani1, Matthias Klapperstueck2, James Manley2, Tim Dwyer2, Alex Fornito1
ORCID iDs: Christopher Leslie Adamson
  1. Turner Institute for Brain and Mental Health, School of Psychological Sciences, and Monash Biomedical Imaging, Monash University, Melbourne, Australia
  2. Faculty of Information Technology, Monash University, Melbourne, Australia
Institutions: Monash University (Australia)
Journal: Network neuroscience (Cambridge, Mass.), volume 10, issue 3, pages 683-705
Dates: received 23 June 2025; accepted 17 March 2026; published online 20 July 2026
Type: Research article · Language: English
License: CC BY
Identifiers: DOI 10.1162/netn.a.569 · PMID 42529553 · PMCID PMC13418255 · OpenAlex W7155199086
Open access: gold, a free copy (OpenAlex)
Status: code verified
Categories: methods / tools (subfield)
Methods: Smoothing, state filtering, decompositions, Graphs, Statistics, fMRI & imaging
Keywords: connectome, visualization, web, software
Topic: Functional Brain Connectivity Studies (Cognitive Neuroscience, Neuroscience), according to OpenAlex
Funding: Department of Health | National Health and Medical Research Council (NHMRC) (1197431, 1146292, 1136192); Australian Research Council (FL220100184, FT130100589, DP200103509); Sylvia and Charles Viertel Charitable Foundation (Viertel Charitable Foundation)
Citations: not cited yet (Europe PMC); 51 references in the paper

Abstract

Brain connectivity data are high-dimensional and are often modeled as graphs comprising in the order of ∼102–104 nodes connected by around 103–106 edges. Generating useful visualizations is essential for reducing and understanding such complexity. Indeed, this complexity offers a particular challenge for transparent science, since investigators must often choose a specific snapshot of a visualization for publication that often overlooks much of the rich detail present in the data. A further challenge for neuroscience is that brains are physical systems, and it is often important to consider how topological properties of the connectome, which can be visualized within arbitrarily abstract spaces, relate to their physical embedding. Most available tools offer visualizations for physically or topologically embedded representations without a clear mapping between the two. Here, we introduce NeuroMArVL, a novel, open-source, web-based brain connectome visualization tool that offers numerous features for moving seamlessly between, and interacting with, different physical and topological representations of connectome data. Critically, visualization data and parameters can be saved locally or on the web server as shareable links, facilitating reuse, collaboration, and open, transparent reporting of results in publications. The software can be freely accessed at https://immersive.erc.monash.edu/neuromarvl/.

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 4 matches between paragraphs and lines of code.

sidchop/brainconn

License: other
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Commit: c1b7569fa8dc2db24327d06317ddf61040489ef6, 18 September 2025
Languages: JavaScript (12), R (10)
Size: 130 files, 22 scripts
Software Heritage: not archived
Found in: the text, “INTRODUCTION”
Holds: README, license file, environment (DESCRIPTION), tests, continuous integration, documentation, 2 notebooks
Not found: CITATION.cff
Tools: cowplot (1 file), ggplot2 (1 file), igraph (1 file)
Availability: 1 check, the latest on 27 September 2026: the link answers
  • 27 September 2026: the link answers
24 files
At the source: github.com/sidchop/brainconn

immersive.erc.monash.edu/neuromarvl

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: the text, “USAGE DETAILS”
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: immersive.erc.monash.edu/NeuroMArVL/

NSBLab/neuromarvl

License: GPL-3.0
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Commit: 7294c83db866d7fea5dee05218ba4d7c156d2812, 2 July 2026
Languages: JavaScript (310), TypeScript (126), MATLAB (14), Python (1)
Size: 4,042 files, 451 scripts
Software Heritage: not archived
Found in: “CODE/DATA AVAILABILITY AND CONTRIBUTIONS”
Holds: README, license file
Not found: CITATION.cff, environment file, tests, continuous integration, documentation
Tools: GIfTI library for MATLAB (3 files), cifti-matlab (2 files), Image Processing Toolbox (2 files)
Availability: 1 check, the latest on 27 September 2026: the link answers
  • 27 September 2026: the link answers
453 files
At the source: github.com/NSBLab/neuromarvl

netneurolab/netneurotools

License: BSD-3-Clause
State: the link answers, verified on 27 September 2026
Evidence: files inventoried
Commit: 49f83c023022ab606581cb10aec6a6282a306c48, 31 July 2026
Languages: Python (83), Shell (3)
Size: 118 files, 86 scripts
Software Heritage: archived
Found in: the resources table
Holds: README, license file, environment (Dockerfile, pyproject.toml, requirements.txt, setup.py, docs/requirements.txt), tests, continuous integration, documentation
Not found: CITATION.cff
Tools: NumPy (41 files), netneurotools (26 files), scikit-learn (11 files), SciPy (10 files), Matplotlib (9 files), NiBabel (8 files), Numba (8 files), Brain Connectivity Toolbox (3 files), neuromaps (1 file), Nilearn (1 file), pandas (1 file)
Availability: 1 check, the latest on 27 September 2026: the link answers
  • 27 September 2026: the link answers
88 files
At the source: github.com/netneurolab/netneurotools

The paper's code and data availability statement is in the Data section.

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:

  • 4 repositories of the authors' code, each at its verified commit, with its license and how the link was found in the paper;
  • 559 scripts, each with its path and the digest of its content;
  • 4 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

No dataset and no data link were found in the paper.

Reproducibility and Data Sharing

NeuroMArVL supports various features, accessible through the data tab, that facilitate the generation of reproducible visualizations by both an individual user and multiple users working collaboratively. This is done by saving and sharing visualization settings, which refer to the appearance of the brain surface, the nodes and edges in the primary view, and the appearance of the secondary view. If a surface model was uploaded, this will also be saved.

The “Save settings to file” function downloads the current settings to a local JSON file. This file can be manually edited if desired. It can later be uploaded using the “Load settings from file” function, which applies these saved settings to the current visualization. This functionality does not save any data to remote servers and the files remain entirely in the control of the user. The JSON file can act as a settings template that can produce reproducible visualizations across multiple datasets: These datasets can use different attributes and adjacency matrices, but must have the same dimensions (vertices and edges) and node labels. This functionality is all maintained when NeuroMArVL is built and deployed locally.

The “Save settings on webserver and share link” function saves the settings and the coordinates, matrix, attributes and labels on the webserver permanently (see Saved Data). Each data file is saved as is on the web server using randomly generated file names, and a link that allows users to share their visualizations with other researchers is generated. Any uploaded data may be deleted on request.

NeuroMArVL also provides functionality to visualize and export images for multiple adjacency matrix/attribute pairs automatically using the “Batch mode” function (Figure 2A, second panel). Firstly, the user sets up a visualization in one dataset by choosing a brain surface model, node locations/labels, and any desired 2D projection, placing and orienting the elements in their appropriate location. Then, in the batch mode tab, the user selects pairs of adjacency/weight matrix and attribute files for which visualization is required. These new adjacency and attribute files must have the same dimensions and format as the originals. After selecting the format and size of the output image files, NeuroMArVL iterates through all the selected adjacency/weight matrix and attribute file pairs and generates images with the same visualization parameters as the original, which can be saved to the local hard drive. As a use case, Figure 5 depicts the images generated from batch mode showing differing edge and node strengths across preprocessing methods for diffusion-based connectomes for a common parcellation scheme.

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

Code/data availability and contributions

All code is available via the repository at https://github.com/NSBLab/neuromarvl. NeuroMArVL can be downloaded, built, and used offline if desired. Contributions can be made and reviewed using GitHub’s forking and pull requests features.

The data included in the viewer are available via the website (https://immersive.erc.monash.edu/neuromarvl/brain-app/data/example.zip) and via the repository. Users can also contribute data by contacting the authors. Surface models must be in MNI space and would be made available in the selectable list. Parcellation schemes, comprising of node locations and labels, would be made available for download via GitHub; these could then be uploaded via the data tab in the NeuroMARvL interface

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 1, 27 September 2026: the first record

Recorded: type, language, journal, volume, issue, pages, dates, 6 authors, 4 keywords, 3 funders, 51 references.

Cite

This paper

Adamson, C. L., Gajwani, M., Klapperstueck, M., Manley, J., Dwyer, T., & Fornito, A. (2026). NeuroMArVL: An interactive and collaborative web-based tool for visualizing brain networks. Network neuroscience (Cambridge, Mass.), 10(3), 683-705. https://doi.org/10.1162/netn.a.569

BibTeX

@article{adamson2026neuromarvl,
author = {Adamson, Christopher Leslie and Gajwani, Mehul and Klapperstueck, Matthias and Manley, James and Dwyer, Tim and Fornito, Alex},
title = {{NeuroMArVL: An interactive and collaborative web-based tool for visualizing brain networks}},
journal = {Network neuroscience (Cambridge, Mass.)},
year = {2026},
month = jul,
volume = {10},
number = {3},
pages = {683--705},
publisher = {MIT Press},
issn = {2472-1751},
doi = {10.1162/netn.a.569},
url = {https://doi.org/10.1162/netn.a.569},
pmid = {42529553},
pmcid = {PMC13418255}
}

RIS

TY - JOUR
AU - Adamson, Christopher Leslie
AU - Gajwani, Mehul
AU - Klapperstueck, Matthias
AU - Manley, James
AU - Dwyer, Tim
AU - Fornito, Alex
TI - NeuroMArVL: An interactive and collaborative web-based tool for visualizing brain networks
T2 - Network neuroscience (Cambridge, Mass.)
J2 - Netw Neurosci
PY - 2026
DA - 2026/07/20
VL - 10
IS - 3
SP - 683
EP - 705
SN - 2472-1751
PB - MIT Press
DO - 10.1162/netn.a.569
UR - https://doi.org/10.1162/netn.a.569
LA - en
ER -

CSL-JSON

{
"id": "10.1162/netn.a.569",
"type": "article-journal",
"title": "NeuroMArVL: An interactive and collaborative web-based tool for visualizing brain networks",
"container-title": "Network neuroscience (Cambridge, Mass.)",
"author": [
{
"family": "Adamson",
"given": "Christopher Leslie"
},
{
"family": "Gajwani",
"given": "Mehul"
},
{
"family": "Klapperstueck",
"given": "Matthias"
},
{
"family": "Manley",
"given": "James"
},
{
"family": "Dwyer",
"given": "Tim"
},
{
"family": "Fornito",
"given": "Alex"
}
],
"container-title-short": "Netw Neurosci",
"volume": "10",
"issue": "3",
"page": "683-705",
"DOI": "10.1162/netn.a.569",
"PMID": "42529553",
"PMCID": "PMC13418255",
"ISSN": "2472-1751",
"publisher": "MIT Press",
"URL": "https://doi.org/10.1162/netn.a.569",
"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.7554/elife.103097 [code]
Canonical neurodevelopmental trajectories of structural and functional manifolds.
Journal: eLife
In common: netneurotools, neuromaps, Brain Connectivity Toolbox, 8 other tools, 4 references
[2] doi:10.1371/journal.pbio.3003856 [code]
Aging and metabolism contribute separately to brain-body health.
Journal: PLoS biology
In common: netneurotools, neuromaps, GIfTI library for MATLAB, 8 other tools, 3 references
[3] doi:10.1038/s42003-025-09444-3 [code]
Decoupling of neurophysiological activity from structure mirrors global microarchitectural and neuromodulatory trends.
Journal: Communications biology
In common: netneurotools, neuromaps, Brain Connectivity Toolbox, 8 other tools, 3 references
[4] doi:10.1038/s41398-026-04025-2 [code]
Brain energetic landscapes shape state dysregulation in major depressive disorder: a morphological network controllability perspective.
Journal: Translational psychiatry
In common: neuromaps, Brain Connectivity Toolbox, GIfTI library for MATLAB, 9 other tools, 3 references
[5] doi:10.1038/s41586-026-10631-3 [code]
A prognostic human brain network for diffuse midline glioma.
Journal: Nature
In common: cifti-matlab, neuromaps, GIfTI library for MATLAB, 8 other tools, 3 references
[6] doi:10.1002/hbm.70605 [code]
BrainEnrich: Revealing Biological Insights for Imaging-Derived Phenotypes Through Transcriptomic Enrichment.
Journal: Human brain mapping
In common: netneurotools, cifti-matlab, GIfTI library for MATLAB, 9 other tools, 2 references
[7] doi:10.1038/s41467-026-71151-2 [code]
Common and distinct neural correlates of social interaction processing and theory of mind in narratives.
Journal: Nature communications
In common: cifti-matlab, Brain Connectivity Toolbox, GIfTI library for MATLAB, 9 other tools, 2 references
[8] doi:10.1038/s41467-026-74466-2 [code]
Neuromorphic hierarchical modular reservoirs.
Journal: Nature communications
In common: netneurotools, neuromaps, Brain Connectivity Toolbox, 8 other tools, 2 references
[9] doi:10.21203/rs.3.rs-9326213/v1 [code]
Multi-task fMRI outperforms resting-state fMRI for revealing task-invariant organization of the human brain
Journal: Research Square (preprint)
In common: neuromaps, GIfTI library for MATLAB, Numba, 8 other tools, 3 references
[10] doi:10.1038/s41467-026-75959-w [code]
Charting higher-order models of brain function beyond pairwise interactions.
Journal: Nature communications
In common: neuromaps, Numba, Nilearn, 6 other tools, 6 references

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.

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: questions and error reports about this paper and its code, from signed-in readers and its authors. It opens with sign-in.

Reproductions: reports from readers who ran the authors' code: what they reproduced, with which environment, commit and data. It opens with sign-in.

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