Skip to content

Commit 549a882

Browse files
MontrealSergiyMontrealSergiy
committed
document custom boutiques properties
1 parent 2bdb000 commit 549a882

File tree

2 files changed

+366
-0
lines changed

2 files changed

+366
-0
lines changed

‎BrainPortal/public/doc/boutiques_custom_properties/cbrain_properties.html‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<title>TABLE OF CBRAIN SPECIFIC BOUTIQUES CUSTOM PROPERTIES</title>
5+
<meta charset="UTF-8">
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
7+
<style>
8+
table {
9+
border-collapse: collapse;
10+
width: 100%;
11+
}
12+
13+
th, td {
14+
border: 1px solid #dddddd;
15+
text-align: left;
16+
padding: 8px;
17+
}
18+
19+
pre {
20+
margin: 0;
21+
}
22+
</style>
23+
</head>
24+
<body>
25+
26+
The standard Boutiques properties set does not cover all the need for CBRAIN
27+
thus we introduce a number of custom properties, which can be added to the
28+
"custom" section of a Boutiques descriptor, to fine-tune the way CBRAIN
29+
interpret the descriptor. For example,
30+
31+
<pre>
32+
"custom":{
33+
"cbrain:readonly-input-files":true,
34+
"cbrain:author":"Erik Lee <leex6144@umn.edu>",
35+
"cbrain:allow_empty_strings":[
36+
"derivatives_prefix"
37+
],
38+
"cbrain:no-run-id-for-outputs":[
39+
"OutputDirectory"
40+
],
41+
"cbrain:integrator_modules":{
42+
"BoutiquesFileTypeVerifier":{
43+
"SubjectDirectory":[
44+
"BidsSubject"
45+
]
46+
},
47+
"BoutiquesFileNameMatcher":{
48+
"SubjectDirectory":"^sub-[a-zA-Z0-9_]+$"
49+
},
50+
"BoutiquesOutputFileTypeSetter":{
51+
"OutputDirectory":"MADEOutput"
52+
},
53+
"BoutiquesForcedOutputBrowsePath":{
54+
"OutputDirectory":"[DERIVATIVES_PREFIX]made"
55+
},
56+
"BoutiquesBidsSingleSubjectMaker":"SubjectDirectory",
57+
"BoutiquesBidsSubjectFileSelector":{
58+
"SubjectDirectory":"all_to_keep"
59+
}
60+
}
61+
}
62+
</pre>
63+
64+
65+
<table>
66+
<tr>
67+
<th>JSON Fragment</th>
68+
<th>Description</th>
69+
</tr>
70+
71+
<tr>
72+
<td>
73+
<pre>
74+
"cbrain:author":
75+
"Full Name &lt;email@address&gt;"
76+
</pre>
77+
</td>
78+
<td>
79+
Author(s) of boutiques descriptor
80+
</td>
81+
</tr>
82+
83+
<tr>
84+
<td>
85+
<pre>
86+
"cbrain:can-submit-new-tasks":
87+
true
88+
</pre>
89+
</td>
90+
<td>
91+
Allows forking sub-task(s). To submit a subtask, a task must create a ".new-task-*.json" JSON file at the root of its work directory
92+
</td>
93+
</tr>
94+
95+
<tr>
96+
<td>
97+
<pre>
98+
"cbrain:ignore_outputs":
99+
[
100+
output_id_1,
101+
output_id_2,
102+
output_id_3,
103+
...
104+
]
105+
</pre>
106+
</td>
107+
<td>
108+
The listed outputs will not be saved.
109+
</td>
110+
</tr>
111+
112+
<tr>
113+
<td>
114+
<pre>
115+
"cbrain:save_back_inputs":
116+
[
117+
id_1,
118+
id_2,
119+
id_3,
120+
...
121+
]
122+
</pre>
123+
</td>
124+
<td>
125+
Saves back listed inputs to the dataprovider (mutates the original inputs)
126+
</td>
127+
</tr>
128+
129+
<tr>
130+
<td>
131+
<pre>
132+
"cbrain:readonly-input-files":
133+
true
134+
</pre>
135+
</td>
136+
<td>
137+
Indicates that the tool cannot modify inputs
138+
</td>
139+
</tr>
140+
141+
<tr>
142+
<td>
143+
<pre>
144+
"cbrain:alters-input-files":
145+
true
146+
</pre>
147+
</td>
148+
<td>
149+
Indicates that this task may alter its input files
150+
</td>
151+
</tr>
152+
153+
<tr>
154+
<td>
155+
<pre>
156+
"cbrain:no-run-id-for-outputs":
157+
[
158+
id_1,
159+
id_2,
160+
id_3,
161+
...
162+
]
163+
</pre>
164+
</td>
165+
<td>
166+
Lists output IDs where no run id is inserted. Prevents the usual practice of adding a run id to output file names. Only allowed for MultiLevel data-providers with "browse path" capability. With this option, new results can overwrite old files.
167+
</td>
168+
</tr>
169+
170+
<tr>
171+
<td>
172+
<pre>
173+
"cbrain:allow_empty_strings":
174+
[input_id]
175+
</pre>
176+
</td>
177+
<td>
178+
Allow an empty string as a valid input
179+
</td>
180+
</tr>
181+
182+
<tr>
183+
<td>
184+
<pre>
185+
"cbrain:boutiques_bosh_exec_mode":
186+
"launch"
187+
</pre>
188+
</td>
189+
<td>
190+
Experimental. The default implied value is 'simulate'. In the mode 'simulate', at the moment of creating the tool's script in `cluster_commands()`, the output of 'bosh exec simulate' will be substituted in the script to generate the tool's command. In the mode 'launch', an actual 'bosh exec launch' command will be put in the script instead.
191+
</td>
192+
</tr>
193+
194+
<tr>
195+
<td>
196+
<pre>
197+
"cbrain:inherits-from-class":
198+
"MyClassName"
199+
</pre>
200+
</td>
201+
<td>
202+
An advanced feature for seasoned CBRAIN experts only. That allows overwriting the standard task behavior with a custom class.
203+
</td>
204+
</tr>
205+
206+
<tr>
207+
<td>
208+
<pre>
209+
"cbrain:integrator_modules":
210+
{
211+
"BoutiquesModuleOne":
212+
{ module-specific-parameters },
213+
"BoutiquesModuleTwo":
214+
{ module-specific-parameters }
215+
}
216+
</pre>
217+
</td>
218+
<td>
219+
Loads a module to modify the CBRAIN behavior. Does not work with legacy integration method. All the modules are defined in the lib folder of CBRAIN codebase or a plugin. Thus documentation for all the module-based sub-properties can be auto-generated with the `rdoc` utility.
220+
</td>
221+
</tr>
222+
223+
<tr>
224+
<td>
225+
<pre>
226+
"cbrain:ignore-exit-status":
227+
true
228+
</pre>
229+
</td>
230+
<td>
231+
Deprecated. Considers the task successful even if the wrong exit status is present. For the case where the tool has wrong exit codes (deprecated, being superseded by a module-based property).
232+
</td>
233+
</tr>
234+
235+
<tr>
236+
<td>
237+
<pre>
238+
"cbrain:walltime-estimate":
239+
value_in_seconds
240+
</pre>
241+
</td>
242+
<td>
243+
Deprecated since walltime was added to Boutiques resources sections.
244+
</td>
245+
</tr>
246+
247+
</table>
248+
249+
</body>
250+
</html>

‎BrainPortal/public/doc/boutiques_custom_properties/cbrain_properties.txt‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
TABLE OF CBRAIN SPECIFIC BOUTIQUES CUSTOM PROPERTIES
2+
3+
The standard Boutiques properties set does not cover all the need for CBRAIN
4+
thus we introduce a number of custom properties, which can be added to the
5+
"custom" section of a Boutiques descriptor, to fine-tune the way CBRAIN
6+
interpret the descriptor. For example,
7+
8+
9+
"custom":{
10+
"cbrain:readonly-input-files":true,
11+
"cbrain:author":"Erik Lee <[email protected]>",
12+
"cbrain:allow_empty_strings":[
13+
"derivatives_prefix"
14+
],
15+
"cbrain:no-run-id-for-outputs":[
16+
"OutputDirectory"
17+
],
18+
"cbrain:integrator_modules":{
19+
"BoutiquesFileTypeVerifier":{
20+
"SubjectDirectory":[
21+
"BidsSubject"
22+
]
23+
},
24+
"BoutiquesFileNameMatcher":{
25+
"SubjectDirectory":"^sub-[a-zA-Z0-9_]+$"
26+
},
27+
"BoutiquesOutputFileTypeSetter":{
28+
"OutputDirectory":"MADEOutput"
29+
},
30+
"BoutiquesForcedOutputBrowsePath":{
31+
"OutputDirectory":"[DERIVATIVES_PREFIX]made"
32+
},
33+
"BoutiquesBidsSingleSubjectMaker":"SubjectDirectory",
34+
"BoutiquesBidsSubjectFileSelector":{
35+
"SubjectDirectory":"all_to_keep"
36+
}
37+
}
38+
}
39+
40+
41+
+-----------------------------------+----------------------------------------------------------------------------------+
42+
| PROPERTY | DESCRIPTION |
43+
+-----------------------------------+----------------------------------------------------------------------------------+
44+
| "cbrain:author": | |
45+
| "Full Name <email@address>" | Author(s) of Boutiques descriptor |
46+
+-----------------------------------+----------------------------------------------------------------------------------+
47+
| "cbrain:can-submit-new-tasks": | Experimental |
48+
| true | Allows forking sub-task(s). To submit a subtask, a task must create |
49+
| | a ".new-task-*.json" JSON file at the root of its work directory |
50+
+-----------------------------------+----------------------------------------------------------------------------------+
51+
| "cbrain:ignore_outputs": [ | |
52+
| output_id_1, | The listed outputs will not be saved. |
53+
| output_id_2, | |
54+
| output_id_3, | |
55+
| ... | |
56+
| ] | |
57+
| | |
58+
+-----------------------------------+----------------------------------------------------------------------------------+
59+
| "cbrain:save_back_inputs": [ | |
60+
| id_1, | Saves back listed inputs to the dataprovider (mutates the original inputs) |
61+
| id_2, | |
62+
| id_3, | |
63+
| ... | |
64+
| ] | |
65+
| | |
66+
+-----------------------------------+----------------------------------------------------------------------------------+
67+
| "cbrain:readonly-input-files": | |
68+
| true | Indicates that the tool cannot modify inputs |
69+
+-----------------------------------+----------------------------------------------------------------------------------+
70+
| "cbrain:alters-input-files": | |
71+
| true | Indicates that this task may alter its input files |
72+
+-----------------------------------+----------------------------------------------------------------------------------+
73+
| "cbrain:no-run-id-for-outputs": [ | |
74+
| id_1, | Lists output IDs where no run id is inserted. |
75+
| id_2, | Prevents the usual practice of adding a run id to output file names. |
76+
| id_3, | Only allowed for MultiLevel data-providers with "browse path" capability. |
77+
| ] | With this option, new results can overwrite old files. |
78+
| | |
79+
| | |
80+
+-----------------------------------+----------------------------------------------------------------------------------+
81+
| "cbrain:allow_empty_strings": | |
82+
| [input_id_1, input_id_2 ...] | Allow an empty string as a valid input |
83+
| | |
84+
+-----------------------------------+----------------------------------------------------------------------------------+
85+
| "cbrain:boutiques_bosh_exec_mode":| (Experimental) |
86+
| "launch" | The default implied value is 'simulate'. |
87+
| | In the mode 'simulate', at the moment of creating the |
88+
| | tool's script in cluster_commands(), the output of |
89+
| | bosh exec simulate |
90+
| | will be substituted in the script to |
91+
| | generate the tool's command. In the mode 'launch', an actual |
92+
| | bosh exec launch |
93+
| | command will be put in the script instead. |
94+
+-----------------------------------+----------------------------------------------------------------------------------+
95+
| "cbrain:inherits-from-class": | ( Restricted use ) |
96+
| "MyClassName" | An advanced feature for seasoned CBRAIN experts only. |
97+
| | That allows overwriting the standard task behavior with a custom class. |
98+
+-----------------------------------+----------------------------------------------------------------------------------+
99+
| "cbrain:integrator_modules": { | Loads a module to modify the CBRAIN behavior. |
100+
| | Does not work for legacy integration method |
101+
| "BoutiquesModuleOne": | All the modules are defined in the lib folder of CBRAIN |
102+
| {module-specific-parameters}, | codebase or a plugin. Thus documentation for all the |
103+
| "BoutiquesModuleTwo": | module-based sub-properties can be auto-generated |
104+
| {module-specific-parameters} | with the rdoc utility. |
105+
| } | |
106+
| | |
107+
+-----------------------------------+----------------------------------------------------------------------------------+
108+
| "cbrain:ignore-exit-status": | (Deprecated) |
109+
| true | Considers the task successful even if there is a wrong exit status. |
110+
| | For the case the tool has wrong exit codes |
111+
| | (deprecated and being superseded by a module-based property). |
112+
| | |
113+
+-----------------------------------+----------------------------------------------------------------------------------+
114+
| "cbrain:walltime-estimate": | (Deprecated) |
115+
| value_in_seconds | Since walltime was added to Boutiques resources sections. |
116+
+-----------------------------------+----------------------------------------------------------------------------------+

0 commit comments

Comments
 (0)