## Sleep Ensemble
[](https://circleci.com/gh/paradoxysm/sleepens/tree/master)
[](https://codecov.io/gh/paradoxysm/sleepens)
[](https://zenodo.org/badge/latestdoi/282098794)
[](https://github.com/paradoxysm/sleepens/blob/master/LICENSE)
Sleep Ensemble is a framework for end-to-end sleep state classification using machine learning. It is designed to allow for modular data processing, classification, and further post-processing.
Published in [SLEEP](https://academic.oup.com/sleep/advance-article-abstract/doi/10.1093/sleep/zsad101/7109541).
## Installation
Install a suitable python environment from [python.org](https://www.python.org/downloads/release/python-378/).
> Sleep Ensemble supports Python 3.7 only. It is extensively tested and developed with 64-bit Python 3.7.8 on Windows.
> Sleep Ensemble pre-trained builds are only useable for the specific OS and 32/64-bit Python environment. The included pre-trained SleepEnsemble4 is built on 64-bit Python 3.7.8 on Windows.
Install the latest `sleepens` release using `pip` (on a terminal like command prompt):
```
pip install sleepens
```
Alternatively, download the source code for the latest release [here](https://github.com/paradoxysm/sleepens/releases). Unzip into desired location. Using the terminal, navigate to the top `sleepens` folder where `setup.py` is located and run the following:
```
python setup.py install
```
Download any pre-trained builds [here](https://github.com/paradoxysm/sleepens/blob/master/BUILDS.md) or train your own.
## Usage
Sleep Ensemble is built for easy use with a text-based python script that you can run in a command terminal. This application allows you to quickly classify data or train new models.
The application runs via `sleepens.py` which can be copied/moved anywhere as needed. To run, using the terminal, navigate to `sleepens.py` and run:
```
python sleepens.py
```
As a framework, the Sleep Ensemble package can be used as you would any other package. The end-user program can be accessed:
```python
import sleepens
sleepens.run()
```
Alongside the Sleep Ensemble application, the framework is designed for high modularity and integration with other scripts in very little code.
```python
# Setup a protocol
from sleepens.protocols.sleepens4 import SleepEnsemble4
model = SleepEnsemble4()
# Load a pre-trained model in a .joblib file
import joblib
model.classifier = joblib.load("/path/to/model.joblib")
# Classify your data
# Data is a list of 2D arrays in the form of (n samples, n features)
predictions = model.predict(data)
```
For full details on usage, see the [documentation](https://github.com/paradoxysm/sleepens/tree/master/doc).
## Changelog
See the [changelog](https://github.com/paradoxysm/sleepens/blob/master/CHANGES.md) for a history of notable changes to `sleepens`.
## Development
[](https://codeclimate.com/github/paradoxysm/sleepens/maintainability)
`sleepens` is in a relatively finished state. It has not been tested on different Python environment and OS combinations.
Currently, `sleepens` supports .mat, .smr/.smrx, .xls file formats for reading and writing. Of note, presently the SONpy interface for reading/writing .smr/.smrx files works for reading .smr only and writing .smrx only. No clear documentation exists to explain errors when attempting to read from .smrx. Additional i/o interfaces can be contributed to `sleepens.io.interfaces` following the basic structure.
The underlying data processing pipelines and classification models are modular and can be adjusted to create different sleep ensemble models. `sleepens` currently contains one protocol, SleepEnsemble4, for 4-state sleep classification. New or modified protocols can be contributed to `sleepens.protocols` following the basic structure.
Finally, `sleepens` uses `joblib` to store the pre-trained builds. This isn't the most secure method nor is the most data storage efficient. Ideally, a custom parameter export/load method is implemented that can reinstate a pre-trained build.
## Dependencies
`sleepens` was developed using Python 3.7.8. Since development, `scikit-learn` has updated to a point that `sleepens` is not compatible with later versions of `scikit-learn` due to attribute name changes. At the same time, `sonpy` is limited to Python 3.7 to 3.9. For the sake of replicability (especially with pre-trained models provided on publication, the repository remains using the below dependencies at these versions. This also limits Python to 3.7.
```
numpy==1.21.6
scikit-learn==0.24.0
joblib==1.0.0
tqdm==4.55.0
xlrd==2.0.1
xlwt==1.3.0
sonpy==1.7.5
scipy==1.7.2
```
Should one wish to upgrade these dependencies to the latest version of `scikit-learn`, change all references of `n_features_` to `n_features_in_` in the following:
- `sleepens/sleepens/ml/_base_model.py`
- `sleepens/sleepens/ml/models/_gb.py`
- `sleepens/sleepens/ml/models/_tsens.py`
- `sleepens/sleepens/ml/models/_stsens.py`
Furthermore, change the loss parameter in `sleepens/sleepens/ml/_gb.py` line 220 to 'log_loss' (which replaces 'deviance' but is algorithmically the same).
## Help and Support
### Documentation
Documentation for `sleepens` can be found [here](https://github.com/paradoxysm/sleepens/tree/master/doc).
### Issues and Questions
Issues and Questions should be posed to the issue tracker [here](https://github.com/paradoxysm/sleepens/issues).
Raw data
{
"_id": null,
"home_page": "http://github.com/paradoxysm/sleepens",
"name": "sleepens",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9, <3.10",
"maintainer_email": "",
"keywords": "python,ml,ensemble,sleep,classification",
"author": "paradoxysm",
"author_email": "paradoxysm.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b0/3f/7f4017f8ee4bb5d8356e130356db3a36100b2de46658da62c726833c7f6a/sleepens-1.0.3.tar.gz",
"platform": null,
"description": "## Sleep Ensemble\n\n[](https://circleci.com/gh/paradoxysm/sleepens/tree/master)\n[](https://codecov.io/gh/paradoxysm/sleepens)\n[](https://zenodo.org/badge/latestdoi/282098794)\n[](https://github.com/paradoxysm/sleepens/blob/master/LICENSE)\n\nSleep Ensemble is a framework for end-to-end sleep state classification using machine learning. It is designed to allow for modular data processing, classification, and further post-processing.\nPublished in [SLEEP](https://academic.oup.com/sleep/advance-article-abstract/doi/10.1093/sleep/zsad101/7109541).\n\n## Installation\n\nInstall a suitable python environment from [python.org](https://www.python.org/downloads/release/python-378/).\n> Sleep Ensemble supports Python 3.7 only. It is extensively tested and developed with 64-bit Python 3.7.8 on Windows.\n\n> Sleep Ensemble pre-trained builds are only useable for the specific OS and 32/64-bit Python environment. The included pre-trained SleepEnsemble4 is built on 64-bit Python 3.7.8 on Windows.\n\nInstall the latest `sleepens` release using `pip` (on a terminal like command prompt):\n```\npip install sleepens\n```\nAlternatively, download the source code for the latest release [here](https://github.com/paradoxysm/sleepens/releases). Unzip into desired location. Using the terminal, navigate to the top `sleepens` folder where `setup.py` is located and run the following:\n```\npython setup.py install\n```\n\nDownload any pre-trained builds [here](https://github.com/paradoxysm/sleepens/blob/master/BUILDS.md) or train your own.\n\n## Usage\n\nSleep Ensemble is built for easy use with a text-based python script that you can run in a command terminal. This application allows you to quickly classify data or train new models.\n\nThe application runs via `sleepens.py` which can be copied/moved anywhere as needed. To run, using the terminal, navigate to `sleepens.py` and run:\n```\npython sleepens.py\n```\n\nAs a framework, the Sleep Ensemble package can be used as you would any other package. The end-user program can be accessed:\n```python\nimport sleepens\nsleepens.run()\n```\n\nAlongside the Sleep Ensemble application, the framework is designed for high modularity and integration with other scripts in very little code.\n\n```python\n# Setup a protocol\nfrom sleepens.protocols.sleepens4 import SleepEnsemble4\nmodel = SleepEnsemble4()\n\n# Load a pre-trained model in a .joblib file\nimport joblib\nmodel.classifier = joblib.load(\"/path/to/model.joblib\")\n\n# Classify your data\n# Data is a list of 2D arrays in the form of (n samples, n features)\npredictions = model.predict(data)\n```\n\nFor full details on usage, see the [documentation](https://github.com/paradoxysm/sleepens/tree/master/doc).\n\n## Changelog\n\nSee the [changelog](https://github.com/paradoxysm/sleepens/blob/master/CHANGES.md) for a history of notable changes to `sleepens`.\n\n## Development\n\n[](https://codeclimate.com/github/paradoxysm/sleepens/maintainability)\n\n`sleepens` is in a relatively finished state. It has not been tested on different Python environment and OS combinations.\n\nCurrently, `sleepens` supports .mat, .smr/.smrx, .xls file formats for reading and writing. Of note, presently the SONpy interface for reading/writing .smr/.smrx files works for reading .smr only and writing .smrx only. No clear documentation exists to explain errors when attempting to read from .smrx. Additional i/o interfaces can be contributed to `sleepens.io.interfaces` following the basic structure.\n\nThe underlying data processing pipelines and classification models are modular and can be adjusted to create different sleep ensemble models. `sleepens` currently contains one protocol, SleepEnsemble4, for 4-state sleep classification. New or modified protocols can be contributed to `sleepens.protocols` following the basic structure.\n\nFinally, `sleepens` uses `joblib` to store the pre-trained builds. This isn't the most secure method nor is the most data storage efficient. Ideally, a custom parameter export/load method is implemented that can reinstate a pre-trained build.\n\n## Dependencies\n\n`sleepens` was developed using Python 3.7.8. Since development, `scikit-learn` has updated to a point that `sleepens` is not compatible with later versions of `scikit-learn` due to attribute name changes. At the same time, `sonpy` is limited to Python 3.7 to 3.9. For the sake of replicability (especially with pre-trained models provided on publication, the repository remains using the below dependencies at these versions. This also limits Python to 3.7.\n\n```\nnumpy==1.21.6\nscikit-learn==0.24.0\njoblib==1.0.0\ntqdm==4.55.0\nxlrd==2.0.1\nxlwt==1.3.0\nsonpy==1.7.5\nscipy==1.7.2\n```\n\nShould one wish to upgrade these dependencies to the latest version of `scikit-learn`, change all references of `n_features_` to `n_features_in_` in the following:\n- `sleepens/sleepens/ml/_base_model.py`\n- `sleepens/sleepens/ml/models/_gb.py`\n- `sleepens/sleepens/ml/models/_tsens.py`\n- `sleepens/sleepens/ml/models/_stsens.py`\n\nFurthermore, change the loss parameter in `sleepens/sleepens/ml/_gb.py` line 220 to 'log_loss' (which replaces 'deviance' but is algorithmically the same). \n\n## Help and Support\n\n### Documentation\n\nDocumentation for `sleepens` can be found [here](https://github.com/paradoxysm/sleepens/tree/master/doc).\n\n### Issues and Questions\n\nIssues and Questions should be posed to the issue tracker [here](https://github.com/paradoxysm/sleepens/issues).\n\n\n\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Sleep Classification using Ensemble Classification",
"version": "1.0.3",
"project_urls": {
"Download": "https://github.com/paradoxysm/sleepens/archive/1.0.3.tar.gz",
"Homepage": "http://github.com/paradoxysm/sleepens"
},
"split_keywords": [
"python",
"ml",
"ensemble",
"sleep",
"classification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9c4e89665434c20a54131ef2ff01fca5c3ba3703ab7d340c8821685735dbab46",
"md5": "8b6d35b3e1a6f3ed0f73da96dfefd0c3",
"sha256": "123fe2308a8097274e53f2aad9dcd86dece9d4e5d6d56708c595ac517e2146bc"
},
"downloads": -1,
"filename": "sleepens-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8b6d35b3e1a6f3ed0f73da96dfefd0c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9, <3.10",
"size": 65948,
"upload_time": "2023-05-15T22:45:02",
"upload_time_iso_8601": "2023-05-15T22:45:02.062351Z",
"url": "https://files.pythonhosted.org/packages/9c/4e/89665434c20a54131ef2ff01fca5c3ba3703ab7d340c8821685735dbab46/sleepens-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b03f7f4017f8ee4bb5d8356e130356db3a36100b2de46658da62c726833c7f6a",
"md5": "f9260871ee214214bd649b8fa6bab18f",
"sha256": "7ce6b65844f59e3ebb73864b4bc2aef478d7860781a0131bd68317769c6114a5"
},
"downloads": -1,
"filename": "sleepens-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "f9260871ee214214bd649b8fa6bab18f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9, <3.10",
"size": 46267,
"upload_time": "2023-05-15T22:45:04",
"upload_time_iso_8601": "2023-05-15T22:45:04.537275Z",
"url": "https://files.pythonhosted.org/packages/b0/3f/7f4017f8ee4bb5d8356e130356db3a36100b2de46658da62c726833c7f6a/sleepens-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-15 22:45:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "paradoxysm",
"github_project": "sleepens",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"circle": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
"==",
"1.21.6"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
"==",
"0.24.0"
]
]
},
{
"name": "joblib",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "tqdm",
"specs": [
[
"==",
"4.55.0"
]
]
},
{
"name": "xlrd",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "xlwt",
"specs": [
[
"==",
"1.3.0"
]
]
},
{
"name": "sonpy",
"specs": [
[
"==",
"1.7.5"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.7.2"
]
]
}
],
"lcname": "sleepens"
}
JSON
