Question: How does the _06a2_find_ica_artifacts detect EOG artifacts?

[scholzri]

I try to recreate the functionality of the mne_bids_pipeline _06a2_find_ica_artifacts step.

Here is my function:

def detect_eog_components(
    ica: mne.preprocessing.ICA,
    raw: mne.io.BaseRaw,
    epochs: mne.Epochs,
    verbose: bool = True
) -> mne.preprocessing.ICA:
    """
    Detect and exclude EOG components from ICA using simulated EOG channels.

    This function creates EOG epochs, finds bad EOG components using ICA,
    and excludes them from the ICA solution.

    Args:
        ica: The ICA object to use for component detection.
        raw: The unfiltered raw MNE data object.
        epochs: The epochs object used for ICA fitting.
        verbose: Whether to output additional information during processing.

    Returns:
        The modified ICA object with EOG components excluded.
    """
    logger.info("Using simulated EOG channel to autoselect independent components")

    eog_channels = ["Fp1", "Fp2"]

    # Create EOG epochs
    eog_epochs = mne.preprocessing.create_eog_epochs(raw, ch_name=eog_channels, baseline=(None, -0.2), verbose=verbose)

    if len(eog_epochs):
        if epochs.reject is not None:
            eog_epochs.drop_bad(reject=epochs.reject)

    # Find bad EOG components
    eog_indices, eog_scores = ica.find_bads_eog(
        eog_epochs,
        ch_name=eog_channels,
        threshold=3.0,
        verbose=verbose
    )

    # Exclude detected EOG components
    ica.exclude = eog_indices

    return ica

Somehow I get a different number of eog epochs detected then with the mne_bids_pipeline. Is mne.preprocessing.create_eog_epochs run on modified raw data in the pipeline? Ideally we would need an extensive documentation that explain the steps in detail so it gets more transparent what they exactly do.

Thank you!!

[larsoner]

I think currently the way to know what is done is to look at the code. And to be able to answer your question it's what I would have to do :slightly_smiling_face:

But it would be great to document it properly somewhere! There are actually a number of steps that are like this. I think ideally we'd document it in the step / module __doc__ like here

https://github.com/mne-tools/mne-bids-pipeline/blob/cce897d3ac3324a6ab5fbd5f7333e1df3c61f919/mne_bids_pipeline/steps/preprocessing/_06a2_find_ica_artifacts.py#L7

And then we could parse these __doc__ entries and add them to https://mne.tools/mne-bids-pipeline/stable/features/steps.html. I think adding them as a clickable dropdown could be a cool way to do it -- like if you wanted to know what that step in particular did and you clicked here:

It could expand to give the rendered __doc__ (where we have commented in the .py file to reflect what the steps actually are). But to start, even linking this step name to a separate .md file (which would be easy to create) with the rendered __doc__ would work if the drop-down stuff is too difficult to get right.

FYI most of our docs (like the steps.html page) are autogenerated so it shouldn't be too hard to get these mechanics right. The tough part I think will be actually going through the code and adding the "what does this actually do" details. But we can do it piecemeal, starting just from the step you're interested in!

[larsoner]

... and it would be awesome if you are interested in working on this, happy to look at a PR or give more guidance/ideas!