https://github.com/mne-tools/mne-hfo
Estimate/compute high-frequency oscillations (HFOs) from iEEG data that are BIDS and MNE compatible using a scikit-learn-style API.
https://github.com/mne-tools/mne-hfo
bids hfo-detection ieeg ieeg-data mne-hfo mne-python
Last synced: 27 days ago
JSON representation
Estimate/compute high-frequency oscillations (HFOs) from iEEG data that are BIDS and MNE compatible using a scikit-learn-style API.
- Host: GitHub
- URL: https://github.com/mne-tools/mne-hfo
- Owner: mne-tools
- License: bsd-3-clause
- Created: 2020-12-18T22:34:06.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-12-26T18:38:26.000Z (about 2 years ago)
- Last Synced: 2025-10-27T12:36:32.342Z (4 months ago)
- Topics: bids, hfo-detection, ieeg, ieeg-data, mne-hfo, mne-python
- Language: Python
- Homepage: http://mne.tools/mne-hfo/
- Size: 8.17 MB
- Stars: 14
- Watchers: 8
- Forks: 16
- Open Issues: 27
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
- Zenodo: .zenodo.json
Awesome Lists containing this project
README
[](https://codecov.io/gh/adam2392/mne-hfo)
[](https://github.com/mne-tools/mne-hfo/actions/workflows/unit_tests.yml)
[](https://circleci.com/gh/mne-tools/mne-hfo)
[](https://github.com/psf/black)
[](https://mne-hfo.readthedocs.io/en/latest/?badge=latest)
[](https://pepy.tech/project/mne-hfo)
MNE-HFO
=======
MNE-HFO is a Python package that computes estimates of high-frequency oscillations in iEEG data stored in
the [BIDS-compatible](https://bids.neuroimaging.io/) datasets with the help of
[MNE-Python](https://mne.tools/stable/index.html).
NOTE: This is currently in ALPHA stage, and we are looking for contributors. Please get in touch via Issues tab if you
would like to contribute.
High frequency oscillations in epilepsy
---------------------------------------
A few notes that are worthy of reading. The initial papers on HFOs (Staba et al.)
actually only observed HFOs on Hippocampus. In addition, the papers cited that are implemented all selected data before
developing their algorithm (i.e. selected channels with HFOs).
It is also noted that the Hilbert detector was used to show HFOs exist in normal brain function, possibly unassociated
with the epileptogenic zone.
Why?
----
Currently HFO detection and algorithms are segmented in Matlab files, which are sometimes not open-source, or possibly
difficult to use. In addition, validation of HFO algorithms depend on i) sharing the algorithms ii) sharing the results
with others in a readable format and iii) comparing algorithms against each other on the same dataset.
MNE-HFO links BIDS, MNE-Python and iEEG HFO event detection with the goal to make HFO detection more transparent, more
robust, and facilitate data and code sharing with co-workers and collaborators.
Installation
------------
Installation can be done via a python virtual environment, using ``pipenv``. The package is hosted on ``pypi``, which
can be installed via pip, or pipenv. For additional installation instructions, see [CONTRIBUTING.md](https://github.com/mne-tools/mne-hfo/blob/master/CONTRIBUTING.md) document.
pip install mne-hfo
or
pipenv install mne-hfo
Note: Installation has been tested on MacOSX and Ubuntu, but should
probably work on Windows too.
Documentation and Usage
-----------------------
The documentation can be found under the following links:
- for the [stable release](https://mne.tools/mne-hfo/)
- for the [latest (development) version](https://mne.tools/mne-hfo/dev/index.html)
Note: Functionality has been tested on MacOSX and Ubuntu.
Basic Working Example
---------------------
A basic working example is listed here, assuming one has loaded in a mne-Python ``Raw`` object already.
from mne_hfo import RMSDetector
detector = RMSDetector()
# assume user has loaded in raw iEEG data using mne-python
detector.fit(raw)
# get the HFO events as an *events.tsv style dataframe
hfo_event_df = detector.hfo_event_df
# get the HFO events as an *events.tsv style dataframe
hfo_annot_df = detector.hfo_df
All output to ``*events.tsv`` BIDS-compliant files will look like the following:
| onset | duration | sample | trial_type |
| ---------- | -------- | ------ | ---------- |
| 1 | 3 | 1000 | hfo_A2-A1 |
which will imply that there is an HFO detected using a bipolar referencing at channel ``A2-A1``
at 1 second with duration of 3 seconds. The onset sample occurs at sample 1000 (thus ``sfreq`` is 1000 Hz). If a
monopolar referencing is used, then the ``trial_type`` might be ``hfo_A2`` to imply that an HFO was detected at
channel ``A2``.
Alternatively, one can output the data in the form of a derivatives ``Annotations``
DataFrame, which is the RECOMMENDED way. Outputting data according to BIDS Extension Proposal 21, instead would result in
an ``*annotations.tsv`` file.
| onset | duration | label | channels |
| ---------- | -------- | ------ | ---------- |
| 1 | 3 | hfo | A2-A1 |
with a corresponding ``*annotations.json`` file.
{
'IntendedFor': sub-01/ses-01/eeg/sub-01_ses-01_task-01_eeg.,
'Description': 'Automatic annotations of HFO events using mne-hfo.',
}
Optimizing Hyperparameters
--------------------------
In all ``MNE-HFO`` HFO detectors, we assume that there are hyper-parameters
specified by the proposed algorithm. These hyper-parameters can be tuned automatically
using the ``scikit-learn`` API for [GridSearchCV](https://scikit-learn.org/stable/modules/grid_search.html#grid-search).
from sklearn.metrics import make_scorer
from sklearn.model_selection import GridSearchCV
from mne_hfo.score import accuracy
from mne_hfo.sklearn import make_Xy_sklearn, DisabledCV
# define hyperparameter grid to search over
parameters = {'threshold': [1, 2, 3], 'win_size': [50, 100, 250]}
# define HFO detector
detector = LineLengthDetector()
# define a scoring function
scorer = make_scorer(accuracy)
# we don't use cross-validation since the
# HFO algorithm is deterministic
cv = DisabledCV()
# instantiate the GridSearch object
gs = GridSearchCV(detector, param_grid=parameters, scoring=scorer,
cv=cv, refit=False, verbose=True)
# load in raw data
# raw =
# load in HFO annotations
# annot_df =
# make sklearn compatible
raw_df, y = make_Xy_sklearn(raw, annot_df)
# run hyperparameter tuning based on accuracy score
gs.fit(raw_df, y, groups=None)
# show the results
print(gs.cv_results_["mean_test_score"])
In the above example, to load in raw data, one can use [``mne-bids``](https://github.com/mne-tools/mne-bids)
and to load in the annotations dataframe, one can check out our API
for different ways of doing so.
Citing
------
For testing and demo purposes, we use the dataset in [1]. If you use the demo/testing dataset, please cite that paper.
If you use ``mne-hfo`` itself in your research, please cite the paper (TBD).
Adam Li. (2021, February 1). MNE-HFO: An open-source Python implementation of HFO detection algorithms (Version 0.0.1). Zenodo. http://doi.org/10.5281/zenodo.4485036
History and state of development
--------------------------------
The initial code was adapted and taken from: https://gitlab.com/icrc-bme/epycom
to turn into a sklearn-compatible API that works with ``mne-python``. Additional algorithms
and functionality were added.
References
----------
[1] Fedele T, Burnos S, Boran E, Krayenbühl N, Hilfiker P, Grunwald T, Sarnthein J. Resection of high frequency
oscillations predicts seizure outcome in the individual patient. Scientific Reports. 2017;7(1):13836.
https://www.nature.com/articles/s41598-017-13064-1
doi:10.1038/s41598-017-13064-1