neurostates


Nameneurostates JSON
Version 0.1.2 PyPI version JSON
download
home_pageNone
SummaryNeurostates is a tool for analyzing patterns of functional connectivity in EEG and fMRI.
upload_time2025-04-07 23:13:24
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseCopyright (c) 2024, Della Bella, Gabriel; Rodriguez, Natalia All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
keywords brain functional connectivity eeg fmri
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # NeuroStates

<img src="https://raw.githubusercontent.com/dellabellagabriel/neurostates/main/res/logo_final.png" alt="logo" width="20%">

[![Gihub Actions CI](https://github.com/dellabellagabriel/neurostates/actions/workflows/CI.yml/badge.svg)](https://github.com/dellabellagabriel/neurostates/actions/workflows/CI.yml)
[![Documentation Status](https://readthedocs.org/projects/neurostates/badge/?version=latest&style=flat)](https://neurostates.readthedocs.io/en/latest/)
[![License](https://img.shields.io/pypi/l/uttrs?color=blue)](https://www.tldrlegal.com/l/bsd3)

**NeuroStates** is a Python package for detecting recurrent functional connectivity patterns (also known as brain states) and estimating their ocurrence probabilities in EEG and fMRI.

# Install
Before installing, make sure you have the following:
- Python 3.9 or later.
- pip (Python's package installer).
- A virtual environment (optional, but recommended).

From PyPI repo, simply run:
```bash
pip install neurostates
```
You can install it in development mode by running:
```bash
pip install -e .
```

# Basic Usage
## Load data

We load two groups of subjects — controls and patients — where each subject's data is a time series of brain activity (e.g., from fMRI or EEG).  
It must be of size `(subjects x regions x time)`.

```python
import numpy as np
import scipy.io as sio

group_controls = sio.loadmat("path/to/control/data")["ts"]
group_patients = sio.loadmat("path/to/patient/data")["ts"]

groups = {
    "controls": group_controls,
    "patients": group_patients
}

print(f"Control group shape (subjects, regions, time): {group_controls.shape}")
print(f"Patient group shape (subjects, regions, time): {group_patients.shape}")
```

```
Control group shape (subjects, regions, time): (10, 90, 500)  
Patient group shape (subjects, regions, time): (10, 90, 500)
```

## Build the pipeline

Neurostates implements a `scikit-learn`-compatible pipeline that includes all of the important steps required for brain state analysis.  
The pipeline includes:

- A sliding window that segments the time series  
- Dynamic connectivity estimation (e.g., Pearson, cosine similarity, Spearman’s R, or a custom metric)  
- Concatenation of all matrices across subjects  
- Clustering using KMeans to extract brain states  

```python
from sklearn.cluster import KMeans
from sklearn.pipeline import Pipeline

from neurostates.core.clustering import Concatenator
from neurostates.core.connectivity import DynamicConnectivityGroup
from neurostates.core.window import SecondsWindowerGroup

brain_state_pipeline = Pipeline(
    [
        (
            "windower",
            SecondsWindowerGroup(length=20, step=5, sample_rate=1)
        ),
        (
            "connectivity",
            DynamicConnectivityGroup(method="pearson")
        ),
        (
            "preclustering",
            Concatenator()
        ),
        (
            "clustering",
            KMeans(n_clusters=3, random_state=42)
        ),
    ]
)
```

Then you can use the `fit_transform()` method to transform your input data and get the centroids (brain states):

```python
brain_state_pipeline.fit_transform(groups)
brain_states = brain_state_pipeline["clustering"].cluster_centers_

# Originally brain_states will be a 3 by 8100 matrix.
# We reshape them to get the matrix structure back
brain_states = brain_states.reshape(3, 90, 90)
```

And you can plot them like so:

```python
import matplotlib.pyplot as plt

fig, ax = plt.subplots(1, 3)
ax[0].imshow(brain_states[0], vmin=-0.5, vmax=1)
ax[0].set_title("state 1")
ax[0].set_ylabel("regions")
ax[0].set_xlabel("regions")

ax[1].imshow(brain_states[1], vmin=-0.5, vmax=1)
ax[1].set_title("state 2")

ax[2].imshow(brain_states[2], vmin=-0.5, vmax=1)
ax[2].set_title("state 3")

plt.show()
```

<img src="https://github.com/dellabellagabriel/neurostates/raw/main/res/states.png" alt="logo" width="50%">

You can also access intermediate results from the pipeline, such as the windowed timeseries or the connectivity matrices:

```python
connectivity_matrices = brain_state_pipeline["connectivity"].dict_of_groups_
print(f"Connectivity matrices has keys: {connectivity_matrices.keys()}")
print(f"Control has size: {connectivity_matrices['controls'].shape}")
```

```
Connectivity matrices has keys: dict_keys(['controls', 'patients'])  
Control has size (subjects, windows, regions, regions): (10, 97, 90, 90)
```

## Compute brain state frequencies

To evaluate how often each brain state occurs for each subject, we use the `Frequencies` transformer:

```python
from neurostates.core.classification import Frequencies

frequencies = Frequencies(
    centroids=brain_state_pipeline["clustering"].cluster_centers_
)
freqs = frequencies.transform(connectivity_matrices)

print(f"freqs has keys: {freqs.keys()}")
print(f"Control has size (subjects, states): {freqs['controls'].shape}")
```

```
freqs has keys: dict_keys(['controls', 'patients'])  
Control has size (subjects, states): (10, 3)
```

Finally, you can plot the frequency of each brain state in the data:

```python
fig, ax = plt.subplots(1, 3, figsize=(8, 4))

ax[0].boxplot(
    [freqs["controls"][:, 0], freqs["patients"][:, 0]],
    labels=["controls", "patients"]
)
ax[0].set_ylabel("frequency")
ax[0].set_title("state 1")

ax[1].boxplot(
    [freqs["controls"][:, 1], freqs["patients"][:, 1]],
    labels=["controls", "patients"]
)
ax[1].set_title("state 2")

ax[2].boxplot(
    [freqs["controls"][:, 2], freqs["patients"][:, 2]],
    labels=["controls", "patients"]
)
ax[2].set_title("state 3")

plt.show()
```

<img src="https://github.com/dellabellagabriel/neurostates/raw/main/res/frequencies.png" alt="logo" width="50%">

# Documentation
If you want to see the full documentation please visit [https://neurostates.readthedocs.io/en/latest/index.html](https://neurostates.readthedocs.io/en/latest/).

# License
Neurostates is under The 3-Clause BSD License

This license allows unlimited redistribution for any purpose as long as its copyright notices and the license's disclaimers of warranty are maintained.

# Contact Us
If you have any questions, feel free to check out our Github issues or write us an email to: dellabellagabriel@gmail.com or natirodriguez114@gmail.com

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "neurostates",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "brain, functional, connectivity, eeg, fmri",
    "author": null,
    "author_email": "Gabriel Della Bella <dellabellagabriel@gmail.com>, Natalia Rodriguez <natirodriguez114@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/bc/79/034f06d5ca1db21f17f6bc5ff9a6f4f3016a928bdb4a60ddc4c089418d97/neurostates-0.1.2.tar.gz",
    "platform": null,
    "description": "# NeuroStates\n\n<img src=\"https://raw.githubusercontent.com/dellabellagabriel/neurostates/main/res/logo_final.png\" alt=\"logo\" width=\"20%\">\n\n[![Gihub Actions CI](https://github.com/dellabellagabriel/neurostates/actions/workflows/CI.yml/badge.svg)](https://github.com/dellabellagabriel/neurostates/actions/workflows/CI.yml)\n[![Documentation Status](https://readthedocs.org/projects/neurostates/badge/?version=latest&style=flat)](https://neurostates.readthedocs.io/en/latest/)\n[![License](https://img.shields.io/pypi/l/uttrs?color=blue)](https://www.tldrlegal.com/l/bsd3)\n\n**NeuroStates** is a Python package for detecting recurrent functional connectivity patterns (also known as brain states) and estimating their ocurrence probabilities in EEG and fMRI.\n\n# Install\nBefore installing, make sure you have the following:\n- Python 3.9 or later.\n- pip (Python's package installer).\n- A virtual environment (optional, but recommended).\n\nFrom PyPI repo, simply run:\n```bash\npip install neurostates\n```\nYou can install it in development mode by running:\n```bash\npip install -e .\n```\n\n# Basic Usage\n## Load data\n\nWe load two groups of subjects \u2014 controls and patients \u2014 where each subject's data is a time series of brain activity (e.g., from fMRI or EEG).  \nIt must be of size `(subjects x regions x time)`.\n\n```python\nimport numpy as np\nimport scipy.io as sio\n\ngroup_controls = sio.loadmat(\"path/to/control/data\")[\"ts\"]\ngroup_patients = sio.loadmat(\"path/to/patient/data\")[\"ts\"]\n\ngroups = {\n    \"controls\": group_controls,\n    \"patients\": group_patients\n}\n\nprint(f\"Control group shape (subjects, regions, time): {group_controls.shape}\")\nprint(f\"Patient group shape (subjects, regions, time): {group_patients.shape}\")\n```\n\n```\nControl group shape (subjects, regions, time): (10, 90, 500)  \nPatient group shape (subjects, regions, time): (10, 90, 500)\n```\n\n## Build the pipeline\n\nNeurostates implements a `scikit-learn`-compatible pipeline that includes all of the important steps required for brain state analysis.  \nThe pipeline includes:\n\n- A sliding window that segments the time series  \n- Dynamic connectivity estimation (e.g., Pearson, cosine similarity, Spearman\u2019s R, or a custom metric)  \n- Concatenation of all matrices across subjects  \n- Clustering using KMeans to extract brain states  \n\n```python\nfrom sklearn.cluster import KMeans\nfrom sklearn.pipeline import Pipeline\n\nfrom neurostates.core.clustering import Concatenator\nfrom neurostates.core.connectivity import DynamicConnectivityGroup\nfrom neurostates.core.window import SecondsWindowerGroup\n\nbrain_state_pipeline = Pipeline(\n    [\n        (\n            \"windower\",\n            SecondsWindowerGroup(length=20, step=5, sample_rate=1)\n        ),\n        (\n            \"connectivity\",\n            DynamicConnectivityGroup(method=\"pearson\")\n        ),\n        (\n            \"preclustering\",\n            Concatenator()\n        ),\n        (\n            \"clustering\",\n            KMeans(n_clusters=3, random_state=42)\n        ),\n    ]\n)\n```\n\nThen you can use the `fit_transform()` method to transform your input data and get the centroids (brain states):\n\n```python\nbrain_state_pipeline.fit_transform(groups)\nbrain_states = brain_state_pipeline[\"clustering\"].cluster_centers_\n\n# Originally brain_states will be a 3 by 8100 matrix.\n# We reshape them to get the matrix structure back\nbrain_states = brain_states.reshape(3, 90, 90)\n```\n\nAnd you can plot them like so:\n\n```python\nimport matplotlib.pyplot as plt\n\nfig, ax = plt.subplots(1, 3)\nax[0].imshow(brain_states[0], vmin=-0.5, vmax=1)\nax[0].set_title(\"state 1\")\nax[0].set_ylabel(\"regions\")\nax[0].set_xlabel(\"regions\")\n\nax[1].imshow(brain_states[1], vmin=-0.5, vmax=1)\nax[1].set_title(\"state 2\")\n\nax[2].imshow(brain_states[2], vmin=-0.5, vmax=1)\nax[2].set_title(\"state 3\")\n\nplt.show()\n```\n\n<img src=\"https://github.com/dellabellagabriel/neurostates/raw/main/res/states.png\" alt=\"logo\" width=\"50%\">\n\nYou can also access intermediate results from the pipeline, such as the windowed timeseries or the connectivity matrices:\n\n```python\nconnectivity_matrices = brain_state_pipeline[\"connectivity\"].dict_of_groups_\nprint(f\"Connectivity matrices has keys: {connectivity_matrices.keys()}\")\nprint(f\"Control has size: {connectivity_matrices['controls'].shape}\")\n```\n\n```\nConnectivity matrices has keys: dict_keys(['controls', 'patients'])  \nControl has size (subjects, windows, regions, regions): (10, 97, 90, 90)\n```\n\n## Compute brain state frequencies\n\nTo evaluate how often each brain state occurs for each subject, we use the `Frequencies` transformer:\n\n```python\nfrom neurostates.core.classification import Frequencies\n\nfrequencies = Frequencies(\n    centroids=brain_state_pipeline[\"clustering\"].cluster_centers_\n)\nfreqs = frequencies.transform(connectivity_matrices)\n\nprint(f\"freqs has keys: {freqs.keys()}\")\nprint(f\"Control has size (subjects, states): {freqs['controls'].shape}\")\n```\n\n```\nfreqs has keys: dict_keys(['controls', 'patients'])  \nControl has size (subjects, states): (10, 3)\n```\n\nFinally, you can plot the frequency of each brain state in the data:\n\n```python\nfig, ax = plt.subplots(1, 3, figsize=(8, 4))\n\nax[0].boxplot(\n    [freqs[\"controls\"][:, 0], freqs[\"patients\"][:, 0]],\n    labels=[\"controls\", \"patients\"]\n)\nax[0].set_ylabel(\"frequency\")\nax[0].set_title(\"state 1\")\n\nax[1].boxplot(\n    [freqs[\"controls\"][:, 1], freqs[\"patients\"][:, 1]],\n    labels=[\"controls\", \"patients\"]\n)\nax[1].set_title(\"state 2\")\n\nax[2].boxplot(\n    [freqs[\"controls\"][:, 2], freqs[\"patients\"][:, 2]],\n    labels=[\"controls\", \"patients\"]\n)\nax[2].set_title(\"state 3\")\n\nplt.show()\n```\n\n<img src=\"https://github.com/dellabellagabriel/neurostates/raw/main/res/frequencies.png\" alt=\"logo\" width=\"50%\">\n\n# Documentation\nIf you want to see the full documentation please visit [https://neurostates.readthedocs.io/en/latest/index.html](https://neurostates.readthedocs.io/en/latest/).\n\n# License\nNeurostates is under The 3-Clause BSD License\n\nThis license allows unlimited redistribution for any purpose as long as its copyright notices and the license's disclaimers of warranty are maintained.\n\n# Contact Us\nIf you have any questions, feel free to check out our Github issues or write us an email to: dellabellagabriel@gmail.com or natirodriguez114@gmail.com\n",
    "bugtrack_url": null,
    "license": "Copyright (c) 2024, Della Bella, Gabriel; Rodriguez, Natalia\n        All rights reserved.\n        \n        Redistribution and use in source and binary forms, with or without\n        modification, are permitted provided that the following conditions are met:\n        \n        * Redistributions of source code must retain the above copyright notice, this\n        list of conditions and the following disclaimer.\n        \n        * Redistributions in binary form must reproduce the above copyright notice,\n        this list of conditions and the following disclaimer in the documentation\n        and/or other materials provided with the distribution.\n        \n        * Neither the name of the copyright holder nor the names of its\n        contributors may be used to endorse or promote products derived from\n        this software without specific prior written permission.\n        \n        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\n        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\n        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE\n        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR\n        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF\n        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS\n        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN\n        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)\n        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\n        POSSIBILITY OF SUCH DAMAGE.",
    "summary": "Neurostates is a tool for analyzing patterns of functional connectivity in EEG and fMRI.",
    "version": "0.1.2",
    "project_urls": null,
    "split_keywords": [
        "brain",
        " functional",
        " connectivity",
        " eeg",
        " fmri"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "73fc006dfe05da1e4bd7d9f3755ade9824b8fc4a7434efad4ff5e0378f31c250",
                "md5": "c759434ac6f969ea936e130f8b3ec750",
                "sha256": "cde90fad17cd5b06e5f9f9abfe5a6112f60fc6c202735d6bc9f8ded782ca2466"
            },
            "downloads": -1,
            "filename": "neurostates-0.1.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c759434ac6f969ea936e130f8b3ec750",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 13219,
            "upload_time": "2025-04-07T23:13:23",
            "upload_time_iso_8601": "2025-04-07T23:13:23.092484Z",
            "url": "https://files.pythonhosted.org/packages/73/fc/006dfe05da1e4bd7d9f3755ade9824b8fc4a7434efad4ff5e0378f31c250/neurostates-0.1.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "bc79034f06d5ca1db21f17f6bc5ff9a6f4f3016a928bdb4a60ddc4c089418d97",
                "md5": "c8227edc803739b4802f970e31f01c11",
                "sha256": "1c903fba08bd31253e8dccffd9a3d5e75cd79884af68f1f4fa36b5f014b7fc7c"
            },
            "downloads": -1,
            "filename": "neurostates-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "c8227edc803739b4802f970e31f01c11",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 12316,
            "upload_time": "2025-04-07T23:13:24",
            "upload_time_iso_8601": "2025-04-07T23:13:24.867320Z",
            "url": "https://files.pythonhosted.org/packages/bc/79/034f06d5ca1db21f17f6bc5ff9a6f4f3016a928bdb4a60ddc4c089418d97/neurostates-0.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-04-07 23:13:24",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "neurostates"
}
        
Elapsed time: 0.41818s