0
# Statistics and Tractometry
1

2
Statistical analysis tools for diffusion metrics, tractometry analysis, and group-level comparisons of white matter properties. DIPY provides comprehensive methods for analyzing tract-specific measurements and performing statistical comparisons.
3

4
## Capabilities
5

6
### AFQ-style Tractometry
7

8
Automated Fiber Quantification (AFQ) approach for tract-based analysis along streamline bundles.
9

10
```python { .api }
11
def afq_profile(data, bundle, affine=None, n_points=100, weights=None):
12
    """
13
    Calculate AFQ-style tract profile along bundle.
14
    
15
    Parameters:
16
        data (array): 3D scalar data (e.g., FA, MD)
17
        bundle (list): streamlines defining the tract
18
        affine (array): voxel-to-world transformation matrix
19
        n_points (int): number of points for profile sampling
20
        weights (array): weights for each streamline
21
        
22
    Returns:
23
        array: tract profile values along bundle
24
    """
25

26
def gaussian_weights(bundle, n_points=100, return_mahalnobis=False, sphere=None):
27
    """
28
    Calculate Gaussian weights for streamlines based on trajectory.
29
    
30
    Parameters:
31
        bundle (list): streamlines in bundle
32
        n_points (int): number of sampling points
33
        return_mahalnobis (bool): return Mahalanobis distances
34
        sphere (Sphere): sphere for directional weighting
35
        
36
    Returns:
37
        array: Gaussian weights for each streamline
38
    """
39

40
def values_from_volume(data, streamlines, affine=None, order=1):
41
    """
42
    Extract values from volume along streamlines.
43
    
44
    Parameters:
45
        data (array): 3D volume data
46
        streamlines (list): streamline coordinates
47
        affine (array): transformation matrix
48
        order (int): interpolation order (0=nearest, 1=linear)
49
        
50
    Returns:
51
        list: values along each streamline
52
    """
53
```
54

55
### Tract Profile Analysis
56

57
Tools for analyzing tract profiles and performing statistical comparisons across subjects or groups.
58

59
```python { .api }
60
class TractProfile:
61
    """Container for tract profile data and analysis."""
62
    def __init__(self, data, bundle, affine=None, n_points=100):
63
        """
64
        Initialize tract profile analysis.
65
        
66
        Parameters:
67
            data (array): scalar diffusion data
68
            bundle (list): tract streamlines
69
            affine (array): coordinate transformation
70
            n_points (int): profile sampling points
71
        """
72
    
73
    def get_profile(self, weights=None):
74
        """
75
        Calculate tract profile.
76
        
77
        Parameters:
78
            weights (array): streamline weights
79
            
80
        Returns:
81
            array: profile values along tract
82
        """
83
    
84
    def bootstrap_profile(self, n_bootstrap=1000):
85
        """
86
        Generate bootstrap confidence intervals for profile.
87
        
88
        Parameters:
89
            n_bootstrap (int): number of bootstrap samples
90
            
91
        Returns:
92
            tuple: (mean_profile, confidence_intervals)
93
        """
94

95
def mean_profile(profiles):
96
    """
97
    Calculate mean profile across subjects.
98
    
99
    Parameters:
100
        profiles (list): list of individual tract profiles
101
        
102
    Returns:
103
        array: mean profile values
104
    """
105

106
def profile_variance(profiles):
107
    """
108
    Calculate variance of profiles across subjects.
109
    
110
    Parameters:
111
        profiles (list): individual profiles
112
        
113
    Returns:
114
        array: variance along tract
115
    """
116
```
117

118
### Bundle Statistics
119

120
Statistical measures for analyzing bundle properties and tract characteristics.
121

122
```python { .api }
123
def bundle_analysis(bundle, affine=None):
124
    """
125
    Comprehensive bundle analysis including geometric properties.
126
    
127
    Parameters:
128
        bundle (list): streamlines in bundle
129
        affine (array): coordinate transformation
130
        
131
    Returns:
132
        dict: bundle statistics (length, volume, density, etc.)
133
    """
134

135
def principal_components_analysis(streamlines):
136
    """
137
    Perform PCA on streamline bundle.
138
    
139
    Parameters:
140
        streamlines (list): bundle streamlines
141
        
142
    Returns:
143
        tuple: (eigenvalues, eigenvectors, mean_streamline)
144
    """
145

146
def streamline_variance(streamlines):
147
    """
148
    Calculate variance within streamline bundle.
149
    
150
    Parameters:
151
        streamlines (list): bundle streamlines
152
        
153
    Returns:
154
        array: variance along streamline length
155
    """
156

157
def bundle_coherence(bundle, metric='angular'):
158
    """
159
    Measure bundle coherence using directional consistency.
160
    
161
    Parameters:
162
        bundle (list): streamlines
163
        metric (str): coherence metric ('angular', 'spatial')
164
        
165
    Returns:
166
        float: coherence measure (0-1)
167
    """
168
```
169

170
### Cross-Subject Analysis
171

172
Tools for group-level statistical analysis and comparison of tract properties.
173

174
```python { .api }
175
class GroupAnalysis:
176
    """Group-level tract analysis."""
177
    def __init__(self, profiles_list, group_labels=None):
178
        """
179
        Initialize group analysis.
180
        
181
        Parameters:
182
            profiles_list (list): list of profiles for each subject
183
            group_labels (array): group membership labels
184
        """
185
    
186
    def ttest(self, group1_indices, group2_indices):
187
        """
188
        Perform t-test between two groups.
189
        
190
        Parameters:
191
            group1_indices (array): indices for group 1
192
            group2_indices (array): indices for group 2
193
            
194
        Returns:
195
            tuple: (t_statistics, p_values)
196
        """
197
    
198
    def anova(self):
199
        """
200
        Perform ANOVA across groups.
201
        
202
        Returns:
203
            tuple: (F_statistics, p_values)
204
        """
205

206
def permutation_test(group1_profiles, group2_profiles, n_permutations=10000, metric='mean_diff'):
207
    """
208
    Non-parametric permutation test for group differences.
209
    
210
    Parameters:
211
        group1_profiles (list): profiles for group 1
212
        group2_profiles (list): profiles for group 2
213
        n_permutations (int): number of permutations
214
        metric (str): test statistic metric
215
        
216
    Returns:
217
        tuple: (observed_statistic, p_value, null_distribution)
218
    """
219

220
def effect_size(group1_profiles, group2_profiles, metric='cohens_d'):
221
    """
222
    Calculate effect size between groups.
223
    
224
    Parameters:
225
        group1_profiles (list): group 1 data
226
        group2_profiles (list): group 2 data
227
        metric (str): effect size metric
228
        
229
    Returns:
230
        array: effect sizes along tract
231
    """
232
```
233

234
### Correlation Analysis
235

236
Tools for analyzing relationships between tract properties and behavioral measures.
237

238
```python { .api }
239
def tract_behavior_correlation(tract_profiles, behavior_scores, method='pearson'):
240
    """
241
    Correlate tract profiles with behavioral measures.
242
    
243
    Parameters:
244
        tract_profiles (array): tract profile data (subjects x points)
245
        behavior_scores (array): behavioral scores for each subject
246
        method (str): correlation method ('pearson', 'spearman')
247
        
248
    Returns:
249
        tuple: (correlation_coefficients, p_values)
250
    """
251

252
def partial_correlation(tract_profiles, behavior_scores, covariates):
253
    """
254
    Partial correlation controlling for covariates.
255
    
256
    Parameters:
257
        tract_profiles (array): tract data
258
        behavior_scores (array): behavioral measures
259
        covariates (array): covariate data
260
        
261
    Returns:
262
        tuple: (partial_correlations, p_values)
263
    """
264

265
class LinearModel:
266
    """General linear model for tract analysis."""
267
    def __init__(self, design_matrix):
268
        """
269
        Initialize GLM with design matrix.
270
        
271
        Parameters:
272
            design_matrix (array): design matrix (subjects x predictors)
273
        """
274
    
275
    def fit(self, tract_data):
276
        """
277
        Fit model to tract data.
278
        
279
        Parameters:
280
            tract_data (array): tract profiles (subjects x points)
281
            
282
        Returns:
283
            dict: fit results with coefficients and statistics
284
        """
285
```
286

287
### Reliability and Reproducibility
288

289
Tools for assessing measurement reliability and reproducibility across sessions.
290

291
```python { .api }
292
def test_retest_reliability(profiles_session1, profiles_session2, metric='icc'):
293
    """
294
    Calculate test-retest reliability.
295
    
296
    Parameters:
297
        profiles_session1 (list): profiles from session 1
298
        profiles_session2 (list): profiles from session 2
299
        metric (str): reliability metric ('icc', 'pearson')
300
        
301
    Returns:
302
        array: reliability coefficients along tract
303
    """
304

305
def measurement_error(repeated_profiles):
306
    """
307
    Estimate measurement error from repeated measurements.
308
    
309
    Parameters:
310
        repeated_profiles (list): list of repeated profile measurements
311
        
312
    Returns:
313
        tuple: (measurement_error, confidence_intervals)
314
    """
315

316
def bland_altman_analysis(method1_profiles, method2_profiles):
317
    """
318
    Bland-Altman analysis comparing two measurement methods.
319
    
320
    Parameters:
321
        method1_profiles (array): profiles from method 1
322
        method2_profiles (array): profiles from method 2
323
        
324
    Returns:
325
        dict: bias, limits of agreement, and statistics
326
    """
327
```
328

329
### Usage Examples
330

331
```python
332
# AFQ-style tractometry analysis
333
from dipy.stats.analysis import afq_profile, gaussian_weights
334
from dipy.data import read_stanford_hardi, read_bundles_2_subjects
335
from dipy.reconst.dti import TensorModel
336
import numpy as np
337

338
# Load data
339
img, gtab = read_stanford_hardi()
340
data = img.get_fdata()
341

342
# Compute FA
343
tensor_model = TensorModel(gtab)
344
tensor_fit = tensor_model.fit(data)
345
fa = tensor_fit.fa
346

347
# Load bundle
348
bundle1, bundle2 = read_bundles_2_subjects()
349

350
# Calculate tract profile
351
profile = afq_profile(fa, bundle1, affine=img.affine, n_points=100)
352
print(f"Tract profile shape: {profile.shape}")
353
print(f"Mean FA along tract: {profile.mean():.3f}")
354

355
# Calculate Gaussian weights for bundle core
356
weights = gaussian_weights(bundle1, n_points=100)
357
weighted_profile = afq_profile(fa, bundle1, affine=img.affine, weights=weights)
358

359
# Group analysis example
360
from dipy.stats.analysis import GroupAnalysis, permutation_test
361

362
# Simulate group data
363
n_subjects_group1 = 20
364
n_subjects_group2 = 18
365
group1_profiles = [profile + np.random.normal(0, 0.01, len(profile)) 
366
                   for _ in range(n_subjects_group1)]
367
group2_profiles = [profile + np.random.normal(0.02, 0.01, len(profile)) 
368
                   for _ in range(n_subjects_group2)]
369

370
# Perform permutation test
371
observed_stat, p_value, null_dist = permutation_test(
372
    group1_profiles, group2_profiles, n_permutations=5000
373
)
374
print(f"Group difference p-value: {p_value:.4f}")
375

376
# Correlation with behavior
377
behavior_scores = np.random.normal(100, 15, n_subjects_group1 + n_subjects_group2)
378
all_profiles = np.array(group1_profiles + group2_profiles)
379

380
from dipy.stats.analysis import tract_behavior_correlation
381
correlations, p_vals = tract_behavior_correlation(all_profiles, behavior_scores)
382

383
# Find significant correlations (FDR corrected)
384
from statsmodels.stats.multitest import fdrcorrection
385
significant_mask, p_corrected = fdrcorrection(p_vals, alpha=0.05)
386
print(f"Significant correlations: {significant_mask.sum()} points out of {len(p_vals)}")
387

388
# Test-retest reliability
389
session2_profiles = [prof + np.random.normal(0, 0.005, len(prof)) 
390
                     for prof in group1_profiles[:10]]
391

392
from dipy.stats.analysis import test_retest_reliability
393
reliability = test_retest_reliability(group1_profiles[:10], session2_profiles)
394
print(f"Mean test-retest reliability: {reliability.mean():.3f}")
395

396
# Bundle statistics
397
from dipy.stats.analysis import bundle_analysis, bundle_coherence
398

399
bundle_stats = bundle_analysis(bundle1)
400
coherence = bundle_coherence(bundle1, metric='angular')
401
print(f"Bundle coherence: {coherence:.3f}")
402
print(f"Bundle statistics: {bundle_stats}")
403
```