download_bids_dataset#
- uniharmony.datasets.download_bids_dataset(subjects: str | list[str], sessions: str | list[str], modalities: str | list[str], tasks: str | list[str], runs: str | list[str], suffixes: str | list[str], extensions: str | list[str], target_path: str | Path, dataset_url: str, root_files: str | list[str], force_download: bool = False, copy: bool = True, hidden: bool = True, tmp_clean: bool = False, tmp_dir_name: str = 'datalad_cache') None#
Download derivatives and root files from a BIDS-compatible dataset.
This function transparently uses a hidden DataLad dataset (stored in a temporary location) to retrieve files from a repository. All DataLad operations happen in the background. The user-visible directory contains only regular files (no symbolic links, Git metadata, or DataLad traces).
Only the requested files are downloaded. Each file is copied as a real file (not symbolic) into the visible dataset directory and immediately dropped from the hidden DataLad cache to minimize disk usage.
- Parameters:
- subjectsstr or list
Subject identifiers to download.
- sessionsstr or list
Session identifiers to download.
- modalitiesstr or list
Modalities to download (“all”, “anat”, “dwi”, “fmap”, “func”, “swi”).
- tasksstr or list
Tasks to download.
- runsstr or list
Runs to download.
- suffixesstr or list
BIDS suffixes to match in filenames (e.g., ‘T1w’, ‘T2w’).
- extensionsstr or list, optional (default “.json”)
File extensions to download (e.g., ‘.json’, ‘.nii.gz’).
- target_pathstr or pathlib.Path
Path to the visible dataset directory where files will be stored.
- dataset_urlstr
Source URL to the BIDS-compatible dataset.
- root_filesstr or list
Name of the file list of files to get from the dataset’s root.
- force_downloadbool, optional (default False)
Whether to force re-download the dataset if it already exists in tmp.
- copybool, optional (default True)
Whether to copy the downloaded files from the hidden cache to the target directory. Ignored when
hidden=False(files are already in the target directory).- hiddenbool, optional (default True)
Whether to use a hidden directory or not. If hidden=False, no hidden folder is made and the target directory acts as hidden. This will avoid getting the files in
/tmp/{tmp_dir_name}and then copying them to the target directory.- tmp_cleanbool, optional (default False)
Whether to drop the downloaded files from the hidden DataLad dataset after copying. If True, files are dropped immediately after copying to the target directory (if copy=True), to minimize disk usage. Ignored when
hidden=False.- tmp_dir_namestr, optional (default “datalad_cache”)
Name of the temporary directory to store the hidden dataset.
Notes
The visible dataset directory will contain only regular files following the BIDS derivatives structure.
Repeated calls are safe and will only download missing files.