{
  "nbformat_minor": 0, 
  "nbformat": 4, 
  "cells": [
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "%matplotlib inline"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "\n\nThe :class:`Evoked <mne.Evoked>` data structure: evoked/averaged data\n=====================================================================\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "import os.path as op\n\nimport mne"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "The :class:`Evoked <mne.Evoked>` data structure is mainly used for storing\naveraged data over trials. In MNE the evoked objects are created by averaging\nepochs data with :func:`mne.Epochs.average`. Here we read the evoked dataset\nfrom a file.\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "data_path = mne.datasets.sample.data_path()\nfname = op.join(data_path, 'MEG', 'sample', 'sample_audvis-ave.fif')\nevokeds = mne.read_evokeds(fname, baseline=(None, 0), proj=True)\nprint(evokeds)"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "Notice that the reader function returned a list of evoked instances. This is\nbecause you can store multiple categories into a single file. Here we have\ncategories of\n``['Left Auditory', 'Right Auditory', 'Left Visual', 'Right Visual']``.\nWe can also use ``condition`` parameter to read in only one category.\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "evoked = mne.read_evokeds(fname, condition='Left Auditory')\nevoked.apply_baseline((None, 0)).apply_proj()\nprint(evoked)"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "If you're gone through the tutorials of raw and epochs datasets, you're\nprobably already familiar with the :class:`Info <mne.Info>` attribute.\nThere is nothing new or special with the ``evoked.info``. All the relevant\ninfo is still there.\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "print(evoked.info)\nprint(evoked.times)"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "The evoked data structure also contains some new attributes easily\naccessible:\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "print(evoked.nave)  # Number of averaged epochs.\nprint(evoked.first)  # First time sample.\nprint(evoked.last)  # Last time sample.\nprint(evoked.comment)  # Comment on dataset. Usually the condition.\nprint(evoked.kind)  # Type of data, either average or standard_error."
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "The data is also easily accessible. Since the evoked data arrays are usually\nmuch smaller than raw or epochs datasets, they are preloaded into the memory\nwhen the evoked object is constructed. You can access the data as a numpy\narray.\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "data = evoked.data\nprint(data.shape)"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "The data is arranged in an array of shape `(n_channels, n_times)`. Notice\nthat unlike epochs, evoked object does not support indexing. This means that\nto access the data of a specific channel you must use the data array\ndirectly.\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "print('Data from channel {0}:'.format(evoked.ch_names[10]))\nprint(data[10])"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "If you want to import evoked data from some other system and you have it in a\nnumpy array you can use :class:`mne.EvokedArray` for that. All you need is\nthe data and some info about the evoked data. For more information, see\n`tut_creating_data_structures`.\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }, 
    {
      "execution_count": null, 
      "cell_type": "code", 
      "source": [
        "evoked = mne.EvokedArray(data, evoked.info, tmin=evoked.times[0])\nevoked.plot()"
      ], 
      "outputs": [], 
      "metadata": {
        "collapsed": false
      }
    }, 
    {
      "source": [
        "To write an evoked dataset to a file, use the :meth:`mne.Evoked.save` method.\nTo save multiple categories to a single file, see :func:`mne.write_evokeds`.\n\n"
      ], 
      "cell_type": "markdown", 
      "metadata": {}
    }
  ], 
  "metadata": {
    "kernelspec": {
      "display_name": "Python 2", 
      "name": "python2", 
      "language": "python"
    }, 
    "language_info": {
      "mimetype": "text/x-python", 
      "nbconvert_exporter": "python", 
      "name": "python", 
      "file_extension": ".py", 
      "version": "2.7.13", 
      "pygments_lexer": "ipython2", 
      "codemirror_mode": {
        "version": 2, 
        "name": "ipython"
      }
    }
  }
}