Coverage for nilearn/datasets/utils.py: 28%

24 statements  

« prev     ^ index     » next       coverage.py v7.9.1, created at 2025-06-20 10:58 +0200

1"""Downloading NeuroImaging datasets: utility functions.""" 

2 

3import os 

4from pathlib import Path 

5from warnings import warn 

6 

7from nilearn._utils import fill_doc 

8from nilearn._utils.logger import find_stack_level 

9 

10_GENERAL_MESSAGE = ( 

11 "The import path 'nilearn.datasets.utils'\n" 

12 "will be deprecated in version 0.13.\n" 

13 "Importing from 'nilearn.datasets.utils will be possible\n" 

14 "at least until release 0.13.0." 

15) 

16 

17 

18@fill_doc 

19def get_data_dirs(data_dir=None): 

20 """Return the directories in which nilearn looks for data. 

21 

22 This is typically useful for the end-user to check where the data is 

23 downloaded and stored. 

24 

25 Parameters 

26 ---------- 

27 %(data_dir)s 

28 

29 Returns 

30 ------- 

31 paths : list of strings 

32 Paths of the dataset directories. 

33 

34 Notes 

35 ----- 

36 This function retrieves the datasets directories using the following 

37 priority : 

38 

39 1. defaults system paths 

40 2. the keyword argument data_dir 

41 3. the global environment variable NILEARN_SHARED_DATA 

42 4. the user environment variable NILEARN_DATA 

43 5. nilearn_data in the user home folder 

44 

45 """ 

46 # We build an array of successive paths by priority 

47 # The boolean indicates if it is a pre_dir: in that case, we won't add the 

48 # dataset name to the path. 

49 paths = [] 

50 

51 # Check data_dir which force storage in a specific location 

52 if data_dir is not None: 

53 paths.extend(str(data_dir).split(os.pathsep)) 

54 

55 # If data_dir has not been specified, then we crawl default locations 

56 if data_dir is None: 

57 global_data = os.getenv("NILEARN_SHARED_DATA") 

58 if global_data is not None: 

59 paths.extend(global_data.split(os.pathsep)) 

60 

61 local_data = os.getenv("NILEARN_DATA") 

62 if local_data is not None: 

63 paths.extend(local_data.split(os.pathsep)) 

64 

65 paths.append(str(Path("~/nilearn_data").expanduser())) 

66 return paths 

67 

68 

69def load_sample_motor_activation_image(): 

70 """Load a single functional image showing motor activations. 

71 

72 Returns 

73 ------- 

74 str 

75 Path to the sample functional image. 

76 """ 

77 from .func import load_sample_motor_activation_image as tmp 

78 

79 warn( 

80 f"{_GENERAL_MESSAGE}" 

81 "Please import this function from 'nilearn.datasets.func' instead.", 

82 DeprecationWarning, 

83 stacklevel=find_stack_level(), 

84 ) 

85 return tmp()