Eelbrain

https://zenodo.org/badge/3651023.svg https://anaconda.org/christianbrodbeck/eelbrain/badges/installer/conda.svg https://anaconda.org/christianbrodbeck/eelbrain/badges/platforms.svg

Eelbrain is an open-source Python package for accessible statistical analysis of MEG and EEG data. It is maintained by Christian Brodbeck at the Computational sensorimotor systems lab at University of Maryland, College Park.

If you use Eelbrain in work that is published, please acknowledge it by citing it with the appropriate DOI for the version you used.

Manual

Installing

Note

Because of the fluid nature of Python development, the recommended way of installing Eelbrain changes occasionally. For up-to-date information, see the corresponding Eelbrain wiki page.

Getting Started

MacOS: Framework Build

On macOS, the GUI tool Eelbrain uses requires a special build of Python called a “Framework build”. You might see this error when trying to create a plot:

SystemExit: This program needs access to the screen.
Please run with a Framework build of python, and only when you are
logged in on the main display of your Mac.

In order to avoid this, Eelbrain installs a shortcut to start IPython with a Framework build:

$ eelbrain

This automatically launches IPython with the “eelbrain” profile. A default startup script that executes from eelbrain import * is created, and can be changed in the corresponding IPython profile.

Quitting iPython

Sometimes iPython seems to get stuck after this line:

Do you really want to exit ([y]/n)? y

In those instances, pressing ctrl-c usually terminates iPython immediately.

Windows: Scrolling

Scrolling inside a plot axes normally uses arrow keys, but this is currently not possible on Windows (due to an issue in Matplotlib). Instead, the following keys can be used:

  ↑ i  
← j   → l
  ↓ k  

Introduction

There are three primary data-objects:

  • Factor for categorial variables
  • Var for scalar variables
  • NDVar for multidimensional data (e.g. a variable measured at different time points)

Multiple variables belonging to the same dataset can be grouped in a Dataset object.

Factor

A Factor is a container for one-dimensional, categorial data: Each case is described by a string label. The most obvious way to initialize a Factor is a list of strings:

>>> A = Factor(['a', 'a', 'a', 'a', 'b', 'b', 'b', 'b'], name='A')

Since Factor initialization simply iterates over the given data, the same Factor can be initialized with:

>>> Factor('aaaabbbb', name='A')
Factor(['a', 'a', 'a', 'a', 'b', 'b', 'b', 'b'], name='A')

There are other shortcuts to initialize factors (see also the Factor class documentation):

>>> A = Factor(['a', 'b', 'c'], repeat=4, name='A')
>>> A
Factor(['a', 'a', 'a', 'a', 'b', 'b', 'b', 'b', 'c', 'c', 'c', 'c'], name='A')

Indexing works like for arrays:

>>> A[0]
'a'
>>> A[0:6]
Factor(['a', 'a', 'a', 'a', 'b', 'b'], name='A')

All values present in a Factor are accessible in its Factor.cells attribute:

>>> A.cells
('a', 'b', 'c')

Based on the Factor’s cell values, boolean indexes can be generated:

>>> A == 'a'
array([ True,  True,  True,  True, False, False, False, False, False,
       False, False, False], dtype=bool)
>>> A.isany('a', 'b')
array([ True,  True,  True,  True,  True,  True,  True,  True, False,
       False, False, False], dtype=bool)
>>> A.isnot('a', 'b')
array([False, False, False, False, False, False, False, False,  True,
        True,  True,  True], dtype=bool)

Interaction effects can be constructed from multiple factors with the % operator:

>>> B = Factor(['d', 'e'], repeat=2, tile=3, name='B')
>>> B
Factor(['d', 'd', 'e', 'e', 'd', 'd', 'e', 'e', 'd', 'd', 'e', 'e'], name='B')
>>> i = A % B

Interaction effects are in many ways interchangeable with factors in places where a categorial model is required:

>>> i.cells
(('a', 'd'), ('a', 'e'), ('b', 'd'), ('b', 'e'), ('c', 'd'), ('c', 'e'))
>>> i == ('a', 'd')
array([ True,  True, False, False, False, False, False, False, False,
       False, False, False], dtype=bool)

Var

The Var class is basically a container to associate one-dimensional numpy.ndarray objects with a name. While simple operations can be performed on the object directly, for any more complex operations on the data the corresponding numpy.ndarray can be retrieved in the Var.x attribute:

>>> Y = Var(np.random.rand(10), name='Y')
>>> Y
Var([0.185, 0.285, 0.105, 0.916, 0.76, 0.888, 0.288, 0.0165, 0.901, 0.72], name='Y')
>>> Y[5:]
Var([0.888, 0.288, 0.0165, 0.901, 0.72], name='Y')
>>> Y + 1
Var([1.18, 1.28, 1.11, 1.92, 1.76, 1.89, 1.29, 1.02, 1.9, 1.72], name='Y+1')
>>> Y.x
array([ 0.18454728,  0.28479396,  0.10546204,  0.91619036,  0.76006963,
        0.88807645,  0.28807859,  0.01645504,  0.90112081,  0.71991843])

Note

Note however that the Var.x attribute is not intended to be replaced; rather, a new Var object should be created for a new array.

NDVar

NDVar objects are containers for multidimensional data, and manage the description of the dimensions along with the data. NDVars are often derived from some import function, for example load.fiff.stc_ndvar(). As an example, consider single trial data from the mne sample dataset:

>>> ds = datasets.get_mne_sample(src='ico')
>>> src = ds['src']
>>> src
<NDVar 'src': 145 case, 5120 source, 76 time>

This representation shows that src contains 145 trials of data, with 5120 sources and 76 time points. NDVars offer numpy functionality that takes into account the dimensions. Through the NDVar.sub() method, indexing can be done using meaningful descriptions, such as selecting data for only the left hemisphere:

>>> src.sub(source='lh')
<NDVar 'src': 145 case, 2559 source, 76 time>

Through several methods data can be aggregated, for example a mean over time:

>>> src.mean('time')
<NDVar 'src': 145 case, 5120 source>

Or a root mean square over sources:

>>> src.rms('source')
<NDVar 'src': 145 case, 76 time>

As with a Var, the corresponding numpy.ndarray can always be accessed in the NDVar.x attribute:

>>> type(src.x)
numpy.ndarray
>>> src.x.shape
(145, 5120, 76)

NDVar objects can be constructed from an array and corresponding dimension objects, for example:

>>> frequency = Scalar('frequency', [1, 2, 3, 4])
>>> time = UTS(0, 0.01, 50)
>>> data = numpy.random.normal(0, 1, (4, 50))
>>> NDVar(data, (frequency, time))
<NDVar: 4 frequency, 50 time>

A case dimension can be added by including the bare Case class:

>>> data = numpy.random.normal(0, 1, (10, 4, 50))
>>> NDVar(data, (Case, frequency, time))
<NDVar: 10 case, 4 frequency, 50 time>

Dataset

The Dataset class is a subclass of collections.OrderedDict from which it inherits much of its behavior. Its intended purpose is to be a vessel for variable objects (Factor, Var and NDVar) describing the same cases. As a dictionary, its keys are strings and its values are data-objects.

The Dataset class interacts with data-objects’ name attribute:

  • A Dataset initialized with a list of data-objects automatically uses their names as keys:

    >>> A = Factor('aabb', name='A')
>>> B = Factor('cdcd', name='B')
>>> ds = Dataset((A, B))
>>> print ds
A   B
-----
a   c
a   d
b   c
b   d
>>> ds['A']
Factor(['a', 'a', 'b', 'b'], name='A')

  • When an unnamed data-object is assigned to a Dataset, the data-object is automatically assigned its key as a name:

    >>> ds['Y'] = Var([2,1,4,2])
>>> print ds
A   B   Y
---------
a   c   2
a   d   1
b   c   4
b   d   2
>>> ds['Y']
Var([2, 1, 4, 2], name='Y')

The “official” string representation of a Dataset contains information on the variables stored in it:

>>> ds
<Dataset n_cases=4 {'A':F, 'B':F, 'Y':V}>

n_cases=4 indicates that the Dataset contains four cases (rows). The subsequent dictionary-like representation shows the keys and the types of the corresponding values (F: Factor, V: Var, Vnd: NDVar). If a variable’s name does not match its key in the Dataset, this is also indicated:

>>> ds['C'] = Factor('qwer', name='another_name')
>>> ds
<Dataset n_cases=4 {'A':F, 'B':F, 'Y':V, 'C':<F 'another_name'>}>

While indexing a Dataset with strings returns the corresponding data-objects, numpy.ndarray-like indexing on the Dataset can be used to access a subset of cases:

>>> ds2 = ds[2:]
>>> print ds2
A   B   Y   C
-------------
b   c   4   e
b   d   2   r
>>> ds2['A']
Factor(['b', 'b'], name='A')

Together with the “informal” string representation (retrieved by the print statement) this can be used to inspect the cases contained in the Dataset:

>>> print ds[0]
A   B   Y   C
-------------
a   c   2   q
>>> print ds[2:]
A   B   Y   C
-------------
b   c   4   e
b   d   2   r

This type of indexing also allows indexing based on the Dataset’s variables:

>>> print ds[A == 'a']
A   B   Y   C
-------------
a   c   2   q
a   d   1   w

Example

Below is a simple example using data objects (for more, see the statistics examples):

>>> from eelbrain import *
>>> import numpy as np
>>> y = np.empty(21)
>>> y[:14] = np.random.normal(0, 1, 14)
>>> y[14:] = np.random.normal(1.5, 1, 7)
>>> Y = Var(y, 'Y')
>>> A = Factor('abc', 'A', repeat=7)
>>> print Dataset((Y, A))
Y           A
-------------
0.10967     a
0.33562     a
-0.33151    a
1.3571      a
-0.49722    a
-0.24896    a
1.0979      a
-0.56123    b
-0.51316    b
-0.25942    b
-0.6072     b
-0.79173    b
0.0019011   b
2.1804      b
2.5373      c
1.7302      c
-0.17581    c
1.8922      c
1.2734      c
1.5961      c
1.1518      c
>>> print table.frequencies(A)
cell   n
--------
a      7
b      7
c      7
>>> print test.anova(Y, A)
                       SS   df               MS         F      p
----------------------------------------------------------------
A                    8.76    2             4.38   5.75*     .012

Residuals   13.7063612608   18   0.761464514489
----------------------------------------------------------------
Total               22.47   20
>>> print test.pairwise(Y, A, corr='Hochberg')

Pairwise t-Tests (independent samples)

    b                  c
----------------------------------------
a   t(12) = 0.71       t(12) = -2.79*
    p = .489           p = .016
    p(c) = .489        p(c) = .032
b                      t(12) = -3.00*
                       p = .011
                       p(c) = .032
(* Corrected after Hochberg, 1988)
>>> t = test.pairwise(Y, A, corr='Hochberg')
>>> print t.get_tex()
\begin{center}
\begin{tabular}{lll}
\toprule
 & b & c \\
\midrule
a & $t_{12} = 0.71^{    \ \ \ \ }$ & $t_{12} = -2.79^{*   \ \ \ }$ \\
 & $p = .489$ & $p = .016$ \\
 & $p_{c} = .489$ & $p_{c} = .032$ \\
b &  & $t_{12} = -3.00^{*   \ \ \ }$ \\
 &  & $p = .011$ \\
 &  & $p_{c} = .032$ \\
\bottomrule
\end{tabular}
\end{center}
>>> plot.Boxplot(Y, A, title="My Boxplot", ylabel="value", corr='Hochberg')
_images/statistics-example.png

Exporting Data

Dataset objects have different Dataset.save() methods for saving in various formats. Iterators (such as Var and Factor) can be exported using the save.txt() function.

Changes

New in 0.29

New in 0.28

  • Transition to Python 3.6
  • API changes:
    • testnd.anova: The match parameter is now determined automatically and does not need to be specified anymore in most cases.
    • testnd.ttest_1samp.diff renamed to testnd.ttest_1samp.difference.
    • plot.Histogram: following matplotlib, the normed parameter was renamed to density.
    • Previously capitalized argument and attribute names Y, X and Xax are now lowercase.
    • Topomap-plot argument order changed to provide consistency between different plots.
  • NDVar and Var support for round(x)
  • MneExperiment:
    • Independent measures t-test

New in 0.27

New in 0.26

New in 0.25

  • Installation with conda (see Installing) and $ eelbrain launch script (see Getting Started).
  • API:
    • NDVar objects now inherit names through operations.
    • Assignment to a Dataset overwrites variable .name attributes, unless the Dataset key is a pythonified version of .name.
  • GUI/plotting:
    • When using iPython 5 or later, GUI start and stop is now automatic. It is possible to revert to the old behavior with plot.configure().
    • There are new hotkeys for most plots (see the individual plots’ help for details).
    • Plots automatically rescale when the window is resized.
  • MneExperiment:
    • A new MneExperiment.sessions attribute replaces defaults['experiment'], with support for multiple sessions in one experiment (see Setting up the file structure).
    • The MneExperiment.epochs parameter sel_epoch has been removed, use base instead.
    • The setting raw='clm' has been renamed to raw='raw'.
    • Custom preprocessing pipelines (see MneExperiment.raw).
    • The model parameter for ANOVA tests is now optional (see MneExperiment.tests).
  • Reverse correlation using boosting().
  • Loading and saving *.wav files (load.wav() and save.wav()).

New in 0.24

New in 0.23

New in 0.22

New in 0.21

  • MneExperiment:
    • New epoch parameters: trigger_shift and vars (see MneExperiment.epochs).
    • load_selected_events(): new vardef parameter to load variables from a test definition.
    • Log files stored in the root directory.
    • Parcellations (MneExperiment.parcs) based on combinations can also include split commands.
  • New Factor method: Factor.floodfill().
  • Model methods: get_table() replaced with as_table(), new head() and tail().
  • API: .sort_idx methods renamed to .sort_index.

New in 0.20

New in 0.19

  • Two-stage tests (see MneExperiment.tests).
  • Safer cache-handling. See note at Analysis.
  • Dataset.head() and Dataset.tail() methods for more efficiently inspecting partial Datasets.
  • The default format for plots in reports is now SVG since they are displayed correctly in Safari 9.0. Use plot.configure() to change the default format.
  • API: Improvements in plot.Topomap with concomitant changes in the constructor signature. For examples see the meg/topographic plotting example.
  • API: plot.ColorList has a new argument called labels.
  • API: testnd.anova attribute probability_maps renamed to p analogous to other testnd results.
  • Rejection-GUI: The option to plot the data range only has been removed.

New in 0.18

  • API: The first argument for MneExperiment.plot_annot() is now parc.
  • API: the fill_in_missing parameter to combine() has been deprecated and replaced with a new parameter called incomplete.
  • API: Several plotting functions have a new xticklabels parameter to suppress x-axis tick labels (e.g. plot.UTSStat).
  • The objects returned by plot.brain plotting functions now contain a plot_colorbar() method to create a corresponding plot.ColorBar plot.
  • New function choose() to combine data in different NDVars on a case by case basis.
  • Rejection-GUI (gui.select_epochs()): Press Shift-i when hovering over an epoch to enter channels for interpolation manually.
  • MneExperiment.show_file_status() now shows the last modification date of each file.
  • Under OS X 10.8 and newer running code under a notifier statement now automatically prevents the computer from going to sleep.

New in 0.17

  • MneExperiment.brain_plot_defaults can be used to customize PySurfer plots in movies and reports.
  • MneExperiment.trigger_shift can now also be a dictionary mapping subject name to shift value.
  • The rejection GUI now allows selecting individual channels for interpolation using the ‘i’ key.
  • Parcellations based on combinations of existing labels, as well as parcellations based on regions around points specified in MNI coordinates can now be defined in MneExperiment.parcs.
  • Source space NDVar can be indexed with lists of region names, e.g., ndvar.sub(source=['cuneus-lh', 'lingual-lh']).
  • API: plot.brain.bin_table() function signature changed slightly (more parameters, new hemi parameter inserted to match other functions’ argument order).
  • API: combine() now raises KeyError when trying to combine Dataset objects with unequal keys; set fill_in_missing=True to reproduce previous behavior.
  • API: Previously, Var.as_factor() mapped unspecified values to str(value). Now they are mapped to ''. This also applies to MneExperiment.variables entries with unspecified values.

New in 0.16

New in 0.15

  • The Eelbrain package on the PYPI is now compiled with Anaconda. This means that the package can now be installed into an Anaconda distribution with pip, whereas easy_install has to be used for the Canopy distribution.
  • GUI gui.select_epochs(): Set marked channels through menu (View > Mark Channels)
  • Datasets can be saved as tables in RTF format (Dataset.save_rtf()).
  • API plot.Timeplot: the default spread indicator changed to SEM, and there is a new argument for timelabels.
  • API: test.anova() is now a function with a slightly changed signature. The old class has been renamed to test.ANOVA.
  • API: test.oneway() was removed. Use test.anova().
  • API: the default value of the plot.Timeplot parameter bottom changed from 0 to None (determined by the data).
  • API: Factor.relabel() renamed to Factor.update_labels().
  • Plotting: New option for the figure legend 'draggable' (drag the legend with the mouse pointer).

New in 0.14

  • API: the plot.Topomap argument sensors changed to sensorlabels.
  • GUI: The python/Quit Eelbrain menu command now closes all windows to ensure that unsaved documents are handled properly. In order to yield to the terminal without closing windows, use the Go/Yield to Terminal command (Command-Alt-Q).
  • testnd.t_contrast_rel: support for unary operation abs.

New in 0.13

  • The gui.select_epochs() GUI can now also be used to set bad channels. MneExperiment subclasses will combine bad channel information from rejection files with bad channel information from bad channel files. Note that while bad channel files set bad channels for a given raw file globally, rejection files set bad channels only for the given epoch.
  • Factor objects can now remember a custom cell order which determines the order in tables and plots.
  • The Var.as_factor() method can now assign all unmentioned codes to a default value.
  • MneExperiment:

New in 0.12

  • API: Dataset construction changed, allows setting the number of cases in the Dataset.
  • API: plot.SensorMap2d was renamed to plot.SensorMap.
  • MneExperiment:
    • API: The default number of samples for reports is now 10‘000.
    • New epoch parameter 'n_cases': raise an error if an epoch definition does not yield expected number of trials.
    • A custom baseline period for epochs can now be specified as a parameter in the epoch definition (e.g., 'baseline': (-0.2, -0.1)). When loading data, specifying baseline=True uses the epoch’s custom baseline.

New in 0.11

  • MneExperiment:
    • Change in the way the covariance matrix is defined: The epoch for the covariance matrix should be specified in MneExperiment.epochs['cov']. The regularization is no longer part of set_inv(), but is instead set with MneExperiment.set(cov='reg') or MneExperiment.set(cov='noreg').
    • New option cov='bestreg' automatically selects the regularization parameter for each subejct.
  • Var.as_factor() allows more efficient labeling when multiple values share the same label.
  • API: Previously plot.configure_backend() is now plot.configure()

New in 0.10

  • Tools for generating colors for categories (see Plotting).
  • Plots now all largely respect matplotlib rc-parameters (see Customizing Matplotlib).
  • Fixed an issue in the testnd module that could affect permutation based p-values when multiprocessing was used.

New in 0.9

  • Factor API change: The rep argument was renamed to repeat.
  • T-values for regression coefficients through NDVar.ols_t().
  • MneExperiment: subject name patterns and eog_sns are now handled automatically.
  • UTSStat and Barplot plots can use pooled error for variability estimates (on by default for related measures designs, can be turned off using the pool_error argument).
    • API: for consistency, the argument to specify the kind of error to plot changed to error in both plots.

New in 0.8

  • A new GUI application controls plots as well as the epoch selection GUI (see notes in the reference sections on Plotting and GUIs).
  • Randomization/Monte Carlo tests now seed the random state to make results replicable.

New in 0.6

New in 0.5

  • The eelbrain.lab and eelbrain.eellab modules are deprecated. Everything can now me imported from eelbrain directly.

New in 0.4

New in 0.3

  • Optimized clustering for cluster permutation tests.

New in 0.2

  • gui.SelectEpochs Epoch rejection GIU has a new “GA” button to plot the grand average of all accepted trials
  • Cluster permutation tests in testnd use multiple cores; To disable multiprocessing set eelbrain._stats.testnd.multiprocessing = False.

New in 0.1.7

  • gui.SelectEpochs can now be initialized with a single mne.Epochs instance (data needs to be preloaded).
  • Parameters that take NDVar objects now also accept mne.Epochs and mne.fiff.Evoked objects.

New in 0.1.5

  • plot.topo.TopoButterfly plot: new keyboard commands (t, left arrow, right arrow).

Publications using Eelbrain

Ordered alphabetically according to authors’ last name:

[1]Esti Blanco-Elorrieta and Liina Pylkkänen. Bilingual language switching in the lab vs. in the wild: the spatio-temporal dynamics of adaptive language control. Journal of Neuroscience, pages 0553–17, 2017. URL: http://www.jneurosci.org/content/early/2017/08/16/JNEUROSCI.0553-17.2017.abstract.
[2]Christian Brodbeck, Laura Gwilliams, and Liina Pylkkänen. EEG can track the time course of successful reference resolution in small visual worlds. Frontiers in psychology, 6:1787, 2015. URL: https://www.frontiersin.org/articles/10.3389/fpsyg.2015.01787.
[3]Christian Brodbeck, Laura Gwilliams, and Liina Pylkkänen. Language in context: MEG evidence for modality general and specific responses to reference resolution. eNeuro, pages ENEURO–0145, 2016. URL: http://www.eneuro.org/content/early/2016/12/15/ENEURO.0145-16.2016.abstract.
[4]Christian Brodbeck, L Elliot Hong, and Jonathan Z Simon. Rapid transformation from auditory to linguistic representations of continuous speech. Current Biology, 28(24):3976–3983, 2018. URL: https://www.sciencedirect.com/science/article/pii/S096098221831409X.
[5]Christian Brodbeck, Alessandro Presacco, and Jonathan Z Simon. Neural source dynamics of brain responses to continuous stimuli: speech processing from acoustics to comprehension. NeuroImage, 172:162–174, 2018. URL: https://www.sciencedirect.com/science/article/pii/S1053811918300429.
[6]Christian Brodbeck and Liina Pylkkänen. Language in context: characterizing the comprehension of referential expressions with MEG. NeuroImage, 147:447–460, 2017. URL: https://www.sciencedirect.com/science/article/pii/S1053811916307169.
[7]Teon L Brooks and Daniela Cid de Garcia. Evidence for morphological composition in compound words using MEG. Frontiers in human neuroscience, 9:215, 2015. URL: https://www.frontiersin.org/articles/10.3389/fnhum.2015.00215.
[8]Julien Dirani and Liina Pylkkanen. Lexical access in comprehension vs. production: spatiotemporal localization of semantic facilitation and interference. bioRxiv, pages 449157, 2018. URL: https://www.biorxiv.org/content/early/2018/10/23/449157.1.abstract.
[9]Graham Flick, Yohei Oseki, Amanda R Kaczmarek, Meera Al Kaabi, Alec Marantz, and Liina Pylkkänen. Building words and phrases in the left temporal lobe. Cortex, 2018. URL: https://www.sciencedirect.com/science/article/pii/S0010945218301904.
[10]Graham Flick and Liina Pylkkänen. Isolating syntax in natural language: MEG evidence for an early contribution of left posterior temporal cortex. BioRxiv, pages 439158, 2018. URL: https://www.biorxiv.org/content/early/2018/10/09/439158.abstract.
[11]Phoebe Gaston and Alec Marantz. The time course of contextual cohort effects in auditory processing of category-ambiguous words: MEG evidence for a single “clash” as noun or verb. Language, Cognition and Neuroscience, 33(4):402–423, 2018. URL: https://www.tandfonline.com/doi/abs/10.1080/23273798.2017.1395466.
[12]Laura Gwilliams, GA Lewis, and Alec Marantz. Functional characterisation of letter-specific responses in time, space and current polarity using magnetoencephalography. NeuroImage, 132:320–333, 2016. URL: https://www.sciencedirect.com/science/article/pii/S105381191600166X.
[13]Laura Gwilliams and Alec Marantz. Morphological representations are extrapolated from morpho-syntactic rules. Neuropsychologia, 114:77–87, 2018. URL: https://www.sciencedirect.com/science/article/pii/S0028393218301568.
[14]William Matchin, Christian Brodbeck, Christopher Hammerly, and Ellen Lau. The temporal dynamics of structure and content in sentence comprehension: evidence from fMRI-constrained MEG. Human brain mapping, 40(2):663–678, 2019. URL: https://onlinelibrary.wiley.com/doi/abs/10.1002/hbm.24403.
[15]Kyriaki Neophytou, Christina Manouilidou, Linnaea Stockall, and Alec Marantz. Syntactic and semantic restrictions on morphological recomposition: MEG evidence from greek. Brain and language, 183:11–20, 2018. URL: https://www.sciencedirect.com/science/article/pii/S0093934X1730130X.
[16]Krishna C Puvvada, Marisel Villafane-Delgado, Christian Brodbeck, and Jonathan Z Simon. Neural coding of noisy and reverberant speech in human auditory cortex. bioRxiv, pages 229153, 2017. URL: https://www.biorxiv.org/content/early/2017/12/04/229153.abstract.
[17]Victoria Sharpe, Samir Reddigari, Liina Pylkkänen, and Alec Marantz. Automatic access to verb continuations on the lexical and categorical levels: evidence from MEG. Language, Cognition and Neuroscience, 34(2):137–150, 2019. URL: https://www.tandfonline.com/doi/abs/10.1080/23273798.2018.1531139.
[18]Eline Verschueren, Jonas Vanthornhout, and Tom Francart. Semantic context enhances neural envelope tracking. bioRxiv, pages 421727, 2018. URL: https://www.biorxiv.org/content/early/2018/09/19/421727.abstract.
[19]Adina Williams, Samir Reddigari, and Liina Pylkkänen. Early sensitivity of left perisylvian cortex to relationality in nouns and verbs. Neuropsychologia, 100:131–143, 2017. URL: https://www.sciencedirect.com/science/article/pii/S0028393217301586.
[20]Linmin Zhang and Liina Pylkkänen. Composing lexical versus functional adjectives: evidence for uniformity in the left temporal lobe. Psychonomic bulletin & review, pages 1–14, 2018. URL: https://link.springer.com/content/pdf/10.3758/s13423-018-1469-y.pdf.
[21]Linmin Zhang and Liina Pylkkänen. Semantic composition of sentences word by word: MEG evidence for shared processing of conceptual and logical elements. Neuropsychologia, 119:392–404, 2018. URL: https://www.sciencedirect.com/science/article/pii/S0028393218305037.

Development

Eelbrain is actively developed and maintained by Christian Brodbeck at the Computational sensorimotor systems lab at University of Maryland, College Park.

Eelbrain is fully open-source and new contributions are welcome on GitHub. Suggestions can be raised as issues, and modifications can be made as pull requests into the master branch.

The Development Version

The Eelbrain source code is hosted on GitHub. Development takes place on the master branch, while release versions are maintained on branches called r/0.26 etc. For further information on working with GitHub see GitHub’s instructions.

Installing the development version requires the presence of a compiler. On macOS, make sure Xcode is installed (open it once to accept the license agreement). Windows will indicate any needed files when the install command is run.

After cloning the repository, the development version can be installed by running, from the Eelbrain repository’s root directory:

$ python setup.py develop

On macOS, the $ eelbrain shell script to run iPython with the framework build is not installed properly by setup.py; in order to fix this, run:

$ ./fix-bin

In Python, you can make sure that you are working with the development version:

>>> import eelbrain
>>> eelbrain.__version__
'dev'

To switch back to the release version use $ pip uninstall eelbrain.

Building with Conda

To build Eelbrain with conda, make sure that conda-build is installed. Then, from Eelbrain/conda run:

$ conda build eelbrain

After building successfully, the build can be installed with:

$ conda install --use-local eelbrain

Contributing

Style guides:

Useful tools:

Testing

Eelbrain uses nose for testing. Tests for individual modules are included in folders called tests, usually on the same level as the module. To run all tests, run $ make test from the Eelbrain project directory. On macOS, nosetests needs to run with the framework build of Python; if you get a corresponding error, run $ ./fix-bin nosetests from the Eelbrain repository root.

Reference

Data Classes

Primary data classes:

Dataset(*args, **kwargs) Stores multiple variables pertaining to a common set of measurement cases
Factor(x[, name, random, repeat, tile, …]) Container for categorial data.
Var(x[, name, repeat, tile, info]) Container for scalar data.
NDVar(x, dims[, info, name]) Container for n-dimensional data.
Datalist([items, name, fmt]) list subclass for including lists in in a Dataset.

Model classes (not usually initialized by themselves but through operations on primary data-objects):

Interaction(base) Represents an Interaction effect.
Model(x) A list of effects.

NDVar dimensions (not usually initialized by themselves but through load functions):

Case(n[, connectivity]) Case dimension
Categorial(name, values[, connectivity]) Simple categorial dimension
Scalar(name, values[, unit, tick_format, …]) Scalar dimension
Sensor(locs[, names, sysname, proj2d, …]) Dimension class for representing sensor information
SourceSpace(vertices[, subject, src, …]) MNE surface-based source space
VolumeSourceSpace(vertices[, subject, src, …]) MNE volume source space
Space(directions[, name]) Represent multiple directions in space
UTS(tmin, tstep, nsamples) Dimension object for representing uniform time series

File I/O

Eelbrain objects can be pickled. Eelbrain’s own pickle I/O functions provide backwards compatibility for Eelbrain objects (although files saved in Python 3 can only be opened in Python 2 if they are saved with protocol<=2):

save.pickle(obj[, dest, protocol]) Pickle a Python object.
load.unpickle([file_path]) Load pickled Python objects from a file.
load.arrow([file_path]) Load object serialized with pyarrow.
save.arrow(obj[, dest]) Save a Python object with pyarrow.
load.update_subjects_dir(obj, subjects_dir) Update NDVar SourceSpace.subjects_dir attributes
Import

Functions and modules for loading specific file formats as Eelbrain object:

load.wav([filename, name]) Load a wav file as NDVar
load.tsv(path, names, bool] = True, types, …) Load a Dataset from a text file.
load.eyelink Tools for loading data form eyelink edf files.
load.fiff Tools for importing data through mne.
load.txt Tools for loading data from text files.
load.besa Tools for loading data from the BESA-MN pipeline.
Export

Dataset with only univariate data can be saved as text using the save_txt() method. Additional export functions:

save.txt(iterator[, fmt, delim, dest]) Write any object that supports iteration to a text file.
save.wav(ndvar[, filename, toint]) Save an NDVar as wav file

Sorting and Reordering

align(d1, d2[, i1, i2, out]) Align two data-objects based on index variables
align1(d, to[, by, out]) Align a data object to an index variable
Celltable(y[, x, match, sub, cat, ds, …]) Divide y into cells defined by x.
choose(choice, sources[, name]) Combine data-objects picking from a different object for each case
combine(items[, name, check_dims, incomplete]) Combine a list of items of the same type into one item.
shuffled_index(n[, cells]) Return an index to shuffle a data-object

NDVar Operations

See also NDVar methods.

Butterworth(low, high, order[, sfreq]) Butterworth filter
complete_source_space(ndvar[, fill]) Fill in missing vertices on an NDVar with a partial source space
concatenate(ndvars[, dim, name, tmin, info, …]) Concatenate multiple NDVars
convolve(h, x[, ds]) Convolve h and x along the time dimension
correlation_coefficient(x, y[, dim, name]) Correlation between two NDVars along a specific dimension
cross_correlation(in1, in2[, name]) Cross-correlation between two NDVars along the time axis
cwt_morlet(y, freqs[, use_fft, n_cycles, …]) Time frequency decomposition with Morlet wavelets (mne-python)
dss(ndvar) Denoising source separation (DSS)
filter_data(ndvar, l_freq, h_freq[, …]) Apply mne.filter.filter_data() to an NDVar
frequency_response(b[, frequencies]) Frequency response for a FIR filter
label_operator(labels[, operation, exclude, …]) Convert labeled NDVar into a matrix operation to extract label values
labels_from_clusters(clusters[, names]) Create Labels from source space clusters
morph_source_space(ndvar, subject_to[, …]) Morph source estimate to a different MRI subject
neighbor_correlation(x[, dim, obs, name]) Calculate Neighbor correlation
psd_welch(ndvar[, fmin, fmax, n_fft, …]) Power spectral density with Welch’s method
resample(ndvar, sfreq[, npad, window, pad, name]) Resample an NDVar along the time dimension
segment(continuous, times, tstart, tstop[, …]) Segment a continuous NDVar
set_parc(ndvar, parc[, dim]) Change the parcellation of an NDVar with SourceSpace dimension
set_tmin(ndvar[, tmin]) Change the time axis of an NDVar
xhemi(ndvar[, mask, hemi, parc]) Project data from both hemispheres to hemi of fsaverage_sym

Reverse Correlation

boosting(y, x, tstart, tstop[, scale_data, …]) Estimate a filter with boosting
BoostingResult(y, x, tstart, tstop, …[, …]) Result from boosting a temporal response function

Tables

Manipulate data tables and compile information about data objects such as cell frequencies:

table.cast_to_ndvar(data, dim_values, match) Create an NDVar by converting a data column to a dimension
table.difference(y, x, c1, c0, match[, by, …]) Subtract data in one cell from another
table.frequencies(y[, x, of, sub, ds]) Calculate frequency of occurrence of the categories in y
table.melt(name, cells, cell_var_name, ds[, …]) Restructure a Dataset such that a measured variable is in a single column
table.melt_ndvar(ndvar[, dim, cells, ds, …]) Transform data to long format by converting an NDVar dimension into a variable
table.repmeas(y, x, match[, sub, ds]) Create a repeated-measures table
table.stats(y, row[, col, match, sub, fmt, …]) Make a table with statistics

Statistics

Univariate statistical tests:

test.Correlation(y, x[, sub, ds]) Pearson product moment correlation between y and x
test.TTest1Sample(y[, match, sub, ds, tail]) 1-sample t-test
test.TTestInd(y, x[, c1, c0, match, sub, …]) Related-measures t-test
test.TTestRel(y, x[, c1, c0, match, sub, …]) Related-measures t-test
test.anova(y, x[, sub, ds, title, caption]) Univariate ANOVA
test.pairwise(y, x[, match, sub, ds, par, …]) Pairwise comparison table
test.ttest(y[, x, against, match, sub, …]) T-tests for one or more samples
test.correlations(y, x[, cat, sub, ds, asds]) Correlation with one or more predictors
test.pairwise_correlations(xs[, sub, ds, labels]) Pairwise correlation table
test.lilliefors(data[, formatted]) Lilliefors’ test for normal distribution

Mass-Univariate Statistics

testnd.ttest_1samp(y[, popmean, match, sub, …]) Mass-univariate one sample t-test
testnd.ttest_rel(y, x[, c1, c0, match, sub, …]) Mass-univariate related samples t-test
testnd.ttest_ind(y, str], x, …) Mass-univariate independent samples t-test
testnd.t_contrast_rel(y, x, contrast[, …]) Mass-univariate contrast based on t-values
testnd.anova(y, x[, sub, ds, samples, pmin, …]) Mass-univariate ANOVA
testnd.corr(y, x[, norm, sub, ds, samples, …]) Mass-univariate correlation

By default the tests in this module produce maps of statistical parameters along with maps of p-values uncorrected for multiple comparison. Using different parameters, different methods for multiple comparison correction can be applied (for more details and options see the documentation for individual tests):

1: permutation for maximum statistic (samples=n)
Look for the maximum value of the test statistic in n permutations and calculate a p-value for each data point based on this distribution of maximum statistics.
2: Threshold-based clusters (samples=n, pmin=p)
Find clusters of data points where the original statistic exceeds a value corresponding to an uncorrected p-value of p. For each cluster, calculate the sum of the statistic values that are part of the cluster. Do the same in n permutations of the original data and retain for each permutation the value of the largest cluster. Evaluate all cluster values in the original data against the distributiom of maximum cluster values (see [1]).
3: Threshold-free cluster enhancement (samples=n, tfce=True)
Similar to (1), but each statistical parameter map is first processed with the cluster-enhancement algorithm (see [2]). This is the most computationally intensive option.
Two-stage tests

Two-stage tests proceed by estimating parameters for a fixed effects model for each subject, and then testing hypotheses on these parameter estimates on the group level. Two-stage tests are implemented by fitting an LM for each subject, and then combining them in a LMGroup to retrieve coefficients for group level statistics.

testnd.LM(y, model[, ds, coding, subject, sub]) Fixed effects linear model
testnd.LMGroup(lms) Group level analysis for linear model LM objects
References
[1]Maris, E., & Oostenveld, R. (2007). Nonparametric statistical testing of EEG- and MEG-data. Journal of Neuroscience Methods, 164(1), 177-190. 10.1016/j.jneumeth.2007.03.024
[2]Smith, S. M., and Nichols, T. E. (2009). Threshold-Free Cluster Enhancement: Addressing Problems of Smoothing, Threshold Dependence and Localisation in Cluster Inference. NeuroImage, 44(1), 83-98. 10.1016/j.neuroimage.2008.03.061

Plotting

Plot univariate data (Var objects):

plot.Barplot(y[, x, match, sub, cells, …]) Barplot for a continuous variable
plot.Boxplot(y[, x, match, sub, cells, …]) Boxplot for a continuous variable
plot.PairwiseLegend([size, trend]) Legend for colors used in pairwise comparisons
plot.Correlation(y, x[, cat, sub, ds, c, …]) Plot the correlation between two variables
plot.Histogram(y[, x, match, sub, ds, …]) Histogram plots with tests of normality
plot.Regression(y, x[, cat, match, sub, ds, …]) Plot the regression of y on x
plot.Timeplot(y, categories, time[, match, …]) Plot a variable over time

Color tools for plotting:

plot.colors_for_categorial(x[, hue_start, cmap]) Automatically select colors for a categorial model
plot.colors_for_oneway(cells[, hue_start, …]) Define colors for a single factor design
plot.colors_for_twoway(x1_cells, x2_cells[, …]) Define cell colors for a two-way design
plot.ColorBar(cmap, vmin[, vmax, label, …]) A color-bar for a matplotlib color-map
plot.ColorGrid(row_cells, column_cells, colors) Plot colors for a two-way design in a grid
plot.ColorList(colors[, cells, labels, h]) Plot colors with labels

Plot uniform time-series:

plot.UTS(y[, xax, axtitle, ds, sub, xlabel, …]) Value by time plot for UTS data
plot.UTSClusters(res[, pmax, ptrend, …]) Plot permutation cluster test results
plot.UTSStat(y[, x, xax, match, sub, ds, …]) Plot statistics for a one-dimensional NDVar

Plot multidimensional uniform time series:

plot.Array(y[, xax, xlabel, ylabel, …]) Plot UTS data to a rectangular grid.
plot.Butterfly(y[, xax, sensors, axtitle, …]) Butterfly plot for NDVars

Plot topographic maps of sensor space data:

plot.TopoArray(y[, xax, ds, sub, vmax, …]) Channel by sample plots with topomaps for individual time points
plot.TopoButterfly(y[, xax, ds, sub, vmax, …]) Butterfly plot with corresponding topomaps
plot.Topomap(y[, xax, ds, sub, vmax, vmin, …]) Plot individual topogeraphies
plot.TopomapBins(y[, xax, ds, sub, …]) Topomaps in time-bins

Plot sensor layout maps:

plot.SensorMap(sensors[, labels, proj, …]) Plot sensor positions in 2 dimensions
plot.SensorMaps(sensors[, select, proj, …]) Multiple views on a sensor layout.
xax parameter

Many plots have an xax parameter which is used to sort the data in y into different categories and plot them on separate axes. xax can be specified through categorial data, or as a dimension in y.

If a categorial data object is specified for xax, y is split into the categories in xax, and for every cell in xax a separate subplot is shown. For example, while

>>> plot.Butterfly('meg', ds=ds)

will create a single Butterfly plot of the average response,

>>> plot.Butterfly('meg', 'subject', ds=ds)

where 'subject' is the xax parameter, will create a separate subplot for every subject with its average response.

A dimension on y can be specified through a string starting with .. For example, to plot each case of meg separately, use:

>>> plot.Butterfly('meg', '.case', ds=ds)
General layout parameters

Most plots that also share certain layout keyword arguments. By default, all those parameters are determined automatically, but individual values can be specified manually by supplying them as keyword arguments.

h, w : scalar
Height and width of the figure. Use a number ≤ 0 to defined the size relative to the screen (e.g., w=0 to use the full screen width).
axh, axw : scalar
Height and width of the axes.
nrow, ncol : None | int
Limit number of rows/columns. If neither is specified, a square layout is produced
ax_aspect : scalar
Width / height aspect of the axes.
name : str
Window title (not displayed on the figure itself).
title : str
Figure title (displayed on the figure).

Plots that do take those parameters can be identified by the **layout in their function signature.

GUI Interaction

By default, new plots are automatically shown and, if the Python interpreter is in interactive mode the GUI main loop is started. This behavior can be controlled with 2 arguments when constructing a plot:

show : bool
Show the figure in the GUI (default True). Use False for creating figures and saving them without displaying them on the screen.
run : bool
Run the Eelbrain GUI app (default is True for interactive plotting and False in scripts).

The behavior can also be changed globally using configure():

Plotting Brains

The plot.brain module contains specialized functions to plot NDVar objects containing source space data. For this it uses a subclass of PySurfer’s surfer.Brain class. The functions below allow quick plotting. More specific control over the plots can be achieved through the Brain object that is returned.

plot.brain.brain(src[, cmap, vmin, vmax, …]) Create a Brain object with a data layer
plot.brain.butterfly(y[, cmap, vmin, vmax, …]) Shortcut for a Butterfly-plot with a time-linked brain plot
plot.brain.cluster(cluster[, vmax]) Plot a spatio-temporal cluster
plot.brain.dspm(src[, fmin, fmax, fmid]) Plot a source estimate with coloring for dSPM values (bipolar).
plot.brain.p_map(p_map[, param_map, p0, p1, …]) Plot a map of p-values in source space.
plot.brain.annot(annot[, subject, surf, …]) Plot the parcellation in an annotation file
plot.brain.annot_legend(lh, rh, *args, **kwargs) Plot a legend for a freesurfer parcellation
plot.brain.SequencePlotter() Grid of anatomical images in one figure
plot._brain_object.Brain
plot.GlassBrain(ndvar[, cmap, vmin, vmax, …]) Plot 2d projections of a brain volume
plot.GlassBrain.butterfly(y[, cmap, vmin, …]) Shortcut for a butterfly-plot with a time-linked glassbrain plot

In order to make custom plots, a Brain figure without any data added can be created with plot.brain.brain(ndvar.source, mask=False).

Surface options for plotting data on fsaverage:

white

surf_white

smoothwm

surf_smoothwm

inflated_pre

surf_inflated_pre

inflated

surf_inflated

inflated_avg

surf_inflated_avg

sphere

surf_sphere

GUIs

Tools with a graphical user interface (GUI):

gui.select_components(path, ds[, sysname, …]) GUI for selecting ICA-components
gui.select_epochs(ds[, data, accept, blink, …]) GUI for rejecting trials of MEG/EEG data
Controlling the GUI Application

Eelbrain uses a wxPython based application to create GUIs. This GUI appears as a separate application with its own Dock icon. The way that control of this GUI is managed depends on the environment form which it is invoked.

When Eelbrain plots are created from within iPython, the GUI is managed in the background and control returns immediately to the terminal. There might be cases in which this is not desired, for example when running scripts. After execution of a script finishes, the interpreter is terminated and all associated plots are closed. To avoid this, the command gui.run(block=True) can be inserted at the end of the script, which will keep all gui elements open until the user quits the GUI application (see gui.run() below).

In interpreters other than iPython, input can not be processed from the GUI and the interpreter shell at the same time. In that case, the GUI application is activated by default whenever a GUI is created in interactive mode (this can be avoided by passing run=False to any plotting function). While the application is processing user input, the shell can not be used. In order to return to the shell, quit the application (the python/Quit Eelbrain menu command or Command-Q). In order to return to the terminal without closing all windows, use the alternative Go/Yield to Terminal command (Command-Alt-Q). To return to the application from the shell, run gui.run(). Beware that if you terminate the Python session from the terminal, the application is not given a chance to assure that information in open windows is saved.

gui.run([block]) Hand over command to the GUI (quit the GUI to return to the terminal)

MNE-Experiment

The MneExperiment class serves as a base class for analyzing MEG data (gradiometer only) with MNE:

MneExperiment([root, find_subjects]) Analyze an MEG experiment (gradiometer only) with MNE
ROITestResult(subjects, samples, …) Test results for temporal tests in one or more ROIs

See also

For the guide on working with the MneExperiment class see The MneExperiment Class.

Datasets

Datasets for experimenting and testing:

datasets.get_loftus_masson_1994() Dataset used for illustration purposes by Loftus and Masson (1994)
datasets.get_mne_sample([tmin, tmax, …]) Load events and epochs from the MNE sample data
datasets.get_uts([utsnd, seed, nrm, vector3d]) Create a sample Dataset with 60 cases and random data.
datasets.get_uv([seed, nrm, vector]) Dataset with random univariate data

Configuration

eelbrain.configure(n_workers=None, frame=None, autorun=None, show=None, format=None, figure_background=None, prompt_toolkit=None, animate=None, nice=None, tqdm=None)

Set basic configuration parameters for the current session

Parameters:
n_workers : bool | int

Number of worker processes to use in multiprocessing enabled computations. False to disable multiprocessing. True (default) to use as many processes as cores are available. Negative numbers to use all but n available CPUs.

frame : bool

Open figures in the Eelbrain application. This provides additional functionality such as copying a figure to the clipboard. If False, open figures as normal matplotlib figures.

autorun : bool

When a figure is created, automatically enter the GUI mainloop. By default, this is True when the figure is created in interactive mode but False when the figure is created in a script (in order to run the GUI at a specific point in a script, call eelbrain.gui.run()).

show : bool

Show plots on the screen when they’re created (disable this to create plots and save them without showing them on the screen).

format : str

Default format for plots (for example “png”, “svg”, …).

figure_background : bool | matplotlib color

While matplotlib uses a gray figure background by default, Eelbrain uses white. Set this parameter to False to use the default from matplotlib.rcParams, or set it to a valid matplotblib color value to use an arbitrary color. True to revert to the default white.

prompt_toolkit : bool

In IPython 5, prompt_toolkit allows running the GUI main loop in parallel to the Terminal, meaning that the IPython terminal and GUI windows can be used without explicitly switching between Terminal and GUI. This feature is enabled by default, but can be disabled by setting prompt_toolkit=False.

animate : bool

Animate plot navigation (default True).

nice : int [-20, 19]

Scheduling priority for muliprocessing (larger number yields more to other processes; negative numbers require root privileges).

tqdm : bool

Enable or disable tqdm progress bars.

Recipes

Group Level Analysis

To do group level analysis one usually wants to construct a Dataset that contains results for each participants along with condition and subject labels. The following illustration assumes functions that compute results for a single subject and condition:

  • result_for(subject, condition) returns an NDVar.
  • scalar_result_for(subject, condition) returns a scalar (float).

Given results by subject and condition, a Dataset can be constructed as follows:

>>> # create lists to collect data and labels
>>> ndvar_results = []
>>> scalar_results = []
>>> subjects = []
>>> conditions = []
>>> # collect data and labels
>>> for subject in ('s1', 's2', 's3', 's4'):
...     for condition in ('c1', 'c2'):
...         ndvar = result_for(subject, condition)
...         s = scalar_result_for(subject, condition)
...         ndvar_results.append(ndvar)
...         scalar_results.append(s)
...         subjects.append(subject)
...         conditions.append(condition)
...
>>> # create a Dataset and convert the collected lists to appropriate format
>>> ds = Dataset()
>>> ds['subject'] = Factor(subjects, random=True)  # treat as random effect
>>> ds['condition'] = Factor(conditions)
>>> ds['y'] = combine(ndvar_results)
>>> ds['s'] = Var(scalar_results)

Now this Dataset can be used for statistical analysis, for example ANOVA:

>>> res = testnd.anova('y', 'condition * subject', ds=ds)

Regression Design

The influence of a continuous predictor on single trial level can be tested by first calculating regression coefficients for each subject, and then performing a one sample t-test across subjects to test the null hypothesis that between subjects, the regression coefficient does not differ significantly from 0.

Assuming that ds_subject is a Dataset containing single trial data for one subject, with data the dependent variable and a predictor (called predictor):

>>> ds_subject
<Dataset 'example' n_cases=145 {'predictor':V, 'data':Vnd}>
>>> ds_subject['data']
<NDVar 'data': 145 (case) X 5120 (source) X 76 (time)>
>>> print ds_subject
predictor
---------
1.9085
0.30836
-0.58802
0.29686
...

The regression coefficient can be calculated the following way:

>>> beta = ds_subject.eval("data.ols(predictor)")
>>> beta
<NDVar 'ols': 1 (case) X 5120 (source) X 76 (time)>

Thus, in order to collect beta values for each subject, you would loop through subjects. We will call the NDVar with beta values ‘beta’:

>>> subjects = []
>>> betas = []
>>> for subject in ['R0001', 'R0002', 'R0003']:
...     ds_subject = my_load_ds_for_subject_function(subject)
...     beta = ds_subject.eval("data.ols(predictor, 'beta')")
...     subjects.append(subject)
...     betas.append(beta)
...
>>> ds = Dataset()
>>> ds['subject'] = Factor(subjects, random=True)
>>> ds['beta'] = combine(betas)

Now you can perform a one-sample t-test:

>>> res = testnd.ttest_1samp('beta', ...)

And analyze the results as for other testnd tests.

Plots for Publication

In order to produce multiple plots it is useful to set some plotting parameters globally in order to ensure that they are consistent between plots, e.g.:

import matplotlib as mpl

mpl.rcParams['font.family'] = 'sans-serif'
mpl.rcParams['font.size'] = 8
for key in mpl.rcParams:
    if 'width' in key:
        mpl.rcParams[key] *= 0.5
mpl.rcParams['savefig.dpi'] = 300  # different from 'figure.dpi'!

Matplotlib’s tight_layout() functionality provides an easy way for plots to use the available space, and most Eelbrain plots use it by default. However, when trying to produce multiple plots with identical scaling it can lead to unwanted discrepancies. In this case, it is better to define layout parameters globally and plot with the tight=False argument:

mpl.rcParams['figure.subplot.left'] = 0.25
mpl.rcParams['figure.subplot.right'] = 0.95
mpl.rcParams['figure.subplot.bottom'] = 0.2
mpl.rcParams['figure.subplot.top'] = 0.95

plot.UTSStat('uts', 'A', ds=ds, w=5, tight=False)

# now we can produce a second plot without x-axis labels that has exactly
# the same scaling:
plot.UTSStat('uts', 'A % B', ds=ds, w=5, tight=False, xlabel=False, ticklabels=False)

If a script produces several plots, the GUI should not interrupt the script. This can be achieved by setting the show=False argument. In addition, it is usually desirable to save the legend separately and combine it in a layout application:

p = plot.UTSStat('uts', 'A', ds=ds, w=5, tight=False, show=False, legend=False)
p.save('plot.svg', transparent=True)
p.save_legend('legend.svg', transparent=True)

The MneExperiment Class

MneExperiment is a base class for managing data analysis for an MEG experiment with MNE.

See also

MneExperiment class reference for details on all available methods

Step by step

Setting up the file structure
MneExperiment.sessions

The first step is to define an MneExperiment subclass with the name of the experiment:

from eelbrain import *

class WordExperiment(MneExperiment):

    sessions = 'words'

Where sessions is the name which you included in your raw data files after the subject identifier.

The pipeline expects input files in a strictly determined folder/file structure. In the schema below, curly brackets indicate slots to be replaced with specific names, for example '{subject}' should be replaced with each specific subject’s label.:

root
mri-sdir                                /mri
mri-dir                                    /{mrisubject}
meg-sdir                                /meg
meg-dir                                    /{subject}
raw-dir
trans-file                                       /{mrisubject}-trans.fif
raw-file                                         /{subject}_{session}-raw.fif

This schema shows path templates according to which the input files should be organized. Assuming that root="/files", for a subject called “R0001” this includes:

  • MRI-directory at /files/mri/R0001
  • the raw data file at /files/meg/R0001/R0001_words-raw.fif (the session is called “words” which is specified in WordExperiment.sessions)
  • the trans-file from the coregistration at /files/meg/R0001/R0001-trans.fif

Once the required files are placed in this structure, the experiment class can be initialized with the proper root parameter, pointing to where the files are located:

>>> e = WordExperiment("/files")

The setup can be tested using MneExperiment.show_subjects(), which shows a list of the subjects that were discovered and the MRIs used:

>>> e.show_subjects()
#    subject   mri
-----------------------------------------
0    R0026     R0026
1    R0040     fsaverage * 0.92
2    R0176     fsaverage * 0.954746600461
...
Pre-processing

Make sure an appropriate pre-processing pipeline is defined as MneExperiment.raw.

To inspect raw data for a given pre-processing stage use:

>>> e.set(raw='1-40')
>>> y = e.load_raw(ndvar=True)
>>> p = plot.TopoButterfly(y, xlim=5)

Which will plot 5 s excerpts and allow scrolling through the data.

Labeling events

Initially, events are only labeled with the trigger ID. Use the MneExperiment.variables settings to add labels. For more complex designs and variables, you can override MneExperiment.label_events(). Events are represented as Dataset objects and can be inspected with corresponding methods and functions, for example:

>>> e = WordExperiment("/files")
>>> ds = e.load_events()
>>> ds.head()
>>> print(table.frequencies('trigger', ds=ds))
Defining data epochs

Once events are properly labeled, define MneExperiment.epochs.

There is one special epoch to define, which is called 'cov'. This is the data epoch that will be used to estimate the sensor noise covariance matrix for source estimation.

In order to find the right sel epoch parameter, it can be useful to actually load the events with MneExperiment.load_events() and test different selection strings. The epoch selection is determined by selection = event_ds.eval(epoch['sel']). Thus, a specific setting could be tested with:

>>> ds = e.load_events()
>>> print(ds.sub("event == 'value'"))
Bad channels

Flat channels are automatically excluded from the analysis.

An initial check for noisy channels can be done by looking at the raw data (see Pre-processing above). If this inspection reveals bad channels, they can be excluded using MneExperiment.make_bad_channels().

Another good check for bad channels is plotting the average evoked response,, and looking for channels which are uncorrelated with neighboring channels. To plot the average before trial rejection, use:

>>> ds = e.load_epochs(epoch='epoch', reject=False)
>>> plot.TopoButterfly('meg', ds=ds)

The neighbor correlation can also be quantified, using:

>>> nc = neighbor_correlation(concatenate(ds['meg']))
>>> nc.sensor.names[nc < 0.3]
Datalist([u'MEG 099'])

A simple way to cycle through subjects when performing a given pre-processing step is MneExperiment.next().

ICA

If preprocessing includes ICA, select which ICA components should be removed. The experiment raw state needs to be set to the ICA stage of the pipeline:

>>> e.set(raw='ica')
>>> e.make_ica_selection(epoch='epoch', decim=10)

Set epoch to the epoch whose data you want to display in the GUI (see MneExperiment.make_ica_selection() for more information, in particular on how to precompute ICA decomposition for all subjects).

In order to select ICA components for multiple subject, a simple way to cycle through subjects is MneExperiment.next(), like:

>>> e.make_ica_selection(epoch='epoch', decim=10)
>>> e.next()
subject: 'R1801' -> 'R2079'
>>> e.make_ica_selection(epoch='epoch', decim=10)
>>> e.next()
subject: 'R2079' -> 'R2085'
...
Trial selection

For each primary epoch that is defined, bad trials can be rejected using MneExperiment.make_epoch_selection(). Rejections are specific to a given raw state:

>>> e.set(raw='ica1-40')
>>> e.make_epoch_selection()
>>> e.next()
subject: 'R1801' -> 'R2079'
>>> e.make_epoch_selection()
...

To reject trials based on a pre-determined threshold, a loop can be used:

>>> for subject in e:
...     e.make_epoch_selection(auto=1e-12)
...
Analysis

Finally, define MneExperiment.tests and create a make-reports.py script so that all reports can be updated by running a single script (see Example).

Warning

If source files are changed (raw files, epoch rejection or bad channel files, …) reports are not updated unless the corresponding MneExperiment.make_report() function is called again. For this reason it is useful to have a script that calls MneExperiment.make_report() for all desired reports. Running the script ensures that all reports are up-to-date, and will only take seconds if nothing has to be recomputed.

Example

The following is a complete example for an experiment class definition file (the source file can be found in the Eelbrain examples folder at examples/mouse/mouse.py):

# skip test: data unavailable
from eelbrain.pipeline import *


# as of mne 0.17
FILTER_KWARGS = {
    'filter_length': 'auto',
    'l_trans_bandwidth': 'auto',
    'h_trans_bandwidth': 'auto',
    'phase': 'zero',
    'fir_window': 'hamming',
    'fir_design': 'firwin',
}


class Mouse(MneExperiment):

    sessions = 'CAT'

    raw = {
        'tsss': RawMaxwell('raw', st_duration=10., ignore_ref=True, st_correlation=0.9, st_only=True),
        '1-40': RawFilter('tsss', 1, 40, **FILTER_KWARGS),
        'fastica': RawICA('tsss', 'CAT', 'fastica', n_components=0.99),
        'fastica1-40': RawFilter('fastica', 1, 40, **FILTER_KWARGS),
    }

    variables = {
        'stimulus': LabelVar('trigger', {(162, 163): 'target', (166, 167): 'prime'}),
        'prediction': LabelVar('trigger', {(162, 166): 'expected', (163, 167): 'unexpected'}),
    }

    epochs = {
        'word': PrimaryEpoch('CAT', "stimulus.isin(('prime', 'target'))", samplingrate=200),
        'prime': SecondaryEpoch('word', "stimulus == 'prime'"),
        'target': SecondaryEpoch('word', "stimulus == 'target'"),
        'cov': SecondaryEpoch('prime', tmax=0),
    }

    tests = {
        '=0': TTestOneSample(),
        'surprise': TTestRel('prediction', 'unexpected', 'expected'),
    }

    parcs = {
        'frontotemporal-lh': CombinationParc('aparc', {
            'frontal-lh': 'parsorbitalis + parstriangularis + parsopercularis',
            'temporal-lh': 'transversetemporal + superiortemporal + middletemporal + inferiortemporal + bankssts',
            }, views='lateral'),
    }


root = '~/Data/Mouse'
e = Mouse(root)

Given the Mouse class definition above, the following is a script that would compute/update analysis reports:

# skip test: data unavailable
"""Generate group level result resports for the Mouse experiment

This script generates HTML reports based on the experiment defined in
``mouse.py``.
"""
from mouse import e


e.set(epoch='target', inv='fixed-3-dSPM')
e.make_report('surprise', mask='frontotemporal-lh', pmin=0.05, baseline=False, tstart=0.3, tstop=0.5, raw='1-40')
e.make_report('surprise', mask='frontotemporal-lh', pmin=0.05, baseline=False, tstart=0.3, tstop=0.5, raw='fastica1-40')

Experiment Definition

Basic setup
MneExperiment.owner

Set MneExperiment.owner to your email address if you want to be able to receive notifications. Whenever you run a sequence of commands with mne_experiment.notification: you will get an email once the respective code has finished executing or run into an error, for example:

>>> e = MyExperiment()
>>> with e.notification:
...     e.make_report('mytest', tstart=0.1, tstop=0.3)
...

will send you an email as soon as the report is finished (or the program encountered an error)

MneExperiment.auto_delete_results

Whenever a MneExperiment instance is initialized with a valid root path, it checks whether changes in the class definition invalidate previously computed results. By default, the user is prompted to confirm the deletion of invalidated results. Set .auto_delete_results=True to delete them automatically without interrupting initialization.

MneExperiment.screen_log_level

Determines the amount of information displayed on the screen while using an MneExperiment (see logging).

MneExperiment.meg_system

Starting with mne 0.13, fiff files converted from KIT files store information about the system they were collected with. For files converted earlier, the MneExperiment.meg_system attribute needs to specify the system the data were collected with. For data from NYU New York, the correct value is meg_system="KIT-157".

MneExperiment.trigger_shift

Set this attribute to shift all trigger times by a constant (in seconds). For example, with trigger_shift = 0.03 a trigger that originally occurred 35.10 seconds into the recording will be shifted to 35.13. If the trigger delay differs between subjects, this attribute can also be a dictionary mapping subject names to shift values, e.g. trigger_shift = {'R0001': 0.02, 'R0002': 0.05, ...}.

Subjects
MneExperiment.subject_re

Subjects are identified by looking for folders in the subjects-directory whose name matches the subject_re regular expression (see re). By default, this is '(R|A|Y|AD|QP)(\d{3,})$', which matches R-numbers like R1234, but also numbers prefixed by A, Y, AD or QP.

Defaults
MneExperiment.defaults

The defaults dictionary can contain default settings for experiment analysis parameters, e.g.:

defaults = {'epoch': 'my_epoch',
            'cov': 'noreg',
            'raw': '1-40'}
Pre-processing (raw)
MneExperiment.raw

Define a pre-processing pipeline as a series of processing steps:

RawFilter(source[, l_freq, h_freq]) Filter raw pipe
RawICA(source, session[, method, …]) ICA raw pipe
RawMaxwell(source, **kwargs) Maxwell filter raw pipe
RawSource([filename, reader, sysname, …]) Raw data source
RawReReference(source[, reference]) Re-reference EEG data
  • Each preprocessing step is defined with its input as first argument.
  • If using FIFF files, no RawSource pipe is neded, and the raw data can be accessed as "raw" input.
  • mne has changed default values for filtering in the past. In order to keep consistent settings across different versions it is advantageous to fully define filter parameters when starting a new experiment.

For example, to use TSSS and a band-pass, and optionally ICA:

# as of mne 0.17
FILTER_KWARGS = {
    'filter_length': 'auto',
    'l_trans_bandwidth': 'auto',
    'h_trans_bandwidth': 'auto',
    'phase': 'zero',
    'fir_window': 'hamming',
    'fir_design': 'firwin',
}


class Experiment(MneExperiment):

    sessions = 'session'

    raw = {
        'tsss': RawMaxwell('raw', st_duration=10., ignore_ref=True, st_correlation=0.9, st_only=True),
        '1-40': RawFilter('tsss', 1, 40, **FILTER_KWARGS),
        'ica': RawICA('tsss', 'session', 'extended-infomax', n_components=0.99),
        'ica1-40': RawFilter('ica', 1, 40, **FILTER_KWARGS),
    }
Event variables
MneExperiment.variables

Event variables add labels and variables to the events:

LabelVar(source, codes[, default, session]) Variable assigning labels to values
EvalVar(code[, session]) Variable based on evaluating a statement
GroupVar(groups[, session]) Group membership for each subject

Most of the time, the main purpose of this attribute is to turn trigger values into meaningful labels:

class Mouse(MneExperiment):

    variables = {
        'stimulus': LabelVar('trigger', {(162, 163): 'target', (166, 167): 'prime'}),
        'prediction': LabelVar('trigger', {162: 'expected', 163: 'unexpected'}),
    }

This defines a variable called “stimulus”, and on this variable all events that have triggers 162 and 163 have the value "target", and events with trigger 166 and 167 have the value "prime". The “prediction” variable only labels triggers 162 and 163. Unmentioned trigger values are assigned the empty string ('').

Epochs
MneExperiment.epochs

Epochs are specified as a {name: epoch_definition} dictionary. Names are str, and epoch_definition are instances of the classes described below:

PrimaryEpoch(session[, sel]) Epoch based on selecting events from a raw file
SecondaryEpoch(base[, sel]) Epoch inheriting events from another epoch
SuperEpoch(sub_epochs, **kwargs) Combine several other epochs

Examples:

epochs = {
    # some primary epochs:
    'picture': PrimaryEpoch('words', "stimulus == 'picture'"),
    'word': PrimaryEpoch('words', "stimulus == 'word'"),
    # use the picture baseline for the sensor covariance estimate
    'cov': SecondaryEpoch('picture', tmax=0),
    # another secondary epoch:
    'animal_words': SecondaryEpoch('noun', sel="word_type == 'animal'"),
    # a superset-epoch:
    'all_stimuli': SuperEpoch(('picture', 'word')),
}
Tests
MneExperiment.tests

Statistical tests are defined as {name: test_definition} dictionary. Test- definitions are defined from the following:

TTestOneSample([tail]) One-sample t-test
TTestRel(model, c1, c0[, tail]) Related measures t-test
TTestInd(model, c1, c0[, tail, vars]) Independent measures t-test (comparing groups of subjects)
ANOVA(x[, model, vars]) ANOVA test
TContrastRel(model, contrast[, tail]) Contrasts of T-maps (see eelbrain.testnd.t_contrast_rel)
TwoStageTest(stage_1[, vars, model]) Two-stage test: T-test of regression coefficients

Example:

tests = {
    'my_anova': ANOVA('noise * word_type * subject'),
    'my_ttest': TTestRel('noise', 'a_lot_of_noise', 'no_noise'),
}
Subject groups
MneExperiment.groups

A subject group called 'all' containing all subjects is always implicitly defined. Additional subject groups can be defined in MneExperiment.groups with {name: group_definition} entries:

Group(subjects) Group defined as collection of subjects
SubGroup(base, exclude) Group defined by removing subjects from a base group

Example:

groups = {
    'good': SubGroup('all', ['R0013', 'R0666']),
    'bad': Group(['R0013', 'R0666']),
}
Parcellations (parcs)
MneExperiment.parcs

The parcellation determines how the brain surface is divided into regions. A number of standard parcellations are automatically defined (see parc/mask (parcellations) below). Additional parcellations can be defined in the MneExperiment.parcs dictionary with {name: parc_definition} entries. There are a couple of different ways in which parcellations can be defined, described below.

CombinationParc(base, labels[, views]) Recombine labels from an existing parcellation
SeededParc(seeds[, mask, surface, views]) Parcellation that is grown from seed coordinates
IndividualSeededParc(seeds[, mask, surface, …]) Seed parcellation with individual seeds for each subject
FreeSurferParc([views]) Parcellation that is created outside Eelbrain for each subject
FSAverageParc([views]) Fsaverage parcellation that is morphed to individual subjects
Visualization defaults
MneExperiment.brain_plot_defaults

The MneExperiment.brain_plot_defaults dictionary can contain options that changes defaults for brain plots (for reports and movies). The following options are available:

surf : ‘inflated’ | ‘pial’ | ‘smoothwm’ | ‘sphere’ | ‘white’
Freesurfer surface to use as brain geometry.
views : str | iterator of str
View or views to show in the figure. Can also be set for each parcellation, see MneExperiment.parc.
foreground : mayavi color
Figure foreground color (i.e., the text color).
background : mayavi color
Figure background color.
smoothing_steps : None | int
Number of smoothing steps to display data.

Analysis parameters

These are parameters that can be set after an MneExperiment has been initialized to affect the analysis, for example:

>>> my_experiment = MneExperiment()
>>> my_experiment.set(raw='1-40', cov='noreg')

sets up my_experiment to use raw files filtered with a 1-40 Hz band-pass filter, and to use sensor covariance matrices without regularization.

raw

Which raw FIFF files to use. Can be customized (see MneExperiment.raw). The default values are:

'raw'
The unfiltered files (as they were added to the data).
'0-40' (default)
Low-pass filtered under 40 Hz.
'0.1-40'
Band-pass filtered between 0.1 and 40 Hz.
'1-40'
Band-pass filtered between 1 and 40 Hz.
group

Any group defined in MneExperiment.groups. Will restrict the analysis to that group of subjects.

epoch

Any epoch defined in MneExperiment.epochs. Specify the epoch on which the analysis should be conducted.

rej (trial rejection)

Trial rejection can be turned off e.set(rej=''), meaning that no trials are rejected, and back on, meaning that the corresponding rejection files are used e.set(rej='man').

equalize_evoked_count

By default, the analysis uses all epoch marked as good during rejection. Set equalize_evoked_count=’eq’ to discard trials to make sure the same number of epochs goes into each cell of the model.

‘’ (default)
Use all epochs.
‘eq’
Make sure the same number of epochs is used in each cell by discarding epochs.
cov

The method for correcting the sensor covariance.

‘noreg’
Use raw covariance as estimated from the data (do not regularize).
‘bestreg’ (default)
Find the regularization parameter that leads to optimal whitening of the baseline.
‘reg’
Use the default regularization parameter (0.1).
‘auto’
Use automatic selection of the optimal regularization method.
src

The source space to use.

  • ico-x: Surface source space based on icosahedral subdivision of the white matter surface x steps (e.g., ico-4, the default).
  • vol-x: Volume source space based on a volume grid with x mm resolution (x is the distance between sources, e.g. vol-10 for a 10 mm grid).
inv

To set the inverse solution use MneExperiment.set_inv().

parc/mask (parcellations)

The parcellation determines how the brain surface is divided into regions. Parcellation are mainly used in tests and report generation:

  • parc or mask arguments for MneExperiment.make_report()
  • parc argument to MneExperiment.make_report_roi()

When source estimates are loaded, the parcellation can also be used to index regions in the source estiomates. Predefined parcellations:

Freesurfer Parcellations
aparc.a2005s, aparc.a2009s, aparc, aparc.DKTatlas, PALS_B12_Brodmann, PALS_B12_Lobes, PALS_B12_OrbitoFrontal, PALS_B12_Visuotopic.
lobes
Modified version of PALS_B12_Lobes in which the limbic lobe is merged into the other 4 lobes.
lobes-op
One large region encompassing occipital and parietal lobe in each hemisphere.
lobes-ot
One large region encompassing occipital and temporal lobe in each hemisphere.
connectivity

Possible values: '', 'link-midline'

Connectivity refers to the edges connecting data channels (sensors for sensor space data and sources for source space data). These edges are used to find clusters in cluster-based permutation tests. For source spaces, the default is to use FreeSurfer surfaces in which the two hemispheres are unconnected. By setting connectivity='link-midline', this default connectivity can be modified so that the midline gyri of the two hemispheres get linked at sources that are at most 15 mm apart. This parameter currently does not affect sensor space connectivity.

select_clusters (cluster selection criteria)

In thresholded cluster test, clusters are initially filtered with a minimum size criterion. This can be changed with the select_clusters analysis parameter with the following options:

name min time min sources min sensors
"all"      
"10ms" 10 ms 10 4
"" (default) 25 ms 10 4
"large" 25 ms 20 8

To change the cluster selection criterion use for example:

>>> e.set(select_clusters='all')

See also

Indices and tables

Eelbrain relies on NumPy, SciPy, Matplotlib, MNE-Python, PySurfer, WxPython, Cython and incorporates icons from the Tango Desktop Project.

Current funding: National Institutes of Health (NIH) grant R01-DC-014085 (since 2016). Past funding: NYU Abu Dhabi Institute grant G1001 (2011-2016).