From c5ba224d8b6677044f2244d0b6f6b342638b8792 Mon Sep 17 00:00:00 2001 From: smathot Date: Wed, 21 Dec 2022 15:04:22 +0100 Subject: [PATCH] Update readme --- readme-template.md | 38 +++++++++----------- readme.md | 89 +++++++++++++++++++++------------------------- 2 files changed, 58 insertions(+), 69 deletions(-) diff --git a/readme-template.md b/readme-template.md index efddd83..b61ede5 100644 --- a/readme-template.md +++ b/readme-template.md @@ -41,12 +41,13 @@ raw.plot() To avoid having to parse the data over and over again, `read_subject()` uses persistent [memoization](https://pydatamatrix.eu/memoization/), which is a way to store the return values of a function on disk and return them right away on subsequent calls. To clear the memoization cache, either call the `read_subject.clear()` function or remove the `.memoize` folder. - Plot the voltage across four occipital electrodes locked to cue onset for three seconds. This is done separately for three different conditions, defined by `cue_eccentricity`. The function `eet.autoreject_epochs()` behaves similarly to `mne.Epochs()`, except that autorejection is applied and that, like `read_subject()`, it uses persistent memoization. ```python +import numpy as np import mne from matplotlib import pyplot as plt +from datamatrix import convert as cnv CUE_TRIGGER = 1 CHANNELS = 'O1', 'O2', 'Oz', 'P3', 'P4' @@ -54,34 +55,31 @@ CHANNELS = 'O1', 'O2', 'Oz', 'P3', 'P4' cue_epoch = eet.autoreject_epochs(raw, eet.epoch_trigger(events, CUE_TRIGGER), tmin=-.1, tmax=3, metadata=metadata, picks=CHANNELS) -for ecc in ('near', 'medium', 'far'): - cue_evoked = cue_epoch[f'cue_eccentricity == "{ecc}"'].average() - plt.plot(cue_evoked.data.mean(axis=0), label=ecc) -plt.legend() -``` - -Plot pupil size during the same period. Because the regular `mne.Epoch()` object doesn't play nice with non-data channels, such as PupilSize, you need to use the `eet.PupilEpochs()` class instead (which is otherwise identical). - -```python -cue_epoch = eet.PupilEpochs(raw, eet.epoch_trigger(events, CUE_TRIGGER), tmin=0, - tmax=3, metadata=metadata, baseline=(0, .05)) -for ecc in ('near', 'medium', 'far'): - cue_evoked = cue_epoch[f'cue_eccentricity == "{ecc}"'].average() - plt.plot(cue_evoked.data.mean(axis=0)) -plt.legend() ``` -You can also convert the `PupilEpochs` object to a `SeriesColumn` and plot it that way, for example using `time_series_test.plot()`. +We can convert the metadata, which is a `DataFrame`, to a `DataMatrix`, and add `cue_epoch` as a multidimensional column ```python from datamatrix import convert as cnv import time_series_test as tst dm = cnv.from_pandas(metadata) -dm.pupil = eet.epochs_to_series(dm, cue_epoch, baseline_trim=(-2, 2)) +dm.erp = cnv.from_mne_epochs(cue_epoch) # rows x channel x time +dm.mean_erp = dm.erp[:, ...] # Average over channels: rows x time +tst.plot(dm, dv='mean_erp', hue_factor='cue_eccentricity') +``` + +Because the regular `mne.Epoch()` object doesn't play nice with non-data channels, such as pupil size, you need to use the `eet.PupilEpochs()` class instead. This is class otherwise identical, except that it by default removes trials where baseline pupil size is more than 2 SD from the mean baseline pupil size. + +```python +pupil_cue_epoch = eet.PupilEpochs(raw, eet.epoch_trigger(events, CUE_TRIGGER), + tmin=0, tmax=3, metadata=metadata, + baseline=(0, .05)) +dm.pupil = cnv.from_mne_epochs(pupil_cue_epoch, ch_avg=True) # only 1 channel tst.plot(dm, dv='pupil', hue_factor='cue_eccentricity') ``` + ## Installation ``` @@ -90,6 +88,7 @@ pip install eeg_eyetracking_parser ## Dependencies +- python-datamatrix >= 1.0 - python-eyelinkparser - mne - autoreject @@ -173,9 +172,6 @@ print(render_obj_docstring( 'eeg_eyetracking_parser.autoreject_epochs._fnc', 'autoreject_epochs')) print('\n\n') -print(render_obj_docstring('eeg_eyetracking_parser.epochs_to_series', - 'epochs_to_series')) -print('\n\n') print(render_obj_docstring('eeg_eyetracking_parser.epoch_trigger', 'epoch_trigger')) print('\n\n') diff --git a/readme.md b/readme.md index e65fdfc..e27d6f8 100644 --- a/readme.md +++ b/readme.md @@ -41,12 +41,13 @@ raw.plot() To avoid having to parse the data over and over again, `read_subject()` uses persistent [memoization](https://pydatamatrix.eu/memoization/), which is a way to store the return values of a function on disk and return them right away on subsequent calls. To clear the memoization cache, either call the `read_subject.clear()` function or remove the `.memoize` folder. - Plot the voltage across four occipital electrodes locked to cue onset for three seconds. This is done separately for three different conditions, defined by `cue_eccentricity`. The function `eet.autoreject_epochs()` behaves similarly to `mne.Epochs()`, except that autorejection is applied and that, like `read_subject()`, it uses persistent memoization. ```python +import numpy as np import mne from matplotlib import pyplot as plt +from datamatrix import convert as cnv CUE_TRIGGER = 1 CHANNELS = 'O1', 'O2', 'Oz', 'P3', 'P4' @@ -54,34 +55,31 @@ CHANNELS = 'O1', 'O2', 'Oz', 'P3', 'P4' cue_epoch = eet.autoreject_epochs(raw, eet.epoch_trigger(events, CUE_TRIGGER), tmin=-.1, tmax=3, metadata=metadata, picks=CHANNELS) -for ecc in ('near', 'medium', 'far'): - cue_evoked = cue_epoch[f'cue_eccentricity == "{ecc}"'].average() - plt.plot(cue_evoked.data.mean(axis=0), label=ecc) -plt.legend() -``` - -Plot pupil size during the same period. Because the regular `mne.Epoch()` object doesn't play nice with non-data channels, such as PupilSize, you need to use the `eet.PupilEpochs()` class instead (which is otherwise identical). - -```python -cue_epoch = eet.PupilEpochs(raw, eet.epoch_trigger(events, CUE_TRIGGER), tmin=0, - tmax=3, metadata=metadata, baseline=(0, .05)) -for ecc in ('near', 'medium', 'far'): - cue_evoked = cue_epoch[f'cue_eccentricity == "{ecc}"'].average() - plt.plot(cue_evoked.data.mean(axis=0)) -plt.legend() ``` -You can also convert the `PupilEpochs` object to a `SeriesColumn` and plot it that way, for example using `time_series_test.plot()`. +We can convert the metadata, which is a `DataFrame`, to a `DataMatrix`, and add `cue_epoch` as a multidimensional column ```python from datamatrix import convert as cnv import time_series_test as tst dm = cnv.from_pandas(metadata) -dm.pupil = eet.epochs_to_series(dm, cue_epoch, baseline_trim=(-2, 2)) +dm.erp = cnv.from_mne_epochs(cue_epoch) # rows x channel x time +dm.mean_erp = dm.erp[:, ...] # Average over channels: rows x time +tst.plot(dm, dv='mean_erp', hue_factor='cue_eccentricity') +``` + +Because the regular `mne.Epoch()` object doesn't play nice with non-data channels, such as pupil size, you need to use the `eet.PupilEpochs()` class instead. This is class otherwise identical, except that it by default removes trials where baseline pupil size is more than 2 SD from the mean baseline pupil size. + +```python +pupil_cue_epoch = eet.PupilEpochs(raw, eet.epoch_trigger(events, CUE_TRIGGER), + tmin=0, tmax=3, metadata=metadata, + baseline=(0, .05)) +dm.pupil = cnv.from_mne_epochs(pupil_cue_epoch, ch_avg=True) # only 1 channel tst.plot(dm, dv='pupil', hue_factor='cue_eccentricity') ``` + ## Installation ``` @@ -90,6 +88,7 @@ pip install eeg_eyetracking_parser ## Dependencies +- python-datamatrix >= 1.0 - python-eyelinkparser - mne - autoreject @@ -197,34 +196,6 @@ right away for subsequent calls. For more information, see -## epochs\_to\_series_(dm, epochs, baseline\_trim=None)_ - -Takes an Epochs, PupilEpochs, or EpochsTFR object and converts it to a -DataMatrix SeriesColumn. If a baseline has been specified in the epoch, it -is applied to each row of the series separately. Rows where the mean -baseline value (z-scored) is not within the range indicated by -`baseline_trim` are set to `NAN`. - -### Parameters - -* **dm: DataMatrix** - - A DataMatrix object to which the series belongs - -* **epochs: Epochs, PupilEpochs, or EpochsTFR** - - The source object with the epoch data. - -* **baseline\_trim: tuple of int, optional** - - The range of acceptable baseline values. This refers to z-scores. - -### Returns - -* **_SeriesColumn_** - - - ## epoch\_trigger_(events, trigger)_ Selects a single epoch trigger from a tuple with event information. @@ -248,11 +219,33 @@ Epoch triggers have values between 1 and 127 (inclusive). -## PupilEpochs_(\*args, \*\*kwargs)_ +## PupilEpochs_(\*args, baseline\_trim=(-2, 2), \*\*kwargs)_ An Epochs class for the PupilSize channel. This allows baseline correction to be applied to pupil size, even though this channel is not a -regular data channel. +regular data channel. In addition, this class allows pupil sizes to be +excluded based on deviant baseline values, which is recommended for +pupil analysis (but not typically done for eeg). + +### Parameters + +* **\*args: iterable** + + Arguments passed to mne.Epochs() + +* **baseline\_trim: tuple of int, optional** + + The range of acceptable baseline values. This refers to z-scores. + +* **\*\*kwargs: dict** + + Keywords passed to mne.Epochs() + +### Returns + +* **_Epochs:_** + + An mne.Epochs() object with autorejection applied.