Wiki source code of Widget TimeSeries

Version 43.1 by rominabaila on 2023/05/15 14:19

version	line-number	content
22.1	1	Source code: [[https:~~/~~/github.com/the-virtual-brain/tvb-widgets>>url:https://github.com/the-virtual-brain/tvb-widgets]]
21.1	2
25.1	3	This is part of a Pypi release: [[https:~~/~~/pypi.org/project/tvb-widgets/>>url:https://pypi.org/project/tvb-widgets/]]
21.1	4
25.1	5	//tvb-widgets// is also already installed in the official image released for EBRAINS lab, where you can test it directly.
	6
23.1	7	== Purpose ==
1.1	8
35.1	9	It is a JupyterLab Widget intended for the visualization of brain signals represented as time series.
5.1	10
32.1	11	== Backends ==
	12
	13	Starting with //tvb-widgets 1.5.0, //the TS widget comes in 2 forms, corresponding to the 2 different libraries (we called them backends) used for plotting: matplotlib and plotly. The matplotlib backend, build on top of the mne library, offers more advanced scientifical features, while the plotly backend has a more appealing look and moves faster when talking about the basic interactions.
	14
36.1	15	Below you can see the TS widget with each backend option (first one using the matplotlib backend, second one using the plotly backend).
32.1	16
	17	(% style="text-align:center" %)
	18	[[image:matplotlib.png]]
	19
	20	(% style="text-align:center" %)
	21	[[image:plotly.png]]
	22
5.1	23	== Inputs ==
	24
17.1	25	Time series can be given as inputs in two forms:
6.1	26
	27	* TVB TimeSeries datatype
	28	* Numpy arrays
	29
17.1	30	This widget supports 2D, 3D, and 4D arrays. In all three cases, there is a fixed shape that the TimeSeries widget expects:
6.1	31
	32	* for 2D: (no_timepoints, no_channels)
	33	* for 3D: (no_timepoints, state_variable/mode, no_channels)
	34	* for 4D: (no_timepoints, state_variable, no_channels, mode)
	35
17.1	36	~* Note that the TVB TimeSeries datatype is always 4D and already has the expected shape.
7.1	37
	38	== Requirements and installation ==
	39
33.1	40
17.1	41	Before installing the tvb-widgets library containing the TimeSeries widget, the following python libraries and Jupyter extensions should be installed:
7.1	42
	43	* Libraries:
33.1	44	** [[mne>>https://mne.tools/stable/index.html]] >= 1.0
	45	** [[matplotlib>>https://matplotlib.org/3.5.0/index.html]]
	46	** [[plotly>>https://plotly.com/python/]] == 5.14.0
	47	** [[ipywidgets>>https://ipywidgets.readthedocs.io/en/7.x/]] == 7.7.2
	48	** [[ipympl>>https://github.com/matplotlib/ipympl#installation]] >= 0.8.5
7.1	49	* (((
11.1	50	Extensions:
7.1	51
	52	(% class="box" %)
	53	(((
8.1	54	jupyter labextension install @jupyter-widgets/jupyterlab-manager
7.1	55
8.1	56	jupyter labextension install jupyter-matplotlib
33.1	57
	58	jupyter labextension install jupyterlab-plotly
7.1	59	)))
	60	)))
	61
12.1	62	Then, to install the tvb-widgets library, just type:
7.1	63
	64	(% class="box" %)
	65	(((
	66	pip install tvb-widgets
	67	)))
13.1	68
	69	== API usage ==
	70
	71	First, the correct matplotlib backend must be set, which enables the interaction with the TimeSeries widget, by running the following command:
	72
	73	(% class="box" %)
	74	(((
	75	%matplotlib widget
	76	)))
	77
34.1	78	Then, simply import the plot_timeseries method, which gives you access to the TS widget:
13.1	79
	80	(% class="box" %)
	81	(((
34.1	82	from tvbwidgets.api import plot_timeseries
13.1	83	)))
	84
	85
34.1	86	Assuming that the user has already created or imported a valid input, this is how the widget can be initialized and displayed (example below assumes that tsr is a TVB TimeSeries datatype):
	87
13.1	88	(% class="box" %)
	89	(((
34.1	90	backend = 'plotly' # change to 'matplotlib' to see the other TS widget
	91
	92	plot_timeseries(data=tsr, backend=backend)
13.1	93	)))
	94
34.1	95	After running the code from above into a Jupyter cell, you should see the TS widget corresponding to the backend you selected.
13.1	96
38.2	97	== 1. TS Widget with matplotlib and mne ==
37.1	98
	99	As it was already mentioned, the matplotlib widget offers more advanced scientifical fearures. In the video below, you can see some of the functionalities that this backend provides, like: increasing/decreasing signal amplitude, selecting/deselecting certain signals, selecting different dimensions (state variable/mode) from the input data, navigating through the timeline, etc.
	100
15.1	101	{{html}}
37.1	102	<iframe width="840" height="480" src="https://www.youtube.com/embed/hozEkVhkWeA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
15.1	103	{{/html}}
36.2	104
38.2	105	== 2. TS Widget with plotly ==
	106
	107	Starting with //tvb-widgets version 1.5.0//, we introduced a second TS Widget, which uses the plotly.py library to create the interactive plot. Below you can watch small tutorials on how to use and interact with this widget.
	108
	109	=== 2.1. Moving through the timeline and channels list ===
38.3	110
38.4	111	To move through the timeline or channels list, go to your cursor over the X (for timeline) and Y (for channels) axes and drag it to navigate.
	112
38.3	113	{{html}}
	114	<iframe width="840" height="480" src="https://www.youtube.com/embed/nZYZxHui-Ao" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
	115	{{/html}}
	116
38.5	117	=== 2.2. Modify spacing between channels ===
	118
43.1	119	To modify the spacing between the channels, go with your cursor over the beginning/end of the Y axis (where the channels list is) and drag it to the outside of the plot area.
38.5	120
	121	{{html}}<iframe width="840" height="480" src="https://www.youtube.com/embed/q_olB7uRSc4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>{{/html}}
	122

Wiki source code of Widget TimeSeries

TVB Widgets