# -*- coding: utf-8 -*- # Authors: Alexandre Gramfort # Matti Hamalainen # Martin Luessi # # License: BSD (3-clause) from copy import deepcopy import re import numpy as np from .constants import FIFF from ..utils import (logger, verbose, _validate_type, fill_doc, _ensure_int, _check_option) def get_channel_types(): """Return all known channel types. Returns ------- channel_types : dict The keys contain the channel types, and the values contain the corresponding values in the info['chs'][idx] dictionary. """ return dict(grad=dict(kind=FIFF.FIFFV_MEG_CH, unit=FIFF.FIFF_UNIT_T_M), mag=dict(kind=FIFF.FIFFV_MEG_CH, unit=FIFF.FIFF_UNIT_T), ref_meg=dict(kind=FIFF.FIFFV_REF_MEG_CH), eeg=dict(kind=FIFF.FIFFV_EEG_CH), stim=dict(kind=FIFF.FIFFV_STIM_CH), eog=dict(kind=FIFF.FIFFV_EOG_CH), emg=dict(kind=FIFF.FIFFV_EMG_CH), ecg=dict(kind=FIFF.FIFFV_ECG_CH), resp=dict(kind=FIFF.FIFFV_RESP_CH), misc=dict(kind=FIFF.FIFFV_MISC_CH), exci=dict(kind=FIFF.FIFFV_EXCI_CH), ias=dict(kind=FIFF.FIFFV_IAS_CH), syst=dict(kind=FIFF.FIFFV_SYST_CH), seeg=dict(kind=FIFF.FIFFV_SEEG_CH), bio=dict(kind=FIFF.FIFFV_BIO_CH), chpi=dict(kind=[FIFF.FIFFV_QUAT_0, FIFF.FIFFV_QUAT_1, FIFF.FIFFV_QUAT_2, FIFF.FIFFV_QUAT_3, FIFF.FIFFV_QUAT_4, FIFF.FIFFV_QUAT_5, FIFF.FIFFV_QUAT_6, FIFF.FIFFV_HPI_G, FIFF.FIFFV_HPI_ERR, FIFF.FIFFV_HPI_MOV]), dipole=dict(kind=FIFF.FIFFV_DIPOLE_WAVE), gof=dict(kind=FIFF.FIFFV_GOODNESS_FIT), ecog=dict(kind=FIFF.FIFFV_ECOG_CH), hbo=dict(kind=FIFF.FIFFV_FNIRS_CH, coil_type=FIFF.FIFFV_COIL_FNIRS_HBO), hbr=dict(kind=FIFF.FIFFV_FNIRS_CH, coil_type=FIFF.FIFFV_COIL_FNIRS_HBR)) _first_rule = { FIFF.FIFFV_MEG_CH: 'meg', FIFF.FIFFV_REF_MEG_CH: 'ref_meg', FIFF.FIFFV_EEG_CH: 'eeg', FIFF.FIFFV_STIM_CH: 'stim', FIFF.FIFFV_EOG_CH: 'eog', FIFF.FIFFV_EMG_CH: 'emg', FIFF.FIFFV_ECG_CH: 'ecg', FIFF.FIFFV_RESP_CH: 'resp', FIFF.FIFFV_MISC_CH: 'misc', FIFF.FIFFV_EXCI_CH: 'exci', FIFF.FIFFV_IAS_CH: 'ias', FIFF.FIFFV_SYST_CH: 'syst', FIFF.FIFFV_SEEG_CH: 'seeg', FIFF.FIFFV_BIO_CH: 'bio', FIFF.FIFFV_QUAT_0: 'chpi', FIFF.FIFFV_QUAT_1: 'chpi', FIFF.FIFFV_QUAT_2: 'chpi', FIFF.FIFFV_QUAT_3: 'chpi', FIFF.FIFFV_QUAT_4: 'chpi', FIFF.FIFFV_QUAT_5: 'chpi', FIFF.FIFFV_QUAT_6: 'chpi', FIFF.FIFFV_HPI_G: 'chpi', FIFF.FIFFV_HPI_ERR: 'chpi', FIFF.FIFFV_HPI_MOV: 'chpi', FIFF.FIFFV_DIPOLE_WAVE: 'dipole', FIFF.FIFFV_GOODNESS_FIT: 'gof', FIFF.FIFFV_ECOG_CH: 'ecog', FIFF.FIFFV_FNIRS_CH: 'fnirs', } # How to reduce our categories in channel_type (originally) _second_rules = { 'meg': ('unit', {FIFF.FIFF_UNIT_T_M: 'grad', FIFF.FIFF_UNIT_T: 'mag'}), 'fnirs': ('coil_type', {FIFF.FIFFV_COIL_FNIRS_HBO: 'hbo', FIFF.FIFFV_COIL_FNIRS_HBR: 'hbr'}), } def channel_type(info, idx): """Get channel type. Parameters ---------- info : instance of Info A measurement info object. idx : int Index of channel. Returns ------- type : str Type of channel. Will be one of:: {'grad', 'mag', 'eeg', 'stim', 'eog', 'emg', 'ecg', 'ref_meg', 'resp', 'exci', 'ias', 'syst', 'misc', 'seeg', 'bio', 'chpi', 'dipole', 'gof', 'ecog', 'hbo', 'hbr'} """ # This is faster than the original _channel_type_old now in test_pick.py # because it uses (at most!) two dict lookups plus one conditional # to get the channel type string. ch = info['chs'][idx] try: first_kind = _first_rule[ch['kind']] except KeyError: raise ValueError('Unknown channel type (%s) for channel "%s"' % (ch['kind'], ch["ch_name"])) if first_kind in _second_rules: key, second_rule = _second_rules[first_kind] first_kind = second_rule[ch[key]] return first_kind def pick_channels(ch_names, include, exclude=[], ordered=False): """Pick channels by names. Returns the indices of the good channels in ch_names. Parameters ---------- ch_names : list of string List of channels. include : list of string List of channels to include (if empty include all available). .. note:: This is to be treated as a set. The order of this list is not used or maintained in ``sel``. exclude : list of string List of channels to exclude (if empty do not exclude any channel). Defaults to []. ordered : bool If true (default False), treat ``include`` as an ordered list rather than a set, and any channels from ``include`` are missing in ``ch_names`` an error will be raised. .. versionadded:: 0.18 See Also -------- pick_channels_regexp, pick_types Returns ------- sel : array of int Indices of good channels. """ if len(np.unique(ch_names)) != len(ch_names): raise RuntimeError('ch_names is not a unique list, picking is unsafe') _check_excludes_includes(include) _check_excludes_includes(exclude) if not ordered: if not isinstance(include, set): include = set(include) if not isinstance(exclude, set): exclude = set(exclude) sel = [] for k, name in enumerate(ch_names): if (len(include) == 0 or name in include) and name not in exclude: sel.append(k) else: if not isinstance(include, list): include = list(include) if len(include) == 0: include = list(ch_names) if not isinstance(exclude, list): exclude = list(exclude) sel, missing = list(), list() for name in include: if name in ch_names: if name not in exclude: sel.append(ch_names.index(name)) else: missing.append(name) if len(missing): raise ValueError('Missing channels from ch_names required by ' 'include:\n%s' % (missing,)) return np.array(sel, int) def pick_channels_regexp(ch_names, regexp): """Pick channels using regular expression. Returns the indices of the good channels in ch_names. Parameters ---------- ch_names : list of string List of channels regexp : string The regular expression. See python standard module for regular expressions. Returns ------- sel : array of int Indices of good channels. See Also -------- pick_channels Examples -------- >>> pick_channels_regexp(['MEG 2331', 'MEG 2332', 'MEG 2333'], 'MEG ...1') [0] >>> pick_channels_regexp(['MEG 2331', 'MEG 2332', 'MEG 2333'], 'MEG *') [0, 1, 2] """ r = re.compile(regexp) return [k for k, name in enumerate(ch_names) if r.match(name)] def _triage_meg_pick(ch, meg): """Triage an MEG pick type.""" if meg is True: return True elif ch['unit'] == FIFF.FIFF_UNIT_T_M: if meg == 'grad': return True elif meg == 'planar1' and ch['ch_name'].endswith('2'): return True elif meg == 'planar2' and ch['ch_name'].endswith('3'): return True elif (meg == 'mag' and ch['unit'] == FIFF.FIFF_UNIT_T): return True return False def _triage_fnirs_pick(ch, fnirs): """Triage an fNIRS pick type.""" if fnirs is True: return True elif ch['coil_type'] == FIFF.FIFFV_COIL_FNIRS_HBO and fnirs == 'hbo': return True elif ch['coil_type'] == FIFF.FIFFV_COIL_FNIRS_HBR and fnirs == 'hbr': return True return False def _check_meg_type(meg, allow_auto=False): """Ensure a valid meg type.""" if isinstance(meg, str): allowed_types = ['grad', 'mag', 'planar1', 'planar2'] allowed_types += ['auto'] if allow_auto else [] if meg not in allowed_types: raise ValueError('meg value must be one of %s or bool, not %s' % (allowed_types, meg)) def _check_info_exclude(info, exclude): _validate_type(info, "info") info._check_consistency() if exclude is None: raise ValueError('exclude must be a list of strings or "bads"') elif exclude == 'bads': exclude = info.get('bads', []) elif not isinstance(exclude, (list, tuple)): raise ValueError('exclude must either be "bads" or a list of strings.' ' If only one channel is to be excluded, use ' '[ch_name] instead of passing ch_name.') return exclude def pick_types(info, meg=True, eeg=False, stim=False, eog=False, ecg=False, emg=False, ref_meg='auto', misc=False, resp=False, chpi=False, exci=False, ias=False, syst=False, seeg=False, dipole=False, gof=False, bio=False, ecog=False, fnirs=False, include=(), exclude='bads', selection=None): """Pick channels by type and names. Parameters ---------- info : dict The measurement info. meg : bool | str If True include all MEG channels. If False include None If string it can be 'mag', 'grad', 'planar1' or 'planar2' to select only magnetometers, all gradiometers, or a specific type of gradiometer. eeg : bool If True include EEG channels. stim : bool If True include stimulus channels. eog : bool If True include EOG channels. ecg : bool If True include ECG channels. emg : bool If True include EMG channels. ref_meg : bool | str If True include CTF / 4D reference channels. If 'auto', the reference channels included if compensations are present and ``meg`` is not False. Can also be the string options allowed for the ``meg`` parameter. misc : bool If True include miscellaneous analog channels. resp : bool If True include response-trigger channel. For some MEG systems this is separate from the stim channel. chpi : bool If True include continuous HPI coil channels. exci : bool Flux excitation channel used to be a stimulus channel. ias : bool Internal Active Shielding data (maybe on Triux only). syst : bool System status channel information (on Triux systems only). seeg : bool Stereotactic EEG channels. dipole : bool Dipole time course channels. gof : bool Dipole goodness of fit channels. bio : bool Bio channels. ecog : bool Electrocorticography channels. fnirs : bool | str Functional near-infrared spectroscopy channels. If True include all fNIRS channels. If False (default) include none. If string it can be 'hbo' (to include channels measuring oxyhemoglobin) or 'hbr' (to include channels measuring deoxyhemoglobin). include : list of string List of additional channels to include. If empty do not include any. exclude : list of string | str List of channels to exclude. If 'bads' (default), exclude channels in ``info['bads']``. selection : list of string Restrict sensor channels (MEG, EEG) to this list of channel names. Returns ------- sel : array of int Indices of good channels. """ # NOTE: Changes to this function's signature should also be changed in # PickChannelsMixin exclude = _check_info_exclude(info, exclude) nchan = info['nchan'] pick = np.zeros(nchan, dtype=np.bool) _check_meg_type(ref_meg, allow_auto=True) _check_meg_type(meg) if isinstance(ref_meg, str) and ref_meg == 'auto': ref_meg = ('comps' in info and info['comps'] is not None and len(info['comps']) > 0 and meg is not False) for param in (eeg, stim, eog, ecg, emg, misc, resp, chpi, exci, ias, syst, seeg, dipole, gof, bio, ecog): if not isinstance(param, bool): w = ('Parameters for all channel types (with the exception ' 'of "meg", "ref_meg" and "fnirs") must be of type bool, ' 'not {0}.') raise ValueError(w.format(type(param))) param_dict = dict(eeg=eeg, stim=stim, eog=eog, ecg=ecg, emg=emg, misc=misc, resp=resp, chpi=chpi, exci=exci, ias=ias, syst=syst, seeg=seeg, dipole=dipole, gof=gof, bio=bio, ecog=ecog) # avoid triage if possible if isinstance(meg, bool): for key in ('grad', 'mag'): param_dict[key] = meg if isinstance(fnirs, bool): for key in ('hbo', 'hbr'): param_dict[key] = fnirs for k in range(nchan): ch_type = channel_type(info, k) try: pick[k] = param_dict[ch_type] except KeyError: # not so simple assert ch_type in ('grad', 'mag', 'hbo', 'hbr', 'ref_meg') if ch_type in ('grad', 'mag'): pick[k] = _triage_meg_pick(info['chs'][k], meg) elif ch_type == 'ref_meg': pick[k] = _triage_meg_pick(info['chs'][k], ref_meg) else: # ch_type in ('hbo', 'hbr') pick[k] = _triage_fnirs_pick(info['chs'][k], fnirs) # restrict channels to selection if provided if selection is not None: # the selection only restricts these types of channels sel_kind = [FIFF.FIFFV_MEG_CH, FIFF.FIFFV_REF_MEG_CH, FIFF.FIFFV_EEG_CH] for k in np.where(pick)[0]: if (info['chs'][k]['kind'] in sel_kind and info['ch_names'][k] not in selection): pick[k] = False myinclude = [info['ch_names'][k] for k in range(nchan) if pick[k]] myinclude += include if len(myinclude) == 0: sel = np.array([], int) else: sel = pick_channels(info['ch_names'], myinclude, exclude) return sel @verbose def pick_info(info, sel=(), copy=True, verbose=None): """Restrict an info structure to a selection of channels. Parameters ---------- info : dict Info structure from evoked or raw data. sel : list of int | None Indices of channels to include. If None, all channels are included. copy : bool If copy is False, info is modified inplace. %(verbose)s Returns ------- res : dict Info structure restricted to a selection of channels. """ # avoid circular imports from .meas_info import _bad_chans_comp info._check_consistency() info = info.copy() if copy else info if sel is None: return info elif len(sel) == 0: raise ValueError('No channels match the selection.') n_unique = len(np.unique(np.arange(len(info['ch_names']))[sel])) if n_unique != len(sel): raise ValueError('Found %d / %d unique names, sel is not unique' % (n_unique, len(sel))) # make sure required the compensation channels are present if len(info.get('comps', [])) > 0: ch_names = [info['ch_names'][idx] for idx in sel] _, comps_missing = _bad_chans_comp(info, ch_names) if len(comps_missing) > 0: logger.info('Removing %d compensators from info because ' 'not all compensation channels were picked.' % (len(info['comps']),)) info['comps'] = [] info['chs'] = [info['chs'][k] for k in sel] info._update_redundant() info['bads'] = [ch for ch in info['bads'] if ch in info['ch_names']] if 'comps' in info: comps = deepcopy(info['comps']) for c in comps: row_idx = [k for k, n in enumerate(c['data']['row_names']) if n in info['ch_names']] row_names = [c['data']['row_names'][i] for i in row_idx] rowcals = c['rowcals'][row_idx] c['rowcals'] = rowcals c['data']['nrow'] = len(row_names) c['data']['row_names'] = row_names c['data']['data'] = c['data']['data'][row_idx] info['comps'] = comps info._check_consistency() return info def _has_kit_refs(info, picks): """Determine if KIT ref channels are chosen. This is currently only used by make_forward_solution, which cannot run when KIT reference channels are included. """ for p in picks: if info['chs'][p]['coil_type'] == FIFF.FIFFV_COIL_KIT_REF_MAG: return True return False def pick_channels_evoked(orig, include=[], exclude='bads'): """Pick channels from evoked data. Parameters ---------- orig : Evoked object One evoked dataset. include : list of string, (optional) List of channels to include (if empty, include all available). exclude : list of string | str List of channels to exclude. If empty do not exclude any (default). If 'bads', exclude channels in orig.info['bads']. Defaults to 'bads'. Returns ------- res : instance of Evoked Evoked data restricted to selected channels. If include and exclude are empty it returns orig without copy. """ if len(include) == 0 and len(exclude) == 0: return orig exclude = _check_excludes_includes(exclude, info=orig.info, allow_bads=True) sel = pick_channels(orig.info['ch_names'], include=include, exclude=exclude) if len(sel) == 0: raise ValueError('Warning : No channels match the selection.') res = deepcopy(orig) # # Modify the measurement info # res.info = pick_info(res.info, sel) # # Create the reduced data set # res.data = res.data[sel, :] return res @verbose def pick_channels_forward(orig, include=[], exclude=[], ordered=False, copy=True, verbose=None): """Pick channels from forward operator. Parameters ---------- orig : dict A forward solution. include : list of string List of channels to include (if empty, include all available). Defaults to []. exclude : list of string | 'bads' Channels to exclude (if empty, do not exclude any). Defaults to []. If 'bads', then exclude bad channels in orig. ordered : bool If true (default False), treat ``include`` as an ordered list rather than a set. .. versionadded:: 0.18 copy : bool If True (default), make a copy. .. versionadded:: 0.19 %(verbose)s Returns ------- res : dict Forward solution restricted to selected channels. If include and exclude are empty it returns orig without copy. """ orig['info']._check_consistency() if len(include) == 0 and len(exclude) == 0: return orig.copy() if copy else orig exclude = _check_excludes_includes(exclude, info=orig['info'], allow_bads=True) # Allow for possibility of channel ordering in forward solution being # different from that of the M/EEG file it is based on. sel_sol = pick_channels(orig['sol']['row_names'], include=include, exclude=exclude, ordered=ordered) sel_info = pick_channels(orig['info']['ch_names'], include=include, exclude=exclude, ordered=ordered) fwd = deepcopy(orig) if copy else orig # Check that forward solution and original data file agree on #channels if len(sel_sol) != len(sel_info): raise ValueError('Forward solution and functional data appear to ' 'have different channel names, please check.') # Do we have something? nuse = len(sel_sol) if nuse == 0: raise ValueError('Nothing remains after picking') logger.info(' %d out of %d channels remain after picking' % (nuse, fwd['nchan'])) # Pick the correct rows of the forward operator using sel_sol fwd['sol']['data'] = fwd['sol']['data'][sel_sol, :] fwd['_orig_sol'] = fwd['_orig_sol'][sel_sol, :] fwd['sol']['nrow'] = nuse ch_names = [fwd['sol']['row_names'][k] for k in sel_sol] fwd['nchan'] = nuse fwd['sol']['row_names'] = ch_names # Pick the appropriate channel names from the info-dict using sel_info fwd['info']['chs'] = [fwd['info']['chs'][k] for k in sel_info] fwd['info']._update_redundant() fwd['info']['bads'] = [b for b in fwd['info']['bads'] if b in ch_names] if fwd['sol_grad'] is not None: fwd['sol_grad']['data'] = fwd['sol_grad']['data'][sel_sol, :] fwd['_orig_sol_grad'] = fwd['_orig_sol_grad'][sel_sol, :] fwd['sol_grad']['nrow'] = nuse fwd['sol_grad']['row_names'] = [fwd['sol_grad']['row_names'][k] for k in sel_sol] return fwd def pick_types_forward(orig, meg=True, eeg=False, ref_meg=True, seeg=False, ecog=False, include=[], exclude=[]): """Pick by channel type and names from a forward operator. Parameters ---------- orig : dict A forward solution meg : bool or string If True include all MEG channels. If False include None If string it can be 'mag' or 'grad' to select only gradiometers or magnetometers. eeg : bool If True include EEG channels ref_meg : bool If True include CTF / 4D reference channels seeg : bool If True include stereotactic EEG channels ecog : bool If True include electrocorticography channels include : list of string List of additional channels to include. If empty do not include any. exclude : list of string | str List of channels to exclude. If empty do not exclude any (default). If 'bads', exclude channels in orig['info']['bads']. Returns ------- res : dict Forward solution restricted to selected channel types. """ info = orig['info'] sel = pick_types(info, meg, eeg, ref_meg=ref_meg, seeg=seeg, ecog=ecog, include=include, exclude=exclude) if len(sel) == 0: raise ValueError('No valid channels found') include_ch_names = [info['ch_names'][k] for k in sel] return pick_channels_forward(orig, include_ch_names) @fill_doc def channel_indices_by_type(info, picks=None): """Get indices of channels by type. Parameters ---------- info : instance of Info A measurement info object. %(picks_all)s Returns ------- idx_by_type : dict A dictionary that maps each channel type to a (possibly empty) list of channel indices. """ idx_by_type = {key: list() for key in _PICK_TYPES_KEYS if key not in ('meg', 'fnirs')} idx_by_type.update(mag=list(), grad=list(), hbo=list(), hbr=list()) picks = _picks_to_idx(info, picks, none='all', exclude=(), allow_empty=True) for k in picks: ch_type = channel_type(info, k) for key in idx_by_type.keys(): if ch_type == key: idx_by_type[key].append(k) return idx_by_type def pick_channels_cov(orig, include=[], exclude='bads'): """Pick channels from covariance matrix. Parameters ---------- orig : Covariance A covariance. include : list of string, (optional) List of channels to include (if empty, include all available). exclude : list of string, (optional) | 'bads' Channels to exclude (if empty, do not exclude any). Defaults to 'bads'. Returns ------- res : dict Covariance solution restricted to selected channels. """ from ..cov import Covariance exclude = orig['bads'] if exclude == 'bads' else exclude sel = pick_channels(orig['names'], include=include, exclude=exclude) data = orig['data'][sel][:, sel] if not orig['diag'] else orig['data'][sel] names = [orig['names'][k] for k in sel] bads = [name for name in orig['bads'] if name in orig['names']] res = Covariance( data=data, names=names, bads=bads, projs=deepcopy(orig['projs']), nfree=orig['nfree'], eig=None, eigvec=None, method=orig.get('method', None), loglik=orig.get('loglik', None)) return res def _mag_grad_dependent(info): """Determine of mag and grad should be dealt with jointly.""" # right now just uses SSS, could be computed / checked from cov # but probably overkill return any(ph.get('max_info', {}).get('sss_info', {}).get('in_order', 0) for ph in info.get('proc_history', [])) def _contains_ch_type(info, ch_type): """Check whether a certain channel type is in an info object. Parameters ---------- info : instance of Info The measurement information. ch_type : str the channel type to be checked for Returns ------- has_ch_type : bool Whether the channel type is present or not. """ _validate_type(ch_type, 'str', "ch_type") meg_extras = ['mag', 'grad', 'planar1', 'planar2'] fnirs_extras = ['hbo', 'hbr'] valid_channel_types = sorted([key for key in _PICK_TYPES_KEYS if key != 'meg'] + meg_extras + fnirs_extras) _check_option('ch_type', ch_type, valid_channel_types) if info is None: raise ValueError('Cannot check for channels of type "%s" because info ' 'is None' % (ch_type,)) return any(ch_type == channel_type(info, ii) for ii in range(info['nchan'])) def _picks_by_type(info, meg_combined=False, ref_meg=False, exclude='bads'): """Get data channel indices as separate list of tuples. Parameters ---------- info : instance of mne.measuerment_info.Info The info. meg_combined : bool | 'auto' Whether to return combined picks for grad and mag. Can be 'auto' to choose based on Maxwell filtering status. ref_meg : bool If True include CTF / 4D reference channels exclude : list of string | str List of channels to exclude. If 'bads' (default), exclude channels in info['bads']. Returns ------- picks_list : list of tuples The list of tuples of picks and the type string. """ _validate_type(ref_meg, bool, 'ref_meg') exclude = _check_info_exclude(info, exclude) if meg_combined == 'auto': meg_combined = _mag_grad_dependent(info) picks_list = [] picks_list = {ch_type: list() for ch_type in _DATA_CH_TYPES_SPLIT} for k in range(info['nchan']): if info['chs'][k]['ch_name'] not in exclude: this_type = channel_type(info, k) try: picks_list[this_type].append(k) except KeyError: # This annoyance is due to differences in pick_types # and channel_type behavior if this_type == 'ref_meg': ch = info['chs'][k] if _triage_meg_pick(ch, ref_meg): if ch['unit'] == FIFF.FIFF_UNIT_T: picks_list['mag'].append(k) elif ch['unit'] == FIFF.FIFF_UNIT_T_M: picks_list['grad'].append(k) else: pass # not a data channel type picks_list = [(ch_type, np.array(picks_list[ch_type], int)) for ch_type in _DATA_CH_TYPES_SPLIT] assert _DATA_CH_TYPES_SPLIT[:2] == ('mag', 'grad') if meg_combined and len(picks_list[0][1]) and len(picks_list[1][1]): picks_list.insert( 0, ('meg', np.unique(np.concatenate([picks_list.pop(0)[1], picks_list.pop(0)[1]]))) ) picks_list = [p for p in picks_list if len(p[1])] return picks_list def _check_excludes_includes(chs, info=None, allow_bads=False): """Ensure that inputs to exclude/include are list-like or "bads". Parameters ---------- chs : any input, should be list, tuple, set, string The channels passed to include or exclude. allow_bads : bool Allow the user to supply "bads" as a string for auto exclusion. Returns ------- chs : list Channels to be excluded/excluded. If allow_bads, and chs=="bads", this will be the bad channels found in 'info'. """ from .meas_info import Info if not isinstance(chs, (list, tuple, set, np.ndarray)): if allow_bads is True: if not isinstance(info, Info): raise ValueError('Supply an info object if allow_bads is true') elif chs != 'bads': raise ValueError('If chs is a string, it must be "bads"') else: chs = info['bads'] else: raise ValueError( 'include/exclude must be list, tuple, ndarray, or "bads". ' + 'You provided type {}'.format(type(chs))) return chs _PICK_TYPES_DATA_DICT = dict( meg=True, eeg=True, stim=False, eog=False, ecg=False, emg=False, misc=False, resp=False, chpi=False, exci=False, ias=False, syst=False, seeg=True, dipole=False, gof=False, bio=False, ecog=True, fnirs=True) _PICK_TYPES_KEYS = tuple(list(_PICK_TYPES_DATA_DICT.keys()) + ['ref_meg']) _DATA_CH_TYPES_SPLIT = ('mag', 'grad', 'eeg', 'seeg', 'ecog', 'hbo', 'hbr') _DATA_CH_TYPES_ORDER_DEFAULT = ('mag', 'grad', 'eeg', 'eog', 'ecg', 'emg', 'ref_meg', 'misc', 'stim', 'resp', 'chpi', 'exci', 'ias', 'syst', 'seeg', 'bio', 'ecog', 'hbo', 'hbr', 'whitened') # Valid data types, ordered for consistency, used in viz/evoked. _VALID_CHANNEL_TYPES = ('eeg', 'grad', 'mag', 'seeg', 'eog', 'ecg', 'emg', 'dipole', 'gof', 'bio', 'ecog', 'hbo', 'hbr', 'misc') _MEG_CH_TYPES_SPLIT = ('mag', 'grad', 'planar1', 'planar2') _FNIRS_CH_TYPES_SPLIT = ('hbo', 'hbr') def _pick_data_channels(info, exclude='bads', with_ref_meg=True): """Pick only data channels.""" return pick_types(info, ref_meg=with_ref_meg, exclude=exclude, **_PICK_TYPES_DATA_DICT) def _pick_aux_channels(info, exclude='bads'): """Pick only auxiliary channels. Corresponds to EOG, ECG, EMG and BIO """ return pick_types(info, meg=False, eog=True, ecg=True, emg=True, bio=True, ref_meg=False, exclude=exclude) def _pick_data_or_ica(info, exclude=()): """Pick only data or ICA channels.""" if any(ch_name.startswith('ICA') for ch_name in info['ch_names']): picks = pick_types(info, exclude=exclude, misc=True) else: picks = _pick_data_channels(info, exclude=exclude, with_ref_meg=True) return picks def _picks_to_idx(info, picks, none='data', exclude='bads', allow_empty=False, with_ref_meg=True, return_kind=False): """Convert and check pick validity.""" from .meas_info import Info picked_ch_type_or_generic = False # # None -> all, data, or data_or_ica (ndarray of int) # orig_picks = picks orig_repr = repr(orig_picks) if isinstance(info, Info): n_chan = info['nchan'] else: info = _ensure_int(info, 'info', 'an int or Info') n_chan = info assert n_chan >= 0 if picks is None: if isinstance(info, int): # special wrapper for no real info picks = np.arange(n_chan) orig_repr += ', treated as range(%d)' % (n_chan,) else: picks = none # let _picks_str_to_idx handle it orig_repr += ', treated as "%s"' % (none,) # # slice # if isinstance(picks, slice): picks = np.arange(n_chan)[picks] # # -> ndarray of int (and make a copy) # picks = np.atleast_1d(picks) # this works even for picks == 'something' picks = np.array([], dtype=int) if len(picks) == 0 else picks if picks.ndim != 1: raise ValueError('picks must be 1D, got %sD' % (picks.ndim,)) if picks.dtype.char in ('S', 'U'): picks = _picks_str_to_idx(info, picks, exclude, with_ref_meg, return_kind, orig_repr, allow_empty) if return_kind: picked_ch_type_or_generic = picks[1] picks = picks[0] if picks.dtype.kind not in ['i', 'u']: raise TypeError('picks must be a list of int or list of str, got ' 'a data type of %s' % (picks.dtype,)) picks = picks.astype(int) # # ensure we have (optionally non-empty) ndarray of valid int # if len(picks) == 0 and not allow_empty: raise ValueError('No appropriate channels found for the given picks ' '(%r)' % (orig_picks,)) if (picks < -n_chan).any(): raise ValueError('All picks must be >= %d, got %r' % (-n_chan, orig_picks)) if (picks >= n_chan).any(): raise ValueError('All picks must be < n_channels (%d), got %r' % (n_chan, orig_picks)) picks %= n_chan # ensure positive if return_kind: return picks, picked_ch_type_or_generic return picks def _picks_str_to_idx(info, picks, exclude, with_ref_meg, return_kind, orig_repr, allow_empty): """Turn a list of str into ndarray of int.""" # special case for _picks_to_idx w/no info: shouldn't really happen if isinstance(info, int): raise ValueError('picks as str can only be used when measurement ' 'info is available') # # first: check our special cases # picks_generic = list() if len(picks) == 1: if picks[0] in ('all', 'data', 'data_or_ica'): if picks[0] == 'all': use_exclude = info['bads'] if exclude == 'bads' else exclude picks_generic = pick_channels( info['ch_names'], info['ch_names'], exclude=use_exclude) elif picks[0] == 'data': picks_generic = _pick_data_channels(info, exclude=exclude, with_ref_meg=with_ref_meg) elif picks[0] == 'data_or_ica': picks_generic = _pick_data_or_ica(info, exclude=exclude) if len(picks_generic) == 0 and orig_repr.startswith('None, ') and \ not allow_empty: raise ValueError('picks (%s) yielded no channels, consider ' 'passing picks explicitly' % (orig_repr,)) # # second: match all to channel names # bad_name = None picks_name = list() for pick in picks: try: picks_name.append(info['ch_names'].index(pick)) except ValueError: bad_name = pick break # # third: match all to types # bad_type = None picks_type = list() kwargs = dict(meg=False) meg, fnirs = set(), set() for pick in picks: if pick in _PICK_TYPES_KEYS: kwargs[pick] = True elif pick in _MEG_CH_TYPES_SPLIT: meg |= {pick} elif pick in _FNIRS_CH_TYPES_SPLIT: fnirs |= {pick} else: bad_type = pick break else: # triage MEG and FNIRS, which are complicated due to non-bool entries extra_picks = set() if len(meg) > 0 and not kwargs.get('meg', False): # easiest just to iterate for use_meg in meg: extra_picks |= set(pick_types( info, meg=use_meg, ref_meg=False, exclude=exclude)) if len(fnirs) > 0 and not kwargs.get('fnirs', False): # if it has two entries, it's both, otherwise it's just one kwargs['fnirs'] = True if len(fnirs) == 2 else list(fnirs)[0] picks_type = pick_types(info, exclude=exclude, **kwargs) if len(extra_picks) > 0: picks_type = sorted(set(picks_type) | set(extra_picks)) # # finally: ensure we have exactly one usable list # all_picks = (picks_generic, picks_name, picks_type) any_found = [len(p) > 0 for p in all_picks] if sum(any_found) == 0: if not allow_empty: raise ValueError( 'picks (%s) could not be interpreted as ' 'channel names (no channel "%s"), channel types (no ' 'type "%s"), or a generic type (just "all" or "data")' % (orig_repr, bad_name, bad_type)) picks = np.array([], int) elif sum(any_found) > 1: raise RuntimeError('Some channel names are ambiguously equivalent to ' 'channel types, cannot use string-based ' 'picks for these') else: picks = np.array(all_picks[np.where(any_found)[0][0]]) if return_kind: picked_ch_type_or_generic = not len(picks_name) return picks, picked_ch_type_or_generic return picks def _pick_inst(inst, picks, exclude, copy=True): """Return an instance with picked and excluded channels.""" if copy is True: inst = inst.copy() picks = _picks_to_idx(inst.info, picks, exclude=[]) pick_names = [inst.info['ch_names'][pick] for pick in picks] inst.pick_channels(pick_names) if exclude == 'bads': exclude = [ch for ch in inst.info['bads'] if ch in inst.info['ch_names']] if exclude is not None: inst.drop_channels(exclude) return inst def _get_channel_types(info, picks=None, unique=True, restrict_data_types=False): """Get the data channel types in an info instance.""" picks = range(info['nchan']) if picks is None else picks ch_types = [channel_type(info, idx) for idx in range(info['nchan']) if idx in picks] if restrict_data_types is True: ch_types = [ch_type for ch_type in ch_types if ch_type in _DATA_CH_TYPES_SPLIT] return set(ch_types) if unique is True else ch_types