larmor.data#

Public example datasets, downloaded once into a cache folder on first use.

Each fetch_ function downloads the files of one dataset that are not in the cache yet, checks each against its SHA-256 checksum, and returns their paths, ready for larmor.io.load_dwi and larmor.io.load_volume. The licence and the citation of a dataset are logged when it is first downloaded and saved in a README.txt next to its files; please cite the dataset when you use it.

data_folder

Returns the folder that example datasets are downloaded into.

fetch_cfin_multishell

Downloads the CFIN multi-shell dataset, if needed, and returns its files.

fetch_ismrm2015

Downloads the ISMRM 2015 Tractography Challenge data, if needed.

fetch_stanford_hardi

Downloads the Stanford HARDI dataset, if needed, and returns its files.
larmor.data.data_folder()#

Returns the folder that example datasets are downloaded into.

It is the folder in the LARMOR_DATA_DIR environment variable when that is set; otherwise the larmor folder in the user’s cache folder: /Library/Caches/larmor on macOS, $XDG_CACHE_HOME/larmor (by default cache/larmor) on Linux and %LOCALAPPDATA%/larmor/Cache on Windows. The folder is created when a dataset is first downloaded.

Returns:

The folder, which may not exist yet.

Return type:

Path

larmor.data.fetch_cfin_multishell(folder=None)#

Downloads the CFIN multi-shell dataset, if needed, and returns its files.

One healthy volunteer scanned at 3 T (Siemens Trio) by Hansen and Jespersen: diffusion-weighted images at 2.5 mm isotropic resolution (96 x 96 x 19 voxels) with one b=0 image and 33 directions at each of 15 b-values from 200 to 3000 s/mm^2, as acquired (no preprocessing), and a defaced 1 mm T1-weighted MPRAGE of the same session. Enough shells and directions for DKI and multi-shell deconvolution. About 197 MB.

The b-vectors follow the FSL convention, the default of load_dwi: load_dwi(files["dwi"], files["bvals"], files["bvecs"]).

The data is published on Dryad (https://doi.org/10.5061/dryad.9bc43) under CC0 1.0. Dryad’s downloads need a browser, so the files come from a copy in the University of Washington’s ResearchWorks archive (http://hdl.handle.net/1773/38488).

Please cite: Hansen B, Jespersen SN. Data for evaluation of fast kurtosis strategies, b-value optimization and exploration of diffusion MRI contrast. Scientific Data 3 (2016) 160072. https://doi.org/10.1038/sdata.2016.72

Parameters:

folder (str | Path | None) – The cache folder; None for data_folder(). The files go into its cfin_multishell subfolder.

Returns:

The paths of the files, by key – “dwi” (NIfTI), “bvals” and “bvecs” (FSL format), and “t1” (NIfTI, on its own grid).

Raises:

  • OSError – If a download fails; run it again to start that file anew.

  • ValueError – If a downloaded file does not match its checksum.

Return type:

dict[str, Path]

larmor.data.fetch_ismrm2015(folder=None)#

Downloads the ISMRM 2015 Tractography Challenge data, if needed.

The data given to the challenge’s contestants, simulated from bundles traced in a real brain: diffusion-weighted images at 2 mm isotropic resolution (90 x 108 x 90 voxels), one b=0 image and 32 directions at b=1000 s/mm^2, with the noise and artefacts of a scan, and a simulated T1-like image at 1 mm on the same field of view. One shell with few directions: enough for DTI, FODs up to lmax 6 and tractography. About 41 MB to download (a zip archive, deleted once its files are extracted), 36 MB in the cache.

The files in the cache differ from the Zenodo originals in one way: the published b-vectors have the wrong sign on their x components, as the challenge’s data page notes, and this function changes that sign when it extracts the file (after checking the archive’s checksum), so the saved dwi.bvecs is right for every program that reads it as an FSL bvecs file, including load_dwi with its default frame: load_dwi(files["dwi"], files["bvals"], files["bvecs"]). Read this way, the tensors’ principal directions follow the challenge’s ground-truth bundles (median |cos| 0.97 in voxels of a single bundle, against 0.65 without the correction, whose fibres are mirrored top to bottom). The corrected file is checked against its own SHA-256, so a cache written before the correction is downloaded and corrected again, and the correction is never applied twice. The README.txt saved next to the files says what changed.

Published on Zenodo (https://doi.org/10.5281/zenodo.572345) under CC BY 4.0.

Please cite: Maier-Hein KH, Neher PF, Houde J-C, et al. The challenge of mapping the human connectome based on diffusion tractography. Nature Communications 8 (2017) 1349. https://doi.org/10.1038/s41467-017-01285-x

Parameters:

folder (str | Path | None) – The cache folder; None for data_folder(). The files go into its ismrm2015 subfolder.

Returns:

The paths of the files, by key – “dwi” (NIfTI), “bvals” and “bvecs” (FSL format, corrected) and “t1” (NIfTI, at 1 mm).

Raises:

  • OSError – If a download fails; run it again to start that file anew.

  • ValueError – If a downloaded file does not match its checksum.

Return type:

dict[str, Path]

larmor.data.fetch_stanford_hardi(folder=None)#

Downloads the Stanford HARDI dataset, if needed, and returns its files.

One healthy volunteer scanned at 3 T at Stanford: diffusion-weighted images at 2 mm isotropic resolution (81 x 106 x 76 voxels), 10 b=0 images and 150 directions at b=2000 s/mm^2, motion corrected; a T1-weighted image and a reduced FreeSurfer parcellation (aparc), both resampled to the diffusion grid. A single shell with many directions, for DTI, FODs and tractography. About 93 MB.

The b-vectors are in world coordinates, not in the FSL convention, so load them with frame="world": load_dwi(files["dwi"], files["bvals"], files["bvecs"], frame="world"). Read as FSL b-vectors they would be mirrored left to right.

Licensed under the Open Data Commons Public Domain Dedication and License 1.0 (https://purl.stanford.edu/yx282xq2090). The repository asks that the data never be used to identify the volunteer.

Please cite: Rokem A, Yeatman J, Pestilli F, Wandell B. High angular resolution diffusion MRI. Stanford Digital Repository (2013). http://purl.stanford.edu/yx282xq2090

Parameters:

folder (str | Path | None) – The cache folder; None for data_folder(). The files go into its stanford_hardi subfolder.

Returns:

The paths of the files, by key – “dwi” (NIfTI), “bvals”, “bvecs” (in world coordinates), “t1” and “labels” (NIfTI, on the diffusion grid).

Raises:

  • OSError – If a download fails; run it again to start that file anew.

  • ValueError – If a downloaded file does not match its checksum.

Return type:

dict[str, Path]