osl_ephys.preprocessing#

Submodules#

Attributes#

logger

backends_to_try

logger

backend

__doc__

Classes#

osl_MNEBrowseFigure

OSL's adaptatation of MNE's mne.viz._mpl_figure.MNEBrowseFigure that

Functions#

find_run_id(infile[, preload])

validate_outdir(outdir)

Checks if an output directory exists and if not creates it.

process_file_inputs(inputs)

Process inputs for several cases

dask_parallel_bag(func, iter_args[, func_args, ...])

A maybe more consistent alternative to dask_parallel.

check_version(test_statement[, mode])

Check whether the version of a package meets a specified condition.

set_random_seed([seed])

Set all random seeds.

print_custom_func_info(func)

Prints info for user-specified functions.

import_data(infile[, preload])

Imports data from a file.

find_func(method[, target, extra_funcs])

Find a preprocessing function.

load_config(config)

Load config.

check_config_versions(config)

Get config from a preprocessed fif file.

get_config_from_fif(inst)

Get config from a preprocessed fif file.

append_preproc_info(dataset, config[, extra_funcs])

Add to the config of already preprocessed data to inst.info['description'].

write_dataset(dataset, outbase, run_id[, ftype, ...])

Write preprocessed data to a file.

read_dataset(fif[, preload, ftype])

Reads fif/npy/yml files associated with a dataset.

plot_preproc_flowchart(config[, outname, show, ...])

Make a summary flowchart of a preprocessing chain.

run_proc_chain(config, infile[, subject, ftype, ...])

Run preprocessing for a single file.

run_proc_batch(config, files[, subjects, ftype, ...])

Run batched preprocessing.

main([argv])

Main function for command line interface.

plot_ica(ica, inst[, picks, start, stop, title, show, ...])

osl-ephys' adaptation of MNE's mne.preprocessing.ICA.plot_sources function to

_plot_sources(ica, inst, picks, exclude, start, stop, ...)

Adaptation of MNE's mne.preprocessing.ica._plot_sources function to allow for OSL additions.

_get_browser(**kwargs)

OSL Adaptation of MNE's mne.viz._figure._get_browser function

_init_browser(backend, **kwargs)

flatten_recursive(lst)

Flatten a list using recursion.

_plot_ica_sources_evoked(evoked, picks, exclude, ...)

Plot average over epochs in ICA space.

Package Contents#

osl_ephys.preprocessing.find_run_id(infile, preload=True)[source]#
osl_ephys.preprocessing.validate_outdir(outdir)[source]#

Checks if an output directory exists and if not creates it.

osl_ephys.preprocessing.process_file_inputs(inputs)[source]#

Process inputs for several cases

The argument, inputs, can be… 1) string path to unicode file 2) string path to dir (e.g. if CTF .ds dir) 3) string path to file or regular-expression matching files 4) list of string paths to files 5) list of string paths to dirs (e.g. if CTF .ds dirs) 6) list of tuples with path to file and output name pairs 7) list of MNE objects

osl_ephys.preprocessing.dask_parallel_bag(func, iter_args, func_args=None, func_kwargs=None)[source]#

A maybe more consistent alternative to dask_parallel.

Parameters:

  • func (function) – The function to run in parallel.

  • iter_args (list) – A list of iterables to pass to func.

  • func_args (list, optional) – A list of positional arguments to pass to func.

  • func_kwargs (dict, optional) – A dictionary of keyword arguments to pass to func.

Returns:

flags – A list of return values from func.

Return type:

list

References

https://docs.dask.org/en/stable/bag.html

osl_ephys.preprocessing.check_version(test_statement, mode='warn')[source]#

Check whether the version of a package meets a specified condition.

Parameters:

  • test_statement (str) – Package version comparison string in the standard format expected by python installs. eg ‘osl-ephys<1.0.0’ or ‘osl-ephys==0.6.dev0’

  • mode ({'warn', 'assert'}) – Flag indicating whether to warn the user or raise an error if the comparison fails

osl_ephys.preprocessing.set_random_seed(seed=None)[source]#

Set all random seeds.

This includes Python’s random module and NumPy.

Parameters:

seed (int) – Random seed.

osl_ephys.preprocessing.logger = None[source]#
osl_ephys.preprocessing.print_custom_func_info(func)[source]#

Prints info for user-specified functions.

Parameters:

func (function) – Function to wrap.

Returns:

Wrapped function.

Return type:

function

osl_ephys.preprocessing.import_data(infile, preload=True)[source]#

Imports data from a file.

Parameters:

  • infile (str) – Path to file to read. File can be bti, fif, ds, meg4 or vhdr.

  • preload (bool) – Should we load the data in the file?

Returns:

raw – Data as an MNE Raw object.

Return type:

mne.io.Raw

osl_ephys.preprocessing.find_func(method, target='raw', extra_funcs=None)[source]#

Find a preprocessing function.

Function priority:

  1. User custom function

  2. MNE/osl-ephys wrapper

  3. MNE method on Raw or Epochs (specified by target)

Parameters:

  • method (str) – Function name.

  • target (str) – Type of MNE object to preprocess. Can be 'raw', 'epochs', 'evoked', 'power' or 'itc'.

  • extra_funcs (list) – List of user-defined functions.

Returns:

Function to preprocess an MNE object.

Return type:

function

osl_ephys.preprocessing.load_config(config)[source]#

Load config.

Parameters:

config (str or dict) – Path to yaml file or string to convert to dict or a dict.

Returns:

Preprocessing config.

Return type:

dict

osl_ephys.preprocessing.check_config_versions(config)[source]#

Get config from a preprocessed fif file.

Parameters:

config (dictionary or yaml string) – Preprocessing configuration to check.

Raises:

  • AssertionError – Raised if package version mismatch found in ‘version_assert’

  • Warning – Raised if package version mismatch found in ‘version_warn’

osl_ephys.preprocessing.get_config_from_fif(inst)[source]#

Get config from a preprocessed fif file.

Reads the inst.info['description'] field of a fif file to get the preprocessing config.

Parameters:

inst (mne.io.Raw, mne.Epochs, mne.Evoked) – Preprocessed MNE object.

Returns:

Preprocessing config.

Return type:

dict

osl_ephys.preprocessing.append_preproc_info(dataset, config, extra_funcs=None)[source]#

Add to the config of already preprocessed data to inst.info['description'].

Parameters:

  • dataset (dict) – Preprocessed dataset.

  • config (dict) – Preprocessing config.

Returns:

Dataset dict containing the preprocessed data edited in place.

Return type:

dict

osl_ephys.preprocessing.write_dataset(dataset, outbase, run_id, ftype='preproc-raw', overwrite=False, skip=None)[source]#

Write preprocessed data to a file.

Will write all keys in the dataset dict to disk with corresponding extensions.

Parameters:

  • dataset (dict) – Preprocessed dataset.

  • outbase (str) – Path to directory to write to.

  • run_id (str) – ID for the output file.

  • ftype (str) – Extension for the fif file (default preproc-raw)

  • overwrite (bool) – Should we overwrite if the file already exists?

  • skip (list or None) – List of keys to skip writing to disk. If None, we don’t skip any keys.

  • Output –

  • ------ –

  • fif_outname (str) – The saved fif file name

osl_ephys.preprocessing.read_dataset(fif, preload=False, ftype=None)[source]#

Reads fif/npy/yml files associated with a dataset.

Parameters:

  • fif (str) – Path to raw fif file (can be preprocessed).

  • preload (bool) – Should we load the raw fif data?

  • ftype (str) – Extension for the fif file (will be replaced for e.g. '_events.npy' or '_ica.fif'). If None, we assume the fif file is preprocessed with osl-ephys and has the extension '_preproc-raw'. If this fails, we guess the extension as whatever comes after the last '_'.

Returns:

dataset – Contains keys: 'raw', 'events', 'event_id', 'epochs', 'ica'.

Return type:

dict

osl_ephys.preprocessing.plot_preproc_flowchart(config, outname=None, show=False, stagecol='wheat', startcol='red', fig=None, ax=None, title=None)[source]#

Make a summary flowchart of a preprocessing chain.

Parameters:

  • config (dict) – Preprocessing config to plot.

  • outname (str) – Output filename.

  • show (bool) – Should we show the plot?

  • stagecol (str) – Stage colour.

  • startcol (str) – Start colour.

  • fig (matplotlib.figure) – Matplotlib figure to plot on.

  • ax (matplotlib.axes) – Matplotlib axes to plot on.

  • title (str) – Title for the plot.

Returns:

  • fig (matplotlib.figure)

  • ax (matplotlib.axes)

osl_ephys.preprocessing.run_proc_chain(config, infile, subject=None, ftype='preproc-raw', outdir=None, logsdir=None, reportdir=None, ret_dataset=True, gen_report=None, overwrite=False, skip_save=None, extra_funcs=None, random_seed='auto', verbose='INFO', mneverbose='WARNING')[source]#

Run preprocessing for a single file.

Parameters:

  • config (str or dict) – Preprocessing config.

  • infile (str) – Path to input file.

  • subject (str) – Subject ID. This will be the sub-directory in outdir.

  • ftype (str) – Extension for the fif file (default preproc-raw)

  • outdir (str) – Output directory.

  • logsdir (str) – Directory to save log files to.

  • reportdir (str) – Directory to save report files to.

  • ret_dataset (bool) – Should we return a dataset dict?

  • gen_report (bool) – Should we generate a report?

  • overwrite (bool) – Should we overwrite the output file if it already exists?

  • skip_save (list or None (default)) – List of keys to skip writing to disk. If None, we don’t skip any keys.

  • extra_funcs (list) – User-defined functions.

  • random_seed ('auto' (default), int or None) – Random seed to set. If ‘auto’, a random seed will be generated. Random seeds are set for both Python and NumPy. If None, no random seed is set.

  • verbose (str) – Level of info to print. Can be: 'CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG' or 'NOTSET'.

  • mneverbose (str) – Level of info from MNE to print. Can be: 'CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG' or 'NOTSET'.

Returns:

If ret_dataset=True, a dict containing the preprocessed dataset with the following keys: raw, ica, epochs, events, event_id. An empty dict is returned if preprocessing fails. If ret_dataset=False, we return a flag indicating whether preprocessing was successful.

Return type:

dict or bool

osl_ephys.preprocessing.run_proc_batch(config, files, subjects=None, ftype='preproc-raw', outdir=None, logsdir=None, reportdir=None, gen_report=True, overwrite=False, skip_save=None, extra_funcs=None, covs=None, random_seed='auto', verbose='INFO', mneverbose='WARNING', strictrun=False, dask_client=False)[source]#

Run batched preprocessing.

This function will write output to disk (i.e. will not return the preprocessed data).

Parameters:

  • config (str or dict) – Preprocessing config.

  • files (str or list or mne.Raw) – Can be a list of Raw objects or a list of filenames (or .ds dir names if CTF data) or a path to a textfile list of filenames (or .ds dir names if CTF data).

  • subjects (list of str) – Subject directory names. These are sub-directories in outdir.

  • ftype (None or str) – Extension of the preprocessed fif files. Default option is _preproc-raw.

  • outdir (str) – Output directory.

  • logsdir (str) – Directory to save log files to.

  • reportdir (str) – Directory to save report files to.

  • gen_report (bool) – Should we generate a report?

  • overwrite (bool) – Should we overwrite the output file if it exists?

  • skip_save (list or None (default)) – List of keys to skip writing to disk. If None, we don’t skip any keys.

  • extra_funcs (list) – User-defined functions.

  • covs (dict or pd.DataFrame) – Covariates to use for building the GLM design

  • random_seed ('auto' (default), int or None) – Random seed to set. If ‘auto’, a random seed will be generated. Random seeds are set for both Python and NumPy. If None, no random seed is set.

  • verbose (str) – Level of info to print. Can be: 'CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG' or 'NOTSET'.

  • mneverbose (str) – Level of info from MNE to print. Can be: 'CRITICAL', 'ERROR', 'WARNING', 'INFO', 'DEBUG' or 'NOTSET'.

  • strictrun (bool) – Should we ask for confirmation of user inputs before starting?

  • dask_client (bool) – Indicate whether to use a previously initialised dask.distributed.Client instance.

Returns:

Flags indicating whether preprocessing was successful for each input file.

Return type:

list of bool

Notes

If you are using a dask.distributed.Client instance, you must initialise it before calling this function. For example:

>>> from dask.distributed import Client
>>> client = Client(threads_per_worker=1, n_workers=4)
osl_ephys.preprocessing.main(argv=None)[source]#

Main function for command line interface.

Parameters:

argv (list) – Command line arguments.

osl_ephys.preprocessing.backends_to_try = ['Qt5Agg', 'QtAgg', 'GTK3Agg', 'GTK4Agg', 'macosx', 'TkAgg', 'GTK3Cairo', 'GTK4Cairo', 'wxAgg'][source]#
osl_ephys.preprocessing.logger = None[source]#
osl_ephys.preprocessing.plot_ica(ica, inst, picks=None, start=None, stop=None, title=None, show=True, block=False, show_first_samp=False, show_scrollbars=True, time_format='float', n_channels=10, bad_labels_list=['eog', 'ecg', 'emg', 'hardware', 'other'])[source]#

osl-ephys’ adaptation of MNE’s mne.preprocessing.ICA.plot_sources function to plot estimated latent sources given the unmixing matrix.

Typical usecases:

  1. plot evolution of latent sources over time based on (Raw input)

  2. plot latent source around event related time windows (Epochs input)

  3. plot time-locking in ICA space (Evoked input)

Parameters:

  • ica (mne.preprocessing.ICA.) – The ICA solution.

  • inst (mne.io.Raw, mne.Epochs, or mne.Evoked.) – The object to plot the sources from.

  • picks (str) – Channel types to pick.

  • start (float | int | None) – If inst is a mne.io.Raw or an mne.Evoked object, the first and last time point (in seconds) of the data to plot. If inst is a mne.io.Raw object, start=None and stop=None will be translated into start=0. and stop=3., respectively. For mne.Evoked, None refers to the beginning and end of the evoked signal. If inst is an mne.Epochs object, specifies the index of the first and last epoch to show.

  • stop (float | int | None) – If inst is a mne.io.Raw or an mne.Evoked object, the first and last time point (in seconds) of the data to plot. If inst is a mne.io.Raw object, start=None and stop=None will be translated into start=0. and stop=3., respectively. For mne.Evoked, None refers to the beginning and end of the evoked signal. If inst is an mne.Epochs object, specifies the index of the first and last epoch to show.

  • title (str | None) – The window title. If None a default is provided.

  • show (bool) – Show figure if True.

  • block (bool) – Whether to halt program execution until the figure is closed. Useful for interactive selection of components in raw and epoch plotter. For evoked, this parameter has no effect. Defaults to False.

  • show_first_samp (bool) – If True, show time axis relative to the raw.first_samp.

  • n_channels (int) – Number of channels to show at the same time (default: 10)

  • bad_labels_list (list of str) – list of bad labels to show in the bad labels list that can be used to mark the type of bad component. Defaults to ["eog", "ecg", "emg", "hardware", "other"].

Returns:

fig – The figure.

Return type:

instance of Figure

Notes

For raw and epoch instances, it is possible to select components for exclusion by clicking on the line. The selected components are added to ica.exclude on close.

New in version 0.10.0.

osl_ephys.preprocessing._plot_sources(ica, inst, picks, exclude, start, stop, show, title, block, show_scrollbars, show_first_samp, time_format, n_channels, bad_labels_list)[source]#

Adaptation of MNE’s mne.preprocessing.ica._plot_sources function to allow for OSL additions.

osl_ephys.preprocessing.backend = None[source]#
osl_ephys.preprocessing._get_browser(**kwargs)[source]#

OSL Adaptation of MNE’s mne.viz._figure._get_browser function that instantiate a new MNE browse-style figure.

osl_ephys.preprocessing._init_browser(backend, **kwargs)[source]#
class osl_ephys.preprocessing.osl_MNEBrowseFigure(inst, figsize, ica=None, xlabel='Time (s)', **kwargs)[source]#

Bases: mne.viz._mpl_figure.MNEBrowseFigure

OSL’s adaptatation of MNE’s mne.viz._mpl_figure.MNEBrowseFigure that creates an interactive figure with scrollbars, for data browsing.

backend_name = 'matplotlib'#
_update_picks()[source]#

Compute which channel indices to show.

_draw_traces()[source]#

Draw (or redraw) the channel data.

plot_topos(ica, ax_topo, picks)[source]#
_keypress(event)[source]#

Handle keypress events.

_on_mouse_press(event)[source]#

Handle mouse clicks for jumping the vertical scrollbar selection.

_update_vscroll()[source]#

Update the vertical scrollbar (channel) selection indicator.

_close(event)[source]#

Handle close events (via keypress or window [x]).

osl_ephys.preprocessing.flatten_recursive(lst)[source]#

Flatten a list using recursion.

osl_ephys.preprocessing._plot_ica_sources_evoked(evoked, picks, exclude, title, show, ica, labels=None, n_channels=10, bad_labels_list=None)[source]#

Plot average over epochs in ICA space.

Parameters:

  • evoked (instance of mne.Evoked) – The Evoked to be used.

  • fitted. (%(picks_base)s all sources in the order as) –

  • exclude (array-like of int) – The components marked for exclusion. If None (default), ICA.exclude will be used.

  • title (str) – The figure title.

  • show (bool) – Show figure if True.

  • labels (None | dict) – The ICA labels attribute.

osl_ephys.preprocessing.__doc__[source]#