# PyRCN
A Python 3 framework for Reservoir Computing with a [scikit-learn](https://scikit-learn.org/stable/)-compatible API.
PyRCN ("Python Reservoir Computing Networks") is a light-weight and transparent Python 3 framework for Reservoir Computing (currently only implementing Echo State Networks) and is based on widely used scientific Python packages, such as numpy or scipy. The API is fully scikit-learn-compatible, so that users of scikit-learn do not need to refactor their code in order to use the estimators implemented by this framework. Scikit-learn's built-in parameter optimization methods and example datasets can also be used in the usual way.
PyRCN is used by the [Chair of Speech Technology and Cognitive Systems, Institute for Acoustics and Speech Communications, Technische Universität Dresden, Dresden, Germany](https://tu-dresden.de/ing/elektrotechnik/ias/stks?set_language=en) and [IDLab (Internet and Data Lab), Ghent University, Ghent, Belgium](https://www.ugent.be/ea/idlab/en).
Currently, it implements Echo State Networks (ESNs) by Herbert Jaeger in different flavors, e.g. Classifier and Regressor. It is actively developed to be extended into several directions:
- Incorporate Feedback
- Better sequence handling with [sktime](http://sktime.org/)
- A unified API to stack ESNs
- More towards future work: Related architectures, such as Liquid State Machines (LSMs) and Perturbative Neural Networks (PNNs)
PyRCN has successfully been used for several tasks:
- Music Information Retrieval (MIR)
- Multipitch tracking
- Onset detection
- Time Series Prediction
- Mackey-Glass benchmark test
- Stock price prediction
- Ongoing research tasks:
- Beat tracking in music signals
- Pattern recognition in sensor data
- Phoneme recognition
Please see the [References section](#references) for more information. For code examples, see [Getting started](#getting-started).
# Installation
## Prerequisites
PyRCn is developed using Python 3.6 or newer. It depends on the following packages:
- [numpy>=1.18.1](https://numpy.org/)
- [scipy>=1.2.0](https://scipy.org/)
- [scikit-learn>=0.23.1](https://scikit-learn.org/stable/)
- [joblib>=0.13.2](https://joblib.readthedocs.io)
- [pandas>=1.0.0](https://pandas.pydata.org/)
- [matplotlib](https://matplotlib.org/)
## Installation from PyPI
The easiest and recommended way to install ``PyRCN`` is to use ``pip`` from [PyPI](https://pypi.org) :
```python
pip install pyrcn
```
## Installation from source
If you plan to contribute to ``PyRCN``, you can also install the package from source.
Clone the Git repository:
```
git clone https://github.com/TUD-STKS/PyRCN.git
```
Install the package using ``setup.py``:
```
python setup.py install --user
```
# Package structure
The package is structured in the following way:
- `doc`
- This folder includes the package documentation.
- `examples`
- This folder includes example code as Jupyter Notebooks and python scripts.
- `images`
- This folder includes the logos used in ´README.md´.
- `pyrcn`
- This folder includes the actual Python package.
# Getting Started
PyRCN includes currently variants of Echo State Networks (ESNs) and Extreme Learning Machines (ELMs): Regressors and Classifiers.
Basic example for the ESNClassifier:
```python
from pyrcn.echo_state_network import ESNClassifier
clf = ESNClassifier()
clf.fit(X=X_train, y=y_train)
y_pred_classes = clf.predict(X=X_test) # output is the class for each input example
y_pred_proba = clf.predict_proba(X=X_test) # output are the class probabilities for each input example
```
Basic example for the ESNRegressor:
```python
from pyrcn.echo_state_network import ESNRegressor
reg = ESNRegressor()
ref.fit(X=X_train, y=y_train)
y_pred = reg.predict(X=X_test) # output is the prediction for each input example
```
An extensive introduction to getting started with PyRCN is included in the [examples](https://github.com/TUD-STKS/PyRCN/blob/master/examples) directory. The notebook [digits](https://github.com/TUD-STKS/PyRCN/blob/master/examples/digits.ipynb) or its corresponding [Python script](https://github.com/TUD-STKS/PyRCN/blob/master/examples/digits.py) show how to set up an ESN for a small hand-written digit recognition experiment.
Launch the digits notebook on Binder:
[](https://mybinder.org/v2/gh/TUD-STKS/PyRCN/master?filepath=examples%2Fdigits.ipynb)
Fore more advanced examples, please have a look at our [Automatic Music Transcription Repository](https://github.com/TUD-STKS/Automatic-Music-Transcription), in which we provide an entire feature extraction, training and test pipeline for multipitch tracking and for note onset detection using PyRCN.
# Citation
If you use PyRCN, please cite the following publication:
```latex
@INPROCEEDINGS{src:Steiner-21c,
author={Peter Steiner and Azarakhsh Jalalvand and Simon Stone Peter Birkholz},
booktitle={The International Joint Conference on Neural Networks},
title={PyRCN: Exploration and Application of ESNs},
year={2021},
note={submitted},
}
```
# References
Glottal Closure Instant Detection using Echo State Networks
```latex
@InProceedings{src:Steiner-21a,
title = {Glottal Closure Instant Detection using Echo State Networkss},
author = {Peter Steiner and Ian S. Howard and Peter Birkholz},
year = {2021},
pages = {161--168},
keywords = {Oral},
booktitle = {Studientexte zur Sprachkommunikation: Elektronische Sprachsignalverarbeitung 2021},
editor = {Stefan Hillmann and Benjamin Weiss and Thilo Michael and Sebastian Möller},
publisher = {TUDpress, Dresden},
isbn = {978-3-95908-227-3}
}
```
Cluster-based Input Weight Initialization for Echo State Networks
```latex
@misc{src:Steiner-21b,
title={Cluster-based Input Weight Initialization for Echo State Networks},
author={Peter Steiner and Azarakhsh Jalalvand and Peter Birkholz},
year={2021},
eprint={2103.04710},
archivePrefix={arXiv},
primaryClass={cs.LG}
}
´´´
PyRCN: Exploration and Application of ESNs
```latex
@INPROCEEDINGS{src:Steiner-21c,
author={Peter Steiner and Azarakhsh Jalalvand and Simon Stone Peter Birkholz},
booktitle={The International Joint Conference on Neural Networks},
title={PyRCN: Exploration and Application of ESNs},
year={2021},
note={submitted},
}
```
Note Onset Detection using Echo State Networks
```latex
@InProceedings{src:Steiner-20a,
title = {Note Onset Detection using Echo State Networks},
author = {Peter Steiner and Simon Stone and Peter Birkholz},
year = {2020},
pages = {157--164},
keywords = {Poster},
booktitle = {Studientexte zur Sprachkommunikation: Elektronische Sprachsignalverarbeitung 2020},
editor = {Ronald Böck and Ingo Siegert and Andreas Wendemuth},
publisher = {TUDpress, Dresden},
isbn = {978-3-959081-93-1}
}
```
Feature Engineering and Stacked ESNs for Musical Onset Detection
```latex
@INPROCEEDINGS{src:Steiner-20d,
author={Peter Steiner and Simon Stone and Azarakhsh Jalalvand and Peter Birkholz},
booktitle={2020 25th International Conference on Pattern Recognition (ICPR)},
title={Feature Engineering and Stacked ESNs for Musical Onset Detection},
year={2020},
volume={},
number={},
note={submitted},
}
```
Multipitch tracking in music signals using Echo State Networks
```latex
@INPROCEEDINGS{src:Steiner-20b,
author={Peter Steiner and Simon Stone and Peter Birkholz and Azarakhsh Jalalvand},
booktitle={28th European Signal Processing Conference (EUSIPCO), 2020},
title={Multipitch tracking in music signals using Echo State Networks},
year={2020},
note={accepted},
}
```
Multiple-F0 Estimation using Echo State Networks
```latex
@inproceedings{src:Steiner-19,
title={Multiple-F0 Estimation using Echo State Networks},
booktitle={{MIREX}},
author={Peter Steiner and Azarakhsh Jalalvand and Peter Birkholz},
year={2019},
url = {https://www.music-ir.org/mirex/abstracts/2019/SBJ1.pdf}
}
```
# Acknowledgements
This research is funded by the European Social Fund (Application number: 100327771) and co-financed by tax funds based on the budget approved by the members of the Saxon State Parliament, and by Ghent University.
Raw data
{
"_id": null,
"home_page": "https://github.com/TUD-STKS/PyRCN",
"name": "PyRCN",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "PyRCN,Echo State Network",
"author": "Peter Steiner",
"author_email": "peter.steiner@tu-dresden.de",
"download_url": "https://files.pythonhosted.org/packages/fa/62/d1b40c66cec2791e35b0d82a437ce98a52e2949039a97e372cd2e50c7925/PyRCN-0.0.12.tar.gz",
"platform": "",
"description": "# PyRCN\nA Python 3 framework for Reservoir Computing with a [scikit-learn](https://scikit-learn.org/stable/)-compatible API.\n\nPyRCN (\"Python Reservoir Computing Networks\") is a light-weight and transparent Python 3 framework for Reservoir Computing (currently only implementing Echo State Networks) and is based on widely used scientific Python packages, such as numpy or scipy. The API is fully scikit-learn-compatible, so that users of scikit-learn do not need to refactor their code in order to use the estimators implemented by this framework. Scikit-learn's built-in parameter optimization methods and example datasets can also be used in the usual way.\n\nPyRCN is used by the [Chair of Speech Technology and Cognitive Systems, Institute for Acoustics and Speech Communications, Technische Universit\u00c3\u00a4t Dresden, Dresden, Germany](https://tu-dresden.de/ing/elektrotechnik/ias/stks?set_language=en) and [IDLab (Internet and Data Lab), Ghent University, Ghent, Belgium](https://www.ugent.be/ea/idlab/en). \n\nCurrently, it implements Echo State Networks (ESNs) by Herbert Jaeger in different flavors, e.g. Classifier and Regressor. It is actively developed to be extended into several directions:\n\n- Incorporate Feedback\n- Better sequence handling with [sktime](http://sktime.org/)\n- A unified API to stack ESNs\n- More towards future work: Related architectures, such as Liquid State Machines (LSMs) and Perturbative Neural Networks (PNNs)\n\nPyRCN has successfully been used for several tasks:\n\n- Music Information Retrieval (MIR)\n - Multipitch tracking\n - Onset detection\n- Time Series Prediction\n - Mackey-Glass benchmark test\n - Stock price prediction\n- Ongoing research tasks:\n - Beat tracking in music signals\n - Pattern recognition in sensor data\n - Phoneme recognition\n\nPlease see the [References section](#references) for more information. For code examples, see [Getting started](#getting-started).\n\n# Installation\n\n## Prerequisites\n\nPyRCn is developed using Python 3.6 or newer. It depends on the following packages:\n\n- [numpy>=1.18.1](https://numpy.org/)\n- [scipy>=1.2.0](https://scipy.org/)\n- [scikit-learn>=0.23.1](https://scikit-learn.org/stable/)\n- [joblib>=0.13.2](https://joblib.readthedocs.io)\n- [pandas>=1.0.0](https://pandas.pydata.org/)\n- [matplotlib](https://matplotlib.org/)\n## Installation from PyPI\n\nThe easiest and recommended way to install ``PyRCN`` is to use ``pip`` from [PyPI](https://pypi.org) :\n\n```python\npip install pyrcn \n```\n\n## Installation from source\n\nIf you plan to contribute to ``PyRCN``, you can also install the package from source.\n\nClone the Git repository:\n\n```\ngit clone https://github.com/TUD-STKS/PyRCN.git\n```\n\nInstall the package using ``setup.py``:\n```\npython setup.py install --user\n```\n\n# Package structure\nThe package is structured in the following way: \n\n- `doc`\n - This folder includes the package documentation.\n- `examples`\n - This folder includes example code as Jupyter Notebooks and python scripts.\n- `images`\n - This folder includes the logos used in \u00c2\u00b4README.md\u00c2\u00b4.\n- `pyrcn`\n - This folder includes the actual Python package.\n\n\n# Getting Started\n\nPyRCN includes currently variants of Echo State Networks (ESNs) and Extreme Learning Machines (ELMs): Regressors and Classifiers.\n\nBasic example for the ESNClassifier:\n\n```python\nfrom pyrcn.echo_state_network import ESNClassifier\n\n\nclf = ESNClassifier()\nclf.fit(X=X_train, y=y_train)\n\ny_pred_classes = clf.predict(X=X_test) # output is the class for each input example\ny_pred_proba = clf.predict_proba(X=X_test) # output are the class probabilities for each input example\n```\n\nBasic example for the ESNRegressor:\n\n```python\nfrom pyrcn.echo_state_network import ESNRegressor\n\n\nreg = ESNRegressor()\nref.fit(X=X_train, y=y_train)\n\ny_pred = reg.predict(X=X_test) # output is the prediction for each input example\n```\n\nAn extensive introduction to getting started with PyRCN is included in the [examples](https://github.com/TUD-STKS/PyRCN/blob/master/examples) directory. The notebook [digits](https://github.com/TUD-STKS/PyRCN/blob/master/examples/digits.ipynb) or its corresponding [Python script](https://github.com/TUD-STKS/PyRCN/blob/master/examples/digits.py) show how to set up an ESN for a small hand-written digit recognition experiment.\n\nLaunch the digits notebook on Binder: \n\n[](https://mybinder.org/v2/gh/TUD-STKS/PyRCN/master?filepath=examples%2Fdigits.ipynb)\n\nFore more advanced examples, please have a look at our [Automatic Music Transcription Repository](https://github.com/TUD-STKS/Automatic-Music-Transcription), in which we provide an entire feature extraction, training and test pipeline for multipitch tracking and for note onset detection using PyRCN.\n\n# Citation\n\nIf you use PyRCN, please cite the following publication:\n\n```latex\n@INPROCEEDINGS{src:Steiner-21c, \n author={Peter Steiner and Azarakhsh Jalalvand and Simon Stone Peter Birkholz}, \n booktitle={The International Joint Conference on Neural Networks}, \n title={PyRCN: Exploration and Application of ESNs},\n year={2021},\n note={submitted},\n}\n```\n\n# References\nGlottal Closure Instant Detection using Echo State Networks\n\n```latex\n@InProceedings{src:Steiner-21a,\n\ttitle = {Glottal Closure Instant Detection using Echo State Networkss},\n\tauthor = {Peter Steiner and Ian S. Howard and Peter Birkholz},\n\tyear = {2021},\n\tpages = {161--168},\n\tkeywords = {Oral},\n\tbooktitle = {Studientexte zur Sprachkommunikation: Elektronische Sprachsignalverarbeitung 2021},\n\teditor = {Stefan Hillmann and Benjamin Weiss and Thilo Michael and Sebastian M\u00c3\u00b6ller},\n\tpublisher = {TUDpress, Dresden},\n\tisbn = {978-3-95908-227-3}\n} \n```\n\nCluster-based Input Weight Initialization for Echo State Networks\n\n```latex\n@misc{src:Steiner-21b,\n title={Cluster-based Input Weight Initialization for Echo State Networks},\n author={Peter Steiner and Azarakhsh Jalalvand and Peter Birkholz},\n year={2021},\n eprint={2103.04710},\n archivePrefix={arXiv},\n primaryClass={cs.LG}\n}\n\u00c2\u00b4\u00c2\u00b4\u00c2\u00b4\n\nPyRCN: Exploration and Application of ESNs\n\n```latex\n@INPROCEEDINGS{src:Steiner-21c, \n author={Peter Steiner and Azarakhsh Jalalvand and Simon Stone Peter Birkholz}, \n booktitle={The International Joint Conference on Neural Networks}, \n title={PyRCN: Exploration and Application of ESNs},\n year={2021},\n note={submitted},\n}\n```\n\nNote Onset Detection using Echo State Networks\n\n```latex\n@InProceedings{src:Steiner-20a,\n\ttitle = {Note Onset Detection using Echo State Networks},\n\tauthor = {Peter Steiner and Simon Stone and Peter Birkholz},\n\tyear = {2020},\n\tpages = {157--164},\n\tkeywords = {Poster},\n\tbooktitle = {Studientexte zur Sprachkommunikation: Elektronische Sprachsignalverarbeitung 2020},\n\teditor = {Ronald B\u00c3\u00b6ck and Ingo Siegert and Andreas Wendemuth},\n\tpublisher = {TUDpress, Dresden},\n\tisbn = {978-3-959081-93-1}\n} \n```\n\nFeature Engineering and Stacked ESNs for Musical Onset Detection\n\n```latex\n@INPROCEEDINGS{src:Steiner-20d, \n author={Peter Steiner and Simon Stone and Azarakhsh Jalalvand and Peter Birkholz}, \n booktitle={2020 25th International Conference on Pattern Recognition (ICPR)}, \n title={Feature Engineering and Stacked ESNs for Musical Onset Detection}, \n year={2020}, \n volume={}, \n number={}, \n note={submitted},\n}\n```\n\nMultipitch tracking in music signals using Echo State Networks\n```latex\n@INPROCEEDINGS{src:Steiner-20b,\n author={Peter Steiner and Simon Stone and Peter Birkholz and Azarakhsh Jalalvand},\n booktitle={28th European Signal Processing Conference (EUSIPCO), 2020},\n title={Multipitch tracking in music signals using Echo State Networks},\n year={2020},\n note={accepted},\n}\n```\n\nMultiple-F0 Estimation using Echo State Networks\n```latex\n@inproceedings{src:Steiner-19,\n title={Multiple-F0 Estimation using Echo State Networks},\n booktitle={{MIREX}},\n author={Peter Steiner and Azarakhsh Jalalvand and Peter Birkholz},\n year={2019},\n url = {https://www.music-ir.org/mirex/abstracts/2019/SBJ1.pdf}\n}\n```\n\n\n# Acknowledgements\nThis research is funded by the European Social Fund (Application number: 100327771) and co-financed by tax funds based on the budget approved by the members of the Saxon State Parliament, and by Ghent University.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A Python3 framework for Reservoir Computing with a scikit-learn-compatible API",
"version": "0.0.12",
"split_keywords": [
"pyrcn",
"echo state network"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "8203609c891f1d102b6328a3cd588503",
"sha256": "511fcc47544a165c93f8ac069eaa2d6e3cc8ce7670e23462f568a08ba305dfd5"
},
"downloads": -1,
"filename": "PyRCN-0.0.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8203609c891f1d102b6328a3cd588503",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 38453,
"upload_time": "2021-04-09T11:56:44",
"upload_time_iso_8601": "2021-04-09T11:56:44.640226Z",
"url": "https://files.pythonhosted.org/packages/1f/c1/0f2a0d5ecea57cc9f6a6ca907d66eb6bee368d8e2aa52a0995ee8019f02d/PyRCN-0.0.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "b76df2ca9baf7ec71376e1eb5550101b",
"sha256": "b6e11986509d4bf26b819d1e6c7835f8ceed7c33a971ff64f5ccaff825605ab9"
},
"downloads": -1,
"filename": "PyRCN-0.0.12.tar.gz",
"has_sig": false,
"md5_digest": "b76df2ca9baf7ec71376e1eb5550101b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 2060952,
"upload_time": "2021-04-09T11:56:46",
"upload_time_iso_8601": "2021-04-09T11:56:46.726037Z",
"url": "https://files.pythonhosted.org/packages/fa/62/d1b40c66cec2791e35b0d82a437ce98a52e2949039a97e372cd2e50c7925/PyRCN-0.0.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-04-09 11:56:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": null,
"github_project": "TUD-STKS",
"error": "Could not fetch GitHub repository",
"lcname": "pyrcn"
}
JSON
