FitLins Example Models¶
This is a collection of example models, written for OpenNeuro (formerly OpenFMRI) datasets.
Statistical models, described in the draft BIDS Stats-Models specification, fit into the BIDS data structure with the following naming convention:
<bids_root>/models/model-<label>_[desc-<description>]_smdl.json
FitLins accepts models that are present in a BIDS directory or are passed with the
-m/--model flag.
These models may be browsed in the examples directory on GitHub.
Word vs Pseudoword Contrast¶
Dataset: https://openneuro.org/datasets/ds000003/versions/00001
This model is translated from model001 in the original OpenFMRI dataset.
It demonstrates using the Factor transform to turn the trial_type
column into a column for each trial type (i.e., the trial_type.word
column has 1 where trial_type was word, 0 elsewhere, and so
on), as well as convolution.
The Model.X section demonstrates selection of regressors for the design
matrix, and Contrasts shows how to perform a simple contrast between
two conditions.
At the dataset level, the DummyContrasts option demonstrates taking
a simple mean at the group level.
ds000003/models/model-001_smdl.json
1{
2 "Name":"ds003_model001",
3 "BIDSModelVersion":"1.0.0",
4 "Description":"",
5 "Input":{
6 "task":"rhymejudgment"
7 },
8 "Nodes":[
9 {
10 "Level":"run",
11 "Name":"subject",
12 "GroupBy":[
13 "subject"
14 ],
15 "Transformations":{
16 "Transformer":"pybids-transforms-v1",
17 "Instructions":[
18 {
19 "Name":"Factor",
20 "Input":[
21 "trial_type"
22 ]
23 },
24 {
25 "Name":"Convolve",
26 "Input":[
27 "trial_type.word",
28 "trial_type.pseudoword"
29 ],
30 "Model":"spm"
31 }
32 ]
33 },
34 "Model":{
35 "X":[
36 "trial_type.word",
37 "trial_type.pseudoword",
38 "framewise_displacement",
39 "trans_x",
40 "trans_y",
41 "trans_z",
42 "rot_x",
43 "rot_y",
44 "rot_z",
45 "a_comp_cor_00",
46 "a_comp_cor_01",
47 "a_comp_cor_02",
48 "a_comp_cor_03",
49 "a_comp_cor_04",
50 "a_comp_cor_05",
51 1
52 ]
53 },
54 "DummyContrasts":{
55 "Conditions":[
56 "trial_type.word",
57 "trial_type.pseudoword"
58 ],
59 "Test":"t"
60 },
61 "Contrasts":[
62 {
63 "Name":"word_gt_pseudo",
64 "ConditionList":[
65 "trial_type.word",
66 "trial_type.pseudoword"
67 ],
68 "Weights":[
69 1,
70 -1
71 ],
72 "Test":"t"
73 },
74 {
75 "Name":"task_vs_baseline",
76 "ConditionList":[
77 "trial_type.word",
78 "trial_type.pseudoword"
79 ],
80 "Weights":[
81 0.5,
82 0.5
83 ],
84 "Test":"t"
85 }
86 ]
87 },
88 {
89 "Level":"dataset",
90 "Name":"t-test",
91 "GroupBy":["contrast"],
92 "Model":{
93 "X":[
94 1
95 ],
96 "Type":"glm"
97 },
98 "DummyContrasts":{
99 "Test":"t"
100 }
101 },
102 {
103 "Level":"dataset",
104 "Name":"F-test",
105 "GroupBy": [],
106 "Model":{
107 "X":[
108 "trial_type.word",
109 "trial_type.pseudoword"
110 ],
111 "Type":"glm"
112 },
113 "Contrasts":[
114 {
115 "Name":"any_words",
116 "ConditionList":[
117 "trial_type.word",
118 "trial_type.pseudoword"
119 ],
120 "Weights":[
121 [
122 1,
123 0
124 ],
125 [
126 0,
127 1
128 ]
129 ],
130 "Test":"F"
131 }
132 ]
133 }
134 ],
135 "Edges":[
136 {
137 "Source":"subject",
138 "Destination":"t-test",
139 "Filter":{
140 "contrast":[
141 "task_vs_baseline",
142 "word_gt_pseudo"
143 ]
144 }
145 },
146 {
147 "Source":"subject",
148 "Destination":"F-test",
149 "Filter":{
150 "contrast":[
151 "trial_type.word",
152 "trial_type.pseudoword"
153 ]
154 }
155 }
156 ]
157}
Balloon Analog Risk Task¶
Dataset: https://openneuro.org/datasets/ds000030/versions/00016
The balloon analog risk task (BART) is a risk-taking game where participants
decide whether to inflate a balloon, risking explosion, or cash out.
There are two trial types (BALOON [sic] and CONTROL), and three
possible actions (ACCEPT, CASHOUT, EXPLODE).
In this model, we contrast responses to ACCEPT and EXPLODE actions
in BALOON trials only.
This model is similar to the word-pseudoword model above, but also demonstrates
the use of the And transformation, that takes the logical and of two binary
(0/1) columns and assigns a new name to the result.
ds000030/models/model-001_smdl.json
1{
2 "Name": "ds000030_bart",
3 "Description": "model for balloon analog risk task",
4 "Input": {
5 "task": "bart"
6 },
7 "Steps": [
8 {
9 "Level": "run",
10 "Transformations": [
11 {
12 "Name": "Factor",
13 "Input": [
14 "trial_type",
15 "action"
16 ]
17 },
18 {
19 "Name": "And",
20 "Input": [
21 "trial_type.BALOON",
22 "action.ACCEPT"
23 ],
24 "Output": [
25 "accept"
26 ]
27 },
28 {
29 "Name": "And",
30 "Input": [
31 "trial_type.BALOON",
32 "action.EXPLODE"
33 ],
34 "Output": [
35 "explode"
36 ]
37 },
38 {
39 "Name": "Convolve",
40 "Input": ["accept", "explode"],
41 "Model": "spm"
42 }
43 ],
44 "Model": {
45 "X": [
46 "accept", "explode",
47 "framewise_displacement",
48 "trans_x", "trans_y", "trans_z", "rot_x", "rot_y", "rot_z"
49 ]
50 },
51 "Contrasts": [
52 {
53 "Name": "accept_vs_explode",
54 "ConditionList": [
55 "accept",
56 "explode"
57 ],
58 "weights": [1, -1],
59 "type": "T"
60 }
61 ]
62 },
63 {
64 "Level": "dataset",
65 "DummyContrasts": {
66 "Conditions": ["accept_vs_explode"],
67 "Type": "t"
68 }
69 }
70 ]
71}
DS000114 Model¶
Dataset: doi:10.18112/openneuro.ds000114.v1.0.1
This model was written to demonstrate a model that specifies all levels of analysis.
The finger_foot_lips task is a block-design motor task with interleaved
blocks of finger-tapping, foot-twitching and lip-pursing.
The Factor and Convolve transforms will be familiar from the above
models.
The contrast, however, shows a three-way contrast, testing for greater response
to finger than foot or lip actions.
Note that the negative values sum to -1 and the positive to 1.
At the session level, no contrast is performed; rather the finger_vs_other
contrasts are split across sessions, to avoid grouping them at the subject level.
The contrast at the subject level is a simple test - retest contrast, and
finally the dataset level again takes a simple mean across subjects.
Note
This model can be run by FitLins, but it has a second-level contrast that
Nistats cannot currently handle, so all group level stats will be NaN.
ds000114/models/model-001_smdl.json
1{
2 "Name": "ds114_model1",
3 "Description": "sample model for ds114",
4 "Input": {
5 "task": "fingerfootlips"
6 },
7 "Steps": [
8 {
9 "Level": "run",
10 "Transformations": [
11 {
12 "Name": "Factor",
13 "Input": ["trial_type"]
14 },
15 {
16 "Name": "Convolve",
17 "Input": [
18 "trial_type.Finger",
19 "trial_type.Foot",
20 "trial_type.Lips"
21 ]
22 }
23 ],
24 "Model": {
25 "X": [
26 "trial_type.Finger",
27 "trial_type.Foot",
28 "trial_type.Lips",
29 "framewise_displacement",
30 "trans_x", "trans_y", "trans_z", "rot_x", "rot_y", "rot_z",
31 "a_comp_cor_00", "a_comp_cor_01", "a_comp_cor_02",
32 "a_comp_cor_03", "a_comp_cor_04", "a_comp_cor_05"
33 ]
34 },
35 "Contrasts": [
36 {
37 "Name": "finger_vs_others",
38 "ConditionList": [
39 "trial_type.Finger",
40 "trial_type.Foot",
41 "trial_type.Lips"
42 ],
43 "Weights": [
44 1,
45 -0.5,
46 -0.5
47 ],
48 "Type": "t"
49 }
50 ]
51 },
52 {
53 "Level": "session",
54 "Transformations": [
55 {
56 "Name": "split",
57 "Input": ["finger_vs_others"],
58 "By": "session"
59 }
60 ]
61 },
62 {
63 "Level": "subject",
64 "Model": {
65 "X": [
66 "finger_vs_others.test",
67 "finger_vs_others.retest"
68 ]
69 },
70 "Contrasts": [
71 {
72 "Name": "session_diff",
73 "ConditionList": [
74 "finger_vs_others.test",
75 "finger_vs_others.retest"
76 ],
77 "Weights": [1, -1],
78 "Type": "t"
79 }
80 ]
81 },
82 {
83 "Level": "dataset",
84 "DummyContrasts": {
85 "Conditions": ["session_diff"],
86 "Type": "t"
87 }
88 }
89 ]
90}
DS000117 Model¶
Dataset: doi:10.18112/openneuro.ds000117.v1.0.3
This model is translated from model001 in the original OpenFMRI dataset.
This model is another basic contrast, mostly interesting because there are several runs per subject to be averaged over before taking the group average.
FitLins does not currently support fixed effects models, but this will be updated as we decide how to indicate that an analysis level should be a fixed or random effects combination.
It also demonstrates the use of the logical Or transformation.
ds000117/models/model-001_smdl.json
1{
2 "Name": "Basic",
3 "Description": "",
4 "Input": {
5 "task": "facerecognition"
6 },
7 "Steps": [
8 {
9 "Level": "run",
10 "Transformations": [
11 {
12 "Name": "Factor",
13 "Input": ["stim_type"]
14 },
15 {
16 "Name": "Or",
17 "Input": [
18 "stim_type.FAMOUS",
19 "stim_type.UNFAMILIAR"
20 ],
21 "output": [
22 "stim_type.REAL"
23 ]
24 },
25 {
26 "Name": "Convolve",
27 "Input": [
28 "stim_type.REAL",
29 "stim_type.SCRAMBLED"
30 ]
31 }
32 ],
33 "Model": {
34 "X": [
35 "stim_type.SCRAMBLED",
36 "stim_type.REAL",
37 "trans_x", "trans_y", "trans_z", "rot_x", "rot_y", "rot_z"
38 ]
39 },
40 "Contrasts": [
41 {
42 "Name": "face_vs_scram",
43 "ConditionList": [
44 "stim_type.REAL",
45 "stim_type.SCRAMBLED"
46 ],
47 "weights": [1, -1],
48 "type": "t"
49 }
50 ]
51 },
52 {
53 "Level": "subject",
54 "DummyContrasts": {
55 "Conditions": ["face_vs_scram"],
56 "Type": "FEMA"
57 }
58 },
59 {
60 "Level": "dataset",
61 "DummyContrasts": {
62 "Conditions": ["face_vs_scram"],
63 "Type": "t"
64 }
65 }
66 ]
67}