Merge pull request #375 from Shotgunosine/remlfit_doc

Adding a section on estimators

docs/conf.py

@@ -59,6 +59,11 @@
 
 source_suffix = ['.rst', '.md']
 
+intersphinx_mapping = {
+    'nilearn': ('https://nilearn.github.io/stable/', None),
+    'afni': ('https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/', None)
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/estimators.rst

@@ -0,0 +1,43 @@
+.. 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.

docs/index.rst

@@ -16,6 +16,7 @@ Contents
    installation
    usage
    model
+   estimators
    examples/index
    changes
    support