Welcome to FACETpy’s Documentation!

FACETpy (fMRI Artifact Correction and Evaluation Toolbox for Python) is a comprehensive, modular toolkit for correcting fMRI-induced artifacts in EEG data.

FACETpy provides a modular architecture with:

🧩 Modular Design - Composable processors for flexible workflows
🔌 Plugin System - Easy extensibility via decorators
⚡ Parallel Processing - Built-in multiprocessing support
🔗 MNE Integration - First-class MNE-Python compatibility
📝 Type Hints - Full IDE support and type safety
🎯 Beginner Friendly - Clear API and comprehensive docs

Quick Start

Install FACETpy from PyPI:

pip install facetpy

Repository: GitHub - H0mire/facetpy

For the full experience (contribution workflow and local example datasets/scripts), use the bootstrap install script (WSL/macOS/Linux):

curl -fsSL https://raw.githubusercontent.com/H0mire/facetpy/main/scripts/bootstrap.sh | sh
cd facetpy

Run a complete correction pipeline:

from facet import create_standard_pipeline

pipeline = create_standard_pipeline(
    input_path="data.edf",
    output_path="corrected.edf",
    trigger_regex=r"\b1\b",
    evaluate=True,
)

result = pipeline.run()
print(f"SNR: {result.metrics['snr']:.2f}")

Documentation Overview

Getting Started

User Guide

Development

Key Features

Modular Processors

Every processing step is a self-contained processor that can be used independently:

from facet.preprocessing import TriggerDetector, UpSample
from facet.correction import AASCorrection

detector = TriggerDetector(regex=r"\b1\b")
upsampler = UpSample(factor=10)
aas = AASCorrection(window_size=30)

Pipeline-Based Workflows

Compose processors into declarative pipelines:

from facet import Pipeline, Loader, EDFExporter, TriggerDetector, UpSample, AASCorrection, DownSample

pipeline = Pipeline([
    Loader(path="data.edf"),
    TriggerDetector(regex=r"\b1\b"),
    UpSample(factor=10),
    AASCorrection(window_size=30),
    DownSample(factor=10),
    EDFExporter(path="corrected.edf")
])

result = pipeline.run(parallel=True)

Plugin System

Create custom processors with simple decorators:

from facet.core import Processor, register_processor

@register_processor
class MyCustomProcessor(Processor):
    name = "my_processor"

    def process(self, context):
        # Your custom logic
        return context

Parallel Processing

Automatic parallelization for compatible processors:

# Automatically uses all CPU cores
result = pipeline.run(parallel=True, n_jobs=-1)

Available Processors

I/O

Loader, BIDSLoader
EDFExporter, BIDSExporter

Preprocessing

Filtering: HighPassFilter, LowPassFilter, BandPassFilter, NotchFilter
Resampling: UpSample, DownSample, Resample
Triggers: TriggerDetector, QRSTriggerDetector, MissingTriggerDetector
Alignment: TriggerAligner, SliceAligner, SubsampleAligner
Transforms: CutAcquisitionWindow, PasteAcquisitionWindow, Crop, PickChannels, DropChannels

Correction

AASCorrection - Averaged Artifact Subtraction
ANCCorrection - Adaptive Noise Cancellation (requires compiled C extension)
PCACorrection - PCA-based artifact removal

Evaluation

SNRCalculator, RMSCalculator, RMSResidualCalculator
MedianArtifactCalculator
FFTAllenCalculator, FFTNiazyCalculator
MetricsReport, RawPlotter

Citation

If you use FACETpy in your research, please cite:

@software{facetpy2025,
  title = {FACETpy: fMRI Artifact Correction and Evaluation Toolbox for Python},
  author = {Mueller, Janik Michael},
  year = {2025},
  version = {2.0.0}
}

License

FACETpy is released under the GPLv3 license. See the LICENSE file for details.