updated the toolkit document

jessdtate · jessdtate · commit efe629f31b79 · 2017-09-15T15:54:46.000-06:00
diff --git a/Documentation/ECGTool_forward.tex b/Documentation/ECGTool_forward.tex
@@ -4,7 +4,7 @@ \section{Overview}
 
 As described previously, the forward problem predicts the potentials observed along some measurement surface (commonly the body surface) given a set of known electrical sources and the geometry through which those source fields conduct. In this chapter, we will provide an overview of the forward problem as it is implemented in the Fwd/Inv toolkit, which generally calculates torso surface potentials given a set of known cardiac source parameters. Of course, these toolkit networks can be manipulated to incorporate other source models (\eg{} brain potentials or transmural cardiac potentials) or solution representations (\eg{} scalp or epicardial potentials) as needed. 
 
-The forward problem can be broken down into two fundamental concepts: 1) how to represent the source and 2) how that source maps to desired observation locations (\eg{} torso surface). One can conceptualize these two concepts in the classic sense by considering the function $(A)x = b$,  where $b$ represents a set of unknowns on the torso surface (observation locations) and $x$ is the cardiac source or source formulation. The function $A$, therefore, represents how source potentials are to be mapped to the observation field and is dependent on the choice of source model, the solution approach (\ie{} FEM/BEM), and relevant torso specific requirements such as conductivities and geometry.
+The forward problem can be broken down into two fundamental concepts: 1) how to represent the source and 2) how that source maps to desired observation locations (\eg{} torso surface). One can conceptualize these two concepts in the classic sense by considering the function $\mathbf{y}(t) = \mathbf{A}\mathbf{x}(t)$,  where $\mathbf{y}(t)$ (Eq.~\ref{eq:TransMat}) represents a set of unknowns on the torso surface (observation locations) and $\mathbf{x}(t)$ is the cardiac source or source formulation. The function $A$, therefore, represents how source potentials are to be mapped to the observation field and is dependent on the choice of source model, the solution approach (\ie{} FEM/BEM), and relevant torso specific requirements such as conductivities and geometry.
 
 The two most common source formulation models used in cardiac forward problems are cardiac potentials and activation times. The use of cardiac potentials is arguably a more intuitive formulation in that it is typically potentials that are recorded from cardiac-specific electrodes.  Activation times must be {\em derived} from recorded signals and are, therefore, one step removed from the original recordings.  In terms of abbreviated physiology, cardiac potentials relate the interaction of cardiac cells to changes in the extracellular potential fields of the myocardium. These extracellular cardiac potentials are then projected to the torso surface. The activation-time-based source formulation, on the other hand, deals with the fact that when inactive and active tissues exist in close proximity, a source much like a dipole or layer of dipoles can be generated that is representative of the propagating activation wavefront, which then projects to the torso surface. Both of these source models contain several assumptions, but each provides a generally accurate model that can be computationally reasonable.
 
@@ -110,20 +110,20 @@ \section{Module Descriptions for Finite Element Solutions}
 \begin{figure}[b]
 \begin{center}
 \includegraphics[width=\textwidth]{ECGToolkitGuide_figures/AddKnowns.png}
-\caption{{\bf AddKnownsToLinearSystem Module.} The {\tt AddKnownsToLinearSystem} module recalibrates  the stiffness matrix and RHS vector for a FE solution given known values in $\mathbf{x}$ and (optionally) $\mathbf{b}$.}
+\caption{{\bf AddKnownsToLinearSystem Module.} The {\tt AddKnownsToLinearSystem} module recalibrates  the stiffness matrix and RHS vector for a FE solution given known values in $\mathbf{x}(t)$ and (optionally) $\mathbf{y}(t)$.}
 \label{fig:AddKnowns}
 \end{center}
 \vspace{-.25 in}
 \end{figure}
 
 {\tt AddKnownsToLinearSystem} makes it possible to add known values as boundary conditions
-to the linear system $Ax=b$, where some values of
-$\mathbf{x}$ are already known. 
-The module receives the stiffness matrix $\mathbf{A}$ along with an $\mathbf{x}$ matrix with known values imposed at the specific indices where data is known and $NaN$ values occupying the remaining vector entries. 
+to the linear system $\mathbf{y}(t) = \mathbf{A}\mathbf{x}(t)$, where some values of
+$\mathbf{x(t)}$ are already known. 
+The module receives the stiffness matrix $\mathbf{A}$ along with an $\mathbf{x(t)}$ matrix with known values imposed at the specific indices where data is known and $NaN$ values occupying the remaining vector entries. 
 A right-hand-side (RHS) matrix may also be provided if any of the solution values are also known, but it is not required. 
 If an RHS field is not included then it is assumed that the vector contains all zeros. % | Is this true...it isn't NaNs?
 Using the provided inputs, the module adjusts the linear system according to the known values. 
-This means that $\mathbf{A}$ and the RHS vector $\mathbf{b}$ are altered in such a way that the product of the new stiffness matrix and RHS $\mathbf{(A2)^{-1}} \mathbf{b2}$ (referring to Figure \ref{fig:AddKnowns}) will produce an $\mathbf{x}$ that contains the defined values at the specified locations. 
+This means that $\mathbf{A}$ and the RHS vector $\mathbf{y}(t)$ are altered in such a way that the product of the new stiffness matrix and RHS $\mathbf{(A2)^{-1}} \mathbf{b2}$ (referring to Figure \ref{fig:AddKnowns}) will produce an $\mathbf{x(t)}$ that contains the defined values at the specified locations. 
 
 %\newpage
 \section{Example Networks for Boundary Element Solutions}
@@ -172,7 +172,7 @@ \section{Example Networks for Boundary Element Solutions}
 \section{Example Networks for Finite Element Solutions}
 
 There are two examples in the Fwd/Inv toolkit for calculating the potential-based forward problem using finite element method. The first example is a direct calculation of the projection of the cardiac potentials into the torso mesh, satisfying Laplace's equation, and from thence to the torso surface. 
-The second example involves the generation of the lead field matrix, or transfer matrix, that is then used  to perform the forward calculation that very much resembles the $\mathbf{Ax=b}$ formulation seen in the BEM method above.
+The second example involves the generation of the lead field matrix, or transfer matrix, that is then used  to perform the forward calculation that very much resembles the $\mathbf{y}(t) = \mathbf{A}\mathbf{x}(t)$ formulation seen in the BEM method above.
 
 \subsection{Potential Based Forward FEM Simulation: Laplacian Solve}
 
@@ -233,7 +233,7 @@ \subsection{Potential Based Forward FEM Simulation: Laplacian Solve}
 \subsection{Potential Based Forward FEM Simulation: Lead Field Calculation}
 
 The following example utilizes two networks in order to produce 1) a lead field matrix with which to solve 
-2) a traditional $\mathbf{Ax=b}$ forward solution. 
+2) a traditional $\mathbf{y}(t) = \mathbf{A}\mathbf{x}(t)$ forward solution. 
 Figure \ref{fig:FEMLead} shows a basic implementation of the finite element method used to calculate a lead field matrix and Figure \ref{fig:FEM_LeadNet} shows how that lead field matrix can be applied to generate a forward solution. 
 These networks also show the complete networks available in the Fwd/Inv toolkit in all their complexity.  
 Input meshes are segmentations that include multiple label masks (including one for the heart volume with a closed epicardium), which require manipulation prior to use. 
diff --git a/Documentation/ECGTool_inverse.tex b/Documentation/ECGTool_inverse.tex
@@ -10,7 +10,7 @@ \section{Descriptions of the Inverse Solution Methods Implemented in SCIRun}
 %%%%%%%%%%%%%%%%%%%%%%%
 \subsection{Tikhonov Regularization}\label{sec:inverse:tikhonov}
     
-    As described in \autoref{sec:math:standardTikhonov}, Tikhonov regularization is a classical inverse method that solves the following least squares problem:
+    As described in Sec.~\ref{sec:math_tikhonov}, Tikhonov regularization is a classical inverse method that solves the following least squares problem:
     \begin{center}
         \begin{eqnarray}
             min_{X} \| P (Y - A X) \|^{2}_{2} + \lambda^{2} \| RX \|^{2}_{2},
@@ -97,7 +97,7 @@ \subsection{Tikhonov Regularization}\label{sec:inverse:tikhonov}
     
     The solutions to the Tikhonov regularization problem depend on the selection of the regularization parameter ($\lambda$).
     There are multiple approaches in the literature that allow for its selection.
-    \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTikhonov}{{\tt SolveInverseProblemWithTikhonov}} is currently implemented so that the user can choose between a direct entry, selection using a slider and the L-curve method, described in \autoref{sec:math:regparam}.
+    \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTikhonov}{{\tt SolveInverseProblemWithTikhonov}} is currently implemented so that the user can choose between a direct entry, selection using a slider and the L-curve method, described in Sec.~\ref{sec:math_regparam}.
     These methods can be found by selecting the appropriate option in the drop-down menu within the ``Lambda Method'' panel.
     
     
@@ -167,7 +167,7 @@ \subsection{Tikhonov SVD Method}
     
     The solutions to the TikhonovSVD regularization problem depend on the selection of the regularization parameter ($\lambda$).
     There are multiple approaches in the literature that allow for its selection.
-    \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php5/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTikhonovSVD}{{\tt SolveInverseProblemWithTikhonovSVD}} is currently implemented so that the user can choose between a direct entry, selection using a slider and the L-curve method, described in \autoref{sec:math:regparam}.
+    \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php5/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTikhonovSVD}{{\tt SolveInverseProblemWithTikhonovSVD}} is currently implemented so that the user can choose between a direct entry, selection using a slider and the L-curve method, described in Sec.~\ref{sec:math_regparam}.
     These methods can be found by selecting the appropriate option in the drop-down menu within the ``Lambda Method'' panel as done in \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTikhonov}{{\tt SolveInverseProblemWithTikhonov}} (see \autoref{fig:tik_module_gui}).
     
     
@@ -237,7 +237,7 @@ \subsection{Truncated SVD Method (TSVD)}
     
     The solutions to the TSVD regularization problem depend on the selection of the regularization parameter ($Q$).
     There are multiple approaches in the literature that allow for its selection.
-    \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php5/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTSVD}{{\tt SolveInverseProblemWithTSVD}} is currently implemented so that the user can choose between a direct entry, selection using a slider and the L-curve method, described in \autoref{sec:math:regparam}.
+    \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php5/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTSVD}{{\tt SolveInverseProblemWithTSVD}} is currently implemented so that the user can choose between a direct entry, selection using a slider and the L-curve method, described in Sec.~\ref{sec:math_regparam}.
     These methods can be found by selecting the appropriate option in the drop-down menu within the ``Lambda Method'' panel as done in \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTikhonov}{{\tt SolveInverseProblemWithTikhonov}} (see \autoref{fig:tik_module_gui}).
 
 
@@ -283,13 +283,13 @@ \subsection{Isotropy Method}
     
     This implementation of the Isotropy Method has extra parameters that determine the operation of the Tikhonov inverse. These parameters are specific to the \href{http://scirundocwiki.sci.utah.edu/SCIRunDocs/index.php/CIBC:Documentation:SCIRun:Reference:BioPSE:SolveInverseProblemWithTikhonov}{{\tt SolveInverseProblemWithTikhonov}} module and we refer the user to \autoref{sec:inverse:tikhonov} for more details.
     
-    \begin{figure}
-        \begin{center}
-        \includegraphics[width=0.9\textwidth]{ECGToolkitGuide_figures/IsotropyMethod_networkExample.png}
-        \caption{The SCIRun network for the Isotropy Method inverse solution example.}
-        \label{fig:IsotropyMethod}
-        \end{center}
-    \end{figure}
+%    \begin{figure}
+%        \begin{center}
+%        \includegraphics[width=0.9\textwidth]{ECGToolkitGuide_figures/IsotropyMethod_networkExample.png}
+%        \caption{The SCIRun network for the Isotropy Method inverse solution example.}
+%        \label{fig:IsotropyMethod}
+%        \end{center}
+%    \end{figure}
     
    
 % \subsection{Spline-Based Inverse Method}
@@ -475,13 +475,13 @@ \subsection{Activation-Based Method}
     \end{enumerate}
     The only output of the method is the inverse solution in the form of an array of activation times.
     
-    \begin{figure}
-        \begin{center}
-        \includegraphics[width=0.9\textwidth]{ECGToolkitGuide_figures/activationBasedNetwork.png}
-        \caption{The SCIRun network for the Activation-Based Method inverse solution example.}
-        \label{fig:activationBasedNetwork}
-        \end{center}
-    \end{figure}
+%    \begin{figure}
+%        \begin{center}
+%        \includegraphics[width=0.9\textwidth]{ECGToolkitGuide_figures/activationBasedNetwork.png}
+%        \caption{The SCIRun network for the Activation-Based Method inverse solution example.}
+%        \label{fig:activationBasedNetwork}
+%        \end{center}
+%    \end{figure}
 
 
 % \subsection{Wavefront-Based Potential Reconstruction (WBPR)}
diff --git a/Documentation/ECGTool_math.tex b/Documentation/ECGTool_math.tex
@@ -286,7 +286,7 @@ \subsection{FEM in the Forward/Inverse Toolkit}
 source vectors consisting of a $1$ at each source node in turn and $0$ at
 all other source nodes \cite{JDT:Gul97}. From this collection of solutions we 
 can obtain the desired transfer matrix, which we will denote as $\mathbf{A}$ 
-as used in eq.~\ref{eg:TransMat}. 
+as used in eq.~\ref{eq:TransMat}. 
 This network is described below in Ch.~\ref{ch:fwd}.
 
 \subsection{BEM in the Forward/Inverse Toolkit}
@@ -410,6 +410,7 @@ \subsection{Potential-based Inverse Solutions in the Forward/Inverse Toolkit}
 are in Ch.~\ref{ch:inv}.
 
 \subsubsection{Standard Tikhonov regularization}
+\label{sec:math_tikhonov}
 
 The Tikhonov regularization minimizes $ \| Ax - y \|$ in order to solve $Ax=y$, 
 which is the same as eq.~\ref{eq:TransMat} with $x$ replacing $x(t)$ for the 
@@ -465,6 +466,7 @@ \subsubsection{Standard Tikhonov regularization}
 decomposition (SVD) of the matrix $\mathbf{A}$. The SVD results in several factor matrices, from which one then obtains the inverse solution. The SVD approach is also implemented in SCIRun and will be described below.
 
 \subsubsection{Choosing the regularization parameter:}
+\label{sec:math_regparam}
 
 Choosing an appropriate value as a regularization parameter is critical for achieving useful solutions.
 The solution typically depends on it in a sensitive fashion, and good
diff --git a/Documentation/ECGTool_overview.tex b/Documentation/ECGTool_overview.tex
@@ -1,5 +1,16 @@
 \chapter{Overview}
 
+\begin{figure}
+    \begin{center}
+    \includegraphics[width=0.75\textwidth]{ECGToolkitGuide_figures/fwd_inv_diag.pdf}
+    \caption{Forward and inverse problems in electrocardiology.  The forward simulation involves 
+        computing the torso potentials with know cardiac sources and torso geometry.  The inverse 
+        solution, called ECG Imaging (ECG) consists of inverting the forward model to calculate cardiac
+        sources from body surface recordings.}
+    \label{fig:fwdinv_diag}
+    \end{center}
+    \end{figure}
+    
 \begin{introduction}
 
 This guide describes and documents the SCIRun ECG Forward/Inverse
@@ -14,7 +25,8 @@ \chapter{Overview}
 
 The purpose of this toolkit is to advance the state of forward and inverse
 solutions in this field by offering a common platform for investigators and
-others to compare geometries and geometric representations, forward and inverse algorithms and data, with the maximum degree of both flexibility
+others to compare geometries and geometric representations, forward and 
+inverse algorithms and data, with the maximum degree of both flexibility
 and commonality that we can achieve. Thus, we hope to increase the
 "reproducibility'' of developments in this field and help
 move these technologies closer to useful clinical applications. As such, the
@@ -43,7 +55,7 @@ \chapter{Overview}
 \end{introduction}
 
 \section{Toolkit overview and capabilities}
-
+    
 Computational modeling of bioelectric fields often requires the solution of
 electrocardiographic or electroencephalographic forward and inverse
 problems in order to non-invasively analyze electrophysiological events
@@ -109,22 +121,24 @@ \section{Toolkit overview and capabilities}
 \hline
 {\bf Forward tools} & {\bf Inverse Tools}\\ \hline
 \hline
-Potential-Based FEM/BEM & Activation-Based$^{\&}$$^{*}$\\ \hline
-Activation-Based FEM$^{\dag}$ & Potential-Based Regularization  Methods\\ \hline
-FEM Lead Field Calculation &   -  Tikhonov  \\ \hline
-Stiffness Matrix Calculation &- Tikhonov SVD  \\ \hline
+Potential-Based FEM/BEM$^\dag$ & Activation-Based$^{\&*\ddag}$\\ \hline
+FEM Lead Field Calculation& Potential-Based Regularization  Methods\\ \hline
+Stiffness Matrix Calculation &   -  Tikhonov  \\ \hline
+ &- Tikhonov SVD  \\ \hline
  & - Truncated SVD\\ \hline
  & - Isotropy method$^{*}$\\ \hline
- & - Gauss-Newton Method$^{*}$\\ \hline
+ & - Gauss-Newton Method$^{*\ddag}$\\ \hline
  & - Wavefront based potential reconstruction$^*$\\ \hline
- & - Total Variation \\ \hline
+ & - Total Variation$^{*}$ \\ \hline
+ & - Method of Fundamental Solution (MFS) $^\ddag$\\ \hline
 \end{tabular}
 \caption{Algorithms currently included in the CIBC ECG Forward/Inverse
 toolkit \newline
-$^\dag$Activation-based BEM forward solution is currently
-unavailable in the toolkit \newline
+$^\dag$Activation-based forward solution is not yet
+unavailable\newline
 $^{\&}$Based on a Gauss-Newton optimization \newline
-$^{*}$Requires Matlab
+$^{*}$ Matlab implementation
+$^\ddag$ Python implementation
 }
 \label{tab:prop}
 \end{table}
