osl-ephys: a Python toolbox for the analysis of electrophysiology data

Abstract

We describe OHBA Software Library for the analysis of electrophysiology data (osl-ephys). This toolbox builds on top of the widely used MNE-Python package and provides unique analysis tools for magneto-/electro-encephalography (M/EEG) sensor and source space analysis, which can be used modularly. In particular, it facilitates processing large amounts of data using batch parallel processing, with high standards for reproducibility through a config API and log keeping, and efficient quality assurance by producing HTML processing reports. It also provides new functionality for doing coregistration, source reconstruction and parcellation in volumetric space, allowing for an alternative pipeline that avoids the need for surface-based processing, e.g., through the use of Fieldtrip. Here, we introduce osl-ephys by presenting examples applied to a publicly available M/EEG data (the multimodal faces dataset). osl-ephys is open-source software distributed on the Apache License and available as a Python package through PyPi and GitHub.

Keywords: M/EEG; MNE-Python; analysis; electroencephalography (EEG); electrophysiology; magnetoencephalography (MEG); python; toolbox.

LISTING 1A

Example API in the preprocessing module. The config specifies the processing recipe applied to the input. Preprocessed data are saved in the processed/subject001 directory. Note that the source reconstruction module works similarly (see section “Examples”).

LISTING 1B

As in 1a, but now including a custom written function. The function is defined at the top, and takes as input “dataset” (a dictionary containing the MNE-Python objects, e.g., Raw), and a “userargs” dictionary (containing the function variable specifications). The function is included in the config, and supplied to chain function as a list of extra functions in the “extra_funcs” input variable.

LISTING 2

Osl-ephys batch preprocessing script.

Figure 1

The output directory structure of run_proc_batch. All outputs are saved in the general output directory specified in the function call (“processed”). Within this, a subdirectory is created for each subject/session that contains the preprocessed data, as well as logs, and preproc_report directories, containing the relevant files for all subjects.

Figure 2

Example of the preprocessing subject report. This HTML page contains tabs for different aspects of QA for each subject/session. The user can browse between tabs on the left for each subject/session in the list on the right. Each tab contains quantitative and qualitative information regarding the preprocessing output.

Figure 3

Example of the preprocessing summary report. Contains summary information and quantitative metrics of all files processed. The Preproc Summary table is interactive and can guide the user to specific subjects/sessions which might require further attention.

Figure 4

Interactive labelling of independent components (ICs) using the osl_ica_label tool. The weights and time courses for each IC are shown as rows. Bad ICs are indicated as coloured the time courses (i.e., other than black, see types on the right); annotations in the time courses indicate bad segments.

Figure 5

Example of the source_recon subject (top) and summary (bottom) report. The subject report contains figures showing the extracted surfaces, the parcel power spectra, and interactive figures showing the coregistration. The summary report contains summary information and quantitative metrics of all processed files, including interactive tables that can guide the user to specific subjects/sessions which might require further attention.

Figure 6

Pictures of real faces elicit statistically different event-related fields than pictures of scrambled faces. (A) example of a first level (session) design matrix, with three regressors and two contrasts. (B) The second level (group) design contains 19 subject regressors, and one mean contrast. (C) The group Faces – Scrambled contrast. Coloured lines show individual parcels, with colours in an anterior–posterior gradient (inset). Shaded areas show significant time periods, and topographies the mean t-statistic in each period. (D) Extent of significant times periods.