MEDUSA© Platform

Getting started

Thank you so much for trying MEDUSA©, you will not regret!

For MEDUSA© Platform v2023

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.

Installation

Python installation

Ignore these steps if you already have a Python 3.8, 3.9 or 3.10 installed in your system.

MEDUSA© requires to have a Python interpreter previously installed in your system. In particular, MEDUSA© Platform v2023 requires Python 3.8, 3.9 or 3.10 versions. If you don't have any of these in your system, go the official website, scroll down to select the desired version, and follow the instructions there.

MEDUSA© installation

There are several possibilities to install MEDUSA©: using the installer (recommended) or by downloading the source code (advanced usage).

Some users reported that MEDUSA© can be seen as suspicious software by some antivirus or mechanisms like Windows SmartScreen when being installed. There is nothing dangerous about MEDUSA©, we are currently working on resolving this issue. If you do not trust us, you can always run it using the source code, where you will not find any problems. We are sorry for the inconvenience!

This is the recommended installation for most users. Follow the steps below to install MEDUSA© Platform:

  1. Download the latest version of the installer from the home page.
  2. Run the installer granting admin privilidges when asked.
  3. Navigate through the installer by clicking Next
  4. Select the version of MEDUSA© Platform and the installation folder. Some locations require admin privilidges for execution (e.g., "C:\Program Files"). We recommend to avoid problems by installing the program in the default location under the user directory. Then click Next.
  5. Find your Python executable. If you have not modified the default destination path it should be in C:\Users\{your_user}\AppData\Local\Programs\Python\Python{yourversion}\python.exe. Note that AppData is, by default, a hidden folder. Type %AppData% in the File Explorer to navigate to it.

    6. Alternatively, you can find the python.exe file by typing 'Python' in the Windows Search Bar, right click the Python app and then select 'Open file location'. Copy the explorer route and paste into the installer.

  6. The installation download MEDUSA, start and download all the Python packages needed for MEDUSA© to run. After the installation, close the installation window.
  7. Congratulations! You have already installed MEDUSA©.

To run MEDUSA©, just click on the shortcut that has been created on your desktop, or alternatively search 'MEDUSA' in the Windows search bar.

If you are a basic user and you are not interested in creating custom apps for MEDUSA©, please install MEDUSA© using the installer.

Although the MEDUSA© installer already creates a Python virtual environment for you with the necessary packages to run MEDUSA© Platform, maybe you are more interested in downloading the source code and creating a custom environment in your favorite IDE.

To proceed, first clone the MEDUSA© Platform repository from GitHub:

                            git clone https://github.com/medusabci/medusa-platform.git
Create the project in your favorite IDE inside the folder src/. Then, create a virtual environment of Python 3.8.x, 3.9.x or 3.10.x in a separate folder (e.g., in src/venv/). Once your environment has been created, install the MEDUSA© requirements by typing: 
                            pip install -r {medusa_path}/requirements.txt
Congratulations! You have already installed MEDUSA© Platform, run the file src/main.py to execute the program.

Set LSL up

Before working with MEDUSA©, it is needed to setup a signal that will be acquired and processed in real time. MEDUSA© is compatible with any signal that is streaming using the lab streaming layer (LSL) protocol.

LSL is a system for the unified collection of measurement time series in research experiments that handles both the networking, time-synchronization, (near-) real-time access as well as optionally the centralized collection, viewing and disk recording of the data. Please, check their website for a more detailed explanation.

Do you have a biomedical device you want to use? If not, please skip the next instructions and go to "Generating a fake signal".

Connecting my device

The main repository of LSL provides a wide list of supported devices. Please, find yours and build or install the required application to transmit the signal via LSL. If you are having trouble with LSL or do not find your device, check the section Getting Help of the repository.

It is possible that your device has an official application to transmit via LSL. Contact the manufacturer to check it out.

Please consider that LSL is a third party application not linked with MEDUSA©. Refer to their authors and main repository to solve doubts and get support.

Generating a fake signal

We do not have the biomedical recording devices always connected, so it is possible to run MEDUSA© while generating a fake signal. We offer you Signal Generator, a simple program that can generate a fake electroencephalographic (EEG) signal for MEDUSA©. Follow the steps below to install it:

  1. Download the latest version of Signal Generator from here.
  2. Navigate through the installer to install the program.

Once installed, open Signal Generator to generate the fake signal:

  1. Customize the stream name, number of channels and other options (if desired).
  2. Press Start to stream the fake signal through LSL.
  3. Press Stop to stop the transmision whenever you want.

Run MEDUSA© Platform

To run MEDUSA©, type MEDUSA in the Windows search bar or double-click the desktop shortcut; or alternatively, run the script src/main.py if you installed it using the source code.

When running MEDUSA© for the first time, the starting prompt asks you to log in to your account. The account is strictly required, since it is used to manage your downloaded apps, as well as your private developments. Not a member yet? Click here to create your account for free.

Once you have your account, now you can log in to MEDUSA© Platform. If you want to log in to other account, press the button.

MEDUSA© Platform login dialog

Before using any application you first have to select the LSL signal that you want to use. Click the button to configure the LSL settings:

  1. In Available LSL streams, select your LSL signal (the one we connected/generated before), and press the button to indicate you want to use it.
  2. Configure the stream settings (e.g., name, type of signal, channels, etc) and press OK.
  3. In this step, you should see your LSL stream marked as Working LSL stream
  4. Add as many LSL streams as you want to the workspace and close the dialog by clicking OK.

The LSL configuration will be saved for future sessions to avoid repeating the previous steps after restarting the Platform.

After restarting a LSL stream (e.g., power off an amplifier and then start recording again) the LSL UID of the stream changes. Thus, MEDUSA requires to add the LSL stream to the workspace again by default, repeating the previous steps. However, v2023.1 introduced a new search mode called "weak search" to avoid this this problem. Activate this mode in the action menu if you are not going to use several LSL streams at the same time with the same name. This will save you time in preparing everything for your experiments..

Great! Now that we have a LSL signal being monitored, we can proceed to visualize our signal in real-time.

  1. Inside the panel REAL TIME PLOTS, press the button to configure the visualization.
  2. In this configuration, you can customize the number of different plots to be displayed in real-time by adding and removing elements inside the grid.
  3. As an example, we are going to create two different visualizations: temporal and spectral.
    1. Fix the grid size to 8×8.
    2. Press to create the first element and drag and drop its corner to occupy half of the screen.
    3. Then, double-click the element we just created to configure it. Select TimePlotMultichannel to create a temporal multi-channel visualization (as an EEG).
    4. Press to create the second element and drag and drop its corner to occupy the rest of the screen.
    5. Double-click the element we just created and select PSDPlot to create a single-channel spectral visualization of the power spectral density (PSD).
    6. Press OK to apply the changes.
  4. Press the button to visualize the charts.
  5. You should now be able to see the desired charts in real-time!

Check the complete guide of the implemented real-time plots in the panels guide.

Download an app

We are now ready to download our first app! In MEDUSA©, apps are distributed in the App Market. There you can download different public apps, contribute with your own apps or manage your private developments, which are linked to your account. Let's do this:

  1. Click here to visit the app market.
  2. Make sure to log in to your account before proceed.
  3. Search for the app you want to download. In this case, we are going to click on the Recorder app.
  4. Go to the tab Downloads and download the latest version by clicking the download button.
    5. If the website says you are not authorized to download the app is because you have not logged in!
  5. Wait until your web browser finished downloading the .app file (i.e., rec.app).
  6. In MEDUSA© Platform, click on the button inside the APPLICATIONS panel.
  7. Find the downloaded .app file and select it.
  8. MEDUSA© Platform will install the app and link it to your account. When installed, the icon for the app will be displayed in the APPLICATIONS panel.

Run the experiment

Once you installed the Recording app, we can perform the experiment.

  1. Select the Recording app by clicking onto their icon inside the APPLICATIONS panel.
  2. You can configure the app settings by clicking the button. Please, refer to the documentation of each app to know more about the configuration options. In the case of the Recording app, the configuration window let us establish the duration of the basal recording.
  3. Now, press the button to start the app. You can pause or stop the experiment whenever you want.
  4. When the paradigm finishes, press the button to stop the app and save the signal together with the paradigm details.
Configuring and running an app

Learn more

I bet you are left wanting to learn more, right? If you are interested in creating your own application for MEDUSA©, check the following tutorials:

  1. Develop your custom app. Learn to program a custom application for MEDUSA© using PyQt and/or Unity. Use the latter when you need to control the refresh rate of the screen to guarantee a strictly exact synchronization between the stimuli and the EEG registering. There, we teach you how to control the refresh rate with Unity and communicate with MEDUSA© via TCP/IP protocol.
  2. How to contribute. Learn how to upload app versions, tutorials and descriptions to your author page!

Or maybe, if you are more interested in knowing more about the classes and functionalities of MEDUSA©, you could check our detailed descriptions for:

  1. Plots panel.
  2. Log panel.
  3. App panel.
  4. TCP/IP communication.

    5. ... and more!