/
ale.py
215 lines (188 loc) · 9.74 KB
/
ale.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
"""
Workflow for running an ALE meta-analysis from a Sleuth text file.
"""
import os
import logging
import pathlib
from shutil import copyfile
from ..io import convert_sleuth_to_dataset
from ..meta.cbma import ALE, ALESubtraction
from ..correct import FWECorrector
LGR = logging.getLogger(__name__)
def ale_sleuth_workflow(sleuth_file, sleuth_file2=None, output_dir=None,
prefix=None, n_iters=10000, v_thr=0.001,
fwhm=None, n_cores=-1):
"""
Perform ALE meta-analysis from Sleuth text file.
"""
LGR.info('Loading coordinates...')
if fwhm:
fwhm_str = 'of {0} mm'.format(fwhm)
else:
fwhm_str = 'determined by sample size'
if not sleuth_file2:
dset = convert_sleuth_to_dataset(sleuth_file, target='ale_2mm')
n_subs = dset.coordinates.drop_duplicates('id')['n'].astype(float).astype(int).sum()
boilerplate = """
An activation likelihood estimation (ALE; Turkeltaub, Eden, Jones, & Zeffiro,
2002; Eickhoff, Bzdok, Laird, Kurth, & Fox, 2012; Turkeltaub et al., 2012)
meta-analysis was performed using NiMARE. The input dataset included {n_foci}
foci from {n_subs} participants across {n_exps} studies/experiments.
Modeled activation maps were generated for each study/experiment by convolving
each focus with a Gaussian kernel {fwhm_str}.
For voxels with overlapping kernels, the maximum value was retained.
The modeled activation maps were rendered in MNI 152 space (Fonov et al., 2009;
Fonov et al., 2011) at 2x2x2mm resolution. A map of ALE values was then
computed for the sample as the union of modeled activation values across
studies/experiments. Voxelwise statistical significance was determined based on
an analytically derived null distribution using the method described in
Eickhoff, Bzdok, Laird, Kurth, & Fox (2012), prior to multiple comparisons
correction.
-> If the cluster-level FWE-corrected results were used, include the following:
A cluster-forming threshold of p < {unc} was used to perform cluster-level FWE
correction. {n_iters} iterations were performed to estimate a null distribution
of cluster sizes, in which the locations of coordinates were randomly drawn
from a gray matter template and the maximum cluster size was recorded after
applying an uncorrected cluster-forming threshold of p < {unc}. The negative
log-transformed p-value for each cluster in the thresholded map was determined
based on the cluster sizes.
-> If voxel-level FWE-corrected results were used, include the following:
Voxel-level FWE-correction was performed. {n_iters} iterations were performed
to estimate a null distribution of ALE values, in which the locations of
coordinates were randomly drawn from a gray matter template and the maximum
ALE value was recorded.
References
----------
- Eickhoff, S. B., Bzdok, D., Laird, A. R., Kurth, F., & Fox, P. T. (2012).
Activation likelihood estimation meta-analysis revisited. NeuroImage,
59(3), 2349–2361.
- Fonov, V., Evans, A. C., Botteron, K., Almli, C. R., McKinstry, R. C.,
Collins, D. L., & Brain Development Cooperative Group. (2011).
Unbiased average age-appropriate atlases for pediatric studies.
Neuroimage, 54(1), 313-327.
- Fonov, V. S., Evans, A. C., McKinstry, R. C., Almli, C. R., & Collins, D. L.
(2009). Unbiased nonlinear average age-appropriate brain templates from birth
to adulthood. NeuroImage, (47), S102.
- Turkeltaub, P. E., Eden, G. F., Jones, K. M., & Zeffiro, T. A. (2002).
Meta-analysis of the functional neuroanatomy of single-word reading: method
and validation. NeuroImage, 16(3 Pt 1), 765–780.
- Turkeltaub, P. E., Eickhoff, S. B., Laird, A. R., Fox, M., Wiener, M.,
& Fox, P. (2012). Minimizing within-experiment and within-group effects in
Activation Likelihood Estimation meta-analyses. Human Brain Mapping,
33(1), 1–13.
"""
ale = ALE(kernel__fwhm=fwhm)
LGR.info('Performing meta-analysis...')
results = ale.fit(dset)
corr = FWECorrector(method='permutation', n_iters=n_iters,
voxel_thresh=v_thr, n_cores=n_cores)
cres = corr.transform(results)
boilerplate = boilerplate.format(
n_exps=len(dset.ids),
n_subs=n_subs,
n_foci=dset.coordinates.shape[0],
unc=v_thr,
n_iters=n_iters,
fwhm_str=fwhm_str)
else:
dset1 = convert_sleuth_to_dataset(sleuth_file, target='ale_2mm')
dset2 = convert_sleuth_to_dataset(sleuth_file2, target='ale_2mm')
n_subs1 = dset1.coordinates.drop_duplicates('id')['n'].astype(float).astype(int).sum()
n_subs2 = dset2.coordinates.drop_duplicates('id')['n'].astype(float).astype(int).sum()
boilerplate = """
Activation likelihood estimation (ALE; Turkeltaub, Eden, Jones, & Zeffiro,
2002; Eickhoff, Bzdok, Laird, Kurth, & Fox, 2012; Turkeltaub et al., 2012)
meta-analyses were performed using NiMARE for each of two datasets.
The first input dataset included {n_foci1} foci from {n_subs1} participants
across {n_exps1} studies/experiments. The second input dataset included
{n_foci2} foci from {n_subs2} participants across {n_exps2} studies/experiments.
Foci were convolved with Gaussian kernels {fwhm_str},
implemented on the MNI 152 template (Fonov et al., 2009; Fonov et al., 2011)
at 2x2x2mm resolution.
-> If the cluster-level FWE-corrected results were used, include the following:
A cluster-forming threshold of p < {unc} was used to perform cluster-level FWE
correction. {n_iters} iterations were performed to estimate a null distribution
of cluster sizes, in which the locations of coordinates were randomly drawn
from a gray matter template and the maximum cluster size was recorded after
applying an uncorrected cluster-forming threshold of p < {unc}. The negative
log-transformed p-value for each cluster in the thresholded map was determined
based on the cluster sizes.
-> If voxel-level FWE-corrected results were used, include the following:
Voxel-level FWE-correction was performed. {n_iters} iterations were performed
to estimate a null distribution of ALE values, in which the locations of
coordinates were randomly drawn from a gray matter template and the maximum
ALE value was recorded.
Following dataset-specific ALE meta-analyses, a subtraction analysis was
performed to compare the two datasets according to the procedure from Laird
et al. (2005). {n_iters} iterations were performed.
References
----------
- Turkeltaub, P. E., Eden, G. F., Jones, K. M., & Zeffiro, T. A. (2002).
Meta-analysis of the functional neuroanatomy of single-word reading: method
and validation. NeuroImage, 16(3 Pt 1), 765–780.
- Eickhoff, S. B., Bzdok, D., Laird, A. R., Kurth, F., & Fox, P. T. (2012).
Activation likelihood estimation meta-analysis revisited. NeuroImage,
59(3), 2349–2361.
- Turkeltaub, P. E., Eickhoff, S. B., Laird, A. R., Fox, M., Wiener, M.,
& Fox, P. (2012). Minimizing within-experiment and within-group effects in
Activation Likelihood Estimation meta-analyses. Human Brain Mapping,
33(1), 1–13.
- Fonov, V., Evans, A. C., Botteron, K., Almli, C. R., McKinstry, R. C.,
Collins, D. L., & Brain Development Cooperative Group. (2011).
Unbiased average age-appropriate atlases for pediatric studies.
Neuroimage, 54(1), 313-327.
- Fonov, V. S., Evans, A. C., McKinstry, R. C., Almli, C. R., & Collins, D. L.
(2009). Unbiased nonlinear average age-appropriate brain templates from birth
to adulthood. NeuroImage, (47), S102.
- Laird, A. R., Fox, P. M., Price, C. J., Glahn, D. C., Uecker, A. M.,
Lancaster, J. L., ... & Fox, P. T. (2005). ALE meta‐analysis: Controlling the
false discovery rate and performing statistical contrasts. Human brain mapping,
25(1), 155-164.
"""
ale1 = ALE(kernel__fwhm=fwhm)
ale2 = ALE(kernel__fwhm=fwhm)
LGR.info('Performing meta-analysis...')
res1 = ale1.fit(dset1)
res2 = ale2.fit(dset2)
corr = FWECorrector(method='permutation', n_iters=n_iters,
voxel_thresh=v_thr, n_cores=n_cores)
cres1 = corr.transform(res1)
cres2 = corr.transform(res2)
sub = ALESubtraction(n_iters=n_iters)
sres = sub.fit(
ale1, ale2,
image1=cres1.get_map('logp_level-cluster_corr-FWE_method-permutation', return_type='image'),
image2=cres2.get_map('logp_level-cluster_corr-FWE_method-permutation', return_type='image'))
boilerplate = boilerplate.format(
n_exps1=len(dset1.ids),
n_subs1=n_subs1,
n_foci1=dset1.coordinates.shape[0],
n_exps2=len(dset2.ids),
n_subs2=n_subs2,
n_foci2=dset2.coordinates.shape[0],
unc=v_thr,
n_iters=n_iters,
fwhm_str=fwhm_str)
if output_dir is None:
output_dir = os.path.abspath(os.path.dirname(sleuth_file))
else:
pathlib.Path(output_dir).mkdir(parents=True, exist_ok=True)
if prefix is None:
base = os.path.basename(sleuth_file)
prefix, _ = os.path.splitext(base)
prefix += '_'
LGR.info('Saving output maps...')
if not sleuth_file2:
cres.save_maps(output_dir=output_dir, prefix=prefix)
copyfile(sleuth_file, os.path.join(output_dir, prefix + 'input_coordinates.txt'))
else:
prefix1 = os.path.splitext(os.path.basename(sleuth_file))[0] + '_'
prefix2 = os.path.splitext(os.path.basename(sleuth_file2))[0] + '_'
prefix3 = prefix + 'subtraction_'
cres1.save_maps(output_dir=output_dir, prefix=prefix1)
cres2.save_maps(output_dir=output_dir, prefix=prefix2)
sres.save_maps(output_dir=output_dir, prefix=prefix3)
copyfile(sleuth_file, os.path.join(output_dir, prefix + 'group1_input_coordinates.txt'))
copyfile(sleuth_file2, os.path.join(output_dir, prefix + 'group2_input_coordinates.txt'))
LGR.info('Workflow completed.')
LGR.info(boilerplate)