PyMODA is a Python implementation of MODA (Multiscale Oscillatory Dynamics Analysis). The user interface is written using PyQt5, and the algorithms are mostly packaged as Python libraries from the existing MATLAB code.
PyMODA is cross-platform and does not require any paid software. To get started, see the User Guide or the Developer Guide.
PyMODA does not yet offer all the functionality available in MODA. This table shows the current status of different features.
Window | Functionality | MATLAB-packaged library | Python implementation |
---|---|---|---|
Time-Frequency Analysis | Wavelet transform | ✔️ | Mostly written |
Time-Frequency Analysis | Windowed Fourier transform | ✔️ | Partially written |
Wavelet Phase Coherence | Phase coherence | ✔️ | Some surrogates written, needs testing |
Ridge Extraction and Filtering | Extract ridges | ✔️ | Not implemented |
Ridge Extraction and Filtering | Bandpass filter | Not implemented | ✔️ |
Wavelet Bispectrum Analysis | Bispectrum analysis | ✔️ | Not implemented |
Dynamical Bayesian Inference | Bayesian inference | Not implemented | Written, not working |
This guide is aimed at users wishing to set up and run PyMODA. If you're interested in modifying or contributing to the program, you should use the Developer Guide.
Tip: If you experience any problems, check the Common Issues document.
- Python 3.6 or 3.7. Scientific distributions of Python are not officially supported.
- MATLAB Runtime, version R2019a (9.6). The runtime does not require a license.
⚠️ Do not use a newer version of the MATLAB Runtime. MATLAB-packaged libraries are neither forward nor backward compatible.
Note: Python 3.8 will not be supported until MATLAB R2020a launches.
PyMODA should run on Windows, macOS and Linux. Linux performs slightly better than Windows (see comparison).
Note: You should ensure that you are familiar with the core knowledge before proceeding.
PyMODA can be downloaded as a .zip file.
- Click here to download the .zip file.
- Extract the zip file to a desired location.
- For simplicity of instructions, rename the folder to
PyMODA
.
⚠️ Do not placePyMODA
in a folder which requires admin permissions, such asC:\Program Files
.
When the code is downloaded and Python is installed, you'll need to install the dependencies.
Open a terminal in the PyMODA
folder and run python packages/install.py
. When prompted, you will then need to press the Enter
key to proceed.
⚠️ For security reasons, do not run this command with elevated permissions.
To start PyMODA, run python src/main.py
in the PyMODA
folder.
⚠️ Linux users also need to specify the path to the MATLAB Runtime using a command-line argument (see command-line arguments).
In the launcher window, click "Create shortcut" to create a shortcut to easily open PyMODA. This has different behaviour on different operating systems.
⚠️ The shortcut will need to be recreated if the path to the PyMODA folder is changed, if the folder is renamed, or if the path to the Python interpreter changes.
A desktop shortcut will be created, which launches PyMODA with the current Python interpreter. If a shortcut already exists, it will be replaced.
An alias will be created, which adds the terminal command pymoda
to launch PyMODA with the current Python interpreter. The alias will be added to ~/.bashrc
for Bash, and if Zsh is installed, to ~/.zshrc
. If the alias already exists, it will be replaced.
Note: This will not take effect in currently open shells. Open a new terminal to try it out.
Tip: If the
-runtime
argument was provided to the instance of PyMODA which created the alias, it does not need to specified when using thepymoda
command.
PyMODA checks for updates occasionally, and shows a blue message in the launcher window if updates are available.
Tip: You can press
Ctrl
+U
to trigger a check for updates.
To apply an update automatically, press the "Update now" button and accept the confirmation. A dialog will show the download progress, and PyMODA will automatically re-open after the update is complete.
Note: If you've made modifications to the code, you should use Git instead of the built-in updater.
If an update fails to apply or introduces a new problem, the previous version of PyMODA can be restored from PyMODA/backup
. Just copy all of the files and folders from PyMODA/backup
and paste them into PyMODA
, overwriting if applicable.
When performing multiple discrete calculations - for example, the wavelet transform of 6 signals - PyMODA uses multiprocessing to greatly increase efficiency by allocating different calculations to different CPU cores.
Therefore, it is more efficient to transform multiple signals if possible. Efficiency will plateau when the number of signals is higher than the number of CPU cores.
The AMD Ryzen 3700X is an 8-core, 16-thread CPU. These tests were run on Manjaro Linux.
Operation | Total time: individually ("Transform Single" for all) | Total time: simultaneously ("Transform All") | Performance improvement |
---|---|---|---|
WT on 32 signals | 134s | 19.1s | x7.0 |
The Intel i7-6700 is a 4-core, 8-thread CPU. These tests were run on KDE neon.
Operation | Total time: individually ("Transform Single" for all) | Total time: simultaneously ("Transform All") | Performance improvement |
---|---|---|---|
WT on 2 signals | 10s | 5.4s | x1.9 |
WT on 6 signals | 30s | 8.4s | x3.6 |
WT on 32 signals | 160s | 43.1s | x3.7 |
Linux performs slightly better than Windows with a small number of signals, and significantly better with many signals.
Operating system | Time: WT on 1 signal | Time: WT on 32 signals |
---|---|---|
Windows 10 | 4.7s | 33.1s |
Manjaro Linux | 4.2s | 19.1s |
Operating system | Time: WT on 6 signals | Time: WT on 32 signals |
---|---|---|
Windows 10 (VM) | 17.5s | 82s |
Manjaro Linux (VM) | 17.4s | 74s |