pycrostates.io.ChInfo#

class pycrostates.io.ChInfo(info=None, ch_names=None, ch_types=None)[source]#

Atemporal measurement information.

Similar to a mne.Info class, but without any temporal information. Only the channel-related information are present. A ChInfo can be created either:

by providing a Info class from which information are retrieved.
by providing the ch_names and the ch_types to create a new instance.

Only one of those 2 methods should be used at once.

Warning

The only entry that should be manually changed by the user is info['bads']. All other entries should be considered read-only, though they can be modified by various functions or methods (which have safeguards to ensure all fields remain in sync).

Parameters:

infoInfo | None: MNE measurement information instance from which channel-related variables are retrieved.
ch_nameslist of str | int | None: Channel names. If an int, a list of channel names will be created from range(ch_names).
ch_typeslist of str | str | None: Channel types. If str, all channels are assumed to be of the same type.

Attributes:

badslist of str: List of bad (noisy/broken) channels, by name. These channels will by default be ignored by many processing steps.
ch_namestuple of str: The names of the channels.
chstuple of dict: A list of channel information dictionaries, one per channel. See Notes for more information.
compslist of dict: CTF software gradient compensation data. See Notes for more information.
ctf_head_tdict | None: The transformation from 4D/CTF head coordinates to Neuromag head coordinates. This is only present in 4D/CTF data.
custom_ref_appliedint: Whether a custom (=other than average) reference has been applied to the EEG data. This flag is checked by some algorithms that require an average reference to be set.
dev_ctf_tdict | None: The transformation from device coordinates to 4D/CTF head coordinates. This is only present in 4D/CTF data.
dev_head_tdict | None: The device to head transformation.
digtuple of dict | None: The Polhemus digitization data in head coordinates. See Notes for more information.
nchanint: Number of channels.
projslist of Projection: List of SSP operators that operate on the data. See mne.Projection for details.

Methods

`anonymize`([daysback, keep_his, verbose])	Anonymize measurement information in place.
`clear`()
`copy`()	Copy the instance.
`from_json_dict`(data_dict)	Reconstruct Info object from a dictionary.
`fromkeys`(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`get_channel_types`([picks, unique, only_data_chs])	Get a list of channel type for each channel.
`get_montage`()	Get a DigMontage from instance.
`items`()
`keys`()
`normalize_proj`()	(Re-)Normalize projection vectors after subselection.
`plot_sensors`([kind, ch_type, title, ...])	Plot sensor positions.
`pop`(key[, default])	If the key is not found, return the default if given; otherwise, raise a KeyError.
`popitem`(/)	Remove and return a (key, value) pair as a 2-tuple.
`rename_channels`(mapping[, allow_duplicates, ...])	Rename channels.
`save`(fname, *[, overwrite, verbose])	Write measurement info in fif file.
`set_channel_types`(mapping, *[, ...])	Specify the sensor types of channels.
`set_meas_date`(meas_date)	Set the measurement start date.
`set_montage`(montage[, match_case, ...])	Set EEG/sEEG/ECoG/DBS/fNIRS channel positions and digitization points.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`to_json_dict`()	Convert Info to a JSON-serializable dictionary.
`update`([other])	Update method using __setitem__().
`values`()

Notes

The following parameters have a nested structure.

chs list of dict:

calfloat
The calibration factor to bring the channels to physical units. Used in product with range to scale the data read from disk.

ch_namestr
The channel name.

coil_typeint
Coil type, e.g. FIFFV_COIL_MEG.

coord_frameint
The coordinate frame used, e.g. FIFFV_COORD_HEAD.

kindint
The kind of channel, e.g. FIFFV_EEG_CH.

locarray, shape (12,)
Channel location. For MEG this is the position plus the normal given by a 3x3 rotation matrix. For EEG this is the position followed by reference position (with 6 unused). The values are specified in device coordinates for MEG and in head coordinates for EEG channels, respectively.

lognoint
Logical channel number, conventions in the usage of this number vary.

rangefloat
The hardware-oriented part of the calibration factor. This should be only applied to the continuous raw data. Used in product with cal to scale data read from disk.

scannoint
Scanning order number, starting from 1.

unitint
The unit to use, e.g. FIFF_UNIT_T_M.

unit_mulint
Unit multipliers, most commonly FIFF_UNITM_NONE.
comps list of dict:

ctfkindint
CTF compensation grade.

colcalsndarray
Column calibrations.

matdict
A named matrix dictionary (with entries “data”, “col_names”, etc.) containing the compensation matrix.

rowcalsndarray
Row calibrations.

save_calibratedbool
Were the compensation data saved in calibrated form.
dig list of dict:

kindint
The kind of channel, e.g. FIFFV_POINT_EEG, FIFFV_POINT_CARDINAL.

rarray, shape (3,)
3D position in m. and coord_frame.

identint
Number specifying the identity of the point. e.g. FIFFV_POINT_NASION if kind is FIFFV_POINT_CARDINAL, or 42 if kind is FIFFV_POINT_EEG.

coord_frameint
The coordinate frame used, e.g. FIFFV_COORD_HEAD.

__contains__(key, /)#: True if the dictionary has the specified key, else False.

__getitem__()#: x.__getitem__(y) <==> x[y]

__iter__(/)#: Implement iter(self).

__len__(/)#: Return len(self).

anonymize(daysback=None, keep_his=False, verbose=None)#

Anonymize measurement information in place.

Parameters:

daysbackint | None: Number of days to subtract from all dates. If None (default), the acquisition date, info['meas_date'], will be set to January 1ˢᵗ, 2000. This parameter is ignored if info['meas_date'] is None (i.e., no acquisition date has been set).
keep_hisbool: If True, his_id of subject_info will not be overwritten. Defaults to False.

Warning

This could mean that info is not fully anonymized. Use with caution.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

instinstance of Raw | Epochs | Evoked: The modified instance.

Notes

Removes potentially identifying information if it exists in info. Specifically for each of the following we use:

meas_date, file_id, meas_id
A default value, or as specified by daysback.
subject_info
Default values, except for ‘birthday’ which is adjusted to maintain the subject age.
experimenter, proj_name, description
Default strings.
utc_offset
None.
proj_id
Zeros.
proc_history
Dates use the meas_date logic, and experimenter a default string.
helium_info, device_info
Dates use the meas_date logic, meta info uses defaults.

If info['meas_date'] is None, it will remain None during processing the above fields.

Operates in place.

Added in version 0.13.0.

clear() → None. Remove all items from D.#

copy()#

Copy the instance.

Returns:

infoinstance of Info: The copied info.

classmethod from_json_dict(data_dict)#

Reconstruct Info object from a dictionary.

Parameters:

data_dictdict: A dictionary representation of an Info object, typically created by the to_json_dict() method.

Returns:

Info: The reconstructed Info object.

See also

to_json_dict: Convert Info to dictionary.

Examples

>>> info = mne.create_info(['MEG1', 'MEG2'], 1000., ['mag', 'mag'])
>>> info_dict = info.to_json_dict()
>>> info_restored = mne.Info.from_json_dict(info_dict)

fromkeys(iterable, value=None, /)#: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)#: Return the value for key if key is in the dictionary, else default.

get_channel_types(picks=None, unique=False, only_data_chs=False)#

Get a list of channel type for each channel.

Parameters:

picksstr | array_like | slice | None: Channels to include. Slices and lists of integers will be interpreted as channel indices. In lists, channel type strings (e.g., ['meg', 'eeg']) will pick channels of those types, channel name strings (e.g., ['MEG0111', 'MEG2623'] will pick the given channels. Can also be the string values 'all' to pick all channels, or 'data' to pick data channels. None (default) will pick all channels. Note that channels in info['bads'] will be included if their names or indices are explicitly provided.
uniquebool: Whether to return only unique channel types. Default is False.
only_data_chsbool: Whether to ignore non-data channels. Default is False.

Returns:

channel_typeslist: The channel types.

get_montage()#

Get a DigMontage from instance.

Returns:

montageNone | DigMontage: A copy of the channel positions, if available, otherwise None.

items() → a set-like object providing a view on D's items#

keys() → a set-like object providing a view on D's keys#

normalize_proj()#

(Re-)Normalize projection vectors after subselection.

Applying projection after sub-selecting a set of channels that were originally used to compute the original projection vectors can be dangerous (e.g., if few channels remain, most power was in channels that are no longer picked, etc.). By default, mne will emit a warning when this is done.

This function will re-normalize projectors to use only the remaining channels, thus avoiding that warning. Only use this function if you’re confident that the projection vectors still adequately capture the original signal of interest.

plot_sensors(kind='topomap', ch_type=None, title=None, show_names=False, ch_groups=None, to_sphere=True, axes=None, block=False, show=True, sphere=None, *, verbose=None)#

Plot sensor positions.

Parameters:

kindstr

Whether to plot the sensors as 3d, topomap or as an interactive sensor selection dialog. Available options ‘topomap’, ‘3d’, ‘select’. If ‘select’, a set of channels can be selected interactively by using lasso selector or clicking while holding control key. The selected channels are returned along with the figure instance. Defaults to ‘topomap’.

ch_typeNone | str

The channel type to plot. Available options 'mag', 'grad', 'eeg', 'seeg', 'dbs', 'ecog', 'all'. If 'all', all the available mag, grad, eeg, seeg, dbs, and ecog channels are plotted. If None (default), then channels are chosen in the order given above.

titlestr | None

Title for the figure. If None (default), equals to 'Sensor positions (%s)' % ch_type.

show_namesbool | array of str

Whether to display all channel names. If an array, only the channel names in the array are shown. Defaults to False.

ch_groups‘position’ | array of shape (n_ch_groups, n_picks) | None

Channel groups for coloring the sensors. If None (default), default coloring scheme is used. If ‘position’, the sensors are divided into 8 regions. See order kwarg of mne.viz.plot_raw(). If array, the channels are divided by picks given in the array.

Added in version 0.13.0.

to_spherebool

Whether to project the 3d locations to a sphere. When False, the sensor array appears similar as to looking downwards straight above the subject’s head. Has no effect when kind=’3d’. Defaults to True.

Added in version 0.14.0.

axesinstance of Axes | instance of Axes3D | None

Axes to draw the sensors to. If kind='3d', axes must be an instance of Axes3D. If None (default), a new axes will be created.

Added in version 0.13.0.

blockbool

Whether to halt program execution until the figure is closed. Defaults to False.

Added in version 0.13.0.

showbool

Show figure if True. Defaults to True.

The sphere parameters to use for the head outline. Can be array-like of shape (4,) to give the X/Y/Z origin and radius in meters, or a single float to give just the radius (origin assumed 0, 0, 0). Can also be an instance of a spherical ConductorModel to use the origin and radius from that object. Can also be a str, in which case:

'auto': the sphere is fit to external digitization points first, and to external + EEG digitization points if the former fails.
'eeglab': the head circle is defined by EEG electrodes 'Fpz', 'Oz', 'T7', and 'T8' (if 'Fpz' is not present, it will be approximated from the coordinates of 'Oz').
- 'extra': the sphere is fit to external digitization points.
- 'eeg': the sphere is fit to EEG digitization points.
- 'cardinal': the sphere is fit to cardinal digitization points.
- 'hpi': the sphere is fit to HPI coil digitization points.

Can also be a list of str, in which case the sphere is fit to the specified digitization points, which can be any combination of 'extra', 'eeg', 'cardinal', and 'hpi', as specified above. None (the default) is equivalent to 'auto' when enough extra digitization points are available, and (0, 0, 0, 0.095) otherwise.

Added in version 0.20.

Changed in version 1.1: Added 'eeglab' option.

Changed in version 1.11: Added 'extra', 'eeg', 'cardinal', 'hpi' and list of str options.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

figinstance of Figure: Figure containing the sensor topography.
selectionlist: A list of selected channels. Only returned if kind=='select'.

See also

mne.viz.plot_layout

Notes

This function plots the sensor locations from the info structure using matplotlib. For drawing the sensors using PyVista see mne.viz.plot_alignment().

Added in version 0.12.0.

pop(key, default=<unrepresentable>, /)#: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem(/)#

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

rename_channels(mapping, allow_duplicates=False, *, on_missing='raise', verbose=None)#

Rename channels.

Parameters:

mappingdict | callable(): A dictionary mapping the old channel to a new channel name e.g. {'EEG061' : 'EEG161'}. Can also be a callable function that takes and returns a string.

Changed in version 0.10.0: Support for a callable function.
allow_duplicatesbool: If True (default False), allow duplicates, which will automatically be renamed with -N at the end.

Added in version 0.22.0.
on_missing‘raise’ | ‘warn’ | ‘ignore’: Can be 'raise' (default) to raise an error, 'warn' to emit a warning, or 'ignore' to ignore when entries in ch_names are not present in the raw instance.

Added in version 0.23.0.

Added in version 1.11.0.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

instinstance of Raw | Epochs | Evoked: The instance (modified in place).

Changed in version 0.20: Return the instance.

Notes

Added in version 0.9.0.

save(fname, *, overwrite=False, verbose=None)#

Write measurement info in fif file.

Parameters:

fnamepath-like: The name of the file. Should end by '-info.fif'.
overwritebool: If True (default False), overwrite the destination file if it exists.

Added in version 1.10.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

See also

mne.io.write_info

set_channel_types(mapping, *, on_unit_change='warn', verbose=None)#

Specify the sensor types of channels.

Parameters:

mappingdict: A dictionary mapping channel names to sensor types, e.g., {'EEG061': 'eog'}.
on_unit_change'raise' | 'warn' | 'ignore': What to do if the measurement unit of a channel is changed automatically to match the new sensor type.

Added in version 1.4.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

instinstance of Raw | Epochs | Evoked: The instance (modified in place).

Changed in version 0.20: Return the instance.

Notes

The following sensor types are accepted:

bio, chpi, csd, dbs, dipole, ecg, ecog, eeg, emg, eog, exci, eyegaze, fnirs_cw_amplitude, fnirs_fd_ac_amplitude, fnirs_fd_phase, fnirs_od, gof, gsr, hbo, hbr, ias, misc, pupil, ref_meg, resp, seeg, stim, syst, temperature.

When working with eye-tracking data, see mne.preprocessing.eyetracking.set_channel_types_eyetrack().

Added in version 0.9.0.

set_meas_date(meas_date)#

Set the measurement start date.

Parameters:

meas_datedatetime | float | tuple | None: The new measurement date. If datetime object, it must be timezone-aware and in UTC. A tuple of (seconds, microseconds) or float (alias for (meas_date, 0)) can also be passed and a datetime object will be automatically created. If None, will remove the time reference.

Returns:

instinstance of Raw | Epochs | Evoked: The modified raw instance. Operates in place.

See also

mne.io.Raw.anonymize

Notes

If you want to remove all time references in the file, call mne.io.anonymize_info(inst.info) after calling inst.set_meas_date(None).

Added in version 0.20.

set_montage(montage, match_case=True, match_alias=False, on_missing='raise', verbose=None)#

Set EEG/sEEG/ECoG/DBS/fNIRS channel positions and digitization points.

Parameters:

montageNone | str | DigMontage: A montage containing channel positions. If a string or DigMontage is specified, the existing channel information will be updated with the channel positions from the montage. Valid strings are the names of the built-in montages that ship with MNE-Python; you can list those via mne.channels.get_builtin_montages(). If None (default), the channel positions will be removed from the Info.
match_casebool: If True (default), channel name matching will be case sensitive.

Added in version 0.20.
match_aliasbool | dict: Whether to use a lookup table to match unrecognized channel location names to their known aliases. If True, uses the mapping in mne.io.constants.CHANNEL_LOC_ALIASES. If a dict is passed, it will be used instead, and should map from non-standard channel names to names in the specified montage. Default is False.

Added in version 0.23.
on_missing‘raise’ | ‘warn’ | ‘ignore’: Can be 'raise' (default) to raise an error, 'warn' to emit a warning, or 'ignore' to ignore when channels have missing coordinates.

Added in version 0.20.1.
verbosebool | str | int | None: Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:

instinstance of Raw | Epochs | Evoked: The instance, modified in-place.

See also

mne.channels.make_standard_montage
mne.channels.make_dig_montage
mne.channels.read_custom_montage

Notes

Warning

Only EEG/sEEG/ECoG/DBS/fNIRS channels can have their positions set using a montage. Other channel types (e.g., MEG channels) should have their positions defined properly using their data reading functions.

Warning

Applying a montage will only set locations of channels that exist at the time it is applied. This means when re-referencing make sure to apply the montage only after calling mne.add_reference_channels()

setdefault(key, default=None, /)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

to_json_dict()#

Convert Info to a JSON-serializable dictionary.

This method converts the Info object to a standard Python dictionary containing only JSON-serializable types (dict, list, str, int, float, bool, None). Numpy arrays are converted to nested lists, and datetime objects to ISO format strings.

Returns:

dict: A JSON-serializable dictionary representation of the Info object.

See also

from_json_dict: Reconstruct Info object from dictionary.

Notes

This method is useful for serializing Info objects to JSON or other formats that don’t support numpy arrays or custom objects.

Examples

>>> info = mne.create_info(['MEG1', 'MEG2'], 1000., ['mag', 'mag'])
>>> info_dict = info.to_json_dict()
>>> import json
>>> json_str = json.dumps(info_dict)  # Save to JSON

update(other=None, **kwargs)#: Update method using __setitem__().

values() → an object providing a view on D's values#

__hash__ = None#

property compensation_grade#: The current gradient compensation grade.