Wiki source code of Extension tvb-ext-xircuits

Last modified by paulapopa on 2023/03/24 08:17

version	line-number	content
1.1	1	Source code: [[https:~~/~~/github.com/the-virtual-brain/tvb-ext-xircuits>>https://github.com/the-virtual-brain/tvb-ext-xircuits]]
	2
28.1	3	Release on Pypi: [[https:~~/~~/pypi.org/project/tvb-ext-xircuits/>>https://pypi.org/project/tvb-ext-xircuits/]]
	4
55.1	5	This extension is also installed already in EBRAINS lab, where it can be tested directly.
	6
47.1	7	== Jupyter Lab Extension for building and executing TVB Workflows on EBRAINS ==
1.1	8
2.1	9	== Purpose ==
1.1	10
45.1	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.
3.1	12
56.1	13	{{html}}
	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>
	15	{{/html}}
	16
14.1	17	== Acknowledgements ==
	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 and EBRAINS. These functionalities are detailed in a section below.
	20
3.1	21	== Installation ==
	22
44.1	23	The extension can be installed using the official PyPi distribution ([[https:~~/~~/pypi.org/project/tvb-ext-xircuits/>>https://pypi.org/project/tvb-ext-xircuits/]]):
3.1	24
	25	(% class="box" %)
	26	(((
	27	pip install tvb-ext-xircuits
	28	)))
	29
9.1	30	After installing the extension and opening a Jupyter Lab session, you should be able to see in the left panel of Jupyter Lab a new icon, which represents the Xircuits components tray:
4.1	31
31.1	32	[[image:side.png]]
9.1	33
13.1	34	== Usage ==
4.1	35
12.1	36	=== Step 1. Create a new Xircuits workflow ===
10.1	37
43.1	38	From the Jupyter Lab launcher, click on the Xircuits File icon, as in the screenshot below.
10.1	39
43.1	40	[[image:newxircs.png]]
	41
	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
	44	[[image:newfile.png]]
	45
	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
12.1	48	=== Step 2. Drag components into the workflow area ===
10.1	49
43.1	50	Open the components tray, from the left-side bar icon highlighted below.
10.1	51
43.1	52	[[image:tray.png]]
	53
	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
	56	[[image:components.png]]
	57
12.1	58	=== Step 3. Configure the components ===
10.1	59
43.1	60	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.
12.1	61
43.1	62	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.
	63
	64	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).
	65
	66	[[image:diagr.png]]
	67
12.1	68	=== Step 4. Make connections ===
	69
43.1	70	After dragging all your desired components/literals in the workflow area, it's time to connect the components.
12.1	71
43.1	72	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.
12.1	73
43.1	74	[[image:diagram.png]]
	75
12.1	76	=== Step 5. Run the workflow ===
	77
54.1	78	After connecting everything, you need to run the workflow to actually see its results.
12.1	79
54.1	80	There are 2 ways to run the workflow in EBRAINS Lab:
	81
	82	~1. Locally:
	83
	84	* 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.
	85
43.1	86	[[image:run.png]]
	87
54.1	88
	89	2. Remotely on HPC (only if you have access to HPC resources)
	90
	91	* First choose the __Remote Run__ in the select box and then click the Run button (▶), which will also implicitly compile the workflow.
	92
	93	[[image:remote.png]]
	94
	95	* A dialog will open to request the HPC connection details:
	96	** which __HPC Site__ to use
	97	** the name of the __HPC Project/Account__ you have access to
	98	** 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.
	99	** 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.
	100
	101	[[image:rem.png]]
	102
	103	* 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:
	104
	105	[[image:uni.png]]
	106
	107
12.1	108	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.
	109
43.1	110	[[image:out.png]]
	111
12.1	112	=== Step 6. Share your work* ===
	113
	114	This step is, of course, optional, but it is worth mentioning that sharing your workflows with others is extremely easy. By just saving and sharing your workflow (*.xircuits) file, anyone can access the entire workflow, see the exact connections that you made and receive the same configuration for the components.
	115
	116
15.1	117	== Custom functionalities ==
12.1	118
15.1	119	As mentioned before, besides all the core functionalities provided by Xircuits, some other functionalities were added to better suit the needs of the EBRAINS users.
	120
54.1	121	=== 1. Configure TVB models using the Phase Plane widget ===
15.1	122
	123	This functionality was added to make it easier for users to provide the correct parameters to TVB models, using the Phase Plane widget.
	124
20.1	125	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:
15.1	126
20.1	127
	128	(% style="text-align:center" %)
	129	[[image:image-20221116125354-2.png\|\|height="800" width="1130"]]
	130
	131
	132	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.
	133
	134	(% style="text-align:center" %)
	135	[[image:image-20221116125822-1.png\|\|height="800" width="821"]]
	136
	137	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).
	138
	139	(% style="text-align:center" %)
	140	[[image:image-20221116130425-1.png\|\|height="900" width="1069"]]
	141
	142
54.1	143	=== 2. Visualize time series resulted from simulations ===
	144
58.1	145	This functionality is available for the StoreResultsToDrive component. Right click on the StoreResultsToDrive and select the Open Viewer option:
54.1	146
	147	[[image:view.png]]
	148
58.1	149	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.
54.1	150
	151	[[image:view2.png]]
	152
58.1	153	Next, you should choose which time series file to display and click the View time series button.
54.1	154
	155	[[image:view3.png]]
	156
57.1	157	== ==
54.1	158
21.1	159	== Workflow examples ==
20.1	160
25.2	161	(((
	162	=== 1. Full TVB Simulation workflow ===
	163	)))
25.1	164
25.2	165	Contains all TVB components necessary for running a TVB simulation (i.e. connectivity, coupling, model, integrator, monitor, simulator).
25.1	166
25.2	167	{{html}}
57.1	168	<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>
25.2	169	{{/html}}
	170
	171
	172	=== 2. Configuring model parameters using the PhasePlaneWidget: ===
	173
	174	Same workflow as before, but the parameter for the model used in simulation are set using the PhasePlaneWidget.
	175
26.1	176	{{html}}
57.1	177	<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>
26.1	178	{{/html}}
25.3	179
	180
	181	=== 3. Using siibra to retrieve connectivities from the EBRAINS KG ===
	182
	183	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.
	184
26.1	185	{{html}}
57.1	186	<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>
26.1	187	{{/html}}
	188
	189
57.1	190	=== 4. Run a workflow as an HPB job ===
26.1	191
	192	A workflow simulation which is run remotely, by submitting a job to an HPC site and getting back the results (TimeSeries object).
	193
57.1	194	{{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}}
26.1	195

Wiki source code of Extension tvb-ext-xircuits

TVB Widgets