Use Cases & Supported Artifacts

This page gives an overview of the artifact types that FACETpy can handle and the research scenarios in which the toolbox has been designed to be used.

Supported Artifacts 

FACETpy targets artifacts that arise from the recording environment or from physiological processes. The table below lists the artifact types, their origin, and the correction methods available in FACETpy.

Artifact	Origin	Correction methods
Gradient artifact (GA)	MRI scanner gradient switching during simultaneous EEG-fMRI recordings	AAS, PCA
Ballistocardiogram (BCG)	Cardiac-induced electrode movements in the static MRI magnetic field	AAS (after BCG detection), PCA
Cardioballistic / pulse artifact	Pulsatile skin and vessel movement under electrodes	BCG detector + AAS
Motion artifact	Head movement, cable pull, or electrode shift	Preprocessing filters, PCA
Power-line noise (50 / 60 Hz)	Electrical mains interference	Notch filter (via MNE preprocessing step)
Muscle (EMG) artifact	Jaw or neck muscle activity contaminating high-frequency EEG	High-frequency filtering, PCA
Amplifier saturation / DC drift	Slow baseline drift or clipping in long recordings	Baseline correction, high-pass filter

Note

Not every artifact class requires a dedicated FACETpy processor. For standard spectral filtering (notch, bandpass) FACETpy delegates to MNE-Python’s built-in filter methods that can be called inside a custom Processor. See Custom Processors for details.

Use Cases 

Simultaneous EEG-fMRI Research 

The primary use case for which FACETpy was created. EEG recorded inside an MRI scanner is contaminated by strong, quasi-periodic gradient artifacts (GA) caused by the rapidly switching magnetic field gradients used for image acquisition, and by ballistocardiogram (BCG) artifacts driven by cardiac activity.

FACETpy addresses both in a single pipeline:

Detect volume triggers from annotations with TriggerDetector.
Optionally upsample the signal with UpSample for sub-sample trigger alignment.
Remove the gradient artifact with AASCorrection.
Detect R-peaks and remove the BCG artifact with a second AAS pass.
Export the corrected data with EDFExporter or BIDSExporter.

from facet import (
    Pipeline, Loader, EDFExporter,
    TriggerDetector, UpSample, DownSample,
    AASCorrection, BCGDetector,
)

pipeline = Pipeline([
    Loader(path="data.edf", preload=True),
    TriggerDetector(regex=r"\b1\b"),
    UpSample(factor=10),
    AASCorrection(window_size=30),                 # remove gradient artifact
    BCGDetector(),                                 # detect cardiac triggers
    AASCorrection(window_size=20, use_bcg=True),  # remove BCG artifact
    DownSample(factor=10),
    EDFExporter(path="corrected.edf", overwrite=True),
], name="EEG-fMRI Correction")

result = pipeline.run()
result.print_summary()

Multi-Subject / Multi-Session Batch Studies 

When you have a BIDS dataset with many subjects and sessions, you can define one pipeline and apply it to all runs automatically using map():

from facet import Pipeline, BIDSLoader, BIDSExporter, AASCorrection, TriggerDetector

template = Pipeline([
    TriggerDetector(regex=r"\b1\b"),
    AASCorrection(window_size=30),
    BIDSExporter(output_root="derivatives/facetpy"),
])

# collect contexts from a BIDS dataset
from facet import BIDSLoader
loader = BIDSLoader(bids_root="my_study/", task="rest")
contexts = loader.load_all()

batch_result = template.map(contexts)
print(batch_result.summary())   # per-run SNR, RMS, timing

Metrics (SNR, RMS ratio) are collected per run and returned in a structured BatchResult object that can be exported to a CSV file for downstream analysis.

Algorithm Comparison & Benchmarking 

FACETpy’s evaluation module makes it straightforward to run several correction strategies on the same dataset and compare them quantitatively. This is particularly useful for methodology papers that require SNR / RMS tables.

from facet import Pipeline, Loader, AASCorrection, PCACorrection
from facet.evaluation import SNRCalculator, RMSCalculator, MetricsReport

data = Loader(path="data.edf", preload=True)

for CorrectionClass, label in [
    (AASCorrection(window_size=30), "AAS"),
    (PCACorrection(n_components=0.95), "PCA"),
]:
    result = Pipeline([data, CorrectionClass, SNRCalculator(), RMSCalculator()]).run()
    print(label, result.metrics)

MetricsReport().compare(results)

Synthetic EEG Testing & Algorithm Development 

When real scanner data is not available — or when you need fully controlled ground truth — EEGGenerator lets you synthesise EEG signals with configurable artifact profiles:

from facet.misc import EEGGenerator

gen = EEGGenerator(
    duration=300,          # seconds
    sfreq=5000,
    n_channels=32,
    artifact_type="gradient",
    tr=1.5,                # MRI repetition time in seconds
)
raw = gen.generate()      # returns mne.io.Raw

Use the generated data together with the normal pipeline processors to benchmark or tune new correction algorithms before running on real data.

Clinical Feasibility Studies 

EEG-fMRI is increasingly used in clinical settings — for example, to localise epileptic foci during sleep MRI or to monitor anaesthesia depth. In these scenarios, it is essential to preserve pathological waveforms (interictal spikes, slow waves) while removing scanner artifacts.

FACETpy supports this by:

Keeping the full correction pipeline reproducible and auditable via history.
Allowing conditional correction steps with ConditionalProcessor so that artefact windows are skipped for clinical events.
Providing per-epoch SNR metrics to quantify the quality of each corrected segment.

See Pipeline Guide for examples of conditional processing.

Teaching & Reproducible Science 

A FACETpy Pipeline serialises the complete analysis as a Python object that can be inspected, versioned, and shared with collaborators. Each pipeline step is documented in the processing history stored inside ProcessingContext, making the provenance of every result transparent.

To share a complete, runnable analysis:

Commit the pipeline definition file and the raw data (or a BIDS dataset) to a repository.
Collaborators reproduce the results by running python pipeline_definition.py after installing FACETpy from PyPI.

No proprietary toolboxes, no manual GUI clicks — full reproducibility from a single script.