{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Analysing continuous features with binning and regression in sensor space\n\nPredict single trial activity from a continuous variable.\nA single-trial regression is performed in each sensor and timepoint\nindividually, resulting in an :class:`mne.Evoked` object which contains the\nregression coefficient (beta value) for each combination of sensor and\ntimepoint. This example shows the regression coefficient; the t and p values\nare also calculated automatically.\n\nHere, we repeat a few of the analyses from :footcite:`DufauEtAl2015`. This\ncan be easily performed by accessing the metadata object, which contains\nword-level information about various psycholinguistically relevant features\nof the words for which we have EEG activity.\n\nFor the general methodology, see e.g. :footcite:`HaukEtAl2006`.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Authors: Tal Linzen <linzen@nyu.edu>\n#          Denis A. Engemann <denis.engemann@gmail.com>\n#          Jona Sassenhagen <jona.sassenhagen@gmail.com>\n#\n# License: BSD-3-Clause\n# Copyright the MNE-Python contributors."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import pandas as pd\n\nimport mne\nfrom mne.datasets import kiloword\nfrom mne.stats import fdr_correction, linear_regression\nfrom mne.viz import plot_compare_evokeds\n\n# Load the data\npath = kiloword.data_path() / \"kword_metadata-epo.fif\"\nepochs = mne.read_epochs(path)\nprint(epochs.metadata.head())"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Psycholinguistically relevant word characteristics are continuous. I.e.,\nconcreteness or imaginability is a graded property. In the metadata,\nwe have concreteness ratings on a 5-point scale. We can show the dependence\nof the EEG on concreteness by dividing the data into bins and plotting the\nmean activity per bin, color coded.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "name = \"Concreteness\"\ndf = epochs.metadata\ndf[name] = pd.cut(df[name], 11, labels=False) / 10\ncolors = {str(val): val for val in df[name].unique()}\nepochs.metadata = df.assign(Intercept=1)  # Add an intercept for later\nevokeds = {val: epochs[name + \" == \" + val].average() for val in colors}\nplot_compare_evokeds(\n    evokeds, colors=colors, split_legend=True, cmap=(name + \" Percentile\", \"viridis\")\n)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We observe that there appears to be a monotonic dependence of EEG on\nconcreteness. We can also conduct a continuous analysis: single-trial level\nregression with concreteness as a continuous (although here, binned)\nfeature. We can plot the resulting regression coefficient just like an\nEvent-related Potential.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "names = [\"Intercept\", name]\nres = linear_regression(epochs, epochs.metadata[names], names=names)\nfor cond in names:\n    res[cond].beta.plot_joint(\n        title=cond, ts_args=dict(time_unit=\"s\"), topomap_args=dict(time_unit=\"s\")\n    )"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Because the :func:`~mne.stats.linear_regression` function also estimates\np values, we can --\nafter applying FDR correction for multiple comparisons -- also visualise the\nstatistical significance of the regression of word concreteness.\nThe :func:`mne.viz.plot_evoked_image` function takes a ``mask`` parameter.\nIf we supply it with a boolean mask of the positions where we can reject\nthe null hypothesis, points that are not significant will be shown\ntransparently, and if desired, in a different colour palette and surrounded\nby dark contour lines.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "reject_H0, fdr_pvals = fdr_correction(res[\"Concreteness\"].p_val.data)\nevoked = res[\"Concreteness\"].beta\nevoked.plot_image(mask=reject_H0, time_unit=\"s\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## References\n.. footbibliography::\n\n"
      ]
    }
  ],
  "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.12.2"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}