0
# Signal Reconstruction Models
1
2
Model-based analysis of diffusion MRI signals including diffusion tensor imaging (DTI), diffusion kurtosis imaging (DKI), constrained spherical deconvolution (CSD), and advanced microstructure models. All models follow a consistent Model/Fit interface pattern.
3
4
## Capabilities
5
6
### Diffusion Tensor Imaging (DTI)
7
8
Classical diffusion tensor model for estimating water diffusion properties and deriving standard diffusion metrics.
9
10
```python { .api }
11
class TensorModel:
12
"""Diffusion tensor imaging model."""
13
def __init__(self, gtab, fit_method='WLS', return_S0_hat=False):
14
"""
15
Initialize tensor model.
16
17
Parameters:
18
gtab (GradientTable): gradient table
19
fit_method (str): fitting method ('WLS', 'OLS', 'NLLS')
20
return_S0_hat (bool): return S0 estimates
21
"""
22
23
def fit(self, data, mask=None):
24
"""
25
Fit tensor model to data.
26
27
Parameters:
28
data (array): diffusion data (4D)
29
mask (array): binary mask for fitting
30
31
Returns:
32
TensorFit: fitted tensor results
33
"""
34
35
class TensorFit:
36
"""Fitted diffusion tensor results."""
37
@property
38
def fa(self):
39
"""array: fractional anisotropy (0-1)"""
40
41
@property
42
def adc(self):
43
"""array: apparent diffusion coefficient"""
44
45
@property
46
def md(self):
47
"""array: mean diffusivity"""
48
49
@property
50
def ad(self):
51
"""array: axial diffusivity"""
52
53
@property
54
def rd(self):
55
"""array: radial diffusivity"""
56
57
@property
58
def eigenvals(self):
59
"""array: tensor eigenvalues"""
60
61
@property
62
def eigenvecs(self):
63
"""array: tensor eigenvectors"""
64
65
def predict(self, gtab=None, S0=1):
66
"""
67
Predict signal from fitted tensor.
68
69
Parameters:
70
gtab (GradientTable): gradient table for prediction
71
S0 (float): baseline signal
72
73
Returns:
74
array: predicted diffusion signal
75
"""
76
```
77
78
### Diffusion Kurtosis Imaging (DKI)
79
80
Extended tensor model that captures non-Gaussian diffusion effects through the kurtosis tensor.
81
82
```python { .api }
83
class DiffusionKurtosisModel:
84
"""Diffusion kurtosis imaging model."""
85
def __init__(self, gtab, fit_method='WLS'):
86
"""
87
Initialize DKI model.
88
89
Parameters:
90
gtab (GradientTable): gradient table (requires multiple b-shells)
91
fit_method (str): fitting method
92
"""
93
94
def fit(self, data, mask=None):
95
"""
96
Fit DKI model to data.
97
98
Parameters:
99
data (array): multi-shell diffusion data
100
mask (array): binary mask
101
102
Returns:
103
DiffusionKurtosisFit: kurtosis fit results
104
"""
105
106
class DiffusionKurtosisFit:
107
"""Fitted diffusion kurtosis results."""
108
@property
109
def mk(self):
110
"""array: mean kurtosis"""
111
112
@property
113
def ak(self):
114
"""array: axial kurtosis"""
115
116
@property
117
def rk(self):
118
"""array: radial kurtosis"""
119
120
@property
121
def kfa(self):
122
"""array: kurtosis fractional anisotropy"""
123
```
124
125
### Constrained Spherical Deconvolution (CSD)
126
127
Advanced model for resolving crossing fibers by deconvolving the fiber orientation distribution function.
128
129
```python { .api }
130
class ConstrainedSphericalDeconvModel:
131
"""Constrained spherical deconvolution model."""
132
def __init__(self, gtab, response, sh_order=8):
133
"""
134
Initialize CSD model.
135
136
Parameters:
137
gtab (GradientTable): gradient table
138
response (tuple): response function (eigenvals, S0)
139
sh_order (int): spherical harmonics order
140
"""
141
142
def fit(self, data, mask=None):
143
"""
144
Fit CSD model to data.
145
146
Parameters:
147
data (array): diffusion data
148
mask (array): binary mask
149
150
Returns:
151
CsdFit: CSD fit results
152
"""
153
154
def auto_response_ssst(gtab, data, roi_radii=10, fa_thr=0.7):
155
"""
156
Automatic single-shell, single-tissue response function estimation.
157
158
Parameters:
159
gtab (GradientTable): gradient table
160
data (array): diffusion data
161
roi_radii (int): ROI radius in voxels
162
fa_thr (float): FA threshold for response estimation
163
164
Returns:
165
tuple: (response, ratio, S0) response function parameters
166
"""
167
```
168
169
### MAP-MRI (Mean Apparent Propagator MRI)
170
171
Advanced model using continuous basis functions to represent the diffusion propagator.
172
173
```python { .api }
174
class MapmriModel:
175
"""MAP-MRI reconstruction model."""
176
def __init__(self, gtab, radial_order=6, laplacian_regularization=True):
177
"""
178
Initialize MAP-MRI model.
179
180
Parameters:
181
gtab (GradientTable): gradient table
182
radial_order (int): radial basis order
183
laplacian_regularization (bool): use Laplacian regularization
184
"""
185
186
def fit(self, data, mask=None):
187
"""
188
Fit MAP-MRI model.
189
190
Parameters:
191
data (array): diffusion data
192
mask (array): binary mask
193
194
Returns:
195
MapmriFit: MAP-MRI fit results
196
"""
197
```
198
199
### IVIM (Intravoxel Incoherent Motion)
200
201
Bi-exponential model separating diffusion and perfusion effects in diffusion MRI.
202
203
```python { .api }
204
class IvimModel:
205
"""IVIM signal model."""
206
def __init__(self, gtab, split_b=400, bounds=None):
207
"""
208
Initialize IVIM model.
209
210
Parameters:
211
gtab (GradientTable): gradient table with low b-values
212
split_b (float): b-value threshold for bi-exponential fitting
213
bounds (tuple): parameter bounds for fitting
214
"""
215
216
def fit(self, data, mask=None):
217
"""
218
Fit IVIM model.
219
220
Parameters:
221
data (array): diffusion data with low b-values
222
mask (array): binary mask
223
224
Returns:
225
IvimFit: IVIM fit results
226
"""
227
228
class IvimFit:
229
"""IVIM fit results."""
230
@property
231
def perfusion_fraction(self):
232
"""array: perfusion fraction (f)"""
233
234
@property
235
def D_star(self):
236
"""array: pseudo-diffusion coefficient"""
237
238
@property
239
def D(self):
240
"""array: true diffusion coefficient"""
241
```
242
243
### Multi-Shell Multi-Tissue CSD
244
245
Extension of CSD for multi-shell data with multiple tissue types.
246
247
```python { .api }
248
class MultiShellMultiTissueModel:
249
"""Multi-shell, multi-tissue CSD model."""
250
def __init__(self, gtab, response, sh_order=8):
251
"""
252
Initialize MSMT-CSD model.
253
254
Parameters:
255
gtab (GradientTable): multi-shell gradient table
256
response (list): response functions for each tissue type
257
sh_order (int): spherical harmonics order
258
"""
259
```
260
261
### Usage Examples
262
263
```python
264
# DTI analysis workflow
265
from dipy.reconst.dti import TensorModel
266
from dipy.data import read_stanford_hardi
267
import numpy as np
268
269
# Load data
270
img, gtab = read_stanford_hardi()
271
data = img.get_fdata()
272
273
# Fit tensor model
274
tenmodel = TensorModel(gtab)
275
tenfit = tenmodel.fit(data)
276
277
# Extract metrics
278
fa = tenfit.fa
279
md = tenfit.md
280
eigenvals = tenfit.eigenvals
281
282
print(f"Mean FA: {np.mean(fa[fa > 0]):.3f}")
283
print(f"Mean MD: {np.mean(md[md > 0]):.6f}")
284
285
# CSD for fiber orientation
286
from dipy.reconst.csdeconv import ConstrainedSphericalDeconvModel, auto_response_ssst
287
288
# Estimate response function
289
response, ratio = auto_response_ssst(gtab, data)
290
291
# Fit CSD model
292
csd_model = ConstrainedSphericalDeconvModel(gtab, response)
293
csd_fit = csd_model.fit(data)
294
295
# IVIM analysis
296
from dipy.reconst.ivim import IvimModel
297
298
# For IVIM, need data with low b-values
299
ivim_model = IvimModel(gtab)
300
ivim_fit = ivim_model.fit(data)
301
302
f = ivim_fit.perfusion_fraction
303
D = ivim_fit.D
304
D_star = ivim_fit.D_star
305
```