natMEEG - Naturalistic M/EEG data analysis

Latest released version: v1.6.10 (2025-04-15). The current branch is under development toward the next release.

Formerly named pyEEG

natMEEG is a library for processing M/EEG data built mostly on top of MNE-Python and scikit-learn. It is designed for data collected with naturalistic stimuli, so it works with continuous recordings rather than trial-based designs. It supports analysis of continuous M/EEG and generation of temporal response functions from continuous signals or real-valued events (for example, word-level or phoneme-level features).

You can find the documentation here.

⚠️Note:

• This code repository is actively maintained as part of the natMEEG project. The library provides tools for computing TRFs (Temporal Response Functions) with the TRFEstimator class in pyeeg/models/, which implements memory-efficient and accelerated computation for handling multiple epochs or multiple subjects.
• The library is suitable for both research and production use.
• The project was formerly known as pyEEG and has been rebranded to natMEEG to better reflect its focus on naturalistic M/EEG data analysis.

Installation

Dependencies

natMEEG requires:

• Python (>= 3.10)
• psutil
• tqdm
• NumPy
• SciPy
• scikit-learn
• matplotlib
• h5py
• pandas
• mne (>= 0.16) [optional]

To generate the doc, Python package sphinx (>= 1.1.0), sphinx_rtd_theme and nbsphinx are required.

User Installation

From PyPI

You can install the package from PyPI using pip:

pip install natmeeg

If you want to install docs building dependencies, you can do:

pip install natmeeg[docs]

If you want to install the package with all dependencies (including MNE), you can do:

pip install natmeeg[full]

From Source

If you prefer to install the package from source, you can clone the repository or download release archive or also use the source distribution (.tar.gz file from PyPi) and build it locally. There is a C-extension that needs to compile, so you need to have a C compiler installed on your machine.

From terminal, cd in root directory of the library after cloning this repository (directory containing pyproject.toml file).

To get the package installed only through symbolic links, namely so that you can modify the source code and use modified versions at will when importing the package in your python scripts do:

pip install -e .

Otherwise, for a standard installation, you can run:

pip install .

Windows Users

There are C-extensions in the library, so you need to have a C compiler installed on your machine. If the default compiler does not work, you can try to install Visual Studio Build Tools and try again.

Optionally try with MinGW, making sure after instalation of it to add the path to mingw/bin in your PATH environment variable. You can check if it is correctly installed by running the following command in your terminal:

gcc --version

If this build tool is available it should be detected during build process (running pip install ., pip install -e . or python -m build).

Usage

The most common usage of the library is to compute temporal response functions (TRF) from continuous M/EEG data. The library provides a TRFEstimator class that allows you to fit a TRF model to your data. The TRF model can be used to predict the M/EEG signal from a stimulus signal (e.g. a continuous audio signal or a sequence of word features):

from pyeeg import TRFEstimator

trf = TRFEstimator(tmin=-0.2, tmax=0.5, srate=fs, alpha=100.0) # TRF between -200ms and 500ms, regularization parameter alpha=100.0
trf.fit(X, y) # assuming data loaded: X is the stimulus signal, y is the M/EEG signal, they must have the same number of samples (rows)
print(trf.score(X, y)) # Normally you would use a separate test set for scoring
trf.plot() # plot the TRF

Examples

See files in examples/.

Computing Envelope TRF and spatial map from CCA

See examples/CCA_envelope.ipynb

Computing Word-feature TRF

See examples/TRF_wordonsets.ipynb

Working with Word vectors

See examples/import_WordVectors.ipynb

Documentation

You can generate an offline HTML version, or a PDF file of all the docs by following the following instructions (HTML pages are easier to navigate in and prettier than the PDF thanks to the nice theme brought by sphinx_rtd_theme).

Generate the documentation

To generate the documentation you will need sphinx to be installed in your Python environment, as well as the extension nbsphinx (for Jupyter Notebook integration) and the theme package sphinx_rtd_theme. Install those with:

pip install natMEEG[docs]

You can access the doc as HTML or PDF format. First get the source documentation files by cloning the repository or downloading the release archive. The documentation is located in the docs folder. To generate the documentation HTML pages, type in a terminal:

For Unix environment (from root directory, as it uses the Makefile):

make doc

For Windows environment (from docs folder, where make.bat is located):

cd docs
make.bat html

Then you can open the docs/build/html/index.html page in your favourite browser.

And for PDF version, simply use docpdf instead of doc above. Then open docs/build/latex/natMEEG.pdf in a PDF viewer.

Note: The PDF documentation can only be generated if latex and latxmk are present on the machine

To clean files created during build process (can be necessary to re-build the documentation):

make clean

License

This project is licensed under the terms of the GPL-3.0 license. See the LICENSE file for details.

Citation

Weissbart, H. Natmeeg - M/EEG Data Analysis in Naturalistic Context. 1.6.10, Zenodo, 9 Sept. 2025, https://doi.org/10.5281/zenodo.17084930.