0
# DIPY
1
2
DIPY (Diffusion Imaging in Python) is a comprehensive Python library for the analysis of diffusion MRI (Magnetic Resonance Imaging) data. It provides scientists and researchers with powerful tools for processing, analyzing, and visualizing diffusion-weighted imaging datasets, enabling advanced brain connectivity studies and white matter research.
3
4
## Package Information
5
6
- **Package Name**: dipy
7
- **Language**: Python
8
- **Installation**: `pip install dipy`
9
- **Documentation**: https://docs.dipy.org/stable/
10
11
## Core Imports
12
13
```python
14
import dipy
15
```
16
17
Common workflow imports:
18
19
```python
20
# Core objects
21
from dipy.core.gradients import gradient_table, GradientTable
22
from dipy.core.sphere import get_sphere, Sphere
23
from dipy.core.geometry import sphere2cart, cart2sphere
24
25
# Data access
26
from dipy.data import read_stanford_hardi, read_sherbrooke_3shell, read_ivim
27
28
# Signal reconstruction
29
from dipy.reconst.dti import TensorModel, TensorFit
30
from dipy.reconst.csdeconv import ConstrainedSphericalDeconvModel
31
from dipy.reconst.dki import DiffusionKurtosisModel
32
33
# Registration and alignment
34
from dipy.align import syn_registration, affine_registration, center_of_mass
35
36
# Tractography
37
from dipy.tracking.streamline import Streamlines
38
from dipy.direction import DeterministicMaximumDirectionGetter, ProbabilisticDirectionGetter
39
from dipy.tracking.local_tracking import LocalTracking
40
41
# Visualization
42
from dipy.viz import window, actor
43
44
# I/O operations
45
from dipy.io.streamline import save_tractogram, load_tractogram
46
from dipy.io.image import load_nifti, save_nifti
47
from dipy.io.gradients import read_bvals_bvecs
48
49
# Utilities
50
from dipy.utils.arrfuncs import normalize_v3
51
```
52
53
## Basic Usage
54
55
```python
56
import dipy
57
from dipy.data import read_stanford_hardi
58
from dipy.core.gradients import gradient_table
59
from dipy.reconst.dti import TensorModel
60
import numpy as np
61
62
# Load example diffusion data
63
img, gtab = read_stanford_hardi()
64
data = img.get_fdata()
65
66
# Create gradient table
67
gtab = gradient_table(gtab.bvals, gtab.bvecs)
68
69
# Fit diffusion tensor model
70
tenmodel = TensorModel(gtab)
71
tenfit = tenmodel.fit(data)
72
73
# Extract fractional anisotropy (FA)
74
fa = tenfit.fa
75
76
# Extract apparent diffusion coefficient (ADC)
77
adc = tenfit.adc
78
79
print(f"FA shape: {fa.shape}")
80
print(f"Mean FA: {np.mean(fa[fa > 0]):.3f}")
81
```
82
83
## Architecture
84
85
DIPY's modular architecture provides a comprehensive framework for diffusion MRI analysis:
86
87
- **Core Objects**: Fundamental data structures (spheres, gradient tables, geometry utilities)
88
- **Data Access**: Extensive example datasets and I/O utilities for various formats
89
- **Signal Reconstruction**: Model-based analysis (DTI, DKI, CSD, MAPMRI, IVIM) with consistent Model/Fit interfaces
90
- **Registration**: Image and streamline alignment with multiple transformation types
91
- **Tractography**: Deterministic and probabilistic fiber tracking with direction selection
92
- **Segmentation**: Streamline clustering and bundle segmentation algorithms
93
- **Statistics**: Tractometry and statistical analysis of diffusion metrics
94
- **Simulations**: Phantom data generation and signal simulation
95
- **Neural Networks**: Deep learning models for denoising and enhancement
96
- **Visualization**: 3D rendering and interactive visualization tools
97
- **Workflows**: Pre-built command-line interfaces for common analysis pipelines
98
- **Utilities**: Array manipulation, coordinate transformations, and helper functions
99
100
This design enables flexible analysis pipelines from raw data through model fitting to visualization and statistical analysis.
101
102
## Capabilities
103
104
### Data Access and Management
105
106
Comprehensive data loading, example datasets, and I/O operations for diffusion MRI data formats including gradient tables, streamlines, and various neuroimaging file types.
107
108
```python { .api }
109
def read_stanford_hardi():
110
"""Load Stanford HARDI dataset."""
111
112
def gradient_table(bvals, *, bvecs=None, big_delta=None, small_delta=None, b0_threshold=50, atol=1e-2, btens=None):
113
"""Create gradient table from b-values and b-vectors."""
114
115
def read_bvals_bvecs(fbvals, fbvecs):
116
"""Read b-values and b-vectors from files."""
117
118
class GradientTable:
119
def __init__(self, gradients, b0_threshold=50): ...
120
@property
121
def bvals(self): ...
122
@property
123
def bvecs(self): ...
124
125
def get_sphere(*, name="symmetric362"):
126
"""Provide triangulated spheres."""
127
```
128
129
[Data Access](./data-access.md)
130
131
### Signal Reconstruction Models
132
133
Model-based analysis of diffusion MRI signals including diffusion tensor imaging (DTI), diffusion kurtosis imaging (DKI), constrained spherical deconvolution (CSD), and advanced microstructure models.
134
135
```python { .api }
136
class TensorModel:
137
def __init__(self, gtab, fit_method="WLS", return_S0_hat=False): ...
138
def fit(self, data, mask=None): ...
139
140
class ConstrainedSphericalDeconvModel:
141
def __init__(self, gtab, response, reg_sphere=None, sh_order=8): ...
142
def fit(self, data, mask=None): ...
143
144
class DiffusionKurtosisModel:
145
def __init__(self, gtab, fit_method="WLS", **kwargs): ...
146
def fit(self, data, mask=None): ...
147
148
class TensorFit:
149
@property
150
def fa(self): ... # Fractional anisotropy
151
@property
152
def adc(self): ... # Apparent diffusion coefficient
153
@property
154
def md(self): ... # Mean diffusivity
155
def predict(self, gtab=None, S0=None): ...
156
```
157
158
[Signal Reconstruction](./signal-reconstruction.md)
159
160
### Registration and Alignment
161
162
Image registration algorithms for aligning diffusion data, including affine and non-linear registration methods, motion correction, and streamline registration.
163
164
```python { .api }
165
def syn_registration(moving, static, moving_affine=None, static_affine=None, prealign=None, **kwargs):
166
"""Symmetric diffeomorphic registration."""
167
168
def affine_registration(moving, static, moving_affine=None, static_affine=None, **kwargs):
169
"""Multi-resolution affine registration."""
170
171
def register_dwi_series(data, gtab, affine=None, b0_ref=0, **kwargs):
172
"""Register DWI series for motion correction."""
173
174
def streamline_registration(moving, static, moving_affine=None, static_affine=None, **kwargs):
175
"""Register streamlines using bundle-based approach."""
176
177
def resample(moving, static, moving_affine=None, static_affine=None, **kwargs):
178
"""Resample image using transformation."""
179
180
def center_of_mass(moving, static):
181
"""Align images using center of mass."""
182
```
183
184
[Registration](./registration.md)
185
186
### Tractography and Fiber Tracking
187
188
Deterministic and probabilistic tractography algorithms with various direction selection methods, streamline generation, and tracking utilities.
189
190
```python { .api }
191
class DeterministicMaximumDirectionGetter:
192
def __init__(self, from_shm, max_angle=60.0, sphere=None, pmf_threshold=0.1): ...
193
194
class ProbabilisticDirectionGetter:
195
def __init__(self, from_shm, max_angle=60.0, sphere=None, pmf_threshold=0.1): ...
196
197
class LocalTracking:
198
def __init__(self, direction_getter, stopping_criterion, seeds, affine=None, step_size=0.5): ...
199
200
class Streamlines:
201
def __init__(self, streamlines=None, affine_to_rasmm=None): ...
202
def __len__(self): ...
203
def __getitem__(self, key): ...
204
205
def peaks_from_model(model, data, sphere, relative_peak_threshold=0.25, min_separation_angle=25, **kwargs):
206
"""Extract peaks from fitted model."""
207
```
208
209
[Tractography](./tractography.md)
210
211
### Visualization and Analysis
212
213
3D visualization tools for diffusion data, streamlines, and scalar maps with interactive rendering capabilities and statistical analysis methods.
214
215
```python { .api }
216
class Scene:
217
def __init__(self, bg=(0, 0, 0)): ...
218
def add(self, actor): ...
219
def rm(self, actor): ...
220
221
def line(lines, colors=None, opacity=1, linewidth=1):
222
"""Create line actor for streamlines."""
223
224
def slicer(data, affine=None, value_range=None, opacity=1, lookup_colormap=None):
225
"""Create slicer actor for volume data."""
226
227
def tensor_slicer(evals, evecs, scalar_colors=None, sphere=None, scale=0.3):
228
"""Create tensor ellipsoid slicer."""
229
```
230
231
[Visualization](./visualization.md)
232
233
### Image Processing and Filtering
234
235
Denoising algorithms, filtering methods, and preprocessing tools for diffusion MRI data quality improvement.
236
237
```python { .api }
238
def nlmeans(arr, sigma=None, mask=None, patch_radius=1, block_radius=5, rician=True):
239
"""Non-local means denoising."""
240
241
def localpca(arr, sigma, mask=None, patch_radius=2, pca_method='eig', **kwargs):
242
"""PCA-based denoising."""
243
244
def mppca(arr, mask=None, patch_radius=2, return_sigma=False, **kwargs):
245
"""Marchenko-Pastur PCA denoising."""
246
247
def gibbs_removal(vol, slice_axis=2, n_points=3):
248
"""Gibbs ringing artifact removal."""
249
```
250
251
[Image Processing](./image-processing.md)
252
253
### Segmentation and Clustering
254
255
Streamline clustering, bundle segmentation, and white matter bundle extraction algorithms for organizing and analyzing tractography results.
256
257
```python { .api }
258
class QuickBundles:
259
def __init__(self, threshold, metric='average'): ...
260
def cluster(self, streamlines): ...
261
262
def bundle_shape_similarity(bundle1, bundle2, rng=None, clust_thr=5): ...
263
def bundle_adjacency(dtracks0, dtracks1, threshold): ...
264
```
265
266
[Segmentation and Clustering](./segmentation.md)
267
268
### Statistics and Tractometry
269
270
Statistical analysis tools for diffusion metrics, tractometry analysis, and group-level comparisons of white matter properties.
271
272
```python { .api }
273
def afq_profile(data, bundle, affine=None, n_points=100): ...
274
def gaussian_weights(bundle, n_points=100, return_mahalnobis=False): ...
275
def values_from_volume(data, streamlines, affine=None): ...
276
```
277
278
[Statistics and Tractometry](./statistics.md)
279
280
### Simulations and Phantoms
281
282
Signal simulation tools for generating synthetic diffusion MRI data, phantoms, and testing algorithms with known ground truth.
283
284
```python { .api }
285
def single_tensor(gtab, S0=1, evals=None, evecs=None, snr=None): ...
286
def multi_tensor(gtab, mevals, angles, fractions, S0=100, snr=None): ...
287
def sticks_and_ball(gtab, d=0.0015, S0=1, angles=[(0, 0)], fractions=[100], snr=None): ...
288
```
289
290
[Simulations and Phantoms](./simulations.md)
291
292
### Neural Networks and Deep Learning
293
294
Deep learning models for image denoising, enhancement, and reconstruction of diffusion MRI data.
295
296
```python { .api }
297
class DummyNeuralNetwork:
298
def __init__(self): ...
299
def predict(self, data, **kwargs): ...
300
301
def deepn4(data, **kwargs): ...
302
def patch2self(data, bvals, patch_radius=0): ...
303
```
304
305
[Neural Networks and Deep Learning](./neural-networks.md)
306
307
### Workflows and Command-Line Tools
308
309
Pre-built workflows and command-line interfaces for common diffusion MRI analysis pipelines and batch processing.
310
311
```python { .api }
312
class Workflow:
313
def run(self, **kwargs): ...
314
315
class IoInfoFlow(Workflow): ...
316
class DenoisingFlow(Workflow): ...
317
class ReconstDtiFlow(Workflow): ...
318
class TrackingFlow(Workflow): ...
319
```
320
321
[Workflows and Command-Line Tools](./workflows.md)
322
323
### Core Utilities
324
325
Essential utility functions for array manipulation, coordinate transformations, and mathematical operations.
326
327
```python { .api }
328
def normalize_v3(vec): ...
329
def as_native_array(arr): ...
330
def sphere2cart(r, theta, phi): ...
331
def cart2sphere(x, y, z): ...
332
```
333
334
[Core Utilities](./core-utilities.md)
335
336
## Types
337
338
```python { .api }
339
class GradientTable:
340
"""Container for diffusion gradient information."""
341
def __init__(self, bvals, bvecs=None, **kwargs): ...
342
@property
343
def bvals(self): ... # b-values array
344
@property
345
def bvecs(self): ... # b-vectors array
346
@property
347
def b0s_mask(self): ... # Boolean mask for b=0 images
348
349
class Streamlines:
350
"""Container for streamline data."""
351
def __init__(self, streamlines=None): ...
352
def __len__(self): ...
353
def __getitem__(self, key): ...
354
355
class Sphere:
356
"""3D sphere representation with vertices and faces."""
357
def __init__(self, xyz=None, faces=None): ...
358
@property
359
def vertices(self): ...
360
@property
361
def faces(self): ...
362
```