Merge remote-tracking branch 'upstream/main'

Conflicts:
	tedana/workflows/tedana.py

.readthedocs.yml

@@ -6,7 +6,7 @@ sphinx:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.8"
+    python: "3.10"
   jobs:
     post_checkout:
       - git fetch --unshallow

docs/_static/decision_tree_meica.tex

@@ -0,0 +1,163 @@
+\documentclass[border=2pt]{standalone}
+\usepackage[utf8]{inputenc} % Required for inserting images
+\usepackage{tikz}
+\usepackage{helvet}
+\usetikzlibrary{shapes.geometric, arrows}
+\pagecolor{white}
+
+%-------------------------defining colorblind friendly colors
+% Using pale color scheme in Figure 6 
+% by Paul Tol https://personal.sron.nl/~pault/
+\definecolor{cbblue}{HTML}{BBCCEE}
+\definecolor{cbcyan}{HTML}{CCEEFF}
+\definecolor{cbgreen}{HTML}{CCDDAA}
+\definecolor{cbyellow}{HTML}{EEEEBB}
+\definecolor{cbred}{HTML}{FFCCCC}
+\definecolor{cbgrey}{HTML}{DDDDDD}
+
+% -------------------------defining nodes 
+\tikzstyle{input} = [trapezium, trapezium left angle =80, trapezium right angle = 100,
+minimum width= 3cm, minimum height=0.5cm, text centered, draw=black, fill=cbblue]
+\tikzstyle{process} = [rectangle, minimum width = 3cm, minimum height = 1cm,
+text centered, , text width=4cm,draw=black, fill=cbgrey]
+\tikzstyle{decision} = [diamond, minimum width = 3cm, minimum height = 1cm,
+text centered, , text width=3.5cm, draw=black, fill=cbcyan]
+\tikzstyle{changeclass} = [rectangle, rounded corners, minimum width=3cm, minimum height=1cm,
+text centered, draw = black, fill=cbyellow]
+\tikzstyle{reject} = [trapezium, trapezium left angle =80, trapezium right angle = 100,
+minimum width= 1cm, minimum height=0.5cm, text centered, draw=black, fill=cbred]
+\tikzstyle{accept} = [trapezium, trapezium left angle =80, trapezium right angle = 100,
+minimum width= 1cm, minimum height=0.5cm, text centered, draw=black, fill=cbgreen]
+
+% -------------------------defining connectors
+\tikzstyle{arrow} = [thick,->, >=stealth]
+\tikzstyle{line} = [thick,-,>=stealth]
+\begin{document}
+
+% ------------------------- tikz image (flow chart)
+\begin{tikzpicture}[node distance = 2cm]
+
+% ------------------------- nodes -------------------------
+
+% ----- node: 0
+\node(0)[input, label={90:\textbf{MEICA Decision Tree}}, label={180:$node\ 0$}] {Set all components to unclassified};
+% ----- node: 1
+\node(1)[decision, below of=0,label={180:$node\ 1$}, yshift=-1.0cm]{$\rho$ $>$ $\kappa$};
+\node(rej0)[reject, right of=1, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
+% ----- node: 2
+\node(2)[decision, below of=1,label={180:$node\ 2$} ,label={[align=center] 315: voxel counts for signif fit\\of multi-echo data\\to $T_2$ or $S_0$ decay models}, yshift=-3.0cm]{$n \, FS_0 \, > \, n \, FT_2$ \& $n \,FT_2$ $>$ 0};
+\node(rej1)[reject, right of=2, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
+% ----- node: 3
+\node(3)[process, below of=2, label={180:$node\ 3$}, label={[align=center] 315: varex: variance explained\\by each component}, yshift=-1.5cm]{Calculate median(varex) across all components};
+% ----- node: 4
+\node(4)[decision, below of=3,label={180:$node\ 4$},label={[align=center] 315:DICE overlap between $T_2$ or $S_0$\\decay models and ICA component\\peak clusters}, yshift=-1.5cm]{dice $FS_0$ $>$ dice $FT_2$ \& varex $>$ median(varex)
+};
+\node(rej2)[reject, right of=4, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
+% ----- node: 5
+\node(5)[decision, below of=4,label={180:$node\ 5$}, label={[align=center] 315: $t-statistic$ of $FT_2$ values\\in component peak clusters vs\\peak voxels outside of clusters}, yshift=-3.5cm]{ $0 \, >$ signal-noise \&  varex $>$ median(varex)};
+\node(rej3)[reject, right of=5, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
+% ----- node: 6
+\node(6)[process, below of=5, label={180:$node\ 6$}, label={0: Uses all components}, yshift=-1.5cm]{Calculate $\kappa$ elbow};
+% ----- node: 7
+\node(7)[process, below of=6, label={180:$node\ 7$}, yshift=-0.0cm]{Identify and exclude $\leq$3 highest variance unclassified components from some $\rho$ elbow calculations};
+% ----- node: 8
+\node(8)[process, below of=7, label={180:$node\ 8$}, label={[align=center] 0: Uses all components and subset\\of unclassified components}]{Calculate $\rho$ elbow\\(kundu method)};
+% ----- node: 9
+\node(9)[decision, below of=8,label={180:$node\ 9$}, yshift=-1.5cm]{$\kappa \geq \kappa$ elbow};
+\node(rej4)[changeclass, right of=9, xshift=3cm]{Provisional accept};
+% ----- node: 10
+\node(10)[decision, below of=9,label={180:$node\ 10$}, yshift=-3.0cm]{$\rho > \rho$ elbow  };
+\node(rej5)[changeclass, right of=10, xshift=3cm]{Unclassified};
+% ----- node: 11
+\node(11)[decision, below of=10, label={180:$node\ 11$}, yshift=-3.5cm]{ \textit{n} classified as $Provisional\ accept < 2$};
+\node(rej6)[input, right of=11, xshift=4cm, align=center]{Rerun ICA, metric calcs,\\\& component selection.\\If max restarts reached,\\accept everything\\not already rejected};
+% ----- node: 12
+\node(12)[process, below of=11,label={180:$node\ 12$},label={0: $90^{th}$ percentile threshold}, yshift=-1.7cm]{Calculate upper varex on provionally accepted components};
+% ----- node: 13
+\node(13)[process, below of=12,label={180:$node\ 13$}, label={0: $25^{th}$ percentile threshold},]{Calculate lower varex on provionally accepted components};
+% ----- node: 14
+\node(14)[process, below of=13,label={180:$node\ 14$}, label={[align=center] 0:$\lceil 2:3 \rceil$ depending on the\\number of fMRI volumes}]{Calculate extend factor};
+% ----- node: 15
+\node(15)[process, below of=14,label={180:$node\ 15$},label={[align=center] 0: \textit{n} Provisional accept\\$*$ extend factor}]{Calculate max good mean metric rank};
+% ----- node: 16
+\node(16)[process, below of=15, label={180:$node\ 16$}, label={[align=center] 0: $\frac{(max-min \, \kappa) \, \div \kappa}{(max-min \, varex) \div varex}$}]{Calculate $\kappa$ ratio on provionally accepted components};
+% ----- node: 17
+\node(17)[decision, below of=16,label={180:$node\ 17$},label={315:variance \& mean metric rank are high}, yshift=-2.5cm]{mean metric rank $>$ max good mean metric rank \& varex$>$extend factor * upper varex};
+\node(rej7)[reject, right of=17, xshift=4cm, align=center]{Less likely BOLD\\$\rightarrow$ Reject};
+% ----- node: 18
+\node(18)[decision, below of=17,label={180:$node\ 18$},label={[align=center] 315: Accept if remaining component\\is less likely to be BOLD,\\but varex is low \& not worth\\losing a degree of freedom for}, yshift=-4.5cm]{mean metric rank $>$ \textit{n} max good mean metric rank \& varex $\leq$ lower varex \& $\kappa$ $\leq \, \kappa$ elbow };
+\node(rej8)[accept, right of=18, xshift=4cm, align=center]{Low variance\\$\rightarrow$ Accept};
+% ----- node: 19
+\node(19)[decision, below of=18,label={180:$node\ 19$},label={315: Nothing unclassified remains}, yshift=-4.0cm]{\textit{n} Unclassified $==0$};
+\node(rej9)[accept, right of=19, xshift=3cm, align=center]{Provisional accept\\$\rightarrow$ Accept};
+% ----- node: 20
+\node(20)[process, below of=19, label={180:$node\ 20$},yshift=-2.0cm, label={[align=center] 315: \textit{n} accepted guess =\\$\frac{\sum(\kappa > \kappa\, elbow\, \&\, \rho > \rho\, elbow)+ \sum(\kappa > \kappa\, elbow)}{2}$}]{Calculate new mean metric ranks and \textit{n} accepted guess on remaining unclassified and provisionally accepted components};
+% ----- node: 21
+\node(21)[decision, below of=20,label={180:$node\ 21$}, yshift=-3.5cm]{new mean metric rank $>$ (\textit{n} accepted guess)/2 \& varex $\kappa$ ratio $>$ 2 entend factor \& varex $>$ 2 upper varex};
+\node(rej10)[changeclass, right of=21, xshift=4cm, align=center]{Less likely BOLD\\$\rightarrow$ Provisional Reject};
+% ----- node: 22
+\node(22)[decision, below of=21,label={180:$node\ 22$}, yshift=-5cm]{new mean metric rank $>$ 0.9*\textit{n} accepted guess \& varex $>$  (lower varex * extend factor)};
+\node(rej11)[changeclass, right of=22, xshift=4cm, align=center]{Less likely BOLD\\$\rightarrow$ Provisional Reject};
+% ----- node: 23
+\node(23)[process, below of=22,label={180:$node\ 23$}, label={[align=center] 220: $25^{th}$ percentile variance\\explained from remaining\\non-rejected components},yshift=-2cm]{Calculate new lower varex};
+% ----- node: 24
+\node(24)[decision, below of=23,label={180:$node\ 24$}, yshift=-2.5cm]{new mean metric rank $>$ \textit{n} accepted guess \& varex $>$ new lower varex};
+\node(rej12)[accept, right of= 24, xshift=4cm, align=center]{Accept borderline\\$\rightarrow$Accept};
+% ----- node: 25
+\node(25)[decision, below of=24,label={180:$node\ 25$}, yshift=-3.5cm]{ $\kappa$ $>$ $\kappa$ elbow \& varex $>$ new lower varex};
+\node(rej13)[accept, right of=25, xshift=3cm, align=center]{Accept borderline\\$\rightarrow$Accept};
+% ----- node: 26
+\node(26)[reject, below of=25,label={180:$node\ 26$}, yshift=-1cm, align=center]{Remaining Provisional Reject $\rightarrow$ Reject};
+% ----- node: 27
+\node(27)[accept, below of=26,label={180:$node\ 27$}, yshift=0.8cm, align=center]{Remaining Unclassified \& Provisional accept\\$\rightarrow$ Likely BOLD $\rightarrow$ Accept};
+
+% ------------------------- connections -------------------------
+% draw[x](origin)--node[anchor=position]{text}(destination);
+\draw[arrow](0)--(1);
+\draw[arrow](1)--(2);
+\draw[arrow](2)--(3);
+\draw[arrow](3)--(4);
+\draw[arrow](4)--(5);
+\draw[arrow](5)--(6);
+\draw[arrow](6)--(7);
+\draw[arrow](7)--(8);
+\draw[arrow](8)--(9);
+\draw[arrow](9)--(10);
+\draw[arrow](10)--(11);
+\draw[arrow](11)--(12);
+\draw[arrow](12)--(13);
+\draw[arrow](13)--(14);
+\draw[arrow](14)--(15);
+\draw[arrow](15)--(16);
+\draw[arrow](16)--(17);
+\draw[arrow](17)--(18);
+\draw[arrow](18)--(19);
+\draw[arrow](19)--(20);
+\draw[arrow](20)--(21);
+\draw[arrow](21)--(22);
+\draw[arrow](22)--(23);
+\draw[arrow](rej10)--(22);
+\draw[arrow](23)--(24);
+\draw[arrow](rej11)--(23);
+\draw[arrow](rej11)--(24);
+\draw[arrow](24)--(25);
+\draw[arrow](25)--(26);
+\draw[arrow](26)--(27);
+\draw[arrow](1)--node[anchor=south] {yes} (rej0);
+\draw[arrow](2)--node[anchor=south] {yes} (rej1);
+\draw[arrow](4)--node[anchor=south] {yes} (rej2);
+\draw[arrow](5)--node[anchor=south] {yes} (rej3);
+\draw[arrow](9)--node[anchor=south] {yes} (rej4);
+\draw[arrow](rej4)--(10);
+\draw[arrow](10)--node[anchor=south] {yes} (rej5);
+\draw[arrow](rej5)--(11);
+\draw[arrow](11)--node[anchor=south] {yes} (rej6);
+\draw[arrow](17)--node[anchor=south] {yes} (rej7);
+\draw[arrow](18)--node[anchor=south] {yes} (rej8);
+\draw[arrow](19)--node[anchor=south] {yes} (rej9);
+\draw[arrow](21)--node[anchor=south] {yes} (rej10);
+\draw[arrow](22)--node[anchor=south] {yes} (rej11);
+\draw[arrow](24)--node[anchor=south] {yes} (rej12);
+\draw[arrow](25)--node[anchor=south] {yes} (rej13);
+\end{tikzpicture}
+\end{document}

docs/_static/decision_tree_kundu.tex → docs/_static/decision_tree_tedana_orig.tex

@@ -40,7 +40,7 @@
 % ------------------------- nodes -------------------------
 
 % ----- node: 0
-\node(0)[input, label={90:\textbf{Kundu Decision Tree (Tedana implementation)}}, label={180:$node\ 0$}] {Set all components to unclassified};
+\node(0)[input, label={90:\textbf{tedana v0.013 Decision Tree}}, label={180:$node\ 0$}] {Set all components to unclassified};
 % ----- node: 1
 \node(1)[decision, below of=0,label={180:$node\ 1$}, yshift=-1.5cm]{$\rho$ $>$ $\kappa$};
 \node(rej0)[reject, right of=1, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};

docs/approach.rst

@@ -348,8 +348,8 @@ classify ICA components as TE-dependent (BOLD signal), TE-independent
 (non-BOLD noise), or neither (to be ignored).
 These classifications are saved in **desc-tedana_metrics.tsv**.
 The actual decision tree is dependent on the component selection algorithm employed.
-``tedana`` includes two options `kundu` and `minimal` (which uses hardcoded thresholds
-applied to each of the metrics). `These decision trees are detailed here`_.
+``tedana`` includes three options `tedana_orig`, `meica` and `minimal` (which uses hardcoded
+thresholds applied to each of the metrics). `These decision trees are detailed here`_.
 
 Components that are classified as noise are projected out of the optimally combined data,
 yielding a denoised timeseries, which is saved as **desc-optcomDenoised_bold.nii.gz**.

docs/building_decision_trees.rst

@@ -51,7 +51,7 @@ The file key names are used below the full file names in the
 General outputs from component selection
 ========================================
 
-New columns in ``selector.component_table`` and the "ICA metrics tsv" file:
+New columns in ``selector.component_table_`` and the "ICA metrics tsv" file:
 
   - classification:
     While the decision table is running, there may also be intermediate
@@ -63,13 +63,13 @@ New columns in ``selector.component_table`` and the "ICA metrics tsv" file:
     or a comma separated list of tags. These tags may be useful parameters
     for visualizing and reviewing results
 
-``selector.cross_component_metrics`` and "ICA cross component metrics json":
+``selector.cross_component_metrics_`` and "ICA cross component metrics json":
   A dictionary of metrics that are each a single value calculated across components,
   for example, kappa and rho elbows. User or pre-defined scaling factors are
   also stored here. Any constant that is used in the component classification
   processes that isn't pre-defined in the decision tree file should be saved here.
 
-``selector.component_status_table`` and "ICA status table tsv":
+``selector.component_status_table_`` and "ICA status table tsv":
   A table where each column lists the classification status of
   each component after each node was run. Columns are only added
   for runs where component statuses can change.
@@ -139,8 +139,8 @@ Each outputs field includes:
     It is possible to add a new metric to the component table during the selection process.
     This is useful if a metric is to be calculated on a subset of components based on what
     happened during previous steps in the selection process. This is **not** recommended,
-    but since it was done as part of the original kundu decision tree process defined in
-    meica it is possible.
+    but, since it was done as part of the original decision tree process used in the
+    meica and tedana_orig, it is possible.
 
 
 **************************************
@@ -160,7 +160,7 @@ Defining a custom decision tree
 Decision trees are stored in json files. The default trees are stored as part of
 the tedana code repository in `resources/decision_trees`_. The minimal tree,
 minimal.json, is a good example highlighting the structure and steps in a tree. It
-may be helpful to look at that tree while reading this section. kundu.json replicates
+may be helpful to look at that tree while reading this section. meica.json replicates
 the decision tree used in MEICA version 2.5, the predecessor to tedana. It is more
 complex, but also highlights additional possible functionality in decision trees.
 
@@ -210,11 +210,9 @@ that is used to check whether results are plausible & can help avoid mistakes.
 
 - necessary_metrics
     A list of the necessary metrics in the component table that will be used
-    by the tree. If a metric doesn't exist then this will raise an error instead
-    of executing a tree. (Depending on future code development, this could
-    potentially be used to run ``tedana`` by specifying a decision tree and
-    metrics are calculated based on the contents of this field.) If a necessary
-    metric isn't used, there will be a warning.
+    by the tree. This field defines what metrics will be calculated on each ICA
+    component. If a metric doesn't exist then this will raise an error instead
+    of executing a tree. If a necessary metric isn't used, there will be a warning.
 
 - generated_metrics
     An optional initial field. It lists metrics that are to be calculated as
@@ -223,7 +221,7 @@ that is used to check whether results are plausible & can help avoid mistakes.
     an error when these metrics are not found. One might want to calculate a new metric
     if the metric uses only a subset of the components based on previous
     classifications. This does make interpretation of results more confusing, but, since
-    this functionality was part of the kundu decision tree, it is included.
+    this functionality is part of the tedana_orig and meica decision trees, it is included.
 
 - intermediate_classifications
     A list of intermediate classifications (i.e. "provisionalaccept",
@@ -315,7 +313,7 @@ are good examples for how to meet these expectations.
 
 Create a dictionary called "outputs" that includes key fields that should be recorded.
 The following line should be at the end of each function to retain the output info:
-``selector.nodes[selector.current_node_idx]["outputs"] = outputs``
+``selector.nodes[selector.current_node_idx_]["outputs"] = outputs``
 
 Additional fields can be used to log function-specific information, but the following
 fields are common and may be used by other parts of the code:
@@ -339,7 +337,7 @@ Before any data are touched in the function, there should be an
 call. This will be useful to gather all metrics a tree will use without requiring a
 specific dataset.
 
-Existing functions define ``function_name_idx = f"Step {selector.current_node_idx}: [text of function_name]``.
+Existing functions define ``function_name_idx = f"Step {selector.current_node_idx_}: [text of function_name]``.
 This is used in logging and is cleaner to initialize near the top of each function.
 
 Each function has code that creates a default node label in ``outputs["node_label"]``.
@@ -378,15 +376,15 @@ dataframe column that is True or False for the components in ``decide_comps`` ba
 the function's criteria.
 That column is an input to :func:`~tedana.selection.selection_utils.change_comptable_classifications`,
 which will update the component_table classifications, update the classification history
-in component_status_table, and update the component classification_tags. Components not
+in ``selector.component_status_table_``, and update the component classification_tags. Components not
 in ``decide_comps`` retain their existing classifications and tags.
 :func:`~tedana.selection.selection_utils.change_comptable_classifications`
 also returns and should assign values to
 ``outputs["n_true"]`` and ``outputs["n_false"]``. These log how many components were
 identified as true or false within each function.
 
 For calculation functions, the calculated values should be added as a value/key pair to
-both ``selector.cross_component_metrics`` and ``outputs``.
+both ``selector.cross_component_metrics_`` and ``outputs``.
 
 :func:`~tedana.selection.selection_utils.log_decision_tree_step`
 puts the relevant info from the function call into the program's output log.
@@ -395,7 +393,7 @@ Every function should end with:
 
 .. code-block:: python
 
-  selector.nodes[selector.current_node_idx]["outputs"] = outputs
+  selector.nodes[selector.current_node_idx_]["outputs"] = outputs
   return selector
 
   functionname.__doc__ = (functionname.__doc__.format(**DECISION_DOCS))