PyRCN


NamePyRCN JSON
Version 0.0.12 PyPI version JSON
download
home_pagehttps://github.com/TUD-STKS/PyRCN
SummaryA Python3 framework for Reservoir Computing with a scikit-learn-compatible API
upload_time2021-04-09 11:56:46
maintainer
docs_urlNone
authorPeter Steiner
requires_python>=3.7
license
keywords pyrcn echo state network
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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: 

[![Binder](https://mybinder.org/badge_logo.svg)](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[![Binder](https://mybinder.org/badge_logo.svg)](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"
}
        
Elapsed time: 0.35905s