mkpy.io.mkh5eeglab module

mkpy.io.mkh5eeglab.mkh5_to_set(mkh5_f, set_f, epochs_name=None, garv_annotations=None, dblock_paths=None, apparatus_yaml=None, fail_on_info=False, fail_on_montage=True, verbose='info')[source]

Convert an mkh5 data file into MNE raw format

The mkh5 EEG data event channels in EEG.data.

The channel info is in EEG.chanlocs and the mkh5 Right Anterior Superior (RAS) coordinates are converted to EEGLAB defaults automatically.

The EEG.events and EEG.urevents fields contain:

  • type field values: * log event codes (string representation) * “boundary” for datablock boundaries and garv annotations * mkh5 dblock path labels

  • latency values: * 1-base data sample index of the event in the EEG.data array

  • duration values: * log events ar duration 0 * dblock boundary events are duration 0 * garv annotation boundary events are garv_annotation tmax - tmin in samples

Additional event fields are description and codemap tags from the epochs table, if any.

Parameters

  • mkh5_f (str) – File path to a mkpy.mkh5 HDF5 file

  • set_f (str) – File path to the EEGLAB .set file.

  • epochs_name (str) – Name of a previously set epochs table in the mkh5 file.

  • garv_annotations (None | dict, optional) – event_channel: (str) # channel name with events to annotate tmin, tmax: (float) # relative to time lock event units: “ms” or “s”. Defaults to None.

  • dblock_paths (None | list of mkh5 datablock paths, optional) – The listed datablock paths will be concatenated in order into the mne.Raw. Defaults to None, in which case all the data blocks in mkh5 file are concatenated in the order returned by mkh5.dblock_paths().

  • apparatus_yaml (None | str, optional) – If a path to a well-formed mkh5 apparatus map YAML file, it is used instead of the map in the mkh5 dblock header, if any. Defaults to None.

  • fail_on_info (bool, optional) – If True, this enforces strict mne.Info identity across the mkh5 data blocks being concatenated. If False (default), some deviations between mne.Info for the mkh5 data blocks are allowed, e.g., for pooling multiple subject files into an experiment or separate cals for a single subject. Defaults to False.

  • fail on montage (bool, optional) – If True, the mne.Montage created from the mkh5 header data streams and channel locations must be the same for all the data blocks. If False, mkh5mne allows the MNE montage to vary across mkh5 data blocks and leaves you to deal with whatever mne.concatenate_raws() does in this case. Defaults to True

  • verbose (NotImplemented)

Notes

This is a thin wrapper around the mkh5mne file format converter.

Examples

Minimal

>>>  mkh5eeglab.mkh5_to_set(("sub01.h5", "sub01.set")

>>> mkh5eeglab.to_set(
        "sub01.h5",
        "sub01.set",
        "apparatus_yaml"="ras_32_chan_xyz_spherical.yaml",
        epochs_name="p3",
        garv_annotations=dict(
            event_channel="p3", tmin=-500, tmax=1500, units="ms"
        )
    )
mkpy.io.mkh5eeglab.mkh5raw_to_set(mkh5raw, fname, epochs_name=None, return_eeglab_events=False)[source]

Export mkh5raw EEG, channel, and event data to an EEGLAB .set file.

Export an mkh5mne.Mkh5Raw instance in memory to an EEGLAB .set file. The log events are stored in EEG.events and EEG.urevents and any mne.Annotations including garv artifacts are stored there as boundary events. . If epochs_name is provided, the mkh5 codemap tags for those events are exported as well. Channel locations are converted to EEGLAB defaults.

Parameters

  • mkh5raw (mkh5mne.Mkh5Raw instance) – As returned by mkh5mne.from_mkh5(), see mkh5mne.from_mkhg() docs for usage.

  • fname (str) – Path to the EEGLAB set file to create.

  • epochs_name (str, optional) – Include event tags from the named mkh5 epochs table in EEGLAB .set events. Defaults to None.

  • return_eeglab_events (bool) – If true, also returns the event information injected into the EEGLAB .set file. Useful for diagnosis, validataion. Default is False.

Returns

eeglab_events_df – Dataframe with the event information exported in the .set

Return type

pandas.DataFrame

Examples

Minimal: Export EEG data, datablock boundaries, and log events

>>> from mkpy.io import mkh5mne, mkh5eeglab
>>>
>>> mne_raw = mkh5mne.from_mkh5("sub000.h5)
>>> mkh5eeglab.mkh5raw_to_set(mne_raw, "sub000.set")

Also export the codemap event tags from mkpy epochs table ‘p3’

>>> mne_raw = mkh5mne.from_mkh5("sub000.h5")
>>> mkh5eeglab.mkh5raw_to_set(mne_raw, "sub000.set", event_channel="p3")