Last modified by teodoramisan on 2026/02/13 10:11
From version 73.7
edited by teodoramisan
on 2026/02/13 09:19
Change comment: There is no comment for this version
To version 61.1
edited by paulapopa
on 2026/02/12 11:01
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.teodoramisan
1 +XWiki.paulapopa
Content
... ... @@ -4,11 +4,11 @@
4 4  
5 5  This extension is also installed already in EBRAINS lab, where it can be tested directly.
6 6  
7 -== Jupyter Lab Extension for building and executing TVB and VBI Workflows on EBRAINS ==
7 +== Jupyter Lab Extension for building and executing TVB Workflows on EBRAINS ==
8 8  
9 9  == Purpose ==
10 10  
11 -This is a Jupyter Lab extension that offers graphical support for TVB and VBI workflows. It is already available in the EBRAINS Lab and it allows users to configure and execute TVB simulations and VBI inference workflows directly from a GUI, while drastically reducing the complexity of configuring them inside a Jupyter Lab notebook.
11 +This is a Jupyter Lab extension that offers graphical support for TVB workflows. It is already available in the EBRAINS Lab and it allows users to configure and execute TVB simulations directly from a GUI, while drastically reducing the complexity of configuring them inside a Jupyter Lab notebook. Try edit
12 12  
13 13  {{html}}
14 14  <iframe width="1200" height="450" src="https://www.youtube.com/embed/-cjZOsU6PBg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
... ... @@ -16,7 +16,7 @@
16 16  
17 17  == Acknowledgements ==
18 18  
19 -This extension is build on top of the [[Xircuits Jupyter extension>>https://xircuits.io/]], but it also comes with custom functionalities, specifically designed for TVB, VBI and EBRAINS. These functionalities are detailed in a section below.
19 +This extension is build on top of the [[Xircuits Jupyter extension>>https://xircuits.io/]], but it also comes with custom functionalities, specifically designed for TVB and EBRAINS. These functionalities are detailed in a section below.
20 20  
21 21  == Installation ==
22 22  
... ... @@ -37,11 +37,11 @@
37 37  
38 38  From the Jupyter Lab launcher, click on the **Xircuits File** icon, as in the screenshot below.
39 39  
40 -[[image:xircuits-file-icon.png||alt="newxircs.png" height="592" width="1100"]]
40 +[[image:xircuits-file-icon.png||alt="newxircs.png"]]
41 41  
42 42  A new file with the .xircuits extension will be generated under your current working directory. This is where you can start building the workflow diagram interactively.
43 43  
44 -[[image:xircuits-generated-file.png||alt="newfile.png" height="592" width="1100"]]
44 +[[image:xircuits-generated-file.png||alt="newfile.png"]]
45 45  
46 46  You will notice that 2 components are already placed inside the workflow: the __Start__ and the __Finish__ components. They cannot be modified or deleted, and they represent the starting and finishing point of the workflow.
47 47  
... ... @@ -49,28 +49,22 @@
49 49  
50 50  Open the components tray, from the left-side bar icon highlighted below.
51 51  
52 -[[image:xircuits-extension-icon.png||alt="tray.png" height="591" width="1100"]]
52 +[[image:xircuits-extension-icon.png||alt="tray.png"]]
53 53  
54 54  Now, you can browse through the components, select the one you wish to use, then drag and drop it into the workflow area.
55 55  
56 -Customizable components can be identified by a suffix (e.g. **TVB_**SIMULATOR, **VBI_**SIMULATION_RUNNER).
56 +[[image:xircuits-component-browser.png||alt="components.png"]]
57 57  
58 -[[image:xircuits-component-browser.png||alt="components.png" height="592" width="1100"]]
59 -
60 60  === **Step 3. Configure the components** ===
61 61  
62 62  The components that are provided in this extensions are configurable, meaning you can set some parameters on almost every component. Some of the parameters are literals, while some parameters are results of other components.
63 63  
64 -Parameters marked with a star (★) are mandatory, the workflow will not run until all required parameters have values assigned.
65 -
66 66  In case of primitives you need to open the //General// tab from the components tray and drag the appropriate //literal//: float, int, string, dict, etc.
67 67  
68 68  The parameters need to be linked to the inputs of the component by dragging and dropping a connection from the output port of a literal/component towards the corresponding input port of the other component (e.g. the gray connections in the screenshot below).
69 69  
70 -Components and parameters include info buttons (**i**) that explain their purpose and how they are used (e.g. the simulator info panel below).
66 +[[image:configure-components.png||alt="diagr.png"]]
71 71  
72 -[[image:Screenshot 2026-02-12 115445.png||alt="diagr.png" height="592" width="1100"]]
73 -
74 74  === **Step 4. Make connections** ===
75 75  
76 76  After dragging all your desired components/literals in the workflow area, it's time to connect the components.
... ... @@ -77,7 +77,7 @@
77 77  
78 78  First, link the __Start__ node to the first component of your workflow. Then make the connections between all your components. The last component should be linked to the __Finish__ node, to indicate the end of your workflow (e.g. the blue connections in the screenshot below). These connections will dictate the order of execution of the components in your workflow.
79 79  
80 -[[image:components-connection.png||alt="diagram.png" height="592" width="1100"]]
74 +[[image:components-connection.png||alt="diagram.png"]]
81 81  
82 82  === **Step 5. Run the workflow** ===
83 83  
... ... @@ -89,7 +89,7 @@
89 89  
90 90  * For this you can click on the Run button (▶), which will also implicitly compile the workflow. Make sure that __Local Run__ is selected near the Run button.
91 91  
92 -[[image:local-run-button.png||alt="run.png" height="592" width="1100"]]
86 +[[image:local-run-button.png||alt="run.png"]]
93 93  
94 94  
95 95  2. Remotely on HPC (only if you have access to HPC resources)
... ... @@ -96,7 +96,7 @@
96 96  
97 97  * First choose the __Remote Run__ in the select box and then click the Run button (▶), which will also implicitly compile the workflow.
98 98  
99 -[[image:remote-run-button.png||alt="remote.png" height="385" width="1100"]]
93 +[[image:remote-run-button.png||alt="remote.png"]]
100 100  
101 101  * A dialog will open to request the HPC connection details:
102 102  ** which __HPC Site__ to use
... ... @@ -104,16 +104,16 @@
104 104  ** one checkbox to choose whether you want the __HPC Monitoring__ to be opened up automatically (via tvb-ext-unicore GUI). This can also be opened up manually using the __Monitor HPC__ button or the __U__ icon from the left side-bar.
105 105  ** one checkbox to choose whether you want the results to be __staged out__ automatically or not. If checked, the workflow waits for the HPC jobs to finish and then performs the stage out. If unchecked, the results can be manually downloaded later on by using the GUI of the tvb-ext-unicore.
106 106  
107 -[[image:remote-run-configuration.png||alt="rem.png" height="591" width="1100"]]
101 +[[image:remote-run-configuration.png||alt="rem.png"]]
108 108  
109 109  * The HPC monitoring is done via the GUI of tvb-ext-unicore which is a separate package we have documented under this Wiki. But it can be nicely used together with tvb-ext-xircuits:
110 110  
111 -[[image:hpc-monitoring.png||alt="uni.png" height="593" width="1100"]]
105 +[[image:hpc-monitoring.png||alt="uni.png"]]
112 112  
113 113  
114 114  After clicking on Run, a new Jupyter Output window should appear in the bottom of your Jupyter Lab environment. Here you will see the output of your workflow, such as logs, static plots, etc.
115 115  
116 -[[image:jupyter-output-window.png||alt="out.png" height="591" width="1100"]]
110 +[[image:jupyter-output-window.png||alt="out.png"]]
117 117  
118 118  === **Step 6. Share your work*** ===
119 119  
... ... @@ -130,7 +130,7 @@
130 130  To use this functionality, drag any model from the **TVB_MODELS** (inside the components tray) into the workflow area. Then right click on the model and select the **Open Viewer** option:
131 131  
132 132  
133 -[[image:open-viewer-on-models.png||alt="image-20221116125354-2.png" data-xwiki-image-style-alignment="center" height="593" width="1100"]]
127 +[[image:open-viewer-on-models.png||alt="image-20221116125354-2.png" data-xwiki-image-style-alignment="center" height="800" width="1130"]]
134 134  
135 135  
136 136  A new Jupyter tab should open, which contains a read-only Jupyter notebook. After following the instructions provided there, you should be able to see the Phase Plane widget associated with this particular model.
... ... @@ -139,44 +139,23 @@
139 139  
140 140  After configuring the parameters with the desired values, go to the Exports tab of the widget and click on **Export model configuration**. Now all you have to do is to go back to the tab where your workflow is and you will see that the model will have values set for all the parameters that you modified in the Phase Plane widget (that is all the parameters there were assigned values different than the default ones).
141 141  
142 -[[image:export-model-configuration.png||alt="image-20221116130425-1.png" data-xwiki-image-style-alignment="center" height="763" width="1000"]]
136 +[[image:export-model-configuration.png||alt="image-20221116130425-1.png" data-xwiki-image-style-alignment="center" height="900" width="1069"]]
143 143  
144 144  
145 -=== 2. Visualize time series resulted from TVB simulations ===
139 +=== 2. Visualize time series resulted from simulations ===
146 146  
147 147  This functionality is available for the **StoreResultsToDrive** component. Right click on the **StoreResultsToDrive** and select the **Open Viewer** option:
148 148  
149 -[[image:open-viewer-button.png||alt="view.png" height="591" width="1100"]]
143 +[[image:open-viewer-button.png||alt="view.png"]]
150 150  
151 151  A new Jupyter tab should open, which contains a read-only Jupyter notebook. After running the cell, you should be able to see the **TimeSeriesBrowser **widget with the //**Collab**// and //**folder**// you have chosen for the **StoreResultsToDrive **component already loaded.
152 152  
153 -[[image:view2.png||height="576" width="1100"]]
147 +[[image:view2.png]]
154 154  
155 155  Next, you should choose which time series file to display and click the **View time series button**.
156 156  
157 -[[image:timeseries-plotly.png||alt="view3.png" height="593" width="1100"]]
151 +[[image:timeseries-plotly.png||alt="view3.png"]]
158 158  
159 -
160 -=== 3. Visualize posterior pairplot resulted from an inference workflow ===
161 -
162 -This functionality is available for the SamplePosterior component. Right click on the component and select the Open Viewer functionality.
163 -
164 -This opens a new JupyterLab tab with an editable notebook. After following the instructions in the notebook, you will generate a pairplot of the posterior samples, showing the distribution of each parameter (uncertainty) and the relationships between parameters.
165 -
166 -*Make sure the workflow has been executed so the viewer has data to load.
167 -
168 -[[image:plot-posteriors.png||height="593" width="1100"]]
169 -
170 -
171 -=== 4. Visualize time series resulted from VBI simulations ===
172 -
173 -This functionality is available for the SimulationRunner component. Right click on the component and select the Open Viewer functionality.
174 -
175 -This opens a new JupyterLab tab with an editable notebook. After following the instructions in the notebook, you will see a simple time-series plot of the simulated model signal over time.
176 -
177 -*Make sure the workflow has been executed so the viewer has data to load.
178 -[[image:plot-timeseries-vbi.png||height="592" width="1100"]]
179 -
180 180  == ==
181 181  
182 182  == Workflow examples ==
... ... @@ -185,20 +185,15 @@
185 185  === 1. Full TVB Simulation workflow ===
186 186  )))
187 187  
188 -Contains all TVB components necessary for running a TVB simulation (e.g., connectivity, coupling, model, integrator, monitor, simulator).
161 +Contains all TVB components necessary for running a TVB simulation (i.e. connectivity, coupling, model, integrator, monitor, simulator).
189 189  
190 190  {{html}}
191 191  <iframe width="1280" height="720" src="https://www.youtube.com/embed/bmqPlIJsWLk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
192 192  {{/html}}
193 193  
194 -=== 2. Full VBI Inference workflow ===
195 195  
196 -Contains all VBI components required to run an inference workflow (e.g., inference configuration, model, simulator, train posterior, sample posterior).
168 +=== 2. Configuring model parameters using the PhasePlaneWidget: ===
197 197  
198 -[[image:vbi_workflow.png||height="590" width="1100"]]
199 -
200 -=== 3. Configuring model parameters using the PhasePlaneWidget: ===
201 -
202 202  Same workflow as before, but the parameter for the model used in simulation are set using the PhasePlaneWidget.
203 203  
204 204  {{html}}
... ... @@ -205,8 +205,9 @@
205 205  <iframe width="1280" height="720" src="https://www.youtube.com/embed/jhGfYul1z9k" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
206 206  {{/html}}
207 207  
208 -=== 4. Using siibra to retrieve connectivities from the EBRAINS KG ===
209 209  
177 +=== 3. Using siibra to retrieve connectivities from the EBRAINS KG ===
178 +
210 210  A simulation workflow where **siibra **is used to retrieve a connectivity from the EBRAINS KG. That connectivity is fed into a TVB Simulator, where the rest of the parameters (coupling, model, etc.) are set to default values.
211 211  
212 212  {{html}}
... ... @@ -213,8 +213,9 @@
213 213  <iframe width="1280" height="720" src="https://www.youtube.com/embed/hnqTpFGCYMg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
214 214  {{/html}}
215 215  
216 -=== 5. Run a workflow as an HPB job ===
217 217  
186 +=== 4. Run a workflow as an HPB job ===
187 +
218 218  A workflow simulation which is run remotely, by submitting a job to an HPC site and getting back the results (TimeSeries object).
219 219  
220 220  {{html}}<iframe width="1280" height="720" src="https://www.youtube.com/embed/M6rZClFgRrM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>{{/html}}
Screenshot 2026-02-12 115445.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.teodoramisan
Size
... ... @@ -1,1 +1,0 @@
1 -275.3 KB
Content
plot-posteriors.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.teodoramisan
Size
... ... @@ -1,1 +1,0 @@
1 -442.0 KB
Content
plot-timeseries-vbi.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.teodoramisan
Size
... ... @@ -1,1 +1,0 @@
1 -579.5 KB
Content
vbi_workflow.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.teodoramisan
Size
... ... @@ -1,1 +1,0 @@
1 -465.2 KB
Content
Public

TVB Widgets