{ "cells": [ { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "%matplotlib inline" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "\n# 02. Detect HFOs on BIDS Dataset\n\nMNE-HFO requires strict adherence to the BIDS specification for EEG/iEEG data.\nIt currently depends on the data structures defined by ``MNE-Python`` and\n``MNE-BIDS``.\n\nIn this example, we use MNE-BIDS to load real raw data and then use\nMNE-HFO to detect HFOs. Specifically, we will follow these steps:\n\n1. Load data via :func:`mne_bids.read_raw_bids`. We will load a sample subject\nfrom the Fedele dataset [1].\n\n2. Run a few ``mne_hfo.base.Detector`` instances to detect HFOs\n\n3. Format the detected HFOs as a :class:`pandas.DataFrame`\n\n4. Write to disk according to BEP-021_ and read it in again.\n\n\n## References\n[1] Fedele T, Burnos S, Boran E, Krayenb\u00fchl N, Hilfiker P, Grunwald T, Sarnthein J.\n Resection of high frequency oscillations predicts seizure outcome in the individual\n patient. Scientific Reports. 2017;7(1):13836.\n https://www.nature.com/articles/s41598-017-13064-1. doi:10.1038/s41598-017-13064-1\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "# Authors: Adam Li \n#" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We are importing everything we need for this example:\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "from pathlib import Path\n\nfrom mne_bids import BIDSPath, read_raw_bids, make_report, print_dir_tree\n\nfrom mne_hfo import (RMSDetector, events_to_annotations, write_annotations,\n read_annotations)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Load the data\n\nFirst, we need some data to work with. We will use the test dataset\navailable with the repository under ``data/`` directory.\n\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "# root of BIDs dataset\nroot = Path('../data/')\n\n# BIDS entities\nsubject = '01'\nsession = 'interictalsleep'\nrun = '01'\ndatatype = 'ieeg'" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "show the contents of the BIDS dataset\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "print_dir_tree(root)\n\n# Let's summarize the dataset.\nprint(make_report(root, verbose=False))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Load the dataset.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "bids_path = BIDSPath(subject=subject, session=session,\n run=run, datatype=datatype, root=root,\n suffix='ieeg', extension='.vhdr')\nraw = read_raw_bids(bids_path)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Let's plot the data and see what it looks like\nraw.plot()\n\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Detect HFOs\nAll detectors inherit from the base class ``mne_hfo.base.Detector``,\nwhich inherits from the :class:`sklearn.base.BaseEstimator` class.\nTo run any estimator, one instantiates it along with the hyper-parameters,\nand then calls the ``fit`` function. Afterwards, detected HFOs are available\nin the various data structures. The recommended usage is the DataFrame, which\nis accessible via the ``mne_hfo.base.Detector.hfo_df`` property.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "kwargs = {\n 'threshold': 3, # threshold for \"significance\"\n 'win_size': 100, # window size in samples\n 'overlap': 0.25 # overlap in percentage relative to the window size\n}\ndetector = RMSDetector(**kwargs)\n\n# run detector\ndetector.fit(X=raw)\n\n# get the HFO results as an events.tsv DataFrame\nevent_df = detector.hfo_event_df\nprint(event_df.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Convert HFO events to annotations\nDetectors output HFO events detected as a DataFrame fashioned after the\n``*_events.tsv`` files in BIDS-iEEG. Instead, HFO events are indeed\nDerivatives of the Raw data, that are estimated/detected using mne-hfo.\nThe correct way to store them is in terms of an ``*_annotations.tsv``,\naccording to the BIDS-Derivatives specification.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "# convert event df -> annotation df\nannot_df = events_to_annotations(event_df)\n\n# alternatively save annotation dataframe to disc\nannot_path = bids_path.copy().update(suffix='annotations',\n root=root / 'derivatives',\n extension='.tsv',\n check=False)\n\nintended_for = raw.filenames[0]\nwrite_annotations(annot_df, fname=annot_path,\n intended_for=intended_for, root=root)\nprint(annot_df.head())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Read data back in\nThe data will match what was written.\nIn addition, you can check for overlapping HFOs.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "annot_df = read_annotations(annot_path)\n\nprint(annot_df.head())" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.8.6" } }, "nbformat": 4, "nbformat_minor": 0 }