| Name | torcheeg JSON |
| Version |
1.1.2
JSON |
| download |
| home_page | https://github.com/tczhangzhi/torcheeg |
| Summary | TorchEEG is a library built on PyTorch for EEG signal analysis. TorchEEG aims to provide a plug-and-play EEG analysis tool, so that researchers can quickly reproduce EEG analysis work and start new EEG analysis research without paying attention to technical details unrelated to the research focus. |
| upload_time | 2024-05-06 14:23:37 |
| maintainer | None |
| docs_url | None |
| author | TorchEEG Team |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
pytorch
eeg
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
TorchEEG
========
|PyPI Version| |Docs Status| |Downloads| |Join the Chat|
`Documentation <https://torcheeg.readthedocs.io/>`__ \| `TorchEEG
Examples <https://github.com/torcheeg/torcheeg/tree/main/examples>`__ \|
`Paper <https://www.sciencedirect.com/science/article/pii/S0957417424004159>`__
TorchEEG is a library built on PyTorch for EEG signal analysis. TorchEEG
aims to provide a plug-and-play EEG analysis tool, so that researchers
can quickly reproduce EEG analysis work and start new EEG analysis
research without paying attention to technical details unrelated to the
research focus.
TorchEEG specifies a unified data input-output format (IO) and implement
commonly used EEG databases, allowing users to quickly access benchmark
datasets and define new custom datasets. The datasets that have been
defined so far include emotion recognition and so on. According to
papers published in the field of EEG analysis, TorchEEG provides data
preprocessing methods commonly used for EEG signals, and provides
plug-and-play API for both offline and online pre-proocessing. Offline
processing allow users to process once and use any times, speeding up
the training process. Online processing allows users to save time when
creating new data processing methods. TorchEEG also provides deep
learning models following published papers for EEG analysis, including
convolutional neural networks, graph convolutional neural networks, and
Transformers.
Installation
------------
TorchEEG depends on PyTorch, please complete the installation of PyTorch
according to the system, CUDA version and other information:
.. code:: shell
# Conda
# please refer to https://pytorch.org/get-started/locally/
# e.g. CPU version
conda install pytorch==1.11.0 torchvision torchaudio cpuonly -c pytorch
# e.g. GPU version
conda install pytorch==1.11.0 torchvision torchaudio cudatoolkit=11.3 -c pytorch
# Pip
# please refer to https://pytorch.org/get-started/previous-versions/
# e.g. CPU version
pip install torch==1.11.0+cpu torchvision==0.12.0+cpu torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cpu
# e.g. GPU version
pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cu113
Anaconda
~~~~~~~~
TorchEEG supports installing with conda! You can
simply install TorchEEG using Anaconda, just run the following command:
.. code:: shell
conda install -c tczhangzhi -c conda-forge torcheeg
Pip
~~~
TorchEEG allows pip-based installation, please use the following
command:
.. code:: shell
pip install torcheeg
Nightly
~~~~~~~
In case you want to experiment with the latest TorchEEG features which
are not fully released yet, please run the following command to install
from the main branch on github:
.. code:: shell
pip install git+https://github.com/tczhangzhi/torcheeg.git
Plugin
~~~~~~
TorchEEG provides plugins related to graph algorithms for converting EEG
in datasets into graph structures and analyzing them using graph neural
networks. This part of the implementation relies on PyG.
If you do not use graph-related algorithms, you can skip this part of
the installation.
.. code:: shell
# Conda
# please refer to https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html
conda install pyg -c pyg
# Pip
# please refer to https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html
# e.g. CPU version
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-1.11.0+cpu.html
# e.g. GPU version
pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-1.11.0+cu113.html
More About TorchEEG
-------------------
At a granular level, PyTorch is a library that consists of the following
components:
+----------------------------------------+-----------------------------+
| Component | Description |
+========================================+=============================+
| `torcheeg.io <https://torcheeg.readthe | A set of unified input and |
| docs.io/en/latest/torcheeg.io.html>`__ | output API is used to store |
| | the processing results of |
| | various EEG databases for |
| | more efficient and |
| | convenient use. |
+----------------------------------------+-----------------------------+
| `torcheeg.da | The packaged benchmark |
| tasets <https://torcheeg.readthedocs.i | dataset implementation |
| o/en/latest/torcheeg.datasets.html>`__ | provides a multi-process |
| | preprocessing interface. |
+----------------------------------------+-----------------------------+
| `torcheeg.transf | Extensive EEG preprocessing |
| orms <https://torcheeg.readthedocs.io/ | methods help users extract |
| en/latest/torcheeg.transforms.html>`__ | features, construct EEG |
| | signal representations, and |
| | connect to commonly used |
| | deep learning libraries. |
+----------------------------------------+-----------------------------+
| `torcheeg.model_selection | Extensive dataset |
| <https://torcheeg.readthedocs.io/en/la | partitioning methods for |
| test/torcheeg.model_selection.html>`__ | users to experiment with |
| | different settings. |
+----------------------------------------+-----------------------------+
| `torchee | Extensive baseline method |
| g.models <https://torcheeg.readthedocs | reproduction. |
| .io/en/latest/torcheeg.models.html>`__ | |
+----------------------------------------+-----------------------------+
Implemented Modules
-------------------
We list currently supported datasets, transforms, data splitting, and
deep learning models by category.
**Datasets:** All datasets rely on a set of efficient IO APIs,
`torcheeg.io <https://torcheeg.readthedocs.io/en/latest/torcheeg.io.html>`__,
to store data preprocessing results on disk and read them quickly during
training. Data preprocessing and storage support multiprocessing (speed
up!).
- `AMIGOS
dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#amigosdataset>`__
from Miranda-Correa et al.: `AMIGOS: A dataset for affect,
personality and mood research on individuals and
groups <https://ieeexplore.ieee.org/abstract/document/8554112/>`__.
- `DREAMER
dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#dreamerdataset>`__
from Katsigiannis et al.: `DREAMER: A database for emotion
recognition through EEG and ECG signals from wireless low-cost
off-the-shelf
devices <https://ieeexplore.ieee.org/abstract/document/7887697>`__.
- `SEED
dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#seeddataset>`__
from Zheng et al.: `Investigating critical frequency bands and
channels for EEG-based emotion recognition with deep neural
networks <https://ieeexplore.ieee.org/abstract/document/7104132>`__.
- `DEAP
dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#deapdataset>`__
from Koelstra et al.: `DEAP: A database for emotion analysis; using
physiological
signals <https://ieeexplore.ieee.org/abstract/document/5871728>`__.
- `MAHNOB
dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#mahnobdataset>`__
from Soleymani et al.: `A multimodal database for affect recognition
and implicit
tagging <https://ieeexplore.ieee.org/abstract/document/5975141>`__.
**Transforms:** TorchEEG provides extensive data transformation tools to
help users build EEG data representations suitable for a variety of task
formulation and a variety of model structures.
- Feature Engineering:
`BandDifferentialEntropy <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-banddifferentialentropy>`__,
`BandPowerSpectralDensity <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandpowerspectraldensity>`__,
`BandMeanAbsoluteDeviation <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandmeanabsolutedeviation>`__,
`BandKurtosis <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandkurtosis>`__,
`BandSkewness <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandskewness>`__,
`Concatenate <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-concatenate>`__
- General Operation:
`PickElectrode <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-pickelectrode>`__,
`MeanStdNormalize <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-meanstdnormalize>`__,
`MinMaxNormalize <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-minmaxnormalize>`__
- For CNN:
`To2d <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-to2d>`__,
`ToGrid <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-togrid>`__,
`ToInterpolatedGrid <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-tointerpolatedgrid>`__
- For GNN:
`ToG <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.pyg.html#transforms-tog>`__
- For Augmentation:
`Resize <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.torch.html#transforms-resize>`__,
`RandomNoise <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.torch.html#transforms-randomnoise>`__,
`RandomMask <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.torch.html#transforms-randommask>`__
- For Label Construction:
`Select <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.label.html#transforms-select>`__,
`Binary <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.label.html#transforms-binary>`__,
`BinariesToCategory <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.label.html#transforms-binariestocategory>`__
**Data Splitting:** In current research in the field of EEG analysis,
there are various settings based on different considerations for data
partitioning. Please choose a reasonable data division method according
to the research focus:
- Subject Dependent:
`KFoldPerSubjectGroupbyTrial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#kfoldpersubjectgroupbytrial>`__,
`train_test_split_per_subject_groupby_trial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#train-test-split-per-subject-groupby-trial>`__
- Subject Independent:
`LeaveOneSubjectOut <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#leaveonesubjectout>`__
- Conventional:
`KFold <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#kfold>`__,
`train_test_split <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#train-test-split>`__,
`KFoldGroupbyTrial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#kfoldgroupbytrial>`__,
`train_test_split_groupby_trial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#train-test-split-groupby-trial>`__
**Models:** Coming soon after pushing to align with the official
implementation or description. If the current version of
`CNNs <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.cnn.html>`__,
`GNNs <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.gnn.html>`__
and
`Transformers <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.transformer.html>`__
is to be used, please refer to the implementation in
`torcheeg.models <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.html>`__.
Quickstart
----------
In this quick tour, we highlight the ease of starting an EEG analysis
research with only a few lines.
The ``torcheeg.datasets`` module contains dataset classes for many
real-world EEG datasets. In this tutorial, we use the ``DEAP`` dataset.
We first go to the official website to apply for data download
permission according to the introduction of `DEAP
dataset <https://www.eecs.qmul.ac.uk/mmv/datasets/deap/>`__, and
download the dataset. Next, we need to specify the download location of
the dataset in the ``root_path`` parameter. For the DEAP dataset, we
specify the path to the ``data_preprocessed_python`` folder,
e.g. ``./tmp_in/data_preprocessed_python``.
.. code:: python
from torcheeg.datasets import DEAPDataset
from torcheeg import transforms
from torcheeg.datasets.constants import \
DEAP_CHANNEL_LOCATION_DICT
dataset = DEAPDataset(
io_path=f'./tmp_out/examples_pipeline/deap',
root_path='./tmp_in/data_preprocessed_python',
offline_transform=transforms.Compose([
transforms.BandDifferentialEntropy(apply_to_baseline=True),
transforms.ToGrid(DEAP_CHANNEL_LOCATION_DICT, apply_to_baseline=True)
]),
online_transform=transforms.Compose(
[transforms.BaselineRemoval(),
transforms.ToTensor()]),
label_transform=transforms.Compose([
transforms.Select('valence'),
transforms.Binary(5.0),
]),
num_worker=8)
The ``DEAPDataset`` API further contains three parameters:
``online_transform``, ``offline_transform``, and ``label_transform``,
which are used to modify samples and labels, respectively.
Here, ``offline_transform`` will only be called once when the dataset is
initialized to preprocess all samples in the dataset, and the processed
dataset will be stored in ``io_path`` to avoid time-consuming repeated
transformations in subsequent use. If offline preprocessing is a
computationally intensive operation, we also recommend setting multi-CPU
parallelism for offline_transform, e.g., set ``num_worker`` to 4.
``online_transform`` is used to transform samples on the fly. Please use
``online_transform`` if you don’t want to wait for the preprocessing of
the entire dataset (suitable for scenarios where new ``transform``
algorithms are designed) or expect data transformation with randomness
each time a sample is indexed.
Next, we need to divide the dataset into a training set and a test set.
In the field of EEG analysis, commonly used data partitioning methods
include k-fold cross-validation and leave-one-out cross-validation. In
this tutorial, we use k-fold cross-validation on the entire dataset
(``KFold``) as an example of dataset splitting.
.. code:: python
from torcheeg.model_selection import KFoldGroupbyTrial
k_fold = KFoldGroupbyTrial(n_splits=10,
split_path='./tmp_out/examples_pipeline/split',
shuffle=True,
random_state=42)
We loop through each cross-validation set, and for each one, we
initialize the CCNN model and define its hyperparameters. For instance,
each EEG sample contains 4-channel features from 4 sub-bands, and the
grid size is 9x9. We then train the model for 50 epochs using the
``ClassifierTrainer``.
.. code:: python
from torch.utils.data import DataLoader
from torcheeg.models import CCNN
from torcheeg.trainers import ClassifierTrainer
import pytorch_lightning as pl
for i, (train_dataset, val_dataset) in enumerate(k_fold.split(dataset)):
train_loader = DataLoader(train_dataset, batch_size=64, shuffle=True)
val_loader = DataLoader(val_dataset, batch_size=64, shuffle=False)
model = CCNN(num_classes=2, in_channels=4, grid_size=(9, 9))
trainer = ClassifierTrainer(model=model,
num_classes=2,
lr=1e-4,
weight_decay=1e-4,
accelerator="gpu")
trainer.fit(train_loader,
val_loader,
max_epochs=50,
default_root_dir=f'./tmp_out/examples_pipeline/model/{i}',
callbacks=[pl.callbacks.ModelCheckpoint(save_last=True)],
enable_progress_bar=True,
enable_model_summary=True,
limit_val_batches=0.0)
score = trainer.test(val_loader,
enable_progress_bar=True,
enable_model_summary=True)[0]
print(f'Fold {i} test accuracy: {score["test_accuracy"]:.4f}')
For more specific usage of each module, please refer to `the
documentation <(https://torcheeg.readthedocs.io/)>`__.
Releases and Contributing
-------------------------
TorchEEG is currently in beta; Please let us know if you encounter a bug
by filing an issue. We also appreciate all contributions.
If you would like to contribute new datasets, deep learning methods, and
extensions to the core, please first open an issue and then send a PR.
If you are planning to contribute back bug fixes, please do so without
any further discussion.
License
-------
TorchEEG has a MIT license, as found in the
`LICENSE <https://github.com/tczhangzhi/torcheeg/blob/main/LICENSE>`__
file.
Citation
--------
If you find this project useful for your research, please cite:
.. code:: latex
@article{zhang2024torcheeg,
title = {{TorchEEGEMO}: A deep learning toolbox towards {EEG}-based emotion recognition},
journal = {Expert Systems with Applications},
pages = {123550},
year = {2024},
issn = {0957-4174},
author = {Zhi Zhang and Sheng-hua Zhong and Yan Liu}
}
.. |PyPI Version| image:: https://badge.fury.io/py/torcheeg.svg
:target: https://pypi.python.org/pypi/torcheeg
.. |Docs Status| image:: https://readthedocs.org/projects/torcheeg/badge/?version=latest
:target: https://torcheeg.readthedocs.io/en/latest/?badge=latest
.. |Downloads| image:: https://pepy.tech/badge/torcheeg
:target: https://pepy.tech/project/torcheeg
.. |Join the Chat| image:: https://badges.gitter.im/torcheeg/community.svg
:target: https://gitter.im/torcheeg/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
Raw data
{
"_id": null,
"home_page": "https://github.com/tczhangzhi/torcheeg",
"name": "torcheeg",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "PyTorch, EEG",
"author": "TorchEEG Team",
"author_email": "tczhangzhi@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f4/d5/45047b7501d635076492c9eb619605d9b43ae68ab719c6db71c8e042b10a/torcheeg-1.1.2.tar.gz",
"platform": null,
"description": "TorchEEG\n========\n\n|PyPI Version| |Docs Status| |Downloads| |Join the Chat|\n\n`Documentation <https://torcheeg.readthedocs.io/>`__ \\| `TorchEEG\nExamples <https://github.com/torcheeg/torcheeg/tree/main/examples>`__ \\|\n`Paper <https://www.sciencedirect.com/science/article/pii/S0957417424004159>`__\n\nTorchEEG is a library built on PyTorch for EEG signal analysis. TorchEEG\naims to provide a plug-and-play EEG analysis tool, so that researchers\ncan quickly reproduce EEG analysis work and start new EEG analysis\nresearch without paying attention to technical details unrelated to the\nresearch focus.\n\nTorchEEG specifies a unified data input-output format (IO) and implement\ncommonly used EEG databases, allowing users to quickly access benchmark\ndatasets and define new custom datasets. The datasets that have been\ndefined so far include emotion recognition and so on. According to\npapers published in the field of EEG analysis, TorchEEG provides data\npreprocessing methods commonly used for EEG signals, and provides\nplug-and-play API for both offline and online pre-proocessing. Offline\nprocessing allow users to process once and use any times, speeding up\nthe training process. Online processing allows users to save time when\ncreating new data processing methods. TorchEEG also provides deep\nlearning models following published papers for EEG analysis, including\nconvolutional neural networks, graph convolutional neural networks, and\nTransformers.\n\nInstallation\n------------\n\nTorchEEG depends on PyTorch, please complete the installation of PyTorch\naccording to the system, CUDA version and other information:\n\n.. code:: shell\n\n # Conda\n # please refer to https://pytorch.org/get-started/locally/\n # e.g. CPU version\n conda install pytorch==1.11.0 torchvision torchaudio cpuonly -c pytorch\n # e.g. GPU version\n conda install pytorch==1.11.0 torchvision torchaudio cudatoolkit=11.3 -c pytorch\n\n # Pip\n # please refer to https://pytorch.org/get-started/previous-versions/\n # e.g. CPU version\n pip install torch==1.11.0+cpu torchvision==0.12.0+cpu torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cpu\n # e.g. GPU version\n pip install torch==1.11.0+cu113 torchvision==0.12.0+cu113 torchaudio==0.11.0 --extra-index-url https://download.pytorch.org/whl/cu113\n\nAnaconda\n~~~~~~~~\n\nTorchEEG supports installing with conda! You can\nsimply install TorchEEG using Anaconda, just run the following command:\n\n.. code:: shell\n\n conda install -c tczhangzhi -c conda-forge torcheeg\n\nPip\n~~~\n\nTorchEEG allows pip-based installation, please use the following\ncommand:\n\n.. code:: shell\n\n pip install torcheeg\n\nNightly\n~~~~~~~\n\nIn case you want to experiment with the latest TorchEEG features which\nare not fully released yet, please run the following command to install\nfrom the main branch on github:\n\n.. code:: shell\n\n pip install git+https://github.com/tczhangzhi/torcheeg.git\n\nPlugin\n~~~~~~\n\nTorchEEG provides plugins related to graph algorithms for converting EEG\nin datasets into graph structures and analyzing them using graph neural\nnetworks. This part of the implementation relies on PyG.\n\nIf you do not use graph-related algorithms, you can skip this part of\nthe installation.\n\n.. code:: shell\n\n # Conda\n # please refer to https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html\n conda install pyg -c pyg\n\n # Pip\n # please refer to https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html\n # e.g. CPU version\n pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-1.11.0+cpu.html\n # e.g. GPU version\n pip install torch-scatter torch-sparse torch-cluster torch-spline-conv torch-geometric -f https://data.pyg.org/whl/torch-1.11.0+cu113.html\n\nMore About TorchEEG\n-------------------\n\nAt a granular level, PyTorch is a library that consists of the following\ncomponents:\n\n+----------------------------------------+-----------------------------+\n| Component | Description |\n+========================================+=============================+\n| `torcheeg.io <https://torcheeg.readthe | A set of unified input and |\n| docs.io/en/latest/torcheeg.io.html>`__ | output API is used to store |\n| | the processing results of |\n| | various EEG databases for |\n| | more efficient and |\n| | convenient use. |\n+----------------------------------------+-----------------------------+\n| `torcheeg.da | The packaged benchmark |\n| tasets <https://torcheeg.readthedocs.i | dataset implementation |\n| o/en/latest/torcheeg.datasets.html>`__ | provides a multi-process |\n| | preprocessing interface. |\n+----------------------------------------+-----------------------------+\n| `torcheeg.transf | Extensive EEG preprocessing |\n| orms <https://torcheeg.readthedocs.io/ | methods help users extract |\n| en/latest/torcheeg.transforms.html>`__ | features, construct EEG |\n| | signal representations, and |\n| | connect to commonly used |\n| | deep learning libraries. |\n+----------------------------------------+-----------------------------+\n| `torcheeg.model_selection | Extensive dataset |\n| <https://torcheeg.readthedocs.io/en/la | partitioning methods for |\n| test/torcheeg.model_selection.html>`__ | users to experiment with |\n| | different settings. |\n+----------------------------------------+-----------------------------+\n| `torchee | Extensive baseline method |\n| g.models <https://torcheeg.readthedocs | reproduction. |\n| .io/en/latest/torcheeg.models.html>`__ | |\n+----------------------------------------+-----------------------------+\n\nImplemented Modules\n-------------------\n\nWe list currently supported datasets, transforms, data splitting, and\ndeep learning models by category.\n\n**Datasets:** All datasets rely on a set of efficient IO APIs,\n`torcheeg.io <https://torcheeg.readthedocs.io/en/latest/torcheeg.io.html>`__,\nto store data preprocessing results on disk and read them quickly during\ntraining. Data preprocessing and storage support multiprocessing (speed\nup!).\n\n- `AMIGOS\n dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#amigosdataset>`__\n from Miranda-Correa et al.: `AMIGOS: A dataset for affect,\n personality and mood research on individuals and\n groups <https://ieeexplore.ieee.org/abstract/document/8554112/>`__.\n- `DREAMER\n dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#dreamerdataset>`__\n from Katsigiannis et al.: `DREAMER: A database for emotion\n recognition through EEG and ECG signals from wireless low-cost\n off-the-shelf\n devices <https://ieeexplore.ieee.org/abstract/document/7887697>`__.\n- `SEED\n dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#seeddataset>`__\n from Zheng et al.: `Investigating critical frequency bands and\n channels for EEG-based emotion recognition with deep neural\n networks <https://ieeexplore.ieee.org/abstract/document/7104132>`__.\n- `DEAP\n dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#deapdataset>`__\n from Koelstra et al.: `DEAP: A database for emotion analysis; using\n physiological\n signals <https://ieeexplore.ieee.org/abstract/document/5871728>`__.\n- `MAHNOB\n dataset <https://torcheeg.readthedocs.io/en/latest/torcheeg.datasets.html#mahnobdataset>`__\n from Soleymani et al.: `A multimodal database for affect recognition\n and implicit\n tagging <https://ieeexplore.ieee.org/abstract/document/5975141>`__.\n\n**Transforms:** TorchEEG provides extensive data transformation tools to\nhelp users build EEG data representations suitable for a variety of task\nformulation and a variety of model structures.\n\n- Feature Engineering:\n `BandDifferentialEntropy <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-banddifferentialentropy>`__,\n `BandPowerSpectralDensity <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandpowerspectraldensity>`__,\n `BandMeanAbsoluteDeviation <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandmeanabsolutedeviation>`__,\n `BandKurtosis <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandkurtosis>`__,\n `BandSkewness <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-bandskewness>`__,\n `Concatenate <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-concatenate>`__\n- General Operation:\n `PickElectrode <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-pickelectrode>`__,\n `MeanStdNormalize <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-meanstdnormalize>`__,\n `MinMaxNormalize <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-minmaxnormalize>`__\n- For CNN:\n `To2d <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-to2d>`__,\n `ToGrid <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-togrid>`__,\n `ToInterpolatedGrid <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.numpy.html#transforms-tointerpolatedgrid>`__\n- For GNN:\n `ToG <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.pyg.html#transforms-tog>`__\n- For Augmentation:\n `Resize <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.torch.html#transforms-resize>`__,\n `RandomNoise <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.torch.html#transforms-randomnoise>`__,\n `RandomMask <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.torch.html#transforms-randommask>`__\n- For Label Construction:\n `Select <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.label.html#transforms-select>`__,\n `Binary <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.label.html#transforms-binary>`__,\n `BinariesToCategory <https://torcheeg.readthedocs.io/en/latest/torcheeg.transforms.label.html#transforms-binariestocategory>`__\n\n**Data Splitting:** In current research in the field of EEG analysis,\nthere are various settings based on different considerations for data\npartitioning. Please choose a reasonable data division method according\nto the research focus:\n\n- Subject Dependent:\n `KFoldPerSubjectGroupbyTrial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#kfoldpersubjectgroupbytrial>`__,\n `train_test_split_per_subject_groupby_trial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#train-test-split-per-subject-groupby-trial>`__\n- Subject Independent:\n `LeaveOneSubjectOut <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#leaveonesubjectout>`__\n- Conventional:\n `KFold <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#kfold>`__,\n `train_test_split <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#train-test-split>`__,\n `KFoldGroupbyTrial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#kfoldgroupbytrial>`__,\n `train_test_split_groupby_trial <https://torcheeg.readthedocs.io/en/latest/torcheeg.model_selection.html#train-test-split-groupby-trial>`__\n\n**Models:** Coming soon after pushing to align with the official\nimplementation or description. If the current version of\n`CNNs <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.cnn.html>`__,\n`GNNs <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.gnn.html>`__\nand\n`Transformers <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.transformer.html>`__\nis to be used, please refer to the implementation in\n`torcheeg.models <https://torcheeg.readthedocs.io/en/latest/torcheeg.models.html>`__.\n\nQuickstart\n----------\n\nIn this quick tour, we highlight the ease of starting an EEG analysis\nresearch with only a few lines.\n\nThe ``torcheeg.datasets`` module contains dataset classes for many\nreal-world EEG datasets. In this tutorial, we use the ``DEAP`` dataset.\nWe first go to the official website to apply for data download\npermission according to the introduction of `DEAP\ndataset <https://www.eecs.qmul.ac.uk/mmv/datasets/deap/>`__, and\ndownload the dataset. Next, we need to specify the download location of\nthe dataset in the ``root_path`` parameter. For the DEAP dataset, we\nspecify the path to the ``data_preprocessed_python`` folder,\ne.g.\u00a0``./tmp_in/data_preprocessed_python``.\n\n.. code:: python\n\n from torcheeg.datasets import DEAPDataset\n from torcheeg import transforms\n\n from torcheeg.datasets.constants import \\\n DEAP_CHANNEL_LOCATION_DICT\n\n dataset = DEAPDataset(\n io_path=f'./tmp_out/examples_pipeline/deap',\n root_path='./tmp_in/data_preprocessed_python',\n offline_transform=transforms.Compose([\n transforms.BandDifferentialEntropy(apply_to_baseline=True),\n transforms.ToGrid(DEAP_CHANNEL_LOCATION_DICT, apply_to_baseline=True)\n ]),\n online_transform=transforms.Compose(\n [transforms.BaselineRemoval(),\n transforms.ToTensor()]),\n label_transform=transforms.Compose([\n transforms.Select('valence'),\n transforms.Binary(5.0),\n ]),\n num_worker=8)\n\nThe ``DEAPDataset`` API further contains three parameters:\n``online_transform``, ``offline_transform``, and ``label_transform``,\nwhich are used to modify samples and labels, respectively.\n\nHere, ``offline_transform`` will only be called once when the dataset is\ninitialized to preprocess all samples in the dataset, and the processed\ndataset will be stored in ``io_path`` to avoid time-consuming repeated\ntransformations in subsequent use. If offline preprocessing is a\ncomputationally intensive operation, we also recommend setting multi-CPU\nparallelism for offline_transform, e.g., set ``num_worker`` to 4.\n\n``online_transform`` is used to transform samples on the fly. Please use\n``online_transform`` if you don\u2019t want to wait for the preprocessing of\nthe entire dataset (suitable for scenarios where new ``transform``\nalgorithms are designed) or expect data transformation with randomness\neach time a sample is indexed.\n\nNext, we need to divide the dataset into a training set and a test set.\nIn the field of EEG analysis, commonly used data partitioning methods\ninclude k-fold cross-validation and leave-one-out cross-validation. In\nthis tutorial, we use k-fold cross-validation on the entire dataset\n(``KFold``) as an example of dataset splitting.\n\n.. code:: python\n\n from torcheeg.model_selection import KFoldGroupbyTrial\n\n k_fold = KFoldGroupbyTrial(n_splits=10,\n split_path='./tmp_out/examples_pipeline/split',\n shuffle=True,\n random_state=42)\n\nWe loop through each cross-validation set, and for each one, we\ninitialize the CCNN model and define its hyperparameters. For instance,\neach EEG sample contains 4-channel features from 4 sub-bands, and the\ngrid size is 9x9. We then train the model for 50 epochs using the\n``ClassifierTrainer``.\n\n.. code:: python\n\n from torch.utils.data import DataLoader\n from torcheeg.models import CCNN\n\n from torcheeg.trainers import ClassifierTrainer\n\n import pytorch_lightning as pl\n\n for i, (train_dataset, val_dataset) in enumerate(k_fold.split(dataset)):\n train_loader = DataLoader(train_dataset, batch_size=64, shuffle=True)\n val_loader = DataLoader(val_dataset, batch_size=64, shuffle=False)\n\n model = CCNN(num_classes=2, in_channels=4, grid_size=(9, 9))\n\n trainer = ClassifierTrainer(model=model,\n num_classes=2,\n lr=1e-4,\n weight_decay=1e-4,\n accelerator=\"gpu\")\n trainer.fit(train_loader,\n val_loader,\n max_epochs=50,\n default_root_dir=f'./tmp_out/examples_pipeline/model/{i}',\n callbacks=[pl.callbacks.ModelCheckpoint(save_last=True)],\n enable_progress_bar=True,\n enable_model_summary=True,\n limit_val_batches=0.0)\n score = trainer.test(val_loader,\n enable_progress_bar=True,\n enable_model_summary=True)[0]\n print(f'Fold {i} test accuracy: {score[\"test_accuracy\"]:.4f}')\n\nFor more specific usage of each module, please refer to `the\ndocumentation <(https://torcheeg.readthedocs.io/)>`__.\n\nReleases and Contributing\n-------------------------\n\nTorchEEG is currently in beta; Please let us know if you encounter a bug\nby filing an issue. We also appreciate all contributions.\n\nIf you would like to contribute new datasets, deep learning methods, and\nextensions to the core, please first open an issue and then send a PR.\nIf you are planning to contribute back bug fixes, please do so without\nany further discussion.\n\nLicense\n-------\n\nTorchEEG has a MIT license, as found in the\n`LICENSE <https://github.com/tczhangzhi/torcheeg/blob/main/LICENSE>`__\nfile.\n\nCitation\n--------\n\nIf you find this project useful for your research, please cite:\n\n.. code:: latex\n\n @article{zhang2024torcheeg,\n title = {{TorchEEGEMO}: A deep learning toolbox towards {EEG}-based emotion recognition},\n journal = {Expert Systems with Applications},\n pages = {123550},\n year = {2024},\n issn = {0957-4174},\n author = {Zhi Zhang and Sheng-hua Zhong and Yan Liu}\n }\n\n.. |PyPI Version| image:: https://badge.fury.io/py/torcheeg.svg\n :target: https://pypi.python.org/pypi/torcheeg\n.. |Docs Status| image:: https://readthedocs.org/projects/torcheeg/badge/?version=latest\n :target: https://torcheeg.readthedocs.io/en/latest/?badge=latest\n.. |Downloads| image:: https://pepy.tech/badge/torcheeg\n :target: https://pepy.tech/project/torcheeg\n.. |Join the Chat| image:: https://badges.gitter.im/torcheeg/community.svg\n :target: https://gitter.im/torcheeg/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "TorchEEG is a library built on PyTorch for EEG signal analysis. TorchEEG aims to provide a plug-and-play EEG analysis tool, so that researchers can quickly reproduce EEG analysis work and start new EEG analysis research without paying attention to technical details unrelated to the research focus.",
"version": "1.1.2",
"project_urls": {
"Homepage": "https://github.com/tczhangzhi/torcheeg"
},
"split_keywords": [
"pytorch",
" eeg"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f4d545047b7501d635076492c9eb619605d9b43ae68ab719c6db71c8e042b10a",
"md5": "9788dadc6bd0e9745cc1d3092050aeb1",
"sha256": "a6f13e12d7aa38e11247ee9ba70f320ea36571fd92f3fe9ed5bd24e23a5757ff"
},
"downloads": -1,
"filename": "torcheeg-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "9788dadc6bd0e9745cc1d3092050aeb1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 214452,
"upload_time": "2024-05-06T14:23:37",
"upload_time_iso_8601": "2024-05-06T14:23:37.404549Z",
"url": "https://files.pythonhosted.org/packages/f4/d5/45047b7501d635076492c9eb619605d9b43ae68ab719c6db71c8e042b10a/torcheeg-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-06 14:23:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tczhangzhi",
"github_project": "torcheeg",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "torcheeg"
}
