\graphicspath{ {./images/} }

\section{Overview}
We present ModFossa, a fast and easy-to-use Python library for creating and
simulating ion channel kinetics using continuous time Markov processes. A
discussion of ModFossa's features, components, design methodology, and
validation are provided in this chapter. Detailed class- and function-level
documentation for the both the C++ core, and the Python library can be found in
the Appendix. 

For those interested, the name ModFossa was formed from two Latin words ---
mod, and fossa, which can be interpreted as \emph{open channel} when written
together.


\section{Features}
\subsection{Python interface}
ModFossa provides easy, yet versatile and powerful ion channel modeling through
its novel Python interface. Python is well-used in the scientific and academic
community; however, we are unaware of any Python libraries which facilitate
the creation and simulation of ion channel kinetics. The popularity of Python
as a research tool stems from its simple syntax and extensive standard library,
and the availability of many high-quality open source numeric and scientific
libraries. Additional qualities of Python include easy third party library
installation; strong, dynamic typing; and an interactive interpreter.

ModFossa can also be used directly as a C++ library, allowing for more
flexibility.

\subsection{Easy model creation}
ModFossa allows the user to define an ion channel's Markov model using states,
rates, and connections. States and rates are referred to by their user-supplied
names. This allows the user to create the model in any order. For example,
connections can be defined before the definition of the states and rate
constants.

\subsubsection{States} States represent the various channel states as defined
by a continuous time Markov chain. All states are referred to by unique name
which is assigned by the user during
creation. States are created as either non-conducting or conducting.
Additionally, the gating of conducting states can by specified during
construction. The gating parameter is used to simulate states that are
partially conducting. For example, assigning a gating value of 0.5 to a state in
a particular model may be used to simulate channel blocking by 50 percent.

\subsubsection{Rates} 
Rates represent the kinetic rate constants which define the rate
of transition between two states. Rates are referred to by unique name. ModFossa
includes the following rate constant types: constant, Boltzmann voltage
dependence, exponential voltage dependence, and ligand-gated. The equations
for each rate constant are presented below.

\emph{Constant} rate constant are defined by a single parameter, $k$, like so:
\begin{equation}
 rate = k.
\end{equation}

\emph{Exponential} voltage dependent rate constants depend exponentially on
the membrane voltage: 
\begin{equation}
 rate(V) = a * exp(k*V),
\end{equation}
where $V$ is the membrane voltage, $exp$ is the exponential function, and $a$
and $k$ are parameters. 

\emph{Boltzmann} voltage dependence is defined using the sigmoid-like
Boltzmann equation:
\begin{equation}
 rate(V) = \frac{a}{\slfrac{1+exp[(V-V_{0.5})}{k}]},
\end{equation}
where $V$ is the membrane voltage, $V_{0.5}$ is the half-maximal activation
voltage (given as a parameter), $exp$ is the exponential function, and $a$
and $k$ are parameters. Taken from Angermann et al. \cite{angermann-2006}.  

\emph{Ligand-gated} rate constants depend on the concentration of a particular
ionic species, $S$, like so:
\begin{equation}
 rate([S]) = k * [S] ^ {n}, 
\end{equation}
where $[S]$ is the concentration of ligand $S$, $n$ is the ligand power, and
$k$ is a parameter.


\subsubsection{Connections} Connections define a transition from one unique
state to another using a specified rate constant. States can have multiple
ingoing and outgoing connections. Rate constants may also be used in multiple
connections.
 
\subsection{Experiment definition}
An experiment consists of a channel Markov model, a voltage protocol, and an
optional concentration protocol. 

\subsubsection{Voltage protocol}
Voltage protocols are a fundamental technique in electrophysiology used to
measure the current response of ion channels. In the laboratory, a small
electrode is inserted into the cell, through the cell membrane. The electrode,
and therefore the cell membrane, is held constant at a desired voltage for a
length of time, as defined by the voltage protocol. A typical voltage protocol
is shown in Figure \ref{fig:voltage_protocol}. As shown in the figure, the
voltage protocol begins with a \emph{hold stage} at -50 mV for 100 ms. Next, a
1 second long \emph{stepped stage} is defined, which steps the voltage from
-100 mV to 140 mV in 20 mV increments. The voltage protocol ends with another
hold stage at -80 mV.

The voltage protocol shown in Figure \ref{fig:voltage_protocol} is easily
defined in ModFossa by adding two hold stages, and one stepped stage. A
ModFossa voltage protocol can have any number of hold stages, but only one
stepped stage.  

%%%% Voltage protocol %%%%
\begin{figure}[h!]
\begin{center}
 
\includegraphics[width=4in]
{angermann_ca_voltage_protocol.eps}
    \caption{Example of a voltage protocol plot generated using ModFossa. This
protocol starts with a hold stage at -50 mV for 100 ms. Next, a
1 second long \emph{stepped stage} is defined, which steps the voltage from
-100 mV to 140 mV in 20 mV increments. The voltage protocol ends with another
hold stage at -80 mV. }
    \label{fig:voltage_protocol}
\end{center}
\end{figure}



\subsubsection{Concentration protocol}
A concentration protocol defines the concentration values (extracellular
or intracellular) of a certain ligand. Like a voltage protocol, ModFossa's
concentration protocols are defined using \emph{hold stages}. However, there is
no support for stepped concentration protocol stages. During simulation, the
simulator will run the model through the entire voltage protocol using a single
stage from the concentration protocol. Next, the concentration protocol will
advance to the next stage, and the voltage protocol will be run using the new
concentration value. This continues until there are no stages left in the
concentration protocol.


\subsection{Data analysis and plotting}   
ModFossa supports the creation of a number of useful plots using the Python
plotting library, PyPlot. Unlike other simulators reviewed in Chapter 2, the
plots can be saved easily in a vector graphics format. Visual examples of each
plot type are found in Chapter 4.

% \subsubsection{state probabilities}
% The state probabilities plot shows the evolution of the occupancy of each state
% in the Markov model over time.
%    
% \subsubsection{IV curve}
% IV curves show the ion channel's current as a function of membrane voltage. The
% voltages used to generate the IV curve are taken from the \emph{stepped stage}
% of the voltage protocol.
% 
% \subsubsection{conductance versus concentration}
% 
% \subsubsection{conductance versus voltage}
 

 
\subsubsection{Model and experiment validation}
To assist the user in creating a valid simulation, ModFossa
provides validation methods which return detailed messages regarding any
problems with the model and experiment definitions. Specific error conditions
include: \emph{no connections defined}, \emph{max conductance not defined},
\emph{rate constant not defined}, \emph{state not defined}, \emph{ligand not
defined}, \emph{no voltage protocols defined}, and \emph{no experiment sweeps
defined}.


 
\section{Design}
A class diagram showing ModFossa's classes and their associations is provided
in Figure \ref{fig:mm_class}. The organization of the classes in the diagram is
as follows: the left side of diagram contains classes related to the model
definition, including rates, states, connections, and the transition matrix.

The bottom right section of the diagram is centered around the SimulationRunner
class, which is top level class of ModFossa, and is the point of entry for the
Python interface (developed using Boost.Python). Also shown are the Simulator
and ODESolver classes, which use the numeric solver, Sundials, to solve the
differential equations that describe the evolution of state
probabilities. The Results class stores the results for each simulation in a map
structure, for later access by the user. 

The remaining classes in the diagram are related to the Experiment class and
the stimulus definition.

%%%% Class Diagram Markov Model  %%%%
\begin{figure}[h!]
\begin{center}
 
\fbox{\includegraphics[width=6in]
{modFossa_classes.eps}}
    \caption{ModFossa C++ library class diagram. The classes on the left
side of the diagram are related to the model definition. Classes relating to
the experiment and stimulus definition are grouped to the right. Boost.Python
is used to provide a Python interface to the library. Additionally, the numeric
solver library Sundials provides the ordinary differential equations solvers
required to simulate the channel model.}
    \label{fig:mm_class}
\end{center}
\end{figure}


\section{Implementation}

\subsection{Development tools}
C++ code was developed under Ubuntu Linux using Eclipse CDT. CMake was chosen as
the build system. Unit tests for the C++ code were written using the Google Test
framework. Having unit tests available aided the development process by
instilling confidence in the correctness of the code, especially during
refactoring. Google Test is included in the source tree, and is built by CMake
during the build process. This removes the need for the user to have Google Test
installed on the target computer.

Doxygen was used to generate documentation for the C++ code, while the Python
documentation was generated using Sphinx. Generated documentation can be found
in the Appendix. 

\subsection{Dependencies}
Sundials (SUite of Nonlinear and DIfferential/ALgebraic equation Solvers) is a C
library developed by Lawrence Livermore National Laboratory. ModFossa uses
Sundials to solve the system of ordinary differential equations governing the
ion channel state probabilities. Armadillo, a C++ linear algebra library
provides easy-to-use matrix structures and linear solvers, and is also used by
ModFossa. However, it would be ideal to remove the dependency on Armadillo in
order to remove complications during ModFossa’s installation.

In order to run ModFossa's Python interface, two Python libraries are required:
MatplotLib and Numpy. 


