\documentclass[english]{article}
\usepackage{mathptmx}
\usepackage{amsmath} % improved typesetting of formula
\usepackage{array} % tabel commands
\usepackage{helvet}
\renewcommand{\ttdefault}{lmtt}
\renewcommand{\familydefault}{\rmdefault}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{geometry}
\geometry{verbose,letterpaper,tmargin=1in,bmargin=1in,lmargin=1in,rmargin=1in,
  headheight=0cm,headsep=0cm,footskip=0.5in}
\setlength{\parskip}{\medskipamount}
\setlength{\parindent}{0pt}
\usepackage{longtable}
\usepackage{listings}

%\VignetteIndexEntry{NetIndices: network indices and food web descriptors in R}
\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\newcommand{\noun}[1]{\textsc{#1}}
%% Bold symbol macro for standard LaTeX users
\providecommand{\boldsymbol}[1]{\mbox{\boldmath $#1$}}

%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.

\usepackage{xspace}
\newcommand{\R}{\textbf{\textsf{R}}\xspace}
\newcommand{\nw}{\textbf{\textsf{NetIndices}}\xspace}

%%
\usepackage{babel}
\makeatother
\usepackage{hyperref}
\setlength{\extrarowheight}{0.5cm}

\begin{document}

\title{Package \nw, network indices and food web descriptors in \R }
\author{Karline Soetaert\\ Netherlands Institute of Sea Research\\ the Netherlands
\and Julius Kipyegon Kones \\ University of Nairobi \\ Kenya
}

\maketitle

  \R package \nw is designed to estimate the most common network indices.

  It has been created to accompany the following article \cite{Kones09}:

  \emph{Kones, J.K., Soetaert, K., van Oevelen, D. and J.Owino (2009).
    Are network indices robust indicators of food web functioning? a
    Monte Carlo approach.  Ecological Modelling, 220: 370-382.}

  http://dx.doi.org/10.1016/j.ecolmodel.2008.10.012

  Please use this reference to cite package \nw in publications.

  In this vignette we first deal with conventions adopted, after which network
  functions are briefly discussed. The formulations for all network indices
  are represented in several tables.

  This table is more complete than the one in the article.

\section	{Notations and flow matrix conventions}
  The descriptions of symbols used in network indices computations are
  in Table 1.
  \footnote{As our work generally involves food webs, our
  notation/terminology will be skewed to this field; hence we will use the
  term "web" where others might use "network", and "flow" instead of "link"}

  As in Latham (2006) we adopt for these tables the convention as described
  in \cite{Hirata84}.
 
  We assume that a system has n biotic and abiotic compartments. The flow
  value $T_{ij}$ is defined as a destination-source flow (i.e. j ->i) .

  Quantitative flows between compartments of a web are classified into
  four types \cite{Field89}:
  \begin{itemize}
    \item exogenous inputs (imports),
    \item inter-compartmental exchanges,
    \item exports of useable medium, and
    \item dissipation of unusable medium .
  \end{itemize}

  The source compartment of imports to the internal network is labeled
  with number 0 (zero), the destination of usable exports (secondary
  production) is labeled n+1 and the destination of unusable exports
  (respiration/dissipation) is labeled n+1 (sensu Hirata and Ulanowicz 1984).
  The flow matrix, with source compartments in columns and destination
  compartments in rows, has dimensions $0<=j<=n$ and $1<=i<=n+2$.

  A matrix containing all flows within a web has dimensions of
  $1<=i<=n$ and $1<=j<=n$ .

\section{Arguments to network index functions}
  In all functions of \nw, the network can be inputted in two ways:
  \begin{itemize}
    \item $Flow$, a matrix defined as source i -> destination j
    \item $T_{ij}$, the transpose of $Flow$, i.e. a matrix defined
      as destination i <- source j
  \end{itemize}
  Internally the calculation uses $T_{ij}$

  If present, the row- and -or column names of $Flow$ or $T_{ij}$ are
  used to label the compartments. This is recommended.

  All functions distinguish between internal components and external
  components.

  Externals are either specified by their name (more general, only
  applicable if the compartments have been labelled) or by a number
  (error-prone):
  \begin{itemize}
    \item Import, externals that are a source to the network. If specified
      by numbers they should refer to *columns* of $T_{ij}$ (or rows of Flow)
    \item Export, externals that are a sink to the network. If specified
      by numbers they should refer to *rows* of $T_{ij}$ (or columns of Flow)
  \end{itemize}


\section{Network indices}
  The R-functions for computing network indices are in Tables 2-8. They
  fall in several categories:
  \begin {itemize}

    \item function \emph{GenInd}. General network indices. In this category
      we consider a number of general systems' properties. \cite{Latham06}
    \item function \emph{UncInd}. Network Uncertainty indices, based on
      communication theory. \cite{Rutledge76}
    \item function \emph{AscInd}. System's growth and development. They are
      the ascendancy, development capacity and overhead. e.g.
      \cite{Ulanowicz80}.
      They can similarly be defined at four decomposed stages of a
      system: import (state 0), internal (between the compartments),
      export and dissipation \cite{Ulanowicz90}.
    \item function \emph{PathInd} Path analysis. Identifies the direct
      and indirect pathways in a network. (e.g. \cite{Finn76})
    \item function \emph{EnvInd}	Environ network indices. (\cite{Fath99})
    \item function \emph{TrophInd}. Trophic level and Omnivory index
      (\cite{Christensen92}. The trophic level of a consumer equals 1 +
      the weighted average of the trophic levels of its food. Primary
      producers and the compartments labeled as "detritus" are assumed to
      have trophic level of 1. The omnivory index measures the variation
      in trophic levels of the food sources of a consumer.
    \item function \emph{Dependency} The dependency matrix estimates the
      direct + indirect dependence of a consumer on a resource.
  \end {itemize}

  Note: Most of the index calculations were based on the paper and the
  software written by Latham (\cite{Latham06}), who did a very commendable
  (if not heroic) job in gathering all the mathematical formulations of
  these indices.

  However, there were a couple of inconsistencies in the paper of Latham:
  \begin{enumerate}
    \item The Connectance index (\cite{Gardner70}): The L reported
    in \cite{Latham06} should be $L_{int}$, because Connectance is only
    calculated on internal links.

    \item The value of TSTbar in figure (2) of the article was shown
      incorrectly (as $T/n$, when it should have been $TST/n$. It was
      however correctly described in the paper.

    \item The Synergism index both in the text and the equations were wrong.
      See Table (7) for how it is correctly estimated.
  \end{enumerate}
\section{Changes in later versions}
\subsection{version 1.3}
  \begin{itemize}
    \item An alternative way to estimate Finn's cycling index has been
    added. It is called $FCI_b$. It is more easily interpretable compared
    to the original index as it scales between 0 and 1.
  \end{itemize}
\begin{table}[t]
\caption{Nomenclature for equations}\label{tb:nomen}
\centering
\begin{tabular}{p{.2\textwidth}p{.75\textwidth}}\\
 Term & Description\\
\hline
$n$            &  Number of internal compartments in the network, excluding
  0 (zero),n+1 and n+2\\
$j=0$          &  External source\\
$i=n+1$        &  Usable export from the network\\
$i=n+2$        &  Unusable export from the network (respiration, dissipation)\\
$T_{ij}$       &  Flow from compartment j to i, where j represents the columns
  of the flow matrix and i the rows \\
$T_{ij}^*$      &  Flow matrix, excluding flows to and from external \\
$T_{i.}$       &  Total inflows to compartment i \\
$T_{.j} $      &  Total outflows from compartment j \\
$T_{i}$        &  Total inflows to compartment i, excluding inflow from
  external sources \\
$T_{j} $       &  Total outflows from compartment j, excluding outflow to
  external sinks \\
${\mathop {\left( {x_i } \right)}\limits^. }_ -  $  &  A negative state
  derivative, considered as a gain to the system pool of mobile energy  \\
${\mathop {\left( {x_i } \right)}\limits^. }_ +  $  &  A positive state
  derivative, considered as a loss from the system pool of mobile energy  \\
$z_{i0} $&  Flow into compartment i from outside the network   \\
$y_{n +,j} $  & Flow out of the network for compartment j to compartments
   n+1 and n+2  \\
$c_{ij} $   & The number of species with which both i and j interact divided
  by the number of species with which either i or j interact    \\
$I,\;\delta _{ij} $   & Identity matrix and its elements    \\
\hline
\end{tabular}
\end{table}


\begin{table}[t]
\caption{General Network indices}\label{tb:general}
\centering
\begin{tabular}{llll}\\
Index name & Code & Formula & Source(s)\\
\hline
Total system throughflow & TST & $ \sum \limits_{i = 1}^n {\sum\limits_{j = 1}^n {\left[ {T_{ij}  + z_{i0}  - \mathop {(x_i )_ -  }\limits^. } \right]} }  $\\
 && $ = \sum\limits_{i = 1}^n {\sum\limits_{j = 1}^n {\left[ {T_{ij}  + y_{n+,j}  + \mathop {(x_j )_ +  }\limits^. } \right]} }$ & \cite{Latham06}\\
Total system throughput & $T..$ & $ \sum\limits_{i = 1}^{n + 2} {\sum\limits_{j = 0}^n {T_{ij} } }$ & \cite{Hirata84}\\
Number of links & $L_{tot}$ & $ \sum\limits_{i = 1}^{n + 2} {\sum\limits_{j = 0}^n {(T_{ij}  > 0)} }$&\\
Number of internal links & $L_{int}$ & $ \sum\limits_{i = 1}^{n} {\sum\limits_{j = 1}^n {(T_{ij}  > 0)} }$&\\
Link density &LD & $\displaystyle \frac{L_tot}{n}$&\cite{Latham06}\\
Connectance &C & $\displaystyle \frac{L_{int}}{n \cdot (n-1)}$ &\cite{Latham06, {Gardner70}}\\
Average link weight & $\overline T_{ij}$ & $\displaystyle  \frac {T_{..}}{L_{tot}}$&\cite{Latham06}\\
Average compartment throughflow &$ \overline {TST}$ & $ \displaystyle \frac{TST}{n}$ &\cite{Latham06}\\
Compartimentalization & $\overline C$ & $  \frac{1}{n \cdot (n-1)} \cdot \sum \limits_{i=1}^{n}{\sum\limits_{j=1,j\neq i}^{n}}{c_{ij}}$ &\cite{Pimm80}\\

\hline
\end{tabular}
\end{table}


\begin{table}[t]
\caption{Network uncertainty indices}\label{tb:uncert}
\centering
\begin{tabular}{l@{$\qquad$}l@{$\qquad$}l@{$\qquad$}l}\\
Index name & Code & Formula & Source(s)\\
\hline Average mutual information & AMI & $ \sum\limits_{i =
1}^{n+2} {\sum\limits_{j = 0}^n {\frac
{T_{ij}}{T_{..}}log_2{\frac{T_{ij}T{..}}{T_{i.}T_{.j}}} }}  $&
\cite{Ulanowicz04,Gallager68,Shannon48,Latham02,Rutledge76}\\
Statistical uncertainty & $H_R$ & $ -\sum\limits_{j = 0}^{n} {\frac{T_{.j}}{T_{..}}log_2 \frac{T_{.j}} {T_{..}}} $ & \cite{Latham06, Ulanowicz90}\\
Conditional uncertainty & $D_R$ & $\displaystyle H_R - AMI$ & \cite{Latham06, Ulanowicz90}\\
Realized uncertainty & $RU_R$ & $\displaystyle  \frac{AMI}{H_R}$& \cite{Latham06, Ulanowicz90}\\
Network uncertainty & $H_{max}$ & $\displaystyle  \sum\limits _{i=1}^n {log_2 (n+2)}$& \cite{Latham06, Ulanowicz90}\\
Network efficiency& $H_{sys}$ & $\displaystyle  -\sum\limits _{i=1}^{n+2}{\sum \limits _{j=1}^n {\frac{T_{ij}}{T_{..}} log_2 \frac{T{ij}}{T_{.j}}}}$& \cite{Latham06, Ulanowicz90}\\
Constraint information& $H_{c}$ & $\displaystyle  H_{max}-H_{sys}$& \cite{Latham06, Ulanowicz90}\\
Constraint efficiency & CE & $\displaystyle \frac{H_c}{H_{max}}$ &\cite{Latham06, Ulanowicz90}\\

\hline
\end{tabular}
\end{table}


\begin{table}[t]
\caption{System growth and development indices}\label{tb:ascend}
\centering
\begin{tabular}{l@{$\qquad$}l@{$\qquad$}l@{$\qquad$}l}\\
Index name & Code & Formula & Source(s)\\
\hline Ascendency & A & $ \displaystyle \sum\limits_{i =
1}^{n+2} {\sum\limits_{j = 0}^n {T_{ij}
log_2{\frac{T_{ij}T{..}}{T_{i.}T_{.j}}} }}  $&
\cite{Ulanowicz00,Ulanowicz90}\\
Development capacity & DC & $\displaystyle -\sum\limits_{i = 1}^{n+2} {\sum\limits_{j = 0}^{n} {T_{ij}log_2 \frac{T_{ij}} {T_{..}}}} $ & \cite{Ulanowicz00, Ulanowicz90}\\
Overhead & $\displaystyle \phi$ & $DC - A$ & \cite{Ulanowicz00,Ulanowicz90}\\
Extent of development & AC & $\displaystyle \frac{A}{DC}$& \cite{Ulanowicz00,Ulanowicz90}\\
\hline
\end{tabular}
\end{table}

\begin{table}[t]
\caption{Effective measures indices}\label{tb:effect}
\centering
\begin{tabular}{l@{$\qquad$}l@{$\qquad$}l@{$\qquad$}l}\\
Index name & Code & Formula & Source(s)\\
\hline
Effective connectivity & $CZ$ & $\displaystyle \prod \limits_{i,j = 1}^{n} {(\frac {T_{ij}^2}{T_{i.}T_{.j}})}^{-0.5 \cdot T_{ij}/T_{..}}  $&  \cite{Zorach03}\\
Effective flows & $FZ$ & $\displaystyle \prod \limits_{i,j = 1}^{n} {(\frac {T_{ij}}{T_{..})}^{-T_{ij}/T_{..}}}  $&       \cite{Zorach03}\\
Effective nodes & $NZ$ & $\displaystyle \prod \limits_{i,j = 1}^{n} {(\frac {T_{..}^2}{T_{i.}T_{.j}})}^{0.5 \cdot T_{ij}/T_{..}}  $&  \cite{Zorach03}\\
Effective roles & $RZ$ & $\displaystyle \prod \limits_{i,j = 1}^{n} {(\frac
{T_{ij}T_{..}}{T_{i.}T_{.j}})}^{T_{ij}/T_{..}}  $& \cite{Zorach03}
\\
\hline
\end{tabular}
\end{table}

\begin{table}[t]
\caption{Pathway analysis}\label{tb:pathway}
\centering
\begin{tabular}{l@{$\qquad$}l@{$\qquad$}l@{$\qquad$}l}\\
Index name & Code & Formula & Source(s)\\
\hline
Total System cycled throughflow & $TST_c$ & $\displaystyle \sum\limits_{j = 1}^{n} {(1-\frac{1}{q_{jj}})\cdot T_j} $ &\cite{Finn76, Finn78,Finn80,Patten84,Patten76}\\
&& $\displaystyle Q = \left[ I-G^* \right] ^{-1}$ & \\
&&  $\displaystyle G^*=\left[ T_{ij}^*/max(T_j,T_i)\right]  $&\\
Total System non-cycled throughflow & $TST_S$ & $\displaystyle TST-TST_c $ & \cite{Finn76, Finn78,Finn80,Patten84,Patten76}\\
Finn's cycling index & FCI & $\displaystyle \frac{{TST_c }}{{TST}}$ & \cite{Finn76, Finn78,Finn80,Patten84,Patten76}\\
revised Finn's cycling index & FCIb & $\displaystyle \frac{{TST_c }}{{T..}}$ & \cite{Ulanowicz86,Allesina04}\\

Average pathlength & $\displaystyle \overline {PL}$ & $\frac{TST}{\sum {z_{i0}}-\sum{  {\mathop {\left( {x_i } \right)}\limits^. }_ -  }}$ &\\
& & $\displaystyle = \frac{TST}{\sum {y_{n+,j}}+\sum{  {\mathop {\left( {x_i } \right)}\limits^. }_ +  }}$  & \cite{Ulanowicz00,Ulanowicz90}\\
\hline
\end{tabular}
\end{table}


\begin{table}[t]
\caption{Environ analysis}\label{tb:environ}
\centering
\begin{tabular}{l@{$\qquad$}l@{$\qquad$}l@{$\qquad$}l}\\
Index name & Code & Formula & Source(s)\\
\hline
Transitive closure matrix & $G$ & $\displaystyle \left[ T_{ij}^*/T_j\right]$ & \cite{Patten82,Fath99}\\
Integral nondimensional matrix & $N$ & $\displaystyle I+G+G^2+...=\left[ I-G \right]^{-1}$ & \cite{Patten82,Patten84}\\
Non-dimensional direct flow-based utility matrix & $D$ & $(d_{ij})= \frac{T_{ij}^*-T_{ji}*}{T_i}$ & \cite{Patten84,Higashi89}\\
Utility nondimensional matrix & $U$ & $\displaystyle I+D+D^2+...=\left[ I-D \right]^{-1}$ & \cite{Patten84,Higashi89}\\
Coefficient of variation of N&CV(N)&$\displaystyle  \sqrt
{{\frac{{\sum\nolimits_{i,j = 1}^n {\left( {\overline N  - N_{ij}
} \right)^2 } }} {{(n^2  - 1) \cdot {\overline N }^2}}}}
$&\cite{Patten81,Fath99b}\\
Coefficient of variation of G&CV(G)&$\displaystyle  \sqrt
{{\frac{{\sum\nolimits_{i,j = 1}^n {\left( {\overline G  - G_{ij}
} \right)^2 } }} {{(n^2  - 1) \cdot {\overline G }^2}}}}
$&\cite{Patten81,Fath99b}\\
Homogenization & $H_p$ & $\displaystyle \frac{{CV(G)}}{{CV(N)}}$ & \cite{Patten81,Fath99b}\\
Integral Utility Matrix & $\gamma$ & $T_i \cdot U$  & \cite{Patten92,Fath98,Fath04}\\
Synergism Index & $\displaystyle \frac{b}{c}$ & $\frac{\sum{+utility~in~\gamma}}{\sum{-utility~in~\gamma}}$ & \cite{Patten92,Fath98,Fath04}\\
Dominance indirect effects & $\displaystyle \frac{i}{d}$ & $\frac{\sum \limits _{i,j=1}^n{(N_{ij}-I_{ij}-G_{ij})}}
{\sum \limits _{i,j=1}^n {G_{ij}}}$ & \cite{Patten92,Fath98,Fath04}\\


\hline
\end{tabular}
\end{table}


\begin{table}[t]
\caption{Trophic analysis}\label{tb:trophic}
\centering
\begin{tabular}{l@{$\qquad$}l@{$\qquad$}l@{$\qquad$}l}\\
Index name & Code & Formula & Source(s)\\
\hline
Diet matrix & $P$ & $\left[ \displaystyle \frac{T_{ij}^*}{T_i} \right]$ &\\
Diet dependency matrix & $D$ & $\displaystyle I+P+P^2+...=\left[ I-P \right]^{-1}$ & \\
Trophic level of compartment i & $TL_i$ & $ 1+ \sum\limits_{j = 1}^{n} {(\frac{T_{ij}^*}{T_i}\cdot TL_j)} $ &\cite{Christensen92,Lindeman42}\\
Omnivory index for compartment i & $OI_i$ & $\sum \limits_{j=1}^n{(TL_j-(TL_i-1))^2 \cdot \frac{T_{ij}^*}{T_i}}$ & \cite{Christensen92}\\
\hline
\end{tabular}
\end{table}
\clearpage
\bibliographystyle{plain}
\bibliography{NetIndices}

\end{document}
