Installation#

This guide covers the installation of eegprep and its dependencies.

System Requirements#

Before installing eegprep, ensure your system meets the following requirements:

  • Python: 3.10 or higher

  • pip: Latest version (for pip installation)

  • conda: Latest version (for conda installation, optional)

  • Operating System: Linux, macOS, or Windows

  • RAM: Minimum 4GB (8GB+ recommended for large datasets)

  • Disk Space: At least 500MB for installation and dependencies

Installation Methods#

Using conda#

If you prefer conda, you can install eegprep from the conda-forge channel:

conda install -c conda-forge eegprep

To create a new conda environment with eegprep:

conda create -n eegprep-env python=3.10 eegprep
conda activate eegprep-env

From Source#

To install eegprep from source for development:

git clone https://github.com/sccn/eegprep.git
cd eegprep
pip install -e .

The -e flag installs the package in editable mode, allowing you to modify the source code and see changes immediately.

Optional Dependencies#

eegprep has several optional dependencies that enable additional functionality:

PyTorch (for GPU acceleration)#

To use GPU-accelerated processing with PyTorch:

pip install torch

For CUDA support (NVIDIA GPUs):

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

For CPU-only PyTorch:

pip install torch --index-url https://download.pytorch.org/whl/cpu

EEGLAB I/O Support#

To enable reading and writing EEGLAB .set files:

pip install eeglabio

MNE-Python Integration#

For integration with MNE-Python:

pip install mne

Documentation Building#

To build the documentation locally:

pip install sphinx sphinx-rtd-theme sphinx-autodoc-typehints

All Optional Dependencies#

To install all optional dependencies at once:

pip install eegprep[all]

Or with specific extras:

pip install eegprep[torch,mne,docs]

Verification#

After installation, verify that eegprep is correctly installed by running:

import eegprep
print(eegprep.__version__)

You should see the version number printed without any errors.

To verify all core modules are available:

from eegprep import (
    pop_loadset,
    pop_saveset,
    clean_artifacts,
    iclabel,
    pop_resample,
    pop_reref,
    topoplot
)
print("All core modules imported successfully!")

Troubleshooting#

Import Errors#

Problem: ModuleNotFoundError: No module named 'eegprep'

Solution: Ensure eegprep is installed:

pip install eegprep

If installing from source, ensure you’re in the correct directory and use:

pip install -e .

Version Conflicts#

Problem: Conflicts with NumPy, SciPy, or other dependencies

Solution: Create a fresh virtual environment:

python -m venv eegprep_env
source eegprep_env/bin/activate  # On Windows: eegprep_env\Scripts\activate
pip install eegprep

PyTorch Installation Issues#

Problem: PyTorch installation fails or GPU not detected

Solution:

  1. Check your CUDA version:

nvidia-smi

  1. Install the matching PyTorch version from https://pytorch.org/get-started/locally/

  2. Verify PyTorch installation:

import torch
print(torch.cuda.is_available())

EEGLAB File Format Issues#

Problem: Cannot read .set files

Solution: Install eeglabio:

pip install eeglabio

Then verify:

from eegprep import pop_loadset
# Should work without errors

Memory Issues#

Problem: Out of memory errors when processing large datasets

Solution:

  1. Process data in chunks or epochs

  2. Reduce the number of channels if possible

  3. Increase available RAM or use a machine with more memory

  4. Use GPU acceleration if available

Getting Help#

If you encounter issues not covered here:

  1. Check the FAQ section

  2. Review the Common Issues guide

  3. Visit the GitHub Issues page

  4. Check the API Documentation

Next Steps#

After successful installation, proceed to the Quick Start guide to learn how to use eegprep.