[REF] Reorganize selcomps and fitmodels_direct (#266)

* Reorganize selcomps and fitmodels_direct

- Rename fitmodels_direct to dependence_metrics
- Split sel_comps into manual_selection, kundu_selection_v2, and
kundu_metrics
- Move kundu_metrics into model.fit
- Rename selcomps to tedica
- Rename PCA-derived variance explained column in PCA component table.
This will no longer overwrite the one from fitmodels_direct
- Add reorder_dataframe function to selection._utils

* Fix test.

* [skip-ci] Update docs

* Add new tests.

* Update value error.

* Fix test.

* Seriously?

* Fix.

* Merge remote-tracking branch 'ME-ICA/master' into reorg-metrics

# Conflicts:
#	tedana/decomposition/eigendecomp.py
#	tedana/selection/__init__.py

* Fix init file.

* More fixing.

* Update docs/api.rst

Co-Authored-By: tsalo <tsalo006@fiu.edu>

* Revert API name change.

* Method -> algorithm

* Address review.

* Maybe importing the functions we use would be good.

docs/api.rst

@@ -20,22 +20,37 @@ API
 .. _calibration_ref:
 
 
-:mod:`tedana.model`: Modeling TE-dependence
---------------------------------------------------
+:mod:`tedana.decay`: Modeling signal decay across echoes
+--------------------------------------------------------
 
-.. automodule:: tedana.model
+.. automodule:: tedana.decay
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.model
-   :toctree: generated/
+.. autosummary:: tedana.decay
    :template: function.rst
+   :toctree: generated/
 
-   tedana.model.fitmodels_direct
+   tedana.decay.fit_decay
+   tedana.decay.fit_decay_ts
 
-   :template: module.rst
+.. currentmodule:: tedana
+
+.. _calibration_ref:
 
-   tedana.model.fit
+
+:mod:`tedana.combine`: Combining time series across echoes
+----------------------------------------------------------
+
+.. automodule:: tedana.combine
+   :no-members:
+   :no-inherited-members:
+
+.. autosummary:: tedana.combine
+   :toctree: generated/
+   :template: function.rst
+
+   tedana.combine.make_optcom
 
 .. currentmodule:: tedana
 
@@ -65,67 +80,65 @@ API
 .. _calibration_ref:
 
 
-:mod:`tedana.combine`: Combine time series
---------------------------------------------------
+:mod:`tedana.model`: Computing TE-dependence metrics
+----------------------------------------------------
 
-.. automodule:: tedana.combine
+.. automodule:: tedana.model
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.combine
+.. autosummary:: tedana.model
    :toctree: generated/
    :template: function.rst
 
-   tedana.combine.make_optcom
+   tedana.model.dependence_metrics
+   tedana.model.kundu_metrics
 
    :template: module.rst
 
-   tedana.combine
+   tedana.model.fit
 
 .. currentmodule:: tedana
 
 .. _calibration_ref:
 
 
-:mod:`tedana.decay`: Signal decay
+:mod:`tedana.selection`: Component selection
 --------------------------------------------------
 
-.. automodule:: tedana.decay
+.. automodule:: tedana.selection
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.decay
+.. autosummary:: tedana.selection
    :toctree: generated/
    :template: function.rst
 
-   tedana.decay.fit_decay
-   tedana.decay.fit_decay_ts
+   tedana.selection.manual_selection
+   tedana.selection.kundu_selection_v2
 
    :template: module.rst
 
-   tedana.decay
+   tedana.selection._utils
 
 .. currentmodule:: tedana
 
 .. _calibration_ref:
 
 
-:mod:`tedana.selection`: Component selection
+:mod:`tedana.gscontrol`: Global signal control
 --------------------------------------------------
 
-.. automodule:: tedana.selection
+.. automodule:: tedana.gscontrol
    :no-members:
    :no-inherited-members:
 
-.. autosummary:: tedana.selection
+.. autosummary:: tedana.gscontrol
    :toctree: generated/
    :template: function.rst
 
-   tedana.selection.selcomps
-
-   :template: module.rst
-
-   tedana.selection._utils
+   tedana.gscontrol.gscontrol_raw
+   tedana.gscontrol.gscontrol_mmix
 
 .. currentmodule:: tedana
 
@@ -146,18 +159,13 @@ API
 
    tedana.io.split_ts
    tedana.io.filewrite
-   tedana.io.gscontrol_mmix
    tedana.io.load_data
    tedana.io.new_nii_like
    tedana.io.write_split_ts
    tedana.io.writefeats
    tedana.io.writeresults
    tedana.io.writeresults_echoes
 
-   :template: module.rst
-
-   tedana.io
-
 .. currentmodule:: tedana
 
 .. _calibration_ref:
@@ -182,10 +190,6 @@ API
    tedana.utils.make_adaptive_mask
    tedana.utils.unmask
 
-   :template: module.rst
-
-   tedana.utils
-
 .. currentmodule:: tedana
 
 .. _calibration_ref:

tedana/decomposition/pca.py

@@ -56,7 +56,7 @@ def run_mlepca(data):
 
 
 def tedpca(data_cat, data_oc, combmode, mask, t2s, t2sG,
-           ref_img, tes, method='mle', source_tes=-1, kdaw=10., rdaw=1.,
+           ref_img, tes, algorithm='mle', source_tes=-1, kdaw=10., rdaw=1.,
            out_dir='.', verbose=False):
     """
     Use principal components analysis (PCA) to identify and remove thermal
@@ -82,7 +82,7 @@ def tedpca(data_cat, data_oc, combmode, mask, t2s, t2sG,
         Reference image to dictate how outputs are saved to disk
     tes : :obj:`list`
         List of echo times associated with `data_cat`, in milliseconds
-    method : {'mle', 'kundu', 'kundu-stabilize'}, optional
+    algorithm : {'mle', 'kundu', 'kundu-stabilize'}, optional
         Method with which to select components in TEDPCA. Default is 'mle'.
     source_tes : :obj:`int` or :obj:`list` of :obj:`int`, optional
         Which echos to use in PCA. Values -1 and 0 are special, where a value
@@ -177,7 +177,7 @@ def tedpca(data_cat, data_oc, combmode, mask, t2s, t2sG,
     data_z = ((data.T - data.T.mean(axis=0)) / data.T.std(axis=0)).T  # var normalize ts
     data_z = (data_z - data_z.mean()) / data_z.std()  # var normalize everything
 
-    if method == 'mle':
+    if algorithm == 'mle':
         voxel_comp_weights, varex, comp_ts = run_mlepca(data_z)
     else:
         ppca = PCA()
@@ -200,10 +200,11 @@ def tedpca(data_cat, data_oc, combmode, mask, t2s, t2sG,
 
     # Normalize each component's time series
     vTmixN = stats.zscore(comp_ts, axis=0)
-    _, comptable, _, _ = model.fitmodels_direct(
-                data_cat, comp_ts, eimum, t2s, t2sG, tes, combmode, ref_img,
-                reindex=False, mmixN=vTmixN, full_sel=False,
+    comptable, _, _, _ = model.dependence_metrics(
+                data_cat, data_oc, comp_ts, eimum, t2s, tes, ref_img,
+                reindex=False, mmixN=vTmixN, algorithm=None,
                 label='mepca_', out_dir=out_dir, verbose=verbose)
+
     # varex_norm from PCA retained on top of varex from fitmodels_direct
     comptable['original normalized variance explained'] = varex_norm
 
@@ -218,11 +219,11 @@ def tedpca(data_cat, data_oc, combmode, mask, t2s, t2sG,
     io.filewrite(comp_maps, 'mepca_OC_components.nii', ref_img)
 
     # Select components using decision tree
-    if method == 'kundu':
+    if algorithm == 'kundu':
         comptable = kundu_tedpca(comptable, n_echos, kdaw, rdaw, stabilize=False)
-    elif method == 'kundu-stabilize':
+    elif algorithm == 'kundu-stabilize':
         comptable = kundu_tedpca(comptable, n_echos, kdaw, rdaw, stabilize=True)
-    elif method == 'mle':
+    elif algorithm == 'mle':
         LGR.info('Selected {0} components with MLE dimensionality '
                  'detection'.format(comptable.shape[0]))
         comptable['classification'] = 'accepted'

tedana/model/__init__.py

@@ -2,8 +2,8 @@
 # ex: set sts=4 ts=4 sw=4 et:
 
 from .fit import (
-    fitmodels_direct, get_coeffs, computefeats2
+    dependence_metrics, kundu_metrics, get_coeffs, computefeats2
 )
 
 __all__ = [
-    'fitmodels_direct', 'get_coeffs', 'computefeats2']
+    'dependence_metrics', 'kundu_metrics', 'get_coeffs', 'computefeats2']