fmri_correctmovement
====================

.. currentmodule:: fmri_toolbox

Description
-----------
FMRI_CORRECTMOVEMENT  Removes motion artifacts from fMRI data via regression.
Regresses out motion parameters from the fMRI time series using ordinary
least squares (OLS). The motion regressors are z-scored before regression
to ensure numerical stability. The residuals represent the data with motion-
related variance removed.

Usage
-----
.. code-block:: matlab

    residual = fmri_correctmovement(data, movementfilepath)

Inputs
------
- **DATA**: fMRI time series, either: vectorized (T x 228453) — scans in rows, voxels in cols volume     (91 x 109 x 91 x T)
- **MOVEMENTFILEPATH**: Path to the motion parameter file (string). The file should contain a numeric matrix of size (T x P) where P is the number of motion regressors (typically 6: 3 translations + 3 rotations).

Outputs
-------
- **RESIDUAL**: Motion-corrected data in the same format as DATA input (T x 228453 if vectorized, 91 x 109 x 91 x T if volume).

Examples
--------
.. code-block:: matlab

    residual = fmri_correctmovement(data, 'sub01_motion.txt');
    residual = fmri_correctmovement(voldata, '/data/motion/sub04.par');

Notes
-----
- Motion parameter files are typically generated by SPM (rp_*.txt) or
- FSL (*.par). Both 6-column (rigid body) and extended regressor sets
- (e.g., 24-parameter) are accepted.

See Also
--------
- fmri_detrend
- fmri_tempsmooth
- fmri_readnii