New feature for removing heart artifacts from EEG or ESG data using a Principal Component Analysis - Optimal Basis Sets (PCA-OBS) algorithm #13037

steinnhauser · 2024-12-18T13:52:37Z

What does this implement/fix?

Our PR implements the PCA-OBS algorithm for removal of heart-artefacts from EEG or ESG datasets. The PCA-OBS algorithm was originally designed to remove the ballistocardiographic artefact in simultaneous EEG-fMRI. Here, it has been adapted to remove the delay between the detected R-peak and the ballistocardiographic artefact such that the algorithm can be applied to remove the cardiac artefact in EEG (electroencephalogrpahy) and ESG (electrospinography) data.

Positive and negative tests have been implemented for the feature, and we have also included an example script which is implemented using data from openneuro (dataset ID: ds004388).

Authors:
Emma Bailey [email protected]
Steinn Hauser Magnusson [email protected]

Updating master with most recent package features

feat: add initial source code

for more information, see https://pre-commit.ci

…e size of indentation tree

…ove more unused variables and imports, add some types

…et data from, how we call functions, how we assert outputs

Update PCA OBS fork with most recent changes in main MNE repo

…ogging to use mne logger instead of prints, add wrapper method in front of private _pca_obs method to handle parallel processing

… to have consistent patterns

larsoner

Looks like a good start! A few code cleanup/MNE-ization comments, plus an idea about the API

mne/preprocessing/pca_obs.py

tutorials/preprocessing/50_artifact_correction_ssp.py

mne/preprocessing/pca_obs.py

make fit_ecg_template a private function Co-authored-by: Eric Larson <[email protected]>

fix CircleCI error Co-authored-by: Eric Larson <[email protected]>

improve docstring for PCA-OBS function, adds citation Co-authored-by: Eric Larson <[email protected]>

mne/preprocessing/pca_obs.py

…_validate_type for ndarray check

…exception type to test parameterization

for more information, see https://pre-commit.ci

…orator, add verbose argument and docstring mention, convert docstring of n_jobs

…, remove redundant test

for more information, see https://pre-commit.ci

steinnhauser · 2025-01-10T19:36:27Z

After adding the copy kwarg I added an additional check in the end of the function:

    if copy:
        return raw

and reflected this "optional return" in the function typehinting:

@verbose
def apply_pca_obs(
    ...
) -> Raw | None:

Added this as I think it's misleading to return anything if the function modifies the raw instance in-place. Happy to change this though if it clashes with the library patterns

drammock · 2025-01-10T20:13:56Z

Added this as I think it's misleading to return anything if the function modifies the raw instance in-place. Happy to change this though if it clashes with the library patterns

we usually do return the instance even when modifying in-place, to allow method chaining. So it should always return modified (copy of) orig raw

…ss of copy kwarg to allow method chaining

steinnhauser · 2025-01-13T09:06:11Z

Added this as I think it's misleading to return anything if the function modifies the raw instance in-place. Happy to change this though if it clashes with the library patterns

we usually do return the instance even when modifying in-place, to allow method chaining. So it should always return modified (copy of) orig raw

Sounds good! Thanks for the feedback. Removed conditional return in d170c39

* upstream/main: [DOC] extend documentation for add_channels (mne-tools#13051) Add `combine_tfr` to API (mne-tools#13054) Add `combine_spectrum()` function and allow `grand_average()` to support `Spectrum` data (mne-tools#13058) BUG: Fix bug with helium anon (mne-tools#13056) [ENH] Add option to store and return TFR taper weights (mne-tools#12910)

emma-bailey and others added 30 commits September 1, 2024 12:57

feat: add initial source code

2013fb4

Minimum working example with local data

6d5f5b2

Implement testing dataset

3622540

Feat: Update examples

6c42f33

Merge pull request #2 from mne-tools/main

38b6b6a

Updating master with most recent package features

Merge pull request #1 from emma-bailey/feat/pca-obs

2fe6a88

feat: add initial source code

[pre-commit.ci] auto fixes from pre-commit.com hooks

61f58b2

for more information, see https://pre-commit.ci

fix: adjust import paths, add init file to module

070037d

refactor: rearrange PCA_OBS arg structure, remove kwarg 'sr'

e1b6732

refactor: move common variables to module init, further cleanup

ccd4298

feat/initial-cleanup: Remove custom pchip as not in use

61a92ea

refactor/initial-cleanup: answer question

a1eb6f6

refactor: rename files to match other modules in preprocessing, reduc…

d75e927

…e size of indentation tree

refactor: remove unused fit_ecgTemplate variable 'baselinerange'

035a9f6

refactor: make main methods private, import from module __init__, rem…

2debb61

…ove more unused variables and imports, add some types

refactor: add docstring templates, gather imports

97f9a15

test: add placeholder tests, add multiple todos to address where we g…

34a2e06

…et data from, how we call functions, how we assert outputs

Removing extra examples

3760c02

Moving example

0a55712

Adding Niazy reference

e887ace

Update example, put pca-obs in a single file

ee3b73e

TODO

adae352

Update example

b3c1b4e

Merge pull request #4 from mne-tools/main

ba36dc2

Update PCA OBS fork with most recent changes in main MNE repo

refactor: change way of calling pca obs method, add comments

e6aa17d

refactor: move pca obs method out of separate python module, change l…

b150b6c

…ogging to use mne logger instead of prints, add wrapper method in front of private _pca_obs method to handle parallel processing

Refactor: Docstrings, removed classes

951e87c

refactor: remove unrequired index references, adjust variable namings…

c70db0a

… to have consistent patterns

docs: minor edits in docstrings

fb8c7ff

fix: add minor sanity checks for the function inputs

4c73a96

emma-bailey added 2 commits January 8, 2025 09:53

example: update comments

c8eb284

tutorial: add ref to pca_obs in SSP tutorial section on ECG artefacts

89278a6

larsoner reviewed Jan 8, 2025

View reviewed changes

steinnhauser and others added 4 commits January 10, 2025 17:42

Merge branch 'mne-tools:main' into main

15c7c5c

Update mne/preprocessing/pca_obs.py

36e0ca0

make fit_ecg_template a private function Co-authored-by: Eric Larson <[email protected]>

Update tutorials/preprocessing/50_artifact_correction_ssp.py

fc5bdc8

fix CircleCI error Co-authored-by: Eric Larson <[email protected]>

Update mne/preprocessing/pca_obs.py

d586d62

improve docstring for PCA-OBS function, adds citation Co-authored-by: Eric Larson <[email protected]>

larsoner reviewed Jan 10, 2025

View reviewed changes

mne/preprocessing/pca_obs.py Outdated Show resolved Hide resolved

steinnhm and others added 10 commits January 10, 2025 19:35

refactor: rework qrs_indices to qrs_times, adjust sanity checks, add …

d6ae456

…_validate_type for ndarray check

test,example: adjust example and tests to new qrs_times changes, add …

420f4fc

…exception type to test parameterization

Merge branch 'mne-tools:main' into main

91b0033

[pre-commit.ci] auto fixes from pre-commit.com hooks

54d67aa

for more information, see https://pre-commit.ci

feat: add copy kwarg, optionally return new instance, add verbose dec…

f4082b4

…orator, add verbose argument and docstring mention, convert docstring of n_jobs

Merge branch 'main' of https://github.com/emma-bailey/mne-python

0e43130

test,example: update tests and example with new copy default behavior…

fd9c41b

…, remove redundant test

[pre-commit.ci] auto fixes from pre-commit.com hooks

a578a7d

for more information, see https://pre-commit.ci

lint: resolve pre-commit errors, format

41559ff

Merge branch 'main' of https://github.com/emma-bailey/mne-python

0079605

fix: remove conditional raw return, always return raw object regardle…

d170c39

…ss of copy kwarg to allow method chaining

steinnhm and others added 8 commits January 13, 2025 10:08

lint: resolve linter errors

b70545b

FIX: Doc

39c322f

[autofix.ci] apply automated fixes

f62f98b

FIX: How

ebda34e

TST: Pre

92fe25c

DOC: whats new

d38e37f

FIX: Name

2472c84

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New feature for removing heart artifacts from EEG or ESG data using a Principal Component Analysis - Optimal Basis Sets (PCA-OBS) algorithm #13037

New feature for removing heart artifacts from EEG or ESG data using a Principal Component Analysis - Optimal Basis Sets (PCA-OBS) algorithm #13037

steinnhauser commented Dec 18, 2024

larsoner left a comment

steinnhauser commented Jan 10, 2025

drammock commented Jan 10, 2025

steinnhauser commented Jan 13, 2025

New feature for removing heart artifacts from EEG or ESG data using a Principal Component Analysis - Optimal Basis Sets (PCA-OBS) algorithm #13037

Are you sure you want to change the base?

New feature for removing heart artifacts from EEG or ESG data using a Principal Component Analysis - Optimal Basis Sets (PCA-OBS) algorithm #13037

Conversation

steinnhauser commented Dec 18, 2024

What does this implement/fix?

larsoner left a comment

Choose a reason for hiding this comment

steinnhauser commented Jan 10, 2025

drammock commented Jan 10, 2025

steinnhauser commented Jan 13, 2025