Getting started
Thank you so much for trying MEDUSA©, you will not regret!
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.
Installation
Python installation
MEDUSA© requires to have a Python interpreter previously installed in your system. In particular, MEDUSA© Platform v2024
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).
This is the recommended installation for most users. Follow the steps below to install MEDUSA© Platform
:
- Download the latest version of the installer from the home page.
- Run the installer granting admin privilidges when asked.
- Navigate through the installer by clicking
Next
- 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 clickNext
. - 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. - The installation download MEDUSA, start and download all the Python packages needed for MEDUSA© to run. After the installation, close the installation window.
- Congratulations! You have already installed MEDUSA©.
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.
To run MEDUSA©, just click on the shortcut that has been created on your desktop, or alternatively search 'MEDUSA' in the Windows search bar.
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:
- Download the latest version of
Signal Generator
from here. - Navigate through the installer to install the program.
Once installed, open Signal Generator
to generate the fake signal:
- Customize the stream name, number of channels and other options (if desired).
- Press
Start
to stream the fake signal through LSL. - 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.
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:
- In
Available LSL streams
, select your LSL signal (the one we connected/generated before), and press thebutton to indicate you want to use it.
- Configure the stream settings (e.g., name, type of signal, channels, etc) and press
OK
. - In this step, you should see your LSL stream marked as
Working LSL stream
- 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.
- Inside the panel
REAL TIME PLOTS
, press thebutton to configure the visualization.
- 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.
- As an example, we are going to create two different visualizations: temporal and spectral.
- Fix the grid size to 8×8.
- Press
to create the first element and drag and drop its corner to occupy half of the screen.
- Then, double-click the element we just created to configure it. Select
TimePlotMultichannel
to create a temporal multi-channel visualization (as an EEG). - Press
to create the second element and drag and drop its corner to occupy the rest of the screen.
- Double-click the element we just created and select
PSDPlot
to create a single-channel spectral visualization of the power spectral density (PSD). - Press
OK
to apply the changes. - Press the
button to visualize the charts.
- 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:
- Click here to visit the app market.
- Make sure to log in to your account before proceed.
- Search for the app you want to download. In this case, we are going to click on the
Recorder
app. - Go to the tab
Downloads
and download the latest version by clicking thedownload button.
- Wait until your web browser finished downloading the
.app
file (i.e.,rec.app
). - In MEDUSA© Platform, click on the
button inside the
APPLICATIONS
panel. - Find the downloaded
.app
file and select it. - 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.
- Select the
Recording
app by clicking onto their icon inside theAPPLICATIONS
panel. - 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. - Now, press the
button to start the app. You can pause
or stop
the experiment whenever you want.
- When the paradigm finishes, press the
button to stop the app and save the signal together with the paradigm details.
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:
- 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.
- 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:
- Plots panel.
- Log panel.
- App panel.
- TCP/IP communication.
... and more!