.. _api-preproc:

Preprocessing
=============

The preprocessing module covers the full EEG pipeline, epoch preparation,
rigid-body motion kinematics, and a set of lower-level signal-processing
utilities that the pipeline calls internally but which are also usable
standalone.

----

EEG pipeline
------------

:class:`~pybemobil.preproc.EEGPreprocessor` orchestrates the full pipeline:
ZapLine → bad-channel detection → bandpass filter → ASR → ICA/JAMICA →
ICLabel classification → dipole fitting → bad-channel interpolation →
average re-reference.  All steps are recorded in a provenance descriptor stored on
the :class:`mne.io.Raw` object.

.. currentmodule:: pybemobil.preproc

Outputs are named after BIDS: :func:`get_derivative_paths` lists the
derivative files written for a given ``fname_out``, and the untouched input is
written to the raw part of the BIDS dataset.

.. autosummary::
   :toctree: generated/

   EEGPreprocessor
   get_derivative_paths

----

Reporting
---------

Builds an :class:`mne.Report` summarising a single :class:`EEGPreprocessor` run
(bad channels, ICA, dipoles, and full-length stream traces for drop-out
inspection).  Called automatically by :meth:`EEGPreprocessor.run_raw` when
``make_report=True`` (the default); can also be called directly on saved
pipeline outputs.

.. autosummary::
   :toctree: generated/

   make_report

----

Bad channel detection
---------------------

Standalone bad-channel detector that combines PyPREP (NaN/flat, deviation,
high-frequency noise, correlation and RANSAC), FASTER's correlation and
variance criteria, and an optional line-noise z-score criterion. It works on
a 1 Hz high-passed, average-referenced copy (flat channels are found before
referencing) and warns when more than a fifth of the channels is flagged.
Called automatically by :class:`EEGPreprocessor` but can also be run on any
:class:`mne.io.Raw` object directly.

.. autosummary::
   :toctree: generated/

   get_bad_chs

----

Signal cleaning
---------------

Individual signal-processing steps that :class:`EEGPreprocessor` calls
internally.  Useful when building a custom pipeline or applying a single step
in isolation.

.. autosummary::
   :toctree: generated/

   remove_line
   compute_asr
   compute_ica
   detect_bad_by_line_noise
   compute_mi_reduction

----

Dipole fitting
--------------

.. autosummary::
   :toctree: generated/

   fit_dipoles_on_ica
   compute_dipolarity
   auto_coreg_fsaverage

----

Epoching
--------

Helpers for converting continuous preprocessed data into epochs, including
stimulus-label renaming utilities.

.. autosummary::
   :toctree: generated/

   EpochPreparer
   get_stimulus_rename_map

----

Motion capture
--------------

Rigid-body kinematics from motion capture channels in a Raw object, e.g.
motion streams that :class:`~pybemobil.io.XDFLoader` merged into
``MultimodalRecording.raw`` as special streams. Channel names follow the
``<body>_quat_[xyzw]``, ``<body>_eul_[xyz]`` and ``<body>_pos_[xyz]``
convention.

.. autosummary::
   :toctree: generated/

   find_rigid_bodies
   process_rigid_body
   split_by_rigid_body

----

Provenance
----------

Lightweight provenance tracking: each pipeline step appends a JSON-serialisable
descriptor to :attr:`mne.Info.description` so that any saved file carries a
record of exactly how it was processed.

.. autosummary::
   :toctree: generated/

   init_descriptor
   set_descriptor
   get_descriptor
   append_desc
   sig_params

----

Utilities
---------

.. autosummary::
   :toctree: generated/

   StepTimer
   format_duration
   build_sys_info