Skip to content

Commit f084dc4

Browse files
handwerkerdtsalo
handwerkerd
and
tsalo
authored
Align with old meica (#952)
* logging MAPCA subsampling * Align with old meica * Added provisionalreject to reject node * Add comments to the minimal decision tree. * Improve comments. * Move from comments to log_extra_report. * Add comments and fix one description. * Update minimal.json * Retain artifacts. * Store correct artifact path. * Test minimal decision tree. * Add newlines. * Update tedana.py * Update tedana.py * Keep documenting the trees. * Update minimal.json * Fix decision tree description. * Document the remaining nodes in the kundu tree. * Fix manrej typo. * Cite Olafsson paper for decision tree nodes. * Updated to include meica and tedana_v0.013 trees * updated minimal.json and started references.bib * Merge 'upstream/main' into doc-tree-dh * aligning to main again * test-component_selector * edited comments. added DOIs. Removed log_extra_reports * fixed references for decision trees * solved citep issue and edited decision tree doi * Fixed citep for olafsson * removed figshare url that excluded version number * Apply suggestions from code review Co-authored-by: Taylor Salo <[email protected]> * add warning for log_extra_report * rename tedana_v0.013 tedana_orig * merged with doc-tree and cleaned up decision trees * cleaning up decision trees * changed kundu tree to warning * Documentation updates * unrelated docstring fix * fixed faq typo --------- Co-authored-by: Taylor Salo <[email protected]> Co-authored-by: Taylor Salo <[email protected]>
1 parent 9cbd484 commit f084dc4

18 files changed

+731
-285
lines changed

‎docs/_static/decision_tree_kundu.png‎

-176 KB
Binary file not shown.

‎docs/_static/decision_tree_meica.png‎

647 KB
Loading

‎docs/_static/decision_tree_meica.tex‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
\documentclass[border=2pt]{standalone}
2+
\usepackage[utf8]{inputenc} % Required for inserting images
3+
\usepackage{tikz}
4+
\usepackage{helvet}
5+
\usetikzlibrary{shapes.geometric, arrows}
6+
\pagecolor{white}
7+
8+
%-------------------------defining colorblind friendly colors
9+
% Using pale color scheme in Figure 6
10+
% by Paul Tol https://personal.sron.nl/~pault/
11+
\definecolor{cbblue}{HTML}{BBCCEE}
12+
\definecolor{cbcyan}{HTML}{CCEEFF}
13+
\definecolor{cbgreen}{HTML}{CCDDAA}
14+
\definecolor{cbyellow}{HTML}{EEEEBB}
15+
\definecolor{cbred}{HTML}{FFCCCC}
16+
\definecolor{cbgrey}{HTML}{DDDDDD}
17+
18+
% -------------------------defining nodes
19+
\tikzstyle{input} = [trapezium, trapezium left angle =80, trapezium right angle = 100,
20+
minimum width= 3cm, minimum height=0.5cm, text centered, draw=black, fill=cbblue]
21+
\tikzstyle{process} = [rectangle, minimum width = 3cm, minimum height = 1cm,
22+
text centered, , text width=4cm,draw=black, fill=cbgrey]
23+
\tikzstyle{decision} = [diamond, minimum width = 3cm, minimum height = 1cm,
24+
text centered, , text width=3.5cm, draw=black, fill=cbcyan]
25+
\tikzstyle{changeclass} = [rectangle, rounded corners, minimum width=3cm, minimum height=1cm,
26+
text centered, draw = black, fill=cbyellow]
27+
\tikzstyle{reject} = [trapezium, trapezium left angle =80, trapezium right angle = 100,
28+
minimum width= 1cm, minimum height=0.5cm, text centered, draw=black, fill=cbred]
29+
\tikzstyle{accept} = [trapezium, trapezium left angle =80, trapezium right angle = 100,
30+
minimum width= 1cm, minimum height=0.5cm, text centered, draw=black, fill=cbgreen]
31+
32+
% -------------------------defining connectors
33+
\tikzstyle{arrow} = [thick,->, >=stealth]
34+
\tikzstyle{line} = [thick,-,>=stealth]
35+
\begin{document}
36+
37+
% ------------------------- tikz image (flow chart)
38+
\begin{tikzpicture}[node distance = 2cm]
39+
40+
% ------------------------- nodes -------------------------
41+
42+
% ----- node: 0
43+
\node(0)[input, label={90:\textbf{MEICA Decision Tree}}, label={180:$node\ 0$}] {Set all components to unclassified};
44+
% ----- node: 1
45+
\node(1)[decision, below of=0,label={180:$node\ 1$}, yshift=-1.0cm]{$\rho$ $>$ $\kappa$};
46+
\node(rej0)[reject, right of=1, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
47+
% ----- node: 2
48+
\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};
49+
\node(rej1)[reject, right of=2, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
50+
% ----- node: 3
51+
\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};
52+
% ----- node: 4
53+
\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)
54+
};
55+
\node(rej2)[reject, right of=4, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
56+
% ----- node: 5
57+
\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)};
58+
\node(rej3)[reject, right of=5, xshift=3cm, align=center]{Unlikely BOLD\\$\rightarrow$ Reject};
59+
% ----- node: 6
60+
\node(6)[process, below of=5, label={180:$node\ 6$}, label={0: Uses all components}, yshift=-1.5cm]{Calculate $\kappa$ elbow};
61+
% ----- node: 7
62+
\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};
63+
% ----- node: 8
64+
\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)};
65+
% ----- node: 9
66+
\node(9)[decision, below of=8,label={180:$node\ 9$}, yshift=-1.5cm]{$\kappa \geq \kappa$ elbow};
67+
\node(rej4)[changeclass, right of=9, xshift=3cm]{Provisional accept};
68+
% ----- node: 10
69+
\node(10)[decision, below of=9,label={180:$node\ 10$}, yshift=-3.0cm]{$\rho > \rho$ elbow };
70+
\node(rej5)[changeclass, right of=10, xshift=3cm]{Unclassified};
71+
% ----- node: 11
72+
\node(11)[decision, below of=10, label={180:$node\ 11$}, yshift=-3.5cm]{ \textit{n} classified as $Provisional\ accept < 2$};
73+
\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};
74+
% ----- node: 12
75+
\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};
76+
% ----- node: 13
77+
\node(13)[process, below of=12,label={180:$node\ 13$}, label={0: $25^{th}$ percentile threshold},]{Calculate lower varex on provionally accepted components};
78+
% ----- node: 14
79+
\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};
80+
% ----- node: 15
81+
\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};
82+
% ----- node: 16
83+
\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};
84+
% ----- node: 17
85+
\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};
86+
\node(rej7)[reject, right of=17, xshift=4cm, align=center]{Less likely BOLD\\$\rightarrow$ Reject};
87+
% ----- node: 18
88+
\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 };
89+
\node(rej8)[accept, right of=18, xshift=4cm, align=center]{Low variance\\$\rightarrow$ Accept};
90+
% ----- node: 19
91+
\node(19)[decision, below of=18,label={180:$node\ 19$},label={315: Nothing unclassified remains}, yshift=-4.0cm]{\textit{n} Unclassified $==0$};
92+
\node(rej9)[accept, right of=19, xshift=3cm, align=center]{Provisional accept\\$\rightarrow$ Accept};
93+
% ----- node: 20
94+
\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};
95+
% ----- node: 21
96+
\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};
97+
\node(rej10)[changeclass, right of=21, xshift=4cm, align=center]{Less likely BOLD\\$\rightarrow$ Provisional Reject};
98+
% ----- node: 22
99+
\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)};
100+
\node(rej11)[changeclass, right of=22, xshift=4cm, align=center]{Less likely BOLD\\$\rightarrow$ Provisional Reject};
101+
% ----- node: 23
102+
\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};
103+
% ----- node: 24
104+
\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};
105+
\node(rej12)[accept, right of= 24, xshift=4cm, align=center]{Accept borderline\\$\rightarrow$Accept};
106+
% ----- node: 25
107+
\node(25)[decision, below of=24,label={180:$node\ 25$}, yshift=-3.5cm]{ $\kappa$ $>$ $\kappa$ elbow \& varex $>$ new lower varex};
108+
\node(rej13)[accept, right of=25, xshift=3cm, align=center]{Accept borderline\\$\rightarrow$Accept};
109+
% ----- node: 26
110+
\node(26)[reject, below of=25,label={180:$node\ 26$}, yshift=-1cm, align=center]{Remaining Provisional Reject $\rightarrow$ Reject};
111+
% ----- node: 27
112+
\node(27)[accept, below of=26,label={180:$node\ 27$}, yshift=0.8cm, align=center]{Remaining Unclassified \& Provisional accept\\$\rightarrow$ Likely BOLD $\rightarrow$ Accept};
113+
114+
% ------------------------- connections -------------------------
115+
% draw[x](origin)--node[anchor=position]{text}(destination);
116+
\draw[arrow](0)--(1);
117+
\draw[arrow](1)--(2);
118+
\draw[arrow](2)--(3);
119+
\draw[arrow](3)--(4);
120+
\draw[arrow](4)--(5);
121+
\draw[arrow](5)--(6);
122+
\draw[arrow](6)--(7);
123+
\draw[arrow](7)--(8);
124+
\draw[arrow](8)--(9);
125+
\draw[arrow](9)--(10);
126+
\draw[arrow](10)--(11);
127+
\draw[arrow](11)--(12);
128+
\draw[arrow](12)--(13);
129+
\draw[arrow](13)--(14);
130+
\draw[arrow](14)--(15);
131+
\draw[arrow](15)--(16);
132+
\draw[arrow](16)--(17);
133+
\draw[arrow](17)--(18);
134+
\draw[arrow](18)--(19);
135+
\draw[arrow](19)--(20);
136+
\draw[arrow](20)--(21);
137+
\draw[arrow](21)--(22);
138+
\draw[arrow](22)--(23);
139+
\draw[arrow](rej10)--(22);
140+
\draw[arrow](23)--(24);
141+
\draw[arrow](rej11)--(23);
142+
\draw[arrow](rej11)--(24);
143+
\draw[arrow](24)--(25);
144+
\draw[arrow](25)--(26);
145+
\draw[arrow](26)--(27);
146+
\draw[arrow](1)--node[anchor=south] {yes} (rej0);
147+
\draw[arrow](2)--node[anchor=south] {yes} (rej1);
148+
\draw[arrow](4)--node[anchor=south] {yes} (rej2);
149+
\draw[arrow](5)--node[anchor=south] {yes} (rej3);
150+
\draw[arrow](9)--node[anchor=south] {yes} (rej4);
151+
\draw[arrow](rej4)--(10);
152+
\draw[arrow](10)--node[anchor=south] {yes} (rej5);
153+
\draw[arrow](rej5)--(11);
154+
\draw[arrow](11)--node[anchor=south] {yes} (rej6);
155+
\draw[arrow](17)--node[anchor=south] {yes} (rej7);
156+
\draw[arrow](18)--node[anchor=south] {yes} (rej8);
157+
\draw[arrow](19)--node[anchor=south] {yes} (rej9);
158+
\draw[arrow](21)--node[anchor=south] {yes} (rej10);
159+
\draw[arrow](22)--node[anchor=south] {yes} (rej11);
160+
\draw[arrow](24)--node[anchor=south] {yes} (rej12);
161+
\draw[arrow](25)--node[anchor=south] {yes} (rej13);
162+
\end{tikzpicture}
163+
\end{document}

‎docs/_static/decision_tree_tedana_orig.png‎

630 KB
Loading

docs/_static/decision_tree_kundu.tex renamed to docs/_static/decision_tree_tedana_orig.tex

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@
4040
% ------------------------- nodes -------------------------
4141

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

‎docs/approach.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -348,8 +348,8 @@ classify ICA components as TE-dependent (BOLD signal), TE-independent
348348
(non-BOLD noise), or neither (to be ignored).
349349
These classifications are saved in **desc-tedana_metrics.tsv**.
350350
The actual decision tree is dependent on the component selection algorithm employed.
351-
``tedana`` includes two options `kundu` and `minimal` (which uses hardcoded thresholds
352-
applied to each of the metrics). `These decision trees are detailed here`_.
351+
``tedana`` includes three options `tedana_orig`, `meica` and `minimal` (which uses hardcoded
352+
thresholds applied to each of the metrics). `These decision trees are detailed here`_.
353353

354354
Components that are classified as noise are projected out of the optimally combined data,
355355
yielding a denoised timeseries, which is saved as **desc-optcomDenoised_bold.nii.gz**.

‎docs/building_decision_trees.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,8 @@ Each outputs field includes:
139139
It is possible to add a new metric to the component table during the selection process.
140140
This is useful if a metric is to be calculated on a subset of components based on what
141141
happened during previous steps in the selection process. This is **not** recommended,
142-
but since it was done as part of the original kundu decision tree process defined in
143-
meica it is possible.
142+
but, since it was done as part of the original decision tree process used in the
143+
meica and tedana_orig, it is possible.
144144

145145

146146
**************************************
@@ -160,7 +160,7 @@ Defining a custom decision tree
160160
Decision trees are stored in json files. The default trees are stored as part of
161161
the tedana code repository in `resources/decision_trees`_. The minimal tree,
162162
minimal.json, is a good example highlighting the structure and steps in a tree. It
163-
may be helpful to look at that tree while reading this section. kundu.json replicates
163+
may be helpful to look at that tree while reading this section. meica.json replicates
164164
the decision tree used in MEICA version 2.5, the predecessor to tedana. It is more
165165
complex, but also highlights additional possible functionality in decision trees.
166166

@@ -221,7 +221,7 @@ that is used to check whether results are plausible & can help avoid mistakes.
221221
an error when these metrics are not found. One might want to calculate a new metric
222222
if the metric uses only a subset of the components based on previous
223223
classifications. This does make interpretation of results more confusing, but, since
224-
this functionality was part of the kundu decision tree, it is included.
224+
this functionality is part of the tedana_orig and meica decision trees, it is included.
225225

226226
- intermediate_classifications
227227
A list of intermediate classifications (i.e. "provisionalaccept",

0 commit comments

Comments
 (0)