Wiki source code of Widget TimeSeries
Version 45.1 by rominabaila on 2023/05/15 15:42
Hide last authors
| author | 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 | |||
| |
45.1 | 109 | === 2.1. Basic controls of the plot === |
| 110 | |||
| 111 | If you hover over a signal, a tooltip will appear where you can see the exact value from that point and the name of the channel you are hovering over. Next, you can zoom in, by dragging and creating an area inside the plot or from the plotly tools area and zoom out, from the same tools area. To come back to the original view, you can click the 'Reset axes' button (house icon) from the tools area. | ||
| 112 | |||
| 113 | To the right of the plot there is a legend, showing the channels which are plotted. The '**[R]**' notation means that the signal is **resampled** so that all of it can be viewed inside the plot. The '**~~20**' notation means that 20 consecutive points are aggregated into a single point in the plot. As you zoom in in the plot, the number of aggregated points decreases. This is all done using the [[**plotly-resampler**>>https://predict-idlab.github.io/plotly-resampler/]] package. | ||
| 114 | |||
| 115 | Moreover, clicking on a channel name from the legend will toggle its visibility inside the plot. This means that the signal corresponding to that channel //is not removed, but just invisible// in the plot. Double clicking on a channel from the legend will isolate it, meaning that will be the only visible channel in the plot and the rest of them will be hidden. Double clicking again will make all the channels visible again. If you wish to hide all the channels or make all of them visible, use the 'Hide All' and 'Show All' buttons. | ||
| 116 | |||
| 117 | {{html}} | ||
| 118 | <iframe width="840" height="480" src="https://www.youtube.com/embed/x4ksyKIFUAk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe> | ||
| 119 | {{/html}} | ||
| 120 | |||
| 121 | |||
| |
38.2 | 122 | === 2.1. Moving through the timeline and channels list === |
| |
38.3 | 123 | |
| |
38.4 | 124 | 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. |
| 125 | |||
| |
38.3 | 126 | {{html}} |
| 127 | <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> | ||
| 128 | {{/html}} | ||
| 129 | |||
| |
38.5 | 130 | === 2.2. Modify spacing between channels === |
| 131 | |||
| |
44.1 | 132 | 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. To decrease the spacing, drag your cursor to the inside of the plot area. To reset the spacing to the default values, click on the 'Reset axes' button (Home icon) from the plotly tools area. |
| |
38.5 | 133 | |
| 134 | {{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}} | ||
| 135 |