Library providing Python implementations of MODA's algorithms.
Project description
PyMODAlib
Introduction
PyMODAlib is a Python library containing the algorithms used by PyMODA. With PyMODAlib, you can write Python scripts to perform the same calculations as PyMODA.
Some of PyMODAlib's algorithms are MATLAB-packaged libraries, while some are Python translations of algorithms belonging to MODA.
License
You may use, distribute and modify this software under the terms of the GNU General Public License v3.0. See LICENSE.
References and citations
To cite PyMODAlib or view its references, please see the DOI at Zenodo.
User Guide
This section describes how to get started with PyMODAlib.
For a full API reference, please see PyMODAlib's ReadTheDocs page, which shows the parameters and output for every function.
Prerequisites
The following software is required to use all of PyMODAlib's functionality:
- Python 3.6 or higher.
- MATLAB Runtime, version 9.6.
Note: PyMODAlib can be used without the MATLAB Runtime, but some functions require it.
Installing PyMODAlib
PyMODAlib can be installed using pip
. Open a terminal and run:
pip install pymodalib
Tip: on macOS/Linux, replace
pip
with the correct command for your system (e.g.pip3
).
Updating PyMODAlib
PyMODAlib will be updated regularly. To update your installed version, open a terminal and run:
pip install -U pymodalib
Current status
PyMODAlib
is still in development. Currently, the features implemented are:
- Wavelet transform.
- Wavelet phase coherence.
- Group coherence for one or two groups, with inter-subject surrogates.
- Detecting harmonics.
- Downsampling.
:warning: Some functions may not be fully stable, and may change before
v1.0.0
.
Getting started
Examples
There are examples of using PyMODAlib's functionality in the examples directory.
To download the dependencies required to run the examples, open a terminal and run:
pip install -U pymodalib matplotlib
To try the examples, download the PyMODAlib repository as a zip file or by using git clone
, then run Python files from the examples
subfolders.
PyMODAlib cache
The group coherence functions use a very large quantity of RAM. To mitigate this problem for machines with smaller RAM capacities, they will allocate arrays which are cached to disk. This may result in significant disk usage.
By default, PyMODAlib will use a folder named .pymodalib
inside your home directory for its cache. However, it will show a RuntimeWarning
unless you set the location manually. This warning is intended to make users aware of the risks of placing the cache folder on an SSD.
:warning: If the cache folder is on an SSD, it may reduce the lifespan of the SSD.
Setting the cache location
To set the location of the cache folder manually, use the PYMODALIB_CACHE
environment variable. Instructions for different operating systems are below.
Windows
On Windows, press the start button and type "environment" until you can select "Edit the system environment variables". Then click "Environment variables" and click "New" in the window which appears. Name it "PYMODALIB_CACHE" and set the location by browsing for a folder.
Now restart your IDE or terminal.
Linux
Run the following commands, replacing <cache_folder>
with the absolute path to your chosen folder:
echo "export PYMODALIB_CACHE=<cache_folder>" >> ~/.bashrc
source ~/.bashrc
macOS
Run the following commands, replacing <cache_folder>
with the absolute path to your chosen folder:
echo "export PYMODALIB_CACHE=<cache_folder>" >> ~/.bash_profile
source ~/.bash_profile
Developer guide
This guide is aimed at developers interested in contributing to PyMODAlib.
Downloading the code
To download the code, you should fork the repository and clone your fork.
Installing the requirements
Open a terminal in the PyMODAlib
folder and run:
pip install -r requirements.txt
pip install matplotlib pre-commit
Git hooks
Git hooks are used to automatically format modified Python files with black
when a commit is made. This ensures that the code follows a uniform style.
To install the Git hooks, open a terminal in the PyMODAlib
folder and run:
pre-commit install
Tip: If this causes an error, try
python -m pre-commit install
.
When you make a commit, the modified Python files will be formatted if necessary. If this occurs, you'll need to repeat your git add
and git commit
commands to make the commit.
Tip: You can still use PyCharm's auto-formatter while writing code. Although it sometimes disagrees with
black
,black
will undo its changes at commit-time, so no harm is done.
Developing PyMODAlib
When developing PyMODAlib, you can test your changes by installing the library locally in "editable" mode. From the root of the repository, run:
pip install -e .
Note: After making changes to PyMODAlib, you don't need to run the
pip install
command again. Any Python script which importspymodalib
will reflect the changes immediately.
Switching back to the release version of PyMODAlib is simple:
pip uninstall pymodalib -y
pip install -U pymodalib
Project structure
The public-facing API is located in the algorithms
package. This package contains wrappers for the actual implementations, which can be found in the implementations
package.
This structure allows the implementation to be easily changed, while ensuring that the API remains backwards-compatible.
__init__.py
In pymodalib.__init__.py
, many functions are imported from the algorithms
package. This allows users to more easily find useful functions: for example, they can use pymodalib.wavelet_transform
instead of pymodalib.algorithms.wavelet.wavelet_transform
.
implementations
package
The implementations
package contains a matlab
package and a python
package. The matlab
package contains wrappers for algorithms supplied by MATLAB-packaged libraries, while the python
package contains algorithms implemented purely in Python.
MATLAB-packaged libraries
Currently, the MATLAB-packaged libraries are not required if functionality that depends on them is not used. MATLAB-packaged libraries are installed by downloading PyMODA and installing its dependencies.
Functions that require the MATLAB Runtime will be marked with the matlabwrapper
decorator. This will check if the correct version of the MATLAB Runtime is installed.
Note: MATLAB libraries are still incompatible with Python 3.8. When MATLAB R2020a releases, Python 3.8 support will be added but the current required version of the MATLAB Runtime will no longer be supported (users will need to upgrade to the newer Runtime).
Packaging the project for PyPI
This section describes how to publish an update to PyPI.
From the documentation:
rm -r dist/
python setup.py sdist
python setup.py bdist_wheel
twine upload dist/*
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for PyMODAlib-0.4.0b1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fd27324531fa722deed16294861e4dfbc5780f51386802b7195a068dd8420804 |
|
MD5 | 89a41aae46cbc43abaaf0806942877d8 |
|
BLAKE2b-256 | b97761fc78a252a8b6efeaa999996b0cc31ce93c01d0c339de1eb8f4dbfda46e |