Extension tvb-ext-xircuits

1

Source code: [[https:~~/~~/github.com/the-virtual-brain/tvb-ext-xircuits>>https://github.com/the-virtual-brain/tvb-ext-xircuits]]

2

3

Release on Pypi: [[https:~~/~~/pypi.org/project/tvb-ext-xircuits/>>https://pypi.org/project/tvb-ext-xircuits/]]

4

5

== Jupyter Lab Extension for building and executing EBRAINS Workflows ==

== Purpose ==

This is a Jupyter Lab extension with the role of offering graphical support for EBRAINS workflows. It allows users to utilize all the TVB and EBRAINS capabilities, while drastically reducing the complexity of configuring them inside a Jupyter Lab environment.

10

11

**Note: **This extension is still a WIP (Work In Progress).

12

13

14

== Acknowledgements ==

15

16

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.

== Installation ==

The extension can installed using the official PyPi distribution ([[https:~~/~~/pypi.org/project/tvb-ext-xircuits/>>https://pypi.org/project/tvb-ext-xircuits/]]):

(% class="box" %)

(((

pip install tvb-ext-xircuits

25

)))

26

27

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:

[[image:side.png]]

== **Usage** ==

=== **Step 1. Create a new Xircuits workflow** ===

35

36

Using the Jupyter Lab launcher. 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.

37

38

=== **Step 2. Drag components into the workflow area** ===

39

40

Open the components tray, browse through the components, select the one you wish to use and drag it into the workflow area.

41

42

=== **Step 3. Configure the components** ===

43

44

The components that are provided in this extensions are configurable, meaning you can set some parameters on almost every component. For this you need to open the //General// tab from the components tray and drag the appropriate //literal//: float, int, string, dict, etc.

45

46

=== **Step 4. Make connections** ===

47

48

After dragging all your desired components in the workflow area, it's time to connect the components.

49

50

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.

51

52

=== **Step 5. Run the workflow** ===

53

54

After connecting everything, you need to run the workflow to actually see its result. For this you can click on the Run button (▶), which will also implicitly compile the workflow.

55

56

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.

57

58

=== **Step 6. Share your work*** ===

59

60

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.

== Custom functionalities ==

65

66

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.

67

68

=== 1. Configure TVB models using the Phase Plane widget. ===

69

70

This functionality was added to make it easier for users to provide the correct parameters to TVB models, using the Phase Plane widget.

71

72

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:

73

74

75

(% style="text-align:center" %)

76

[[image:image-20221116125354-2.png||height="800" width="1130"]]

77

78

79

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.

80

81

(% style="text-align:center" %)

82

[[image:image-20221116125822-1.png||height="800" width="821"]]

83

84

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).

85

86

(% style="text-align:center" %)

87

[[image:image-20221116130425-1.png||height="900" width="1069"]]

88

89

90

== Workflow examples ==

91

92

(((

93

=== 1. Full TVB Simulation workflow ===

94

)))

95

96

Contains all TVB components necessary for running a TVB simulation (i.e. connectivity, coupling, model, integrator, monitor, simulator).

=== 2. Configuring model parameters using the PhasePlaneWidget: ===

104

105

Same workflow as before, but the parameter for the model used in simulation are set using the PhasePlaneWidget.

=== 3. Using siibra to retrieve connectivities from the EBRAINS KG ===

113

114

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.

=== 4. Run a workflow inside an HPB job ===

122

123

A workflow simulation which is run remotely, by submitting a job to an HPC site and getting back the results (TimeSeries object).

124

125

{{html}}<iframe src="https://drive.google.com/file/d/1rvcj_9lGtR069iXlL3Rm1czMNdA3qmGM/preview" width="1280" height="720" allow="autoplay"></iframe>{{/html}}

126

Wiki source code of Extension tvb-ext-xircuits

TVB Widgets