mkpy.io.mkh5mne module

import mkpy5 HDF5 data files to MNE Raw and Epochs, savable as .fif files

mkpy.io.mkh5mne.find_mkh5_events(mne_raw, channel_name)[source]

Replacement for mne.find_events for mkh5 integer event code channels

Finds single-sample positive and negative integer event codes and returns them without modification unlike mne.find_events() which switches the sign of negative event codes.

Parameters

  • mne_raw (Mkh5Raw or mne.io.Raw object) – data with the stim channel to search

  • channel_name (str) – name of the channel to search for non-zero codes

Returns

event_array – Three column MNE format where event_array[idx, :] = [sample, 0, code]

Return type

np.array

Raises

  • ValueError – If channel_name does not exist.

  • TypeError – If channel_name is not an MNE ‘stim’ type channel.

Example

>>> mne_raw = mkh5mne("sub01.h5")
>>> mne_events = mkh5mne.find_mkh5_events(mne_raw, "p3")
mkpy.io.mkh5mne.from_mkh5(mkh5_f, garv_annotations=None, dblock_paths=None, apparatus_yaml=None, fail_on_info=False, fail_on_montage=True, verbose='info')[source]

Read an mkh5 data file into MNE raw format

The mkh5 EEG data, events are converted to mne.BaseRaw for use with native MNE methods. The mkh5 timelock events and tags in the epochs tables are added to the raw data and mne.Info for use as MNE events and metadata with mne.Epochs.

Parameters

  • mkh5_f (str) – File path to a mkpy.mkh5 HDF5 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)

Returns

subclassed from mne.BaseRaw for use as native MNE.

Return type

Mkh5Raw

Raises

Exceptions – if data block paths or apparatus map information is misspecified or the info and montage test flags are set and fail.

Notes

EEG and events.

The mkh5 data block columns are converted to mne channels and concatenated into a single mne Raw in the order given by dblock_paths. The default is to convert the entire mkh5 file in mkh5.dblock_paths order.

Epochs.

The mkh5 epochs table time locking events are indexed to the mne.Raw data samples and the epoch tables stored as a JSON string in the description field of :py:class”mne.Info. The named mkh5 format epochs table is recovered by converting the JSON to a pandas.DataFrame which is well-formed mne.Epochs.metadata for the events on the epochs_name stim channel.

Examples

>>> mne_raw = mkh5mne("sub01.h5")

>>> mne_raw = mkh5mne.from_mkh5(
        "sub01.h5",
        garv_annotations=dict(
            event_channel="log_evcodes", tmin=-500, tmax=500, units="ms"
        )
   )

>>> mne_raw = mkh5mne(
        "sub01.h5",
        dblock_paths=["sub01/dblock_0", "sub01/dblock_1"]  # first two dblocks only
    )
mkpy.io.mkh5mne.get_epochs(mne_raw, epochs_name, metadata_columns='all', **kwargs)[source]

retrieve mkh5 epochs table dataframe from mne.Raw.info[“description”]

The mne.Epoch interval [tmin, tmax] matches the tmin_ms, tmax_ms interval mkh5.set_epochs(epochs_name, events, tmin_ms, tmax_ms).

Parameters

  • mne_raw (mne.Raw) – The raw must have been converted from a mkpy.mkh5 file that contains at least one named epochs table.

  • epochs_name (str) – Name of the epochs_table to get.

  • metadata_columns (“all” or list of str, optional) – Specify which metadata columns to include with the epochs, default is all.

  • **kwargs – kwargs passed to mne.Epochs()

Return type

mne.Epochs

mkpy.io.mkh5mne.get_epochs_metadata(mne_raw, epochs_name)[source]

retrieve mkh5 epochs table dataframe from mne.Raw.info[“description”]

Parameters

  • mne_raw (mne.Raw) – converted from a mkpy.mkh5 file that contains at least one named epochs table.

  • epochs_name (str) – name of the epochs_table

Returns

mne.Epochs.metadata format, one row per epoch corresponding to the time-locking event at time=0.

Return type

pandas.DataFrame

mkpy.io.mkh5mne.get_garv_bads(mne_raw, event_channel=None, tmin=None, tmax=None, units=None, garv_channel='log_flags')[source]

create mne BAD_garv annotations spanning events on a stim event channel

This time locks the annotation to non-zero events on event_channel that have a non-zero codes on the log_flags column, e.g., as given by as given by running avg -x -a subNN.arf to set log_flags in subNN.log.

The annotations may be attached to an mne.Raw for triggering artifact exclusion during epoching.

Parameters

  • mne_raw (mne.Raw) – mne.Raw data object converted from mkh5

  • event_channel (str) – name of the mne channel with events to annotate with BAD_garv

  • tmin, tmax (float) – interval to annotate, relative to time lock event, e.g., -500, 1000

  • unit ({“ms”, “s”}) – for the interval units as milliseconds or seconds

  • garv_channel (str, optional) – name of the channel to check for non-zero codes at time-lock events. The default=”log_flags” is where avg -x puts garv rejects, other routines may use other channels.

Returns

formatted as BAD_garv_N where N is the non-zero log_flag value

Return type

mne.Annotations

Examples

>>>  mkh5mn3.get_garv_bads(
         mne_raw,
         event_channel="p3_events",
         tmin=-500,
         tmax=1000,
         units="ms"
     )
mkpy.io.mkh5mne.read_raw_mkh5(mkh5_file, garv_annotations=None, dblock_paths=None, apparatus_yaml=None, fail_on_info=False, fail_on_montage=True, verbose='info')[source]

Read an mkh5 data file into MNE raw format

Deprecated since version 0.2.6: Use from_mkh5()