download_xtract_tracts: Download a white matter tract atlas (streamlines).

Description

Download one of the tract atlases that are distributed as streamlines in TrackVis TRK format, one file per white matter bundle. The bundle files (and the provenance and attribution files that document them) are downloaded into the fsbrain file cache, where get_optional_data_filepath can be used to access them. The bundles can then be read with read.tract.bundles and plotted with vis.tracts.

Usage

download_xtract_tracts(
  atlas = "xtract_medium",
  download = TRUE,
  scheme = "https",
  silent = FALSE
)

Value

named list. The list has the entries "available" (vector of character strings, the paths of the bundle files that are available in the local file cache) and "missing" (vector of character strings, the files that could not be retrieved).

Arguments

atlas: character string, the atlas to download. One of 'xtract_tiny' (the smallest one, useful for quick tests), 'xtract_small', 'xtract_medium' (the default) or 'xtract_large' (the most detailed one).
download: logical, whether to download the files if they are not in the cache. If FALSE, the function only reports the status of the files.
scheme: character string, the URL scheme to use, see the 'scheme' parameter of download_fs_LR_32_meshes.
silent: logical, whether to suppress the progress messages.

Details

The atlases are the XTRACT atlas of the 42 major white matter tracts (Warrington et al., 2020, tools:::Rd_expr_doi("10.1126/sciadv.aba8245")), whose streamlines were converted from the probabilistic tract atlases and are available in four levels of spatial detail. Note that the bundles are defined in MNI152 space, while the fs_LR_32 and fsaverage templates of fsbrain use a different (fsaverage-like) space: the two spaces are very similar, so the tracts align with the template surfaces well enough for visualization, but they are not identical. If you need an exact alignment, register the template to MNI152 and pass the resulting matrix to the parameter transform_matrix of vis.tracts.

The files are hosted on the rcmd.org server of this project, in the same way as the other optional data of the package, see download_optional_data. They are redistributed from the archives of the MIT licensed 'yabplot' Python package, which uses the same streamlines; the attribution and provenance files that come with them document the origin (see tracts/xtract.attribution.json and the per-level tracts/xtract_<level>/xtract_<level>.provenance.json in the file cache). This data is not required for the package to work.

Examples

Run this code

if (FALSE) {
  # Download the small version of the XTRACT atlas:
  download_xtract_tracts("xtract_small");

  # The bundle files are now in the cache:
  atlas_dir = file.path(get_optional_data_filepath("tracts"), "xtract_small");
  list.files(atlas_dir);
}