Version History

Known issues

Check for open issues, or report new ones on GitHub.

• If using WSL (Windows Subsystem for Linux), please store your dataset on the Linux filesystem (e.g., under /home/username/...) instead of the Windows filesystem (e.g., /mnt/c/...) to avoid its slow cross-OS file access.

Issues on prior versions

• Fixed in 0.38.3, Windows only (#52): due to unexpected data loss in multiprocessing.sharedctypes.RawArray for large arrays, permutation tests on large datasets using multiprocessing could return spurious results in which p-values for all clusters were reported as exactly 0.

Major changes

New in 0.41

• API:

  • To align with MNE-Python, adjacency has replaced connectivity in the names of:

    • Arguments to functions, such as eelbrain.load.cnd()

    • Function name: eelbrain.set_connectivity() → eelbrain.set_adjacency()

    • Method names for all NDVar dimension classes, such as eelbrain.Case.connectivity() → eelbrain.Case.adjacency()

    • Method names for Sensor:

      • eelbrain.Sensor.get_connectivity() → eelbrain.Sensor.get_adjacency()

      • eelbrain.Sensor.set_connectivity() → eelbrain.Sensor.set_adjacency()

New in 0.40

• API:

  • Plotting parameters ncol and nrow have been renamed to columns and rows.

  • Factor cells that are not specified in labels are now ordered by their first ocurrence in x (previously order was alphabetic).

  • The pool_error argument is replaced by within_subject_error.

• boosting():

  • Now accepts data with ragged trials (trials of different lengths).

  • Now stores both the l1 and l2 loss of the final fit.

  • Due to optimization, results may be numerically different from earlier versions.

• Pipeline:

  • pipeline.RawICA preprocessing pipe now allows setting fit_kwargs.

  • The default pipeline.MneExperiment.subject_re pattern for finding subjects is now more general.

• Permutation tests:

  • Due to a change in randomization algorithm, the permutation distribution for vector-based tests may be slightly different (old and new versions are both valid randomizations).

New in 0.39

• testnd.LM now supports permutation-based significance testing.

• New NDVar functions for time series and an auditory model: pad(), gammatone_bank(), edge_detector()

• API:

  • The common ds parameter has been renamed to data to be more consistent with other packages.

  • The evaluation context for Dataset does not include from numpy import * anymore, to avoid overwriting builtins like abs(); instead, NumPy is accessible as numpy.

  • testnd.LM: The default number of permutations is now 10000 and the argument order has changed slightly to be consistent with other testnd tests. To use testnd.LM for two-stage tests, set samples=0.

  • plot.Barplot parameter c renamed to color.

New in 0.38

• boosting() optimized (as a consequence, the progress bar has been disabled).

New in 0.37

• ICA-GUI (gui.select_components()): Sort noisy epochs by dominant components - makes it easier to find components that capture specific artifacts.

• API: load.mne.events() now loads events from all stim-channels. To use a subset, use the stim_channel parameter.

• New plot: plot.SensorMap3d.

• plot.styles_for_twoway() to quickly generate different color and line-style combinations.

• New function set_connectivity to set the neighborhood structure of an NDVar.

• pipeline.MneExperiment:

  • pipeline.MneExperiment.plot_evoked(): plot sensor data with corresponding source estimates

  • API: By default, events are now loaded from all stim-channels. To only use a subset of stim-channels, use the new pipeline.MneExperiment.stim_channel attribute.

New in 0.36

• Preview cross-validation data partitions with plot.preview_partitions().

• BoostingResult.partition_result_data() method to retrieve results from different partitions.

New in 0.35

• ICA GUI (gui.select_components(); pipeline.MneExperiment.make_ica_selection()):

  • In the source time-course window, display the range of the data before and after cleaning in real-time.

  • New keyboard shortcut: alt + arrow keys to go to the beginning/end.

  • New context-menu commands: find top component for an epoch.

• Mark pairwise comparisons individually with plot.Barplot.mark_pair() and plot.Boxplot.mark_pair().

• NDVar.dot() generalized to multiple dimensions.

New in 0.34

• API:

  • plot.Correlation renamed to plot.Scatter with some parameter changes for improved functionality.

• New:

  • boosting(): Option to store TRFs for the different test partitions (partition_results parameter).

  • normalize_in_cells() (see Compare topographies).

  • UTS dimension: unit parameter to represent time in units other than seconds.

  • report submodule with shortcuts for data summary and visualization.

  • load.convert_pickle_protocol() for compatibility with older Python version.

New in 0.33

• API load.mne.events(): The merge parameter is now by default inferred based on the raw data.

• Boosting: plot data partitioning scheme (BoostingResult.splits.plot()).

• MneExperiment pipeline:

  • New pipeline.MneExperiment.merge_triggers attribute.

  • Compatibility with Microsoft Windows.

New in 0.32

• Requires at least Python 3.7

• API changes:

  • Consistent class names for tests in test, testnd and pipeline.

  • plot.Timeplot argument order: second and third argument switched to facilitate plotting single category.

  • Significance markers for trends (.05 < p ≤ .1) are disabled by default.

• boosting():

  • When using a basis, the function now considers the effect of the basis when normalizing predictors. This change leads to slightly different results, so TRFs should not be compared between this and previous versions. To facilitate keeping track of this change, it corresponds to a change in the BoostingResult.algorithm_version attribute from -1 to 0.

  • Different tstart/tstop for different predictors (contributed by Joshua Kulasingham)

  • Cross-validation of model fit (test parameter)

• plot.Style to control advanced plotting options by category (see Boxplot example).

• New functions/methods:

  • NDVar.quantile()

• MneExperiment pipeline:

  • Methods with decim parameter now also have samplingrate parameter

  • More control over Events

New in 0.31

• API changes:

  • Var and NDVar argument order changed to be consistent with other data objects

  • combine(): Combining NDVar with unequal dimensions will now raise an error; to combine them by taking the intersection of valid elements (previous behavior), use dim_intersection=True

  • Dataset.save_txt(): delim parameter renamed to delimiter

  • testnd API: For permutation tests, the samples parameter now defaults to 10,000 (previously 0)

  • table.difference(): The by parameter is deprecated, use match instead

  • NDVar.smooth() with a window with an even number of samples, and BoostingResult.h for boosting() with a basis with an even number of samples: the time axis is now consistent with scipy.signal.convolve() (was previously shifted by half a sample)

  • testnd.LMGroup.coefficients_dataset() now returns a wide form table by default

  • plot.Topomap.mark_sensors(), plot.TopomapBins.mark_sensors() and plot.SensorMap.mark_sensors(): The second argument now specifies axis to mark

• New functions:

  • gaussian()

  • powerlaw_noise()

  • set_time()

  • plot.two_step_colormap()

• plot.Boxplot: Accepts additional arguments (label_fliers and boxplot() parameters)

• plot.BarplotHorizontal: Horizontal bar-plot

• Non-parametric univariate tests test.MannWhitneyU and test.WilcoxonSignedRank

• MneExperiment pipeline:

  • pipeline.SubParc: Simplified subset parcellation

New in 0.30

• Support for vector data (with many contributions from Proloy Das):

  • Space dimension to represent physical space

  • VolumeSourceSpace to represent volume source spaces

  • Statistical tests: testnd.Vector, testnd.VectorDifferenceRelated

  • Plotting with plot.GlassBrain

• ICA-GUI: tool to find high amplitude signals

• Documentation: New Examples section

• Dataset.summary() method

• Element-wise maximum() and minimum() functions for NDVar objects

• MneExperiment pipeline:

  • RawApplyICA preprocessing pipe to apply ICA estimated in a different branch of the pipeline.

  • pipeline.MneExperiment.load_evoked_stc() API more closely matches pipeline.MneExperiment.load_epochs_stc()

  • pipeline.MneExperiment.load_neighbor_correlation()

New in 0.29

• API: Better default parameters for resample()

• Predictor-specific stopping for boosting()

• New NDVar function correlation_coefficient()

• Plotting:

  • General layout parameters for plot size relative to screen size

  • Better plots for masked statistic maps

• MneExperiment pipeline:

  • API: pipeline.MneExperiment.make_rej() renamed to pipeline.MneExperiment.make_epoch_selection()

  • Object-based definitions (see The Pipeline)

  • New method pipeline.MneExperiment.plot_raw()

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.TTestOneSample.diff renamed to testnd.TTestOneSample.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 pipeline:

  • Independent measures t-test

New in 0.27

• API changes:

  • To change the parcellation of an NDVar with source-space data, use the new function set_parc(). The SourceSpace.set_parc() method has been removed because dimension objects should be treated as immutable, as they can be shared between different NDVar instances. Analogously, UTS.set_tmin() is now set_tmin().

  • table.frequencies(): If the input y is a Var object, the output will also be a Var (was Factor).

  • NDVar.smooth(): window-based smoothing now uses a symmetric window, which can lead to slightly different results.

• concatenate(): concatenate multiple NDVar objects to form a new dimension.

• NDVar.ols(): regress on a dimension.

• plot.brain.SequencePlotter to plot multiple anatomical images on one figure.

• New functions and objects:

  • complete_source_space()

  • psd_welch()

  • frequency_response()

  • test.Correlation, test.pairwise_correlations()

  • xhemi()

• New methods:

  • Dataset.zip(), Dataset.tile()

  • Factor.sort_cells()

New in 0.26

• API changes:

  • A new global configure() function replaces module-level configuration functions.

  • Dataset: when a one-dimensional array is assigned to an unused key, the array is now automatically converted to a Var object.

  • SourceSpace.vertno has been renamed to SourceSpace.vertices.

• Plotting:

  • The new name argument allows setting the window title without adding a title to the figure.

  • Plots that reresent time have a new method to synchronize the time axis on multiple plots: link_time_axis().

  • Plot source space time series: plot.brain.butterfly()

• ANOVAs now support mixed models with between- and within-subjects factors (see examples at test.ANOVA).

• load.mne: when generating epochs from raw data, a new tstop argument allows specifying the time interval exclusive of the last sample.

• New functions:

  • table.cast_to_ndvar()

  • test.TTestIndependent()

• New methods:

  • NDVar.log()

  • NDVar.smooth()

• MneExperiment pipeline:

  • pipeline.MneExperiment.reset() (replacing pipeline.MneExperiment.store_state() and pipeline.MneExperiment.restore_state())

  • New pipeline.MneExperiment.auto_delete_results attribute to control whether invalidated results are automatically deleted.

  • pipeline.MneExperiment.screen_log_level

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 pipeline.MneExperiment.sessions attribute replaces defaults['experiment'], with support for multiple sessions in one experiment (see Setting up the file structure).

  • The pipeline.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 pipeline.MneExperiment.raw).

  • The model parameter for ANOVA tests is now optional (see pipeline.MneExperiment.tests).

• Deconvolution using boosting().

• Loading and saving *.wav files (load.wav() and save.wav()).

New in 0.24

• API:

  • pipeline.MneExperiment: For data from the NYU New York system converted with mne < 0.13, the pipeline.MneExperiment.meg_system attribute needs to be set to "KIT-157" to distinguish it from data collected with the KIT UMD system.

  • masked_parameter_map() method of cluster-based test results: use of pmin=None is deprecated, use pmin=1 instead.

• New test: test.TTestRelated.

• pipeline.MneExperiment.make_report_rois() includes corrected p-values in reports for tests in more than one ROI

• pipeline.MneExperiment.make_rej() now has a decim parameter to improve display performance.

• pipeline.MneExperiment: BEM-solution files are now created dynamically with mne and are not cached any more. This can lead to small changes in results due to improved numerical precision. Delete old files to free up space with mne_experiment.rm('bem-sol-file', subject='*').

• New pipeline.MneExperiment.make_report_coreg() method.

• New pipeline.MneExperiment: analysis parameter adjacency

• plot.TopoButterfly: press Shift-T for a large topo-map with sensor names.

New in 0.23

• API plot.colors_for_twoway() and plot.colors_for_categorial(): new color model, different options.

• testnd.TContrastRelated contrasts can contain * to include the average of multiple cells.

• New NDVar methods: NDVar.envelope(), NDVar.fft().

New in 0.22

• Epoch Rejection GUI:

  • New “Tools” menu.

  • New “Info” tool to show summary info on the rejection.

  • New “Find Bad Channels” tool to automatically find bad channels.

  • Set marked channels by clicking on topo-map.

  • Faster page redraw.

• plot.Barplot and plot.Boxplot: new cells argument to customize the order of bars/boxes.

• pipeline.MneExperiment: new method pipeline.MneExperiment.show_rej_info().

• NDVar: new method NDVar.label_clusters().

• plot.configure(): option to revert to wxPython backend for plot.brain.

New in 0.21

• MneExperiment:

  • New epoch parameters: trigger_shift and vars (see pipeline.MneExperiment.epochs).

  • load_selected_events(): new vardef parameter to load variables from a test definition.

  • Log files stored in the root directory.

  • Parcellations (pipeline.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

• pipeline.MneExperiment: new analysis parameter select_clusters='all' to keep all clusters in cluster tests (see select_clusters (cluster selection criteria)).

• Use testnd.configure() to limit the number of CPUs that are used in permutation cluster tests.

New in 0.19

• Two-stage tests (see pipeline.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.

• 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 pipeline.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.

• pipeline.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

• pipeline.MneExperiment.brain_plot_defaults can be used to customize PySurfer plots in movies and reports.

• pipeline.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 pipeline.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 pipeline.MneExperiment.variables entries with unspecified values.

New in 0.16

• New function for plotting a legend for annot-files: plot.brain.annot_legend() (automatically used in reports).

• Epoch definitions in pipeline.MneExperiment.epochs can now include a 'base' parameter, which will copy the given “base” epoch and modify it with the current definition.

• pipeline.MneExperiment.make_mov_ttest() and pipeline.MneExperiment.make_mov_ga_dspm() are fixed but require PySurfer 0.6.

• New function: table.melt_ndvar().

• API: plot.brain function signatures changed slightly to accommodate more layout-related arguments.

• API: use Brain.image() instead of plot.brain.image().

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.TContrastRelated: support for unary operation abs.

New in 0.13

• The gui.select_epochs() GUI can now also be used to set bad channels. pipeline.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:

  • API: Subclasses should remove the subject and experiment parameters from pipeline.MneExperiment.label_events().

  • API: pipeline.MneExperiment can now be imported directly from eelbrain.

  • API: The pipeline.MneExperiment._defaults attribute should be renamed to pipeline.MneExperiment.defaults.

  • A draft for a guide at The Pipeline.

  • Cached files are now saved in a separate folder at root/eelbrain-cache. The cache can be cleared using pipeline.MneExperiment.clear_cache(). To preserve cached test results, move the root/test folder into the root/eelbrain-cache folder.

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 pipeline.MneExperiment.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().

• pipeline.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 recipes (outdated).

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

• Optimized ANOVA evaluation, support for unbalanced fixed effects models.

• rpy2 interaction: Dataset.from_r() to create a Dataset from an R Data Frame, and Dataset.to_r() to cerate an R Data Frame from a Dataset.

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