.. include:: links.rst

Estimators
==========

When fitting hierarchical models, there are two broad classes of estimators:
time-series estimators, which accept a time series and a design matrix
and produce statistical maps;
and summary-statistic estimators, which accept a collection of statistical maps
and a design matrix, and produce statistical maps.
Time-series estimators fit models that are often called "first-level" or "run-level"
models, and summary-statistic estimators fit models that are often called "second-level"
or perhaps "subject-level" or "group-level".


Time-series estimators
----------------------
Fitlins supports two estimators for first-level models:
Nilearn's :py:class:`~nilearn.glm.first_level.FirstLevelModel`
and AFNI's :ref:`3dREMLfit<afni:ahelp_3dremlfit>`.
In both cases, the design matrix is generated by PyBIDS and Nilearn.
You can select the AFNI estimator by passing ``--estimator afni`` to FitLins.

Nilearn
~~~~~~~
Fits a normal general linear model (GLM) assuming that the residuals are not autocorrelated.
This is quick and no-frills.

AFNI
~~~~
Fits a "prewhitened" GLM with an ARMA(1,1) model to each voxel to account for autocorrelated time series noise.
The GLM and the ARMA(1,1) model are simultaneously optimized with a restricted maximum likelihood approach.
The downside of the approach is that it's a bit slower as it has to iteratively fit the GLM and ARMA model at each voxel.


Summary statistic estimators
----------------------------
For ``"glm"`` model types, FitLins currently only supports Nilearn's
:py:class:`~nilearn.glm.second_level.SecondLevelModel` estimator.

For ``"meta"`` model types, FitLins uses Nilearn's
:py:func:`~nilearn.glm.compute_fixed_effects` to compute a fixed-effects
combination.