Data Classes

Primary data classes:

Dataset([items, name, caption, info, n_cases])

Store multiple variables pertaining to a common set of measurement cases

Factor(x[, name, random, repeat, tile, …])

Container for categorial data.

Var(x[, name, info, repeat, tile])

Container for scalar data.

NDVar(x, dims[, name, info])

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):


Represents an Interaction effect.


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 pickled Python objects from a file.


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


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

load.wav([filename, name, backend])

Load a wav file as NDVar

load.tsv([path, names, types, delimiter, …])

Load a Dataset from a text file.


Tools for loading data form eyelink edf files.


Tools for importing data through mne.


Tools for loading data from text files.


Tools for loading data from the BESA-MN pipeline.


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, …])

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 Initializers

gaussian(center, width, time)

Gaussian window NDVar

powerlaw_noise(dims, exponent)

Gaussian (1/f)^{exponent} noise.

NDVar Operations

NDVar objects support the native abs() and round() functions. See also NDVar methods.

Butterworth(low, high, order[, sfreq])

Butterworth filter

complete_source_space(ndvar[, fill, mask])

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, name])

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)


Denoising source separation (DSS)

filter_data(ndvar, l_freq, h_freq[, …])

Apply mne.filter.filter_data() to an NDVar

find_intervals(ndvar[, interpolate])

Find intervals from a boolean NDVar


Find local maxima in 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

maximum(ndvars[, name])

Element-wise maximum of multiple NDVar objects

minimum(ndvars[, name])

Element-wise minimum of multiple NDVar objects

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_time(ndvar, time[, mode])

Crop and/or pad an NDVar to match the time axis time

set_tmin(ndvar[, tmin])

Shift the time axis of an NDVar relative to its data

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 linear filter with coordinate descent

BoostingResult(y, x, tstart, tstop, …[, …])

Result from boosting a temporal response function

epoch_impulse_predictor(shape[, value, …])

Time series with one impulse for each of n epochs

event_impulse_predictor(shape[, time, …])

Time series with multiple impulses


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[, sub, …])

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


Univariate statistical tests:

test.Correlation(y, x[, sub, ds])

Pearson product moment correlation between y and x

test.TTestOneSample(y[, match, sub, ds, …])

One-sample t-test

test.TTestIndependent(y, x[, c1, c0, match, …])

Independent measures t-test

test.TTestRelated(y, x[, c1, c0, match, …])

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.MannWhitneyU(y, x[, c1, c0, match, …])

Mann-Whitney U-test (non-parametric independent measures test)

test.WilcoxonSignedRank(y, x[, c1, c0, …])

Wilcoxon signed-rank test (non-parametric related measures test)

test.lilliefors(data[, formatted])

Lilliefors’ test for normal distribution

Mass-Univariate Statistics

testnd.TTestOneSample(y[, popmean, match, …])

Mass-univariate one sample t-test

testnd.TTestRelated(y, x[, c1, c0, match, …])

Mass-univariate related samples t-test

testnd.TTestIndependent(y, x[, c1, c0, …])

Mass-univariate independent samples t-test

testnd.TContrastRelated(y, x, contrast[, …])

Mass-univariate contrast based on t-values

testnd.ANOVA(y, x[, sub, ds, samples, pmin, …])

Mass-univariate ANOVA

testnd.Correlation(y, x[, norm, sub, ds, …])

Mass-univariate correlation

testnd.Vector(y[, match, sub, ds, samples, …])

Test a vector field for vectors with non-random direction

testnd.VectorDifferenceRelated(y, x[, c1, …])

Test difference between two vector fields for non-random direction

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 (see Two-stage test example).

testnd.LM(y, model[, ds, coding, subject, sub])

Fixed effects linear model


Group level analysis for linear model LM objects



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


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


Plot univariate data (Var objects):

plot.Barplot(y[, x, match, sub, cells, …])

Barplot for a continuous variable

plot.BarplotHorizontal(y[, x, match, sub, …])

Horizontal 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, time[, categories, 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.soft_threshold_colormap(cmap, …[, …])

Soft-threshold a colormap to make small values transparent

plot.two_step_colormap(left_max, left[, …])

Colormap using lightness to extend range

plot.Style([color, marker, hatch, …])

Control color/pattern by category

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, size, h])

Plot colors with labels

Plot uniform time-series:

plot.LineStack(y[, x, sub, ds, offset, …])

Stack multiple lines vertically

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, wscalar

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, axwscalar

Height and width of the axes.

nrow, ncolNone | int

Limit number of rows/columns. If neither is specified, a square layout is produced


Absolute subplot parameters (in inches). Implies tight=False. If margins is specified, axw and axh are interpreted exclusive of the margins, i.e., axh=2, margins={'top': .5} for a plot with one axes will result in a total height of 2.5. Example:

    'top': 0.5,  # from top of figure to top axes
    'bottom': 1,  # from bottom of figure to bottom axes
    'hspace': 0.1,  # height of space between axes
    'left': 0.5,  #  from left of figure to left-most axes
    'right': 0.1,  # from right of figure to right-most axes
    'wspace': 0.1,  # width of space between axes

Width / height aspect of the axes.

framebool | str

How to frame the axes of the plot. Options:

  • True (default): normal matplotlib frame, spines around axes

  • False: omit top and right spines

  • 't': draw spines at x=0 and y=0, common for ERPs

  • 'none': no spines at all


Window title (not displayed on the figure itself).


Figure title (displayed on the figure).


Use matplotlib’s tight_layout to resize all axes to fill the figure.

right_ofeelbrain plot

Position the new figure to the right of this figure.

beloweelbrain plot

Position the new figure below this 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 the figure in the GUI (default True). Use False for creating figures and saving them without displaying them on the screen.


Run the Eelbrain GUI app (default is True for interactive plotting and False in scripts).

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

By default, Eelbrain plots open in windows with enhance GUI features such as copying a figure to the OS clip-board. To plot figures in bare matplotlib windows, configure() Eelbrain with eelbrain.configure(frame=False).

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

Brain(subject, hemi[, surf, title, cortex, …])

PySurfer Brain subclass returned by plot.brain functions


Grid of anatomical images in one figure

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:














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


GUI for detecting and loading source estimates

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 can be inserted at the end of the script, which will keep all gui elements open until the user quits the GUI application (see 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 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.[block])

Hand over command to the GUI (quit the GUI to return to the terminal)

Formatted Text

The fmtxt submodule provides tools for exporting results. Most eelbrain functions and methods that print tables in fact return fmtxt objects, which can be exported in different formats, for example:

>>> ds = datasets.get_uts()
>>> table.stats('Y', 'A', 'B', ds=ds)
     b0       b1
a0   0.8857   0.4525
a1   0.3425   1.377
>>> type(table.stats('Y', 'A', 'B', ds=ds))

This means that the result can be exported as formatted text, for example:

>>> fmtxt.save_pdf(table.stats('Y', 'A', 'B', ds=ds))

See available export functions and the module documentation for details:


Document model for formatted text documents


Copy an FMText object to the clipboard as PDF


Copy an FMText object to the clipboard as tex code

fmtxt.save_html(fmtext[, path, …])

Save an FMText object in HTML format

fmtxt.save_pdf(fmtext[, path])

Save an FMText object as a PDF (requires LaTeX installation)

fmtxt.save_rtf(fmtext[, path])

Save an FMText object in Rich Text format

fmtxt.save_tex(fmtext[, path])

Save an FMText object as TeX code

Experiment Pipeline

The MneExperiment class provides a template for analyzing EEG and MEG data. The objects for specifying the analysis are all in the pipeline submodule.

See also

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

MneExperiment([root, find_subjects])

Analyze an MEG or EEG experiment

Result containers:

ROITestResult(subjects, samples, …)

Test results for temporal tests in one or more ROIs

ROI2StageResult(subjects, samples, …)

Test results for 2-stage tests in one or more ROIs

Participant groups:


Group defined as collection of subjects

SubGroup(base, exclude)

Group defined by removing subjects from a base group


RawSource([filename, reader, sysname, …])

Raw data source

RawFilter(source[, l_freq, h_freq, cache])

Filter raw pipe

RawICA(source, session[, method, …])

ICA raw pipe

RawMaxwell(source[, bad_condition, cache])

Maxwell filter raw pipe

RawReReference(source[, reference, add, …])

Re-reference EEG data

RawApplyICA(source, ica[, cache])

Apply ICA estimated in a RawICA pipe

Event variables:

EvalVar(code[, session])

Variable based on evaluating a statement

GroupVar(groups[, session])

Group membership for each subject

LabelVar(source, codes[, default, session])

Variable assigning labels to values


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


ANOVA(x[, model, vars])

ANOVA test


One-sample t-test

TTestIndependent(model, c1, c0[, tail])

Independent measures t-test (comparing groups of subjects)

TTestRelated(model, c1, c0[, tail])

Related measures t-test

TContrastRelated(model, contrast[, tail])

Contrasts of T-maps (see eelbrain.testnd.TContrastRelated)

TwoStageTest(stage_1[, vars, model])

Two-stage test: T-test of regression coefficients

Brain parcellations:

SubParc(base, labels[, views])

A subset of labels in another parcellation

CombinationParc(base, labels[, views])

Recombine labels from an existing parcellation


Parcellation that is created outside Eelbrain for each subject


Fsaverage parcellation that is morphed to individual subjects

SeededParc(seeds[, mask, surface, views])

Parcellation that is grown from seed coordinates

IndividualSeededParc(seeds[, mask, surface, …])

Seed parcellation with individual seeds for each subject


Datasets for experimenting and testing:


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

datasets.simulate_erp([n_trials, seed])

Simulate event-related EEG data


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

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

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.