MEDUSA© Panels

Here you have a detailed explanation about the three main panels of MEDUSA© Platform: plots, log and app panels.


For MEDUSA© Platform v2024

If you have any questions that are beyond the scope of this help file, please feel free to ask for help in the forum or contact with us.


Plots panel

The right part of the MEDUSA© main screen shows the “Real time plots”. There you can view the signals that are being monitored in real time. Different features, such as the shape and number of plots displayed, can be fully customized to suit your needs. Four categories of real-time plots are provided:

  • Time plots. This type of graph presents the time courses of one (or more) channels.
  • PSD plots. This type of graph shows the power spectral density (PSD) of the signals you are recording in real time. Detailed information on what a PSD is can be found here.
  • Topography plots. This type of graph shows the power spectral density (PSD) M/EEG signals in real-time as a heat map over the head.
  • Connectivity plots. This type of graph shows different functional connectivity measures of M/EEG signals in real time as links between electrode positions over the head.

Of course, these graphs have many options to configure, adapting to the requirements of the study. Let's see how to add graphics to the MEDUSA© window and configure them!

Configuring the plot window layout

First of all, you need to consider how many charts you want to create and their size. To do so, the first step is to click the button (remember to set up the LSL signal first!).

Main GUI of MEDUSA© Platform

The window below will appear. In the upper left corner, you can set the size of the grid to accommodate different plots. You can also create a new plot by clicking the button. Created parcels can be deleted by dragging them to the icon in the upper right corner. At the bottom of the window, the Clear button would remove all existing charts, Load and Save buttons would restore and save a specific plot layout, OK button would apply the current layout, and Cancel button would discard the changes and close the window.

Configuration screen for plot layout

Now that you know what all the buttons do, let's create some graphs! To do this, click the button. A light gray square will appear indicating the position of the created graph. You can change its position by dragging it on the grid, and the size by clicking and dragging on its bottom right corner. Now create 4 different plots with the layout indicated in the figure below.

Configuring the plot options

Once the plot layout is configured, it is time to configure each of these graphs. This will change the color of the plots to green, indicating that the plot is ready for use. To configure a graph, you must right-click on it to open the configuration window shown below. There, you can choose the source data in the Connect to dropdown, plus you can choose between four different graphs in the Plot type list. The plots currently provided by MEDUSA© Platform are: TimePlot and TimePlotMultichannel, to represent the time course of the signal from one or more channels, respectively; and PSDPlot and PSDPlotMultichannel to display the power spectral density of the data from one or more channels, respectively.

Configuration screen for the plot options

Below the Plot type list, there are two sections where you can complete the configuration of the plot.

The following settings are encoded as JSON strings. If you are unfamiliar with JSON, please read more about this notation here.

On the one hand, in Preprocessing options, different transformations can be applied to the original signal to adapt the representation to your study (e.g., a bandpass filter if you are interested in a certain frequency band).


{
    "update-rate": 0.1,
    "frequency-filter": {
        "apply": true,
        "type": "highpass",
        "cutoff-freq": [
            1
        ],
        "order": 5
    },
    "notch-filter": {
        "apply": true,
        "freq": 50,
        "bandwidth": [
            -0.5,
            0.5
        ],
        "order": 5
    },
    "re-referencing": {
        "apply": false,
        "type": "car",
        "channel": ""
    },
    "downsampling": {
        "apply": false,
        "factor": 2
    }
}
              

Let's see what this section contains:

  • update-rate This parameter controls the update rate, in seconds, of the plot. You can tune this parameter to adequate the computational cost to your computer. For instance, an update rate of 0.1 s updates the plot each 100 ms (ten times per second).
  • frequency-filter This feature allows you to set an infinite impulse response (IIR) filter for online real-time visualization. Setting apply to true activates the filter. The type option controls the type of filter (i.e., lowpass, highpass, bandpass and stopband). The cutoff-freq defines the frequency limits (e.g., for a bandpass filter between 8 and 13 Hz, we would enter [8, 13]. Finally, defining order allows you to set the order of the filter (note: higher filter orders increase the computational cost).
  • notch-filter Generally, you want to get rid of power line interference in EEG recordings. This is an alternative way to create notch filters. In this case, instead of defining upper and lower cutoff frequencies, you can define a center frequency in the freq section, and relative limits in the bandwidth section. In this specific case, a notch filter is created between 49.5 and 50.5 Hz. This would be equivalent to setting the filter using the frequency-filter setting with type set to bandstop and cutoff-freq set to [49.5, 50.5].
  • re-referencing Use this field to change the reference of your signals. Type of re-referencing can be "car" or "channel". The first refers to Common Average Reference, a technique widely used for M/EEG. In the case, the parameter "channel" is ignored. On the other hand, type "channel" will subtract the the signal of the specified channel (label) from the rest of the channels.
  • downsampling Use this parameter to reduce the sample rate of the incoming LSL stream and reduce the computational cost of the real-time plot. .

You may have noticed that all of our visualization filters are IIR. Despite the non-linear phase and the numerical instability they offer, we use IIR filters for online visualization because their order makes them much more computationally efficient than finite impulse response (FIR) ones. For more information on this topic, you can refer to this link.

On the other hand, in the Visualization options section you can customize the plot display parameters.


{
    "mode": "clinical",
    "x_axis": {
        "seconds_displayed": 10,
        "display_grid": true,
        "line_separation": 1,
        "label": "Time (s)"
    },
    "y_axis": {
        "cha_separation": 1,
        "display_grid": true,
        "autoscale": {
            "apply": false,
            "n_std_tolerance": 1.25,
            "n_std_separation": 5
        },
    "label": {
        "text": "Signal",
        "units": "auto"
        },
    "title": "auto"
}

                          

The configuration options available for time charts is explained below:

  • mode This parameter determines how events are presented in the graphics. You can choose between Clinical , where the display grid updates in a sweeping manner, or Geek if you prefer the signal to appear continuously.
  • x_axis The seconds_displayed parameter refers to the time range (in seconds) displayed in the visualization window. Also, display_grid controls the visibility of the display grid. line_separation This parameter allows you to modify the display grid's dimensions. Finally, you can set a label for the X-axis with this parameter label .
  • y_axis The cha_separation parameter indicates the initial limits of the Y-axis. autoscale allows signals to be automatically scaled for ease of viewing by settings apply. The n_std_tolerance parameter controls the autoscale limit(i.e., if the signal exceeds this value, the scale will be re-adjusted), so higher values give less auto-scaling. Also, n_std_separation indicates the separation between channels (in standard deviations). Finally, you can set a label for the Y-axis with this parameter label label.
  • title Allows to set a title for the plot.
Furthermore, it is possible to adjust the channel amplitudes using the mouse wheel.

The configuration options available for PSD charts is explained below:


{
    "psd_window_seconds": 5,
    "scaling": {
        "apply_autoscale": true,
        "n_std_tolerance_autoscale": 1.25,
        "std_factor_separation_autoscale": 5,
        "initial_channel_separation": 0.01
    },
    "welch_overlap_pct": 25,
    "welch_seg_len_pct": 50,
    "x_range": [
        0.1,
        30
    ],
    "y_range": "auto",
    "init_channel_label": null,
    "title": "PSDPlotMultichannel",
    "x_axis_label": [
        "Frequency",
        "Hz"
    ],
    "y_axis_label": [
        "Power",
        "V2/Hz"
    ]
}
                          
  • psd_window_seconds Time interval in which the PSD will be estimated.
  • welch_seg_len_pct Percentage of the window that will be used to estimate the PSD.
  • welch_overlap_pct Percentage of segment overlapping that will be used to estimate the PSD
  • x_range Frequency limits of the PSD visualization.
  • y_range Limits for the Y-axis.

The estimation of the PSD is carried out following the Welch method. Click here for further explanation, and here for learning more about the Python implementation.

The configuration options available for Topography charts is explained below:


{
    "title": "TopoPlot",
    "channel-standard": "10-05",
    "extra_radius": 0.29,
    "interp_points": 100,
    "cmap": "PiYG",
    "head_skin_color": "#E8BEAC",
    "plot_channel_labels": true,
    "plot_channel_points": true
}
                          
  • title Displayed title.
  • channel-standard EEG channel standard "10-20", "10-10", "10-05", as defined in medusa-kernel, that contains the labels of the incoming EEG signal
  • extra_radius Extra area to plot outside the electrodes.
  • interp_points Number of interpolation points.
  • cmap Matplotlib colormap.
  • head_skin_color Head skin color.
  • plot_channel_labels Boolean to display the channel labels or not.
  • plot_channel_points Boolean to display channel points or not.

The estimation of the PSD is carried out following the Welch method. Click here for further explanation, and here for learning more about the Python implementation.

The configuration options available for Topography charts is explained below:


{
    "title": "ConnectivityPlot",
    "channel-standard": "10-05",
    "cmap": "RdBu",
    "head_skin_color": "#E8BEAC",
    "plot_channel_labels": true,
    "plot_channel_points": true
}
                          
  • title Displayed title.
  • channel-standard EEG channel standard "10-20", "10-10", "10-05", as defined in medusa-kernel, that contains the labels of the incoming EEG signal
  • extra_radius Extra area to plot outside the electrodes.
  • interp_points Number of interpolation points.
  • cmap Matplotlib colormap.
  • head_skin_color Head skin color.

The estimation of the PSD is carried out following the Welch method. Click here for further explanation, and here for learning more about the Python implementation.

Visualizing the final layout

Now that you know how to configure the plots, let's arrange the layout (using the default options) as follows:

  • 0 is the TimePlotMultichannel.
  • 1 is the TimePlot.
  • 2 is the PSDPlotMultichannel.
  • 3 is the PSDPlot.

The plot layout will now be green, as shown in the figure below. It's time to press the OK button and visualize our signals.

Plot layout with all the graphs already configured

After pressing the OK button, you will notice that the charts do not work, but that is ok, just click the button and the visualizations will be activated. Of note, you can activate and deactivate the visualizations at any time by clicking the button. In addition, you can modify your plots at any time by clicking the button as long as the plots are deactivated.


Log panel

The left-hand corner of MEDUSA Platform refers to the log panel. Within this panel, users can see a chronological record of events that have had an impact on the platform. These logs not only document the events themselves but also provide insights into the resulting changes and consequences that these events have generated.

Log panel of MEDUSA© Platform

  • This option enables you to save the text file generated from the logs into the folder of your choice. It server as a valuable function for archiving or backing up the log data in a location that you specify.
  • Clears the screen where the notifications are generated. It is particularly useful for maintaining a clutter-free and distraction- free workspace by removing outdated or redudant information.
  • Log settings. Still under development.
  • This feature allows you to adjust the size of the console, which can be valuable for adapting the user interface to your specific preferences or needs. You can expand or shrink for a more comfortable user experience.
  • Apps panel

    A comprehensive list of all the applications included in the platform is displayed in this panel. The apps are listed in order of installation. Detailed information on the necessary configurations of each application can be found in their respective documentation.

    Apps panel of MEDUSA© Platform

    In the first block:

  • After selecting the desired application from the list, this button will allow the app to be started.
  • Once the application has been launched and a TCP/IP connection established, this button provides the functionality to initiate or pause the app.
  • Ends the app and immediately a save recording file box appears to save our signal in the folder indicated.
  • This button offers the capability to adjust various parameters corresponding to each individual application.
  • On the left-hand side, you can conveniently highlight a specific application by typing its name in the provided search box. This simplifies the process of locating and accessing desired applications.
  • Allows you to install a new application on the platform. To accomplish this, you should select the .app within the appropriate file folder.
  • The second block, which contains the central icons, focuses on session creation and management. Through this feature, you can create customized sessions that include various applications with different paradigms, each with its own configuration settings.

  • Load session Allows to load a pre-configured session for the different applications.
  • Play session Initiates the configured session.
  • Configure session Modify the specified parameters of an existing session.
  • Create session Facilitates the creation of a new session by allowing the input of various parameters:
  • Panel where you can configure each session.

    Click on + to add the new parameters. The parameters to modify:

  • RUN ID The name assigned to the run.
  • APP ID The identifier of the application to be referenced. A tab will open where you can select the required application (must be installed on your MEDUSA© platform).
  • Settings file Allows to load a previously saved configuration.
  • Max time(s) Define the maximum runtime for the application, particularly beneficial for apps configured to run indefinitely.
  • File ext Extension indicating the type of format of the file (bson, mat or json).
  • Autoplay If enabled, the application will launch automatically after the previous one, bypassing the need for the user to click the play button.
  • Below the box, you can choose to automatically update the default record IDs, ensuring that the application refreshes whenever changes are detected.
    In the Preference tab, there is an option to enable or disable study mode, which enables potential visualization of the desktop folder corresponding to our created session.

    Lastly, in Edit recording info you have the opportunity to configure recording details and establish parameters such as recording ID, file extension and file path. This streamlines the process of saving recordings and allows for the inclusion of supplementary information, such as studio ID, subject ID, session ID and studio information, enhancing the overall recording experience.