Helper Cookbook

This page collects concise recipes for helper APIs that are easy to miss in the long-form guides.

Quick File Conversion (facet.load / facet.export)

Use top-level convenience helpers when you only need loading/exporting and no explicit pipeline object.

import facet

ctx = facet.load("./examples/datasets/NiazyFMRI.edf", preload=True)
ctx = ctx | facet.HighPassFilter(freq=1.0)
facet.export(ctx, "./outputs/NiazyFMRI_cleaned.set", overwrite=True)

Manual Trigger Injection (with_trigger_samples)

If you already have trigger samples from an external system, inject them without running TriggerDetector.

from facet import load

ctx = load("data.edf", preload=True)
ctx = ctx.with_trigger_samples(
    [1000, 2000, 3000, 4000],
    tr_seconds=2.0,
    trigger_regex="manual",
)

MNE Events Bridge (with_mne_events)

Convert existing MNE events to FACETpy trigger metadata, including automatic first_samp handling.

import mne
from facet import ProcessingContext

raw = mne.io.read_raw_fif("sub-01_task-rest_eeg.fif", preload=True)
events, event_id = mne.events_from_annotations(raw)

ctx = ProcessingContext(raw=raw).with_mne_events(
    events,
    event="R128",
    event_id=event_id,
    tr_seconds=2.0,
)

Batch Processing (Pipeline.map + BatchResult.summary_df)

Use one pipeline for many files and collect per-file metrics in one table.

from facet import Pipeline, TriggerDetector, AASCorrection, SNRCalculator

pipeline = Pipeline([
    TriggerDetector(regex=r"\b1\b"),
    AASCorrection(window_size=30),
    SNRCalculator(),
])

batch = pipeline.map([
    "sub-01.edf",
    "sub-02.edf",
    "sub-03.edf",
], keep_raw=False)

batch.print_summary()
df = batch.summary_df  # pandas.DataFrame (or None if pandas is unavailable)

Result Convenience (PipelineResult.metric, metrics_df, plot, release_raw)

Access metrics and plots without digging through nested metadata dictionaries.

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

snr = result.metric("snr")
flat_metrics = result.metrics_df

# Optional quick visual check
result.plot(channel="Fp1", start=5.0, duration=10.0)

# Free memory after extracting metrics
result.release_raw()

Context Metric Shortcut (ProcessingContext.get_metric)

For conditional branches, get_metric keeps logic readable.

from facet import ConditionalProcessor, PCACorrection

def needs_extra_cleanup(ctx):
    return ctx.get_metric("snr", float("inf")) < 10

maybe_pca = ConditionalProcessor(
    condition=needs_extra_cleanup,
    processor=PCACorrection(n_components=0.95),
)

Trigger QA (TriggerExplorer / InteractiveTriggerExplorer)

Inspect candidate triggers before correction when marker quality is uncertain.

from facet import Pipeline, Loader, AASCorrection
from facet.preprocessing import TriggerExplorer

pipeline = Pipeline([
    Loader(path="data.edf", preload=True),
    TriggerExplorer(),
    AASCorrection(window_size=30),
])

result = pipeline.run()