coco_pipe.dim_reduction.preprocessing
=====================================

.. py:module:: coco_pipe.dim_reduction.preprocessing

.. autoapi-nested-parse::

   PCA score preprocessing utilities.

   Functions
   ---------
   apply_pca_score_baseline
       Baseline-correct PCA scores using an N-point or time-window approach.
   flip_pc_scores_for_consistency
       Flip PC sign so the mean within a reference window is positive.



Functions
---------

.. autoapisummary::

   coco_pipe.dim_reduction.preprocessing.apply_pca_score_baseline
   coco_pipe.dim_reduction.preprocessing.flip_pc_scores_for_consistency


Module Contents
---------------

.. py:function:: apply_pca_score_baseline(time, scores, n_points = None, baseline_min_ms = -200.0, baseline_max_ms = 0.0)

   Baseline-correct PCA scores.

   Two modes are available:

   * **N-point mode** (``n_points`` is not ``None``): subtract the mean of
     the first ``n_points`` time samples from every PC row.  Applied before
     any time cropping so that it replicates older script behaviour.
   * **Time-window mode** (default): subtract the mean within
     ``[baseline_min_ms, baseline_max_ms]``.

   :param time: Time stamps aligned with the columns of ``scores``.
   :type time: np.ndarray of shape (n_times,)
   :param scores: PC rows x time columns.
   :type scores: pd.DataFrame
   :param n_points: Number of leading samples to use as baseline.  When set, takes
                    priority over the time-window mode.
   :type n_points: int, optional
   :param baseline_min_ms: Time-window baseline boundaries used when ``n_points`` is ``None``.
   :type baseline_min_ms: float
   :param baseline_max_ms: Time-window baseline boundaries used when ``n_points`` is ``None``.
   :type baseline_max_ms: float

   :returns: Baseline-corrected copy of ``scores``.
   :rtype: pd.DataFrame


.. py:function:: flip_pc_scores_for_consistency(scores, time, flip_window_ms = (-200.0, 800.0))

   Flip each PC row so its mean within a reference window is non-negative.

   This makes the sign of PCA components visually consistent across subjects
   and conditions, removing the arbitrary sign indeterminacy of PCA.

   :param scores: PC rows x time columns.
   :type scores: pd.DataFrame
   :param time: Time stamps aligned with the columns of ``scores``.
   :type time: np.ndarray of shape (n_times,)
   :param flip_window_ms: Half-open time window used to compute the reference mean.
   :type flip_window_ms: tuple[float, float], default=(-200.0, 800.0)

   :returns: Copy of ``scores`` with sign-flipped rows as needed.
   :rtype: pd.DataFrame