0
# Data Access and Management
1

2
Comprehensive data loading, example datasets, and I/O operations for diffusion MRI data. DIPY provides extensive example datasets for testing and learning, along with utilities for handling various neuroimaging file formats.
3

4
## Capabilities
5

6
### Example Data Loading
7

8
Access to curated example datasets for testing and educational purposes, including diffusion MRI data from various research institutions and phantom data.
9

10
```python { .api }
11
def read_stanford_hardi():
12
    """
13
    Load Stanford HARDI dataset.
14
    
15
    Returns:
16
        tuple: (img, gtab) - NiBabel image and gradient table
17
    """
18

19
def read_sherbrooke_3shell():
20
    """
21
    Load Sherbrooke 3-shell dataset.
22
    
23
    Returns:
24
        tuple: (img, gtab) - Multi-shell diffusion data
25
    """
26

27
def read_taiwan_ntu_dsi():
28
    """
29
    Load Taiwan NTU DSI dataset.
30
    
31
    Returns:
32
        tuple: (img, gtab) - Diffusion spectrum imaging data
33
    """
34

35
def read_isbi2013_2shell():
36
    """
37
    Load ISBI 2013 2-shell challenge dataset.
38
    
39
    Returns:
40
        tuple: (img, gtab) - Two-shell diffusion data
41
    """
42

43
def read_ivim():
44
    """
45
    Load IVIM (Intravoxel Incoherent Motion) dataset.
46
    
47
    Returns:
48
        tuple: (img, gtab) - IVIM diffusion data
49
    """
50
```
51

52
### Dataset Fetching
53

54
Functions to download and cache datasets from various sources, providing access to larger research datasets.
55

56
```python { .api }
57
def fetch_stanford_hardi():
58
    """
59
    Fetch Stanford HARDI dataset from remote source.
60
    
61
    Returns:
62
        tuple: File paths to downloaded data
63
    """
64

65
def fetch_hcp():
66
    """
67
    Fetch Human Connectome Project data.
68
    
69
    Returns:
70
        tuple: Paths to HCP diffusion data
71
    """
72

73
def fetch_bundles_2_subjects():
74
    """
75
    Fetch streamline bundles from 2 subjects.
76
    
77
    Returns:
78
        tuple: Paths to bundle data files
79
    """
80

81
def fetch_bundle_atlas_hcp842():
82
    """
83
    Fetch bundle atlas from HCP 842 subjects.
84
    
85
    Returns:
86
        str: Path to atlas files
87
    """
88

89
def fetch_mni_template():
90
    """
91
    Fetch MNI brain template.
92
    
93
    Returns:
94
        str: Path to template file
95
    """
96
```
97

98
### Gradient Table Management
99

100
Creation and manipulation of gradient tables that define the diffusion sensitization directions and strengths.
101

102
```python { .api }
103
def gradient_table(bvals, bvecs=None, *, big_delta=None, small_delta=None, b0_threshold=50, atol=1e-2):
104
    """
105
    Create gradient table from b-values and b-vectors.
106
    
107
    Parameters:
108
        bvals (array): b-values in s/mm²
109
        bvecs (array): gradient directions (3 x N or N x 3)
110
        big_delta (float): diffusion time parameter
111
        small_delta (float): gradient duration parameter  
112
        b0_threshold (float): threshold for b=0 images
113
        atol (float): tolerance for b-value comparison
114
        
115
    Returns:
116
        GradientTable: Container with gradient information
117
    """
118

119
class GradientTable:
120
    """Container for diffusion gradient information."""
121
    def __init__(self, bvals, bvecs=None, **kwargs): ...
122
    
123
    @property
124
    def bvals(self):
125
        """array: b-values in s/mm²"""
126
    
127
    @property 
128
    def bvecs(self):
129
        """array: normalized gradient directions"""
130
    
131
    @property
132
    def b0s_mask(self):
133
        """array: boolean mask for b=0 images"""
134
    
135
    @property
136
    def gradients(self):
137
        """array: gradient directions scaled by b-values"""
138
```
139

140
### File I/O Operations
141

142
Reading and writing various neuroimaging file formats including b-values, b-vectors, and streamline data.
143

144
```python { .api }
145
def read_bvals_bvecs(fbvals, fbvecs):
146
    """
147
    Read b-values and b-vectors from files.
148
    
149
    Parameters:
150
        fbvals (str): path to b-values file
151
        fbvecs (str): path to b-vectors file
152
        
153
    Returns:
154
        tuple: (bvals, bvecs) arrays
155
    """
156

157
def save_pickle(fname, dix):
158
    """
159
    Save object using pickle serialization.
160
    
161
    Parameters:
162
        fname (str): output filename
163
        dix (object): object to save
164
    """
165

166
def load_pickle(fname):
167
    """
168
    Load object from pickle file.
169
    
170
    Parameters:
171
        fname (str): pickle file path
172
        
173
    Returns:
174
        object: deserialized object
175
    """
176

177
class Dpy:
178
    """DIPY's native streamline format handler."""
179
    def __init__(self, fname, mode='r'): ...
180
    
181
    def read_streamlines(self):
182
        """Read streamlines from file."""
183
    
184
    def write_streamlines(self, streamlines):
185
        """Write streamlines to file."""
186
    
187
    def close(self):
188
        """Close file handle."""
189
```
190

191
### Simulation Data
192

193
Generate synthetic diffusion data for testing and validation purposes.
194

195
```python { .api }
196
def get_sim_voxels(*, name="fib1"):
197
    """
198
    Provide simulated voxel data for testing.
199
    
200
    Parameters:
201
        name (str): simulation type ('fib0', 'fib1', 'fib2')
202
        
203
    Returns:
204
        dict: Dictionary with 'data', 'fibres', 'gradients', 'bvals', 'snr'
205
    """
206

207
def dsi_voxels():
208
    """
209
    DSI dataset for testing.
210
    
211
    Returns:
212
        tuple: (data, gtab) synthetic DSI data
213
    """
214
```
215

216
### Sphere Utilities
217

218
Access to predefined spherical sampling schemes used in spherical harmonics and directional analysis.
219

220
```python { .api }
221
def get_sphere(name='symmetric724'):
222
    """
223
    Get pre-built sphere objects.
224
    
225
    Parameters:
226
        name (str): sphere configuration name
227
        
228
    Returns:
229
        Sphere: sphere object with vertices and faces
230
    """
231
```
232

233
### Usage Examples
234

235
```python
236
# Load example data
237
from dipy.data import read_stanford_hardi
238
from dipy.core.gradients import gradient_table
239

240
# Read diffusion data
241
img, gtab = read_stanford_hardi()
242
data = img.get_fdata()
243

244
# Create custom gradient table
245
import numpy as np
246
bvals = np.array([0, 1000, 1000, 2000, 2000])
247
bvecs = np.random.randn(5, 3)
248
bvecs[0] = 0  # b=0 has no direction
249
gtab = gradient_table(bvals, bvecs)
250

251
print(f"Number of gradients: {len(gtab.bvals)}")
252
print(f"Number of b=0 images: {gtab.b0s_mask.sum()}")
253

254
# Load streamline data using Dpy format
255
from dipy.io.streamline import Dpy
256

257
# Read streamlines
258
with Dpy('streamlines.dpy', 'r') as dpy:
259
    streamlines = dpy.read_streamlines()
260

261
# Access simulation data
262
from dipy.data import get_sim_voxels
263

264
sim_data = get_sim_voxels(name='fib1')
265
print(f"Simulation data shape: {sim_data['data'].shape}")
266
print(f"Number of fibers: {sim_data['fibres']}")
267
```