extract_channels#

brainsets.utils.mne_utils.extract_channels(recording_data, channel_names_mapping=None, type_channels_mapping=None, channel_pos_mapping=None, ignore_channels=None)[source]#

Extract channel metadata from an MNE Raw object, with support for custom channel name, type, and position mappings.

This function returns a channel-level ArrayDict containing (at minimum) the unique channel IDs (id) and types (type) for each channel in the provided MNE Raw object. Optionally, it can also include the 3D channel locations (pos) and “bad” channel labels, depending on mappings and recording metadata.

Channel name, type, and/or position dictionaries, if provided, can be used to override or map the values from the raw file using either original or renamed channel names (but not a mix).

Parameters:

  • recording_data – MNE Raw object containing the electrophysiological data and metadata.

  • channel_names_mapping – Optional dictionary mapping original channel names to new names (e.g., {“EEG01”: “Fp1”}). Ensures renaming is unique.

  • type_channels_mapping – Optional dictionary mapping types (e.g., “eeg”) to lists of channel names (e.g., {“eeg”: [“C3”, “C4”]}). See _validate_channel_types_mapping for remapping logic.

  • channel_pos_mapping – Optional dictionary mapping channel names to 3D position numpy arrays. Falls back to using montage positions if not provided.

  • ignore_channels – Optional list of channel names to ignore. If provided, the channels will be excluded from the extraction.

Returns:

  • id: np.ndarray of (new) channel identifiers.

  • type: np.ndarray of channel types (lowercased).

  • pos: (optional) np.ndarray of shape (n_channels, 3) giving 3D coordinates for each channel.

  • bad: (optional) np.ndarray[bool] mask for bad channels (from MNE info[‘bads’]).

Return type:

ArrayDict containing channel information with fields

Raises:

  • ImportError – If MNE is not installed.

  • TypeError – If input recording or mappings do not match expected types.

  • ValueError – If mapping keys mix original and renamed names, or have duplicate new channel names.

Examples

>>> from mne.io import read_raw_edf
>>> raw = read_raw_edf("example.edf", preload=True)
>>> metadata = extract_channels(raw)
>>> print(metadata.keys())
['id', 'type', 'pos', 'bad']

>>> # Remap channel names, types, and positions
>>> name_map = {"EEG F3-M2": "F3", "EEG F4-M1": "F4"}
>>> type_map = {"eeg": ["F3", "F4"]}
>>> pos_map = {"F3": np.array([0.0, 0.7, 0.0]), "F4": np.array([0.6, 0.7, 0.0])}
>>> metadata = extract_channels(raw, name_map, type_map, pos_map)
On this page