% !TEX root =  centrtutorial.tex
\section{Introduction}

\begin{frame}
  \frametitle{Social network analysis}
  \begin{itemize}
    \item Social network analysis is the study of \emph{social entities and
      their interactions and relationships}
      \pause \item The interactions and relationships can be represented with a network or graph,
      \begin{itemize}
        \pause  \item each vertex represents an actor
        \pause  \item each link represents a relationship
    \end{itemize}
    \pause \item From the graph, we can study the properties of its structure,
    and the \emph{role}, \emph{position}, and \emph{prestige} of each social entity.
    \pause\item We can also find various kinds of sub-graphs, e.g.,
    \emph{communities} formed by groups of actors.
\end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Centrality in networks}
  \begin{itemize}
    \item Important or prominent actors are those that are \emph{extensively
      linked or involved with other actors}
    \item A person with extensive contacts (links) or communications
      with many other people in the organization is considered more important
      than a person with relatively fewer contacts
    \pause
    \item A central actor is one involved in many ties
    \pause
    \item \emph{Graph centrality} is a topic of uttermost importance in
      \emph{social sciences}
    \pause
    \item Also related to the problem of \emph{ranking} in the context of
      \emph{Web Search}:
      \begin{itemize}
        \item Each webpage is a social actor
        \item Each hyperlink is an endorsement relationship
        \item Centrality measures provide a query independent link-based score
          of \emph{importance} of a web page
      \end{itemize}
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{History of centrality (in a nutshell)}
  \begin{itemize}
    \pause
    \item first attempts in the late 1940s at MIT~(Bavelas 1946), in the
      framework of communication patterns and \emph{group collaboration};
    \pause
    \item in the following decades, various measures of centralities were
      proposed and employed by \emph{social scientists} in a myriad of contexts
      (Bavelas 1951; Katz 1953; Shaw 1954; Beauchamp 1965; Mackenzie 1966;
      Burgess 1969; Anthonisse 1971; Czapiel 1974...)
    \pause\
    item a new interest raised in the mid-90s with the \emph{advent of search
    engines:} a ``reincarnation'' of centrality.
  \end{itemize}
  \pause
  \begin{block}{Freeman, 1979}
    \begin{quotation}
      ``several measures are often only vaguely related to the intuitive ideas
      they purport to index, and many are so complex that it is difficult or
      impossible to discover what, if anything, they are measuring.''
    \end{quotation}
  \end{block}
\end{frame}

\begin{frame}
  \frametitle{Types of centralities}
  Starting point: the \emph{central vertex of a star} is the most important!\\
  \qquad Why?
  \pause
  \begin{enumerate}
    \item the vertex with \emph{largest degree};
    \item the vertex that is closest to the other vertexes (e.g., that has the
      \emph{smallest average distance} to other vertexes);
    \item the vertex through which \emph{all shortest paths pass};
    \item the vertex with the largest number of incoming paths of length $k$,
      for every $k$;
    \item the vertex that maximizes the \emph{dominant eigenvector} of the graph
      adjacency matrix;
    \item the vertex with \emph{highest probability in the stationary
      distribution} of the natural random walk on the graph.
  \end{enumerate}
  \pause
  These observations lead to corresponding competing views of centrality.
\end{frame}

\begin{frame}
  \frametitle{Types of centralities}
  This observation leads to the following classes of indices of centrality:
  \begin{enumerate}
    \pause
    \item measures based on \emph{distances} [degree, closeness, Lin's index];
    \pause
    \item measures based on \emph{paths} [betweenness, Katz's index];
    \pause
    \item \emph{spectral} measures [dominant eigenvector, Seeley's index,
      PageRank, HITS, SALSA].
  \end{enumerate}
  \vfill
  \pause
  The last two classes are largely the same (even if that wasn't fully
  understood for a long time.)
\end{frame}

\begin{frame}
  \frametitle{Geometric centralities}
  \begin{itemize}
    \pause
    \item \emph{degree} (folklore): $c_{\mathrm{deg}}(x)=d^-(x)$
    \pause
    \item \emph{closeness} (Bavelas, 1950):
      $c_{\mathrm{clos}}(x)=\closeness(x)=\frac1{\sum_y d(y,x)}$
    \pause
    \item \emph{Lin} (Lin, 1976): $c_{\mathrm{Lin}}(x)=\frac{r(x)^2}{\sum_y
      d(y,x)}$ where $r(x)$ is the number of vertexes that are co-reachable from
      $x$
    \pause
    \item \emph{harmonic} (Boldi and Vigna, 2013)
      $c_{\mathrm{harm}}(x)=\sum_{y\neq x}\frac1{d(y,x)}$
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Path-based centralities}
  \begin{itemize}
    \pause
    \item \emph{betweenness} (Anthonisse, 1971):
      $c_{\mathrm{bet}}(x)=\betw(x)=\sum_{y,z \neq x,\sigma_{yz}\neq 0} \frac{\sigma_{yz}(x)}{\sigma_{yz}}$ where $\sigma_{yz}$ is the number of shortest paths $y \to z$, and $\sigma_{yz}(x)$ is the number of such paths passing through $x$
    \pause
    \item \emph{Katz} (Katz, 1951): $c_{\mathrm{Katz}}(x)=\sum_{t\geq 0} \beta^t
      p_t(x)$ where $p_t(x)$ is the number of paths of length $t$ ending in $x$,
      and $\beta$ is a parameter ($\beta<1/\rho$)
  \end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Spectral centralities}
  \begin{itemize}
    \item \emph{dominant} (Wei, 1953):
      $c_{\mathrm{dom}}(x)$ is the dominant (right) eigenvector of $G$
    \item \emph{Seeley} (Seeley, 1949):
      $c_{\mathrm{Seeley}}(x)$ is the dominant (left) eigenvector of $G_r$
    \item \emph{PageRank} (Brin, Page \emph{et al.}, 1999):
      $c_{\mathrm{PR}}(x)$ is the dominant (left) eigenvector of $\alpha
      G_r+(1-\alpha) \mathbf{1}^T\mathbf{1}/n$ (where $\alpha<1$)
    \item \emph{HITS} (Kleinberg, 1997):
      $c_{\mathrm{HITS}}(x)$ is the dominant (left) eigenvector of $G^TG$
    \item \emph{SALSA} (Lempel, Moran, 2001):
      $c_{\mathrm{SALSA}}(x)$ is the dominant (left) eigenvector of $G_c^TG_r$
  \end{itemize}
  \small Where $G$ denotes the adjacency matrix of the graph, $G_r$ is the
  adjacency matrix normalized by row, and $G_c$ is the adjacency matrix
  normalized by column.
\end{frame}

\subsection{Closeness and Betweenness}

\begin{frame}
  \frametitle{Closeness centrality}
  \begin{block}{Motivation}
    It measures the ability to \emph{quickly} access or pass information through
    the graph;
  \end{block}
  \pause
  \begin{definition}[Closeness Centrality]
    \begin{itemize}
      \item closeness centrality $\closeness(x)$ of a vertex $x$
        $$
        \closeness(x)=\frac{1}{\sum_{y \neq x \in V}d(y,x).}
        $$
      \item $d(y,x)$ is the length of a shortest path between $y$ and $x$.
      \item The closeness of a vertex is defined as the \emph{inverse of the sum
        of the Shortest Path (SP) distances} between the vertex and all other
        vertexes of the graph.
      \item When multiplied by $n-1$, it is effectively the inverse of the
        average SP distance.
    \end{itemize}
  \end{definition}
\end{frame}

\begin{frame}
  \frametitle{Betweenness centrality}
  \begin{block}{Motivation}
    It measures the frequency with which a user appears in a shortest path
    between two other users.
  \end{block}
  \begin{columns}[c]
    \begin{column}{55mm}
      \begin{definition}[Betweennes centrality]
        \begin{itemize}
          \item betweenness centrality $\betw(x)$ of a vertex $x$:
            \[
              \betw(x)=\sum_{\substack{s\neq x\neq t \in V\\s\neq t}}
              \frac{\sigma_{st}(x)}{\sigma_{st}}
            \]
          \item $\sigma_{st}$:  number of SPs from $s$ to $t$
          \item $\sigma_{st}(x)$: how many of them pass through $x$
        \end{itemize}
      \end{definition}
    \end{column}
    \begin{column}{45mm}
      \includegraphics[width=42mm]{imgs/Graph_betweenness.pdf}
      \\ \hspace{10mm} \tiny{Example retrieved from  Wikipedia}
    \end{column}
  \end{columns}
\end{frame}

\begin{frame}
  \frametitle{Betweenness centrality}
  \begin{itemize}
    \item Can be defined also for edges (similarly to vertexes)
    \item Edges with high betweenness are known as \emph{``weak ties''}
    \item They tend to act as \emph{bridges between two communities}
  \end{itemize}
  \begin{columns}[T]
    \begin{column}{60mm}
      \begin{block}{The strength of weak ties (Granovetter 1973)}
        \begin{itemize}
          \item \emph{Dissemination and coordination dynamics} are influenced
            by links established to vertexes of different communities.
          \item The importance of these links has become more and more with
            the rise of social networks and professional networking platforms.
        \end{itemize}
      \end{block}
    \end{column}
    \hspace{-16mm}\begin{column}{40mm}
      \includegraphics[width=62mm]{imgs/weak_ties.pdf}
    \end{column}
  \end{columns}
\end{frame}

\begin{frame}
  \frametitle{Weak ties}
  \begin{block}{Bakshy et al. 2012}
    Weak links have a greater potential to \emph{expose links to new contacts}
    that otherwise would not have been discovered.
  \end{block}
  \begin{center}
    \includegraphics[width=70mm]{imgs/facebook_graph.pdf}
  \end{center}
\end{frame}

\begin{frame}
  \frametitle{Weak ties}
  \begin{block}{Grabowicz et al. 2012}
    \begin{itemize}
      \item Personal interactions are more likely to occur in internal links within communities (strong links)
      \item Events or new information is propagated faster by intermediate links (weak links).
    \end{itemize}
  \end{block}
  \includegraphics[width=50mm]{imgs/weak_ties2.pdf}
  \includegraphics[width=50mm]{imgs/weak_ties3.pdf}
\end{frame}

\begin{frame}
  \frametitle{Girvan-Newman algorithm for community detection (Girvan and Newman 2002)}
  Hierarchical divisive clustering by \emph{recursively removing the ``weakest
  tie''}:
  \begin{enumerate}
    \item Compute edge betweenness centrality of all edges;
    \item Remove the edge with the highest betweenness centrality;
    \item Repeat from 1.
  \end{enumerate}
  \centering
  \includegraphics[width=82mm]{imgs/gn.pdf}
\end{frame}

\begin{frame}
  \frametitle{Comparison}
  \begin{block}{Which vertex is the most central?}
    \begin{itemize}
      \item for Degree Centrality:
      \item for Closeness Centrality:
      \item for Betweenness Centrality:
    \end{itemize}
  \end{block}
  \centering
  \includegraphics[width=100mm]{imgs/centrality_comparison.pdf}
\end{frame}

\begin{frame}
  \frametitle{Comparison}
  \begin{block}{Which vertex is the most central?}
    \begin{itemize}
      \item for Degree Centrality:  {\color{blue}  user A}
      \item for Closeness Centrality:
      \item for Betweenness Centrality:
    \end{itemize}
  \end{block}
  \centering
  \includegraphics[width=100mm]{imgs/centrality_comparison.pdf}
\end{frame}

\begin{frame}
  \frametitle{Comparison}
  \begin{block}{Which vertex is the most central?}
    \begin{itemize}
      \item for Degree Centrality: {\color{blue}  user A}
      \item for Closeness Centrality: {\color{blue}  users B and C}
      \item for Betweenness Centrality:
    \end{itemize}
  \end{block}
  \centering
  \includegraphics[width=100mm]{imgs/centrality_comparison.pdf}
\end{frame}

\begin{frame}
  \frametitle{Comparison}
  \begin{block}{Which vertex is the most central?}
    \begin{itemize}
      \item for Degree Centrality: {\color{blue}  user A}
      \item for Closeness Centrality: {\color{blue}  users B and C}
      \item for Betweenness Centrality: {\color{blue}  user D}
    \end{itemize}
  \end{block}
  \centering
  \includegraphics[width=100mm]{imgs/centrality_comparison.pdf}
\end{frame}

\begin{frame}
  \frametitle{Visual Comparison}
  \begin{itemize}
    \item[A] Degree Centrality
    \item[B] Closeness Centrality
    \item[C] Betweenness Centrality
  \end{itemize}
  \centering
  \includegraphics[width=100mm]{imgs/centrality.pdf}
\end{frame}

\subsection{Axioms for centrality (Boldi and Vigna 2013)}

\begin{frame}
  \frametitle{Assessing}
  \begin{block}{Question}
    Is there a robust way to convince oneself that a certain centrality measure
    is better than another?
  \end{block}
  \pause
  \begin{block}{Answer}
    \emph{Axiomatization}\dots
    \begin{itemize}
      \pause
      \item \dots hard axioms (characterize a centrality measure completely)
      \pause
      \item \dots soft axioms (like the $T_i$ axioms for topological spaces)
    \end{itemize}
  \end{block}
\end{frame}

\begin{frame}
  \frametitle{Sensitivity to size}
  Idea: size matters!

  $S_{k,p}$ be the union of a $k$-clique and a $p$-cycle.
  \begin{itemize}
    \item if $k\to\infty$, every vertex of the clique becomes ultimately
      strictly more important than every vertex of the cycle
    \item if $p\to\infty$, every vertex of the cycle becomes ultimately
      strictly more important than every vertex of the clique
  \end{itemize}
  \medskip
  \centering
  \includegraphics[width=82mm]{imgs/sts.pdf}
\end{frame}

\begin{frame}
  \frametitle{Sensitivity to density}
  Idea: density matters!

  $D_{k,p}$ be made by a $k$-clique and a $p$-cycle connected by a single
  bidirectional bridge:
  \begin{itemize}
    \item if $k\to\infty$, the vertex on the clique-side of the bridge
      becomes more important than the vertex on the cycle-side.
  \end{itemize}
  \medskip
  \centering
  \includegraphics[width=82mm]{imgs/std.pdf}
\end{frame}

\begin{frame}
  \frametitle{Score monotonicity}
  Adding an edge $x \to y$ strictly increases the score of $y$.

  \smallskip
  \pause {\bf Doesn't say anything about the score of other vertexes!}
\end{frame}

\begin{frame}
  \frametitle{Rank monotonicity}
  Adding an edge $x \to y$\dots
  \begin{itemize}
    \pause\item if $y$ used to dominate $z$, then the same holds after adding
    the edge
    \pause\item if $y$ had the same score as $z$, then the same holds after
    adding the edge
    \pause\item {\bf strict variant: } if $y$ had the same score as $z$, then $y$
    dominates $z$ after adding the edge
\end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Rank monotonicity}
  \begin{table}
    \renewcommand{\arraystretch}{1.2}
    \begin{minipage}{\textwidth}
      \centering
      \begin{tabular}{l|c|c|c|c|c|c}
        \multicolumn{1}{c|}{}&\multicolumn{4}{c|}{Monotonicity}&\multicolumn{2}{c}{Other axioms}\\
        \multicolumn{1}{c|}{}&\multicolumn{2}{c|}{General}&\multicolumn{2}{c|}{Strongly connected}&\multicolumn{2}{c}{}\\
        Centrality & Score & Rank & Score & Rank & Size & Density
        \\
        \hline
        Harmonic & yes  & yes* & yes & yes* & yes & yes \\
        Degree  & yes & yes* & yes & yes* & only $k$ & yes \\
        Katz & yes & yes*& yes & yes* & only $k$ & yes \\
        PageRank &  yes & yes*& yes & yes* & no & yes \\
        Seeley & no & no & yes & yes & no & yes \\
        Closeness & no  & no & yes & yes & no & no \\
        Lin & no & no & yes & yes & only $k$& no \\
        Betweenness & no & no & no & no & only $p$ & no \\
        Dominant & no & no &? &? & only $k$ & yes \\
        HITS & no & no & no &no & only $k$ &yes\\
        SALSA & no & no & no &no & no & yes
      \end{tabular}
    \end{minipage}
  \end{table}
\end{frame}

\begin{frame}
  \frametitle{Kendall's $\tau$}
  \begin{tabular}{c}
    Hollywood collaboration network\\
    \includegraphics[width=\textwidth]{imgs/kendall2.pdf}\\
    \medskip \\
    .uk (May 2007 snapshot)\\
    \includegraphics[width=\textwidth]{imgs/kendal.pdf}\\
  \end{tabular}
\end{frame}

\begin{frame}
  \frametitle{Correlation}
  \begin{itemize}
    \pause \item most geometric indices and HITS
    are rather correlated to one another;
    \pause \item Katz, degree and SALSA are also
    highly correlated;
    \pause \item PageRank stands alone in the first dataset, but it is correlated to degree, Katz, and SALSA in the second dataset;
    \pause \item Betweenness is not correlated to anything in the first dataset, and could not be computed in the second dataset due to the size of the graph (106M vertices).
\end{itemize}
\end{frame}


\chapter{The age-resolved spatial structure of the Milky Way disk}

\section{Density Fits}
\label{sec:densityfits}
I briefly discuss the quality of the fits performed with the method outlined in section \ref{sec:methoda}. Figures \ref{fig:low_fitcomp} and \ref{fig:high_fitcomp} show the distance modulus distribution of the APOGEE DR12 data in each of the mono-age and mono-\feh{} bins (grey histograms) and the resulting distance modulus distribution when the best fit density model for each bin is run through the calculated effective selection function (which is the space in which models are fit in our procedure). The red line represents a single-exponential fit to the radial and vertical spatial distribution and the black lines give the best fit broken-exponential density model (upon which I base the results).I show the single-exponential fit in order to demonstrate that in most cases this does not provide a good fit to the data and that when a single exponential is a better fit, the broken-exponential density fit matches it.

Regarding Figure \ref{fig:low_fitcomp}, which shows the low \afe{} sub-populations, it is clear that the black curve (broken exponential) represents a far better model for the data than the red curve (single exponential), in all mono-age, mono-\feh{} bins. While the black curve is not perfect in all cases, the peak of the distribution tends to lie at the correct $\mu$, whereas the red curve finds a peak at higher $\mu$ in most cases (due to the higher than necessary density at low Galactocentric radius in this model).

 Figure \ref{fig:high_fitcomp} demonstrates the fits for the high \afe{} sub-populations. The hatched out panels reflect those with less than 30 stars, which are too noisy to render reliable fits. In many of the remaining panels, the red curve is similar or identical to the black, due to the fact that many of the high \afe{} populations are better described by single exponentials, and the broken exponential generally recovers this result. In most of the cases where the curves differ greatly, the red curve recovers the peak of the distribution better than the black - suggesting that breaks which \emph{were} fit in the radial range considered are artificial, and due to the noisy data in this regime. I discuss the broken exponential fits in the main text in order to make proper comparison with the low \afe{} sample, although it seems plausible that the single exponential model provides a better explanation of the data.

 \begin{figure*}
      \includegraphics[width=\textwidth]{low_fitcomparison.pdf}
   \caption[Comparison between the APOGEE DR12 data and best-fit density models for the low \afe{} mono-age, mono-\feh{} populations]{ Comparison between the best fit models and the APOGEE data for mono-age, mono-\feh{} populations in the low \afe{} sub-sample. The grey histogram shows the distance modulus distribution of the APOGEE data for the mono-age, mono-\feh{} bin indicated by the (\feh{} [dex], age [Gyr]) coordinate given in each panel, where each panel shows a different mono-age, mono-\feh{} bin. The coloured curves show the distance modulus distribution found when the best fit broken exponential (black) and single exponential (red) density model is run through the effective selection function. It is clear that the broken exponential density model provides a qualitatively better fit to the data in all cases.}
     \label{fig:low_fitcomp}
 \end{figure*}

 \begin{figure*}
      \includegraphics[width=\textwidth]{high_fitcomparison.pdf}
   \caption[Comparison between the APOGEE DR12 data and best-fit density models for the high \afe{} mono-age, mono-\feh{} populations]{Comparison between the best fit models and the APOGEE data for mono-age, mono-\feh{} populations in the high \afe{} sub-sample. Each panel again shows a different mono-age, mono-\feh{} bin. The grey histogram shows the distance modulus distribution of the APOGEE data for the mono-age, mono-\feh{} bin indicated by the (\feh{} [dex], age [Gyr]) coordinate given in each panel. The coloured curves show the distance modulus distribution found when the best fit broken exponential (black) and single exponential (red) density model is run through the effective selection function. In many cases the red and black curves are indistinguishable (only red is seen), or very similar. In cases where the black and red curves are different, the red provides a qualitatively better fit. Bins with less than 30 stars (which I disregard for the majority of the analysis and discussion) are hatched out. }
     \label{fig:high_fitcomp}
 \end{figure*}

 \section{The effect of uncertainties on trends with age}
 \label{sec:ageerror}

In order to demonstrate and characterise the effect that the age errors have on the interpretation of the trends between structural parameters and age, I use a mock data set with an input trend of $h_Z$ with age which increased monotonically with age from 0.2 to 1.2 kpc. Ages are assigned to each $h_Z$ population, sampling uniformly in bins of width 2 Gyr, to which I then added a random gaussian error of $40\%$, replicating the shifting of stars with different $h_Z$ into each age bin. In each bin, I sample a single exponential (a broken exponential with $R_\mathrm{peak}=0$) with scale length 8 kpc. This higher scale length is required to make the test computationally efficient, to produce realistic numbers of stars when selecting stars in APOGEE fields and does not impact on the results of this test. We assume no error on the stellar positions, in order to isolate the effect of the age errors.

 \begin{figure}
      \includegraphics[width=0.5\columnwidth]{montecarlo_hz.pdf}
   \caption[Scale height vs. age for a Monte Carlo mock data set, intended to simulate the effect of age uncertainties on the trends recovered by the density fitting methodology]{The resulting age-$h_Z$ trend from the Monte Carlo sampling of a set of mock density distributions. The input  density models had $h_Z$ increasing monotonically with age (in bins of $\Delta\mathrm{age}= 2$ Gyr) from 0.2 to 1.2 kpc (shown by the \emph{blue} dashed line). After sampling of the density distribution, random errors of $40\%$ were applied to the mock ages, and the structural parameters were measured using the exact density fitting method applied to the APOGEE data. The method is able to approximately recover the general shape of the input age-$h_Z$ relation, showing a clear trend with age. The age errors increase the error bar sizes significantly where mixing does occur, but the results are consistent with the input in most cases.}
     \label{fig:montecarlo_hz}
 \end{figure}

While this test is a somewhat simplistic representation of the underlying processes, it serves as a good example of the effect of the age uncertainties which are expected in the present data. One example of its simplicity is the assignment of a single $h_Z$ to relatively wide bins in age. It seems logical to assume that if there is an age-$h_Z$ relation, then the change in $h_Z$ should be somewhat continuous with age. This test assigns the same $h_Z$ to stars at bin edges (which should have $h_Z$ close to that of the bin-edge stars in the neighbouring bin). This may artificially increase the amount of blurring of the age-$h_Z$ trend. I also simplify the test by assuming that the only changing parameter is the scale height. Realistic structural parameters would change the relative number of stars within each bin observed by APOGEE (and considered in our test), and may change the level of contamination between bins. However, this simple approximation represents a `worst case' scenario, where the mixing between bins is maximal.

I restrict the mock data to the APOGEE fields, simplifying the selection function to a distance cut (assuming the selection fraction is 1 out to a distance which corresponds to $M_\mathrm{H}= -1.5$, assuming no extinction).  I apply the method described in Section \ref{sec:methoda} to the mock data, fitting a broken exponential profile, and using the best fit solution to initiate an MCMC sampling of the posterior probability distribution. As in the main body of the paper, the reported parameter values reflect the median and $\sigma$ of one dimensional projections of the MCMC chain. The resulting age-$h_Z$ relation is shown in Figure \ref{fig:montecarlo_hz}.  A clear trend is recovered between age and $h_Z$. The trend is still recovered at high age, regardless of the high level of mixing between bins, which increases the size of the error bars. The higher-scale height components are recovered by the analysis, but results are scattered around the input values, with large error bars. This serves to show that even in the face of large age uncertainties causing mixing between the adopted bins, this method is still able to recover the underlying trends of parameters with age.


\section{Foundations}

\begin{frame}[c]
\Huge{\centerline{Foundations}}
\end{frame}

%----------------------------------------------------------------------------------------

\begin{frame}\frametitle{Introduction \& Purpose}
	\begin{itemize}
		\item \textbf{Goal:} Ability to interpret complex "black box" models, deemed uninterpretable for decades.
		\bigskip
		\item \textbf{Solution:} Some approaches that increase a complex model's transparency, accountability, and fairness are the following:
		\bigskip
		\begin{itemize}
			\item Decision tree surrogate models [\cite{dt_surrogate1}; \cite{dt_surrogate2}]
			\item Partial dependence plots [\cite{esl}]
			\item Individual conditional expectation (ICE) plots [\cite{ice_plots}]
			\item Random forest feature importance [\cite{esl}]
			\item Leave-one-covariate-out (LOCO) local feature importance [\cite{conformal_reg}]
			\item Local Interpretable Model-agnostic Explanations (LIME) [\cite{lime}]
			\item Shapley Explanations [\cite{shapley}; \cite{tree_shap}]
			\end{itemize}
	\end{itemize}
\end{frame}
%----------------------------------------------------------------------------------------

\begin{frame}\frametitle{Introduction \& Purpose}
	\begin{itemize}
		\item The following slides will detail the mathematics behind each of these approaches and techniques.
	\end{itemize}
\end{frame}

%----------------------------------------------------------------------------------------

\begin{frame}\frametitle{Notation \& Preliminaries}
	\begin{itemize}
		\item \textbf{Spaces}.
			\begin{itemize}
				\item The input features come from a set  $\mathcal{X}$ contained in a \textit{P}-dimensional input space (i.e. $\mathcal{X} \subset \mathbb{R}^P)$.
				\item The output responses come from a set $\mathcal{Y}$ contained in a $C$-dimensional output space (i.e. $\mathcal{Y} \subset \mathbb{R}^C$).
			\end{itemize}
			\bigskip
		\item \textbf{Dataset}. A dataset $\mathbf{D}$ consists of $N$ tuples of observations:\\ $[(\mathbf{x}^{(0)},\mathbf{y}^{(0)}), (\mathbf{x}^{(1)},\mathbf{y}^{(1)}), \dots, (\mathbf{x}^{(N-1)},\mathbf{y}^{(N-1)})], \mathbf{x}^{(i)} \in \mathcal{X}, \mathbf{y}^{(i)} \in \mathcal{Y}$.\\
			\begin{itemize}
			\item The input data $\mathbf{X}$ is composed of the set of row vectors $\mathbf{x}^{(i)}$.
				\begin{itemize}
					\item let $\mathcal{P}$ be the set of features  $\{X_0, X_1, \dots, X_{P-1}\}$, where $X_j = \left[x_{j}^{(0)}, x_{j}^{(1)}, \dots, x_{j}^{(N-1)} \right]^T$.
					\item then each $i$-th observation denoted as $\mathbf{x}^{(i)} = \left[x_0^{(i)}, x_1^{(i)}, \dots, x_{P-1}^{(i)} \right]$ is an instance of $\mathcal{P}$.
				\end{itemize}
		\end{itemize}
	\end{itemize}
\end{frame}
%----------------------------------------------------------------------------------------

\begin{frame}\frametitle{Preliminaries (Cont.)}
	\begin{itemize}
		\item \textbf{Learning Problem}. We want to discover some \textit{unknown target function} $f: \mathcal{X} \rightarrow \mathcal{Y}$ from our data $\mathbf{D}$, which we assume is identically and independently distributed (i.i.d).  To do so, we explore a \textit{hypothesis set} $\mathcal{H}$ and use a given learning algorithm $\mathcal{A}$ to find a function $g$ that we hope sufficiently approximates our target function: $\mathbf{D} \xrightarrow[]{\mathcal{A}} g \approx f$.  For a given training example $(\mathbf{x}, \mathbf{y})$ in $\mathbf{D}$, we hope that $g(\mathbf{x}) = \hat{\mathbf{y}} \approx \mathbf{y}$ and $g$ generalizes well for unseen observations.
	\end{itemize}
\end{frame}

%----------------------------------------------------------------------------------------

\begin{frame}\frametitle{Preliminaries (Cont.)}
	\begin{figure}[htb]
	\begin{center}
		\includegraphics[width=0.77\textwidth]{images/learning_problem.png}
		\caption{The learning problem. Adapted from \textbf{Learning From Data}.}
		\label{fig:learning_problem}
	\end{center}
	\end{figure}
\end{frame}

%----------------------------------------------------------------------------------------

\begin{frame}\frametitle{Preliminaries (Cont.)}
	\begin{itemize}
		\item \textbf{Explanation}. To justify the predictions of $g(\mathbf{x})$, we may resort to a number of techniques. Some techniques will be global in scope and simply seek to generate an interpretable approximation, $h$, for $g$ itself, such that $h(\mathbf{x}) \approx g(\mathbf{x}) = \hat{\mathbf{y}}(\mathbf{x})$. Other techniques will be more local in scope and attempt to rank local contributions for each feature $X_j \in \mathcal{P}$ for some observation $\mathbf{x}^{(i)}$; this can create reason codes for $g(\mathbf{x}^{(i)})$. Local contributions are often estimated by evaluating the product of a learned parameter $\beta_j$ in $g$ with a corresponding observed feature value $x_j^{(i)}$ (i.e. $\beta_jx_j^{(i)}$), or by seeking to remove the contribution of some $X_j$ in a prediction, $g(\mathbf{x}_{(-j)}^{(i)})$.
	\end{itemize}
\end{frame}


\subsection{Group contraction from Lorentz to Euclid}


\subsection{Lights}
\index{lighting}
\index{lighting!point lights}
The most frequently used type of lights provided by Tachyon are positional
point light sources.  The lights are actually small spheres, which are
visible.  A point light is composed of three pieces of
information, a center, a radius (since its a sphere), and a color.
To define a light, simply write the {\bf LIGHT} keyword, followed by
its {\bf CENTER} (a X, Y, Z coordinate), its {\bf RAD} (radius, a scalar),
and its {\bf COLOR} (a Red Green Blue triple).  The radius parameter will
accept any value of 0.0 or greater.  Lights of radius 0.0 will not be
directly visible in the rendered scene, but contribute light to the scene
normally.
For a light, the color values
range from 0.0 to 1.0, any values outside this range may yield unpredictable
results.  A simple light definition looks like this:
\begin{verbatim}
  LIGHT CENTER 4.0 3.0 2.0
        RAD    0.2
        COLOR  0.5 0.5 0.5
\end{verbatim}
This light would be gray colored if seen directly, and would be 50\%
intensity in each RGB color component.

\index{lighting!directional lights}
Tachyon supports simple directional lighting, commonly used in
CAD and scientific visualization programs for its performance
advantages over positional lights.  Directional lights cannot be
seen directly in scenes rendered by Tachyon, only their illumination
contributes to the final image.

\begin{verbatim}
DIRECTIONAL_LIGHT
  DIRECTION 0.0 -1.0 0.0
  COLOR   1.0 0.0  0.0
\end{verbatim}

\index{lighting!spotlights}
Tachyon supports spotlights, which are described very similarly to a
point light, but they are attenuated by angle from the direction vector,
based on a  ``falloff start'' angle and ``falloff end''angle.  Between
the starting and ending angles, the illumination is attenuated linearly.
The syntax for a spotlight description in a scene file is as follows.
\begin{verbatim}
SPOTLIGHT
  CENTER  0.0 3.0  17.0
  RAD     0.2
  DIRECTION 0.0 -1.0 0.0
    FALLOFF_START 20.0
    FALLOFF_END   45.0
  COLOR   1.0 0.0  0.0
\end{verbatim}

\index{lighting!attenuation}
The lighting system implemented by Tachyon provides various levels of
distance-based lighting attenuation.  By default, a light is not attenuated
by distance.  If the {\em attenuation} keywords is present immediately
prior to the light's color, Tachyon will accept coefficients which are used
to calculate distance-based attenuation, which is applied the light by
multiplying with the resulting value.  The attenuation factor is calculated
from the equation
\begin{equation}
\label{eq:attenuation}
  \frac {1} {K_c + K_l d + k_q d^2}
\end{equation}

This attenuation equation should be familiar to some as it
is the same lighting attenuation equation used by OpenGL.
The constant, linear, and quadratic terms are specified in a scene file
as shown in the following example.
\begin{verbatim}
LIGHT
  CENTER  -5.0 0.0 10.0
  RAD     1.0
  ATTENUATION CONSTANT 1.0 LINEAR 0.2 QUADRATIC 0.05
  COLOR   1.0 0.0 0.0
\end{verbatim}


\section{Structural Synthesis}
\label{sec:struct}
In order to generate a reduced grammar $G', \languageOf{G'} \subset \languageOf{G}$, we require domain-specific knowledge from the user.
Specifically, the user provides our synthesis system with a set of grammar transformations \mbox{$t: \typeOfGrammar \to \typeOfGrammar$}, where the transformations strictly reduce the size of the set terminals that the grammar can generate, \mbox{$\forall G \in \typeOfGrammar. \ \languageOf{t(G)} \subseteq \languageOf{G}$}.
The user then also provides a refinement predicate $r: \exampleDomain \to \exampleDomain \to Boolean$ that describes when each transformation $t$ can be applied.

The language containment problem ($\languageOf{G_{1}} \subset \languageOf{G_{2}}$) is important for us here since we want to be sure that we are strictly decreasing the space of candidate programs to ensure that our search terminates.
The problem of checking language containment ($\languageOf{G_{1}} \subset \languageOf{G_{2}}$) for arbitrary context-free grammars $G_1$ and $G_2$ is undecidable in general~\cite{hopcroft1969equivalence}.
Ensuring that arbitrary transformations of the grammar indeed shrinks the search space is then not feasible.
However, our structural refinements do not require this power.
We instead limit the transformation to be one that only reduces the production rules $\productionRules_G$ to the production rules $\productionRules_{t(G)}$.
Specifically, the transformation $t$ is constructed by a mapping of $RHS$ components of the production rules.

\begin{align*}
P_{t(G)} =& \ \{ \ (lhs,\ rhs(lhs)\ )\  \} \\
&\text{where}\\
&\qquad lhs = proj_{LHS}(P_G) \\
&\qquad rhs(l) \subseteq proj_{RHS}(l)
\end{align*}

The user must specify when each transformation may be applied.
If the input/output examples have some relation $r$, then we can transform the search space in a way that removes potential programs that are not good.
Put formally, we want to define relation $r$ and transformation $t$, such that all the programs that we have removed have a higher cost than some program in the transformed grammar.

\begin{align*}
   r(i,o) &\implies \\
   & \forall p \in \languageOf{G} \setminus \languageOf{t(G)}. \\
   & \exists p' \in \languageOf{t(G)}. \\
   & \distFxn(o,p(i)) > \distFxn(o,p'(i))
\end{align*}

\begin{exmp} Limiting the DSP Grammar

%Should this come earlier?
In the grammar of our running example, we have two filters, a low-pass filter, $LFP \ [0,20k]\ [0,1]$, and a high-pass filter $HPF\ [0,20k]\ [0,1]$.
A low-pass filter lets frequencies lower than a given threshold pass through to the output.
Concertizing the threshold constants of $LPF$ at a value of 1500 Hz, and the application constant at 1, we then get $LPF \ 1500 \ 1$.

Applying $LPF \ 1500 \ 1$ to an audio file with a flat frequency response look as follows:

\markk{image of audio here}

We then build a relation from this observation, using a similar syntax to the refinement type system for Haskell, LiquidHaskell~\cite{vazou2014refinement},
Based on the above observation, we can write a refinement type on $LPF$ to describe that says the amplitude of the frequencies greater than the threshold frequency have decreased in the output Audio.
%
\begin{align*}
  &\texttt{lpf :: t:\reals} \to  \texttt{xs:Audio} \to\ \texttt{ys:Audio}\ \mid \\
  &\forall f_1 \in  \texttt{spectrogram(xs)}.\ \forall f_2 \in \texttt{spectrogram(ys)}. \\
  &(f_1 > \texttt{t}  \land  f_2 > \texttt{t}  \land f_1 == f_2) \implies \texttt{amp}(f_1) > \texttt{amp}(f_2)
\end{align*}

Where \texttt{t} represents the level at which the lowpass filter is applied, \texttt{spectrogram} represents the spectrogram of the sound sample, $f_i$ represents a frequency, and \texttt{amp()} represents the amplitude of the frequency.

Similarly, we can build a relation to describe a high-pass filter as a refinement type that says the amplitude of the frequencies less than the threshold frequency have decreased in the output Audio.
%
\begin{align*}
  &\texttt{hpf :: t:\reals} \to\ \texttt{xs:Audio} \to\ \texttt{ys:Audio}\ \mid \\
  &(\forall f_1 \in \texttt{spectrogram(xs)}. \forall f_2 \in \texttt{spectrogram(ys)}). \\
  &(f_1 < \texttt{t} \land f_2 < \texttt{t} \land f_1 == f_2) \implies \texttt{amp(}f_1\texttt{)} > \texttt{amp(} f_2 \texttt{)}
\end{align*}

Notice that in these refinement types, we only need to calculate the spectrogram for the input and output statically.
As opposed to the current technique of generating filters, applying them, and the calculating the aural distance, this approach is relatively static.
We could quickly check many threshold values over the input and output examples.

\end{exmp}


\documentclass[english]{article}
\usepackage[english]{babel}
\usepackage{graphicx}
\usepackage{subfig}
\usepackage{url}
\usepackage{algorithm}
\usepackage{algorithmic}
\begin{document}

\title{MATH:7450\\
Topological Data Analysis Project: \\
Population Diversity of Genetic Algorithm\\
for Solving Sudoku Puzzles}

\author{Gregory Tanner,\\
Applied Math and Computational Sciences,\\
University of Iowa
\and Brice Merwine,\\
Applied Math and Computational Sciences,\\
University of Iowa}
\maketitle

\section{Abstract}
\section{Introduction}
In this project, we use the Topological Data Analysis (TDA) Mapper algorithm to analyze the generational results from genetic algorithms applied to solving Sudoku puzzles.
Specifically, we aim to answer questions about the diversity of candidate solutions over time.
\section{Background}
\subsection{Problem Description}
Sudoku is a popular pencil and paper puzzle that takes place on a 9-by-9 grid divided into nine 3-by-3 blocks. The puzzle begins with certain cells (givens) of the grid filled in with the numbers 1-9. The goal of the puzzle is to fill in the remaining grid such that:
\begin{enumerate}
\item Every row contains the numbers 1-9 exactly once.
\item Every column contains the numbers 1-9 exactly once.
\item Every 3-by-3 block contains the numbers 1-9 exactly once.
\end{enumerate}
\begin{figure}
\centering
\subfloat[Unsolved Sudoku Puzzle \cite{sudoku1}]{\includegraphics[width=0.42\textwidth]{Sudoku_Puzzle_Unfilled.png}}
\qquad
\subfloat[Solved Sudoku Puzzle \cite{sudoku2}]{\includegraphics[width=0.42\textwidth]{Sudoku_Puzzle_Filled.png}}
\end{figure}

Genetic algorithms are a biology-inspired stochastic optimization strategy that aims to mimic the processes of evolution and natural selection. In search of an optimal solution, the algorithm produces a population of solutions that evolve over successive generations. The main evolutionary operators that are applied are recombination (also called crossover) and mutation. In recombination, information from two (or more) parents is randomly combined to create an new offspring solution. In mutation, a small portion of the information of a solution is randomly changed. At each generation, a certain number of current population and offspring is chosen to survive. This process repeats until a termination condition is reached. The general scheme of a genetic algorithm follows\cite{eiben2003introduction}:
\begin{algorithm}
  \caption{Genetic Algorithm Pseudocode}
  \begin{algorithmic}
    \STATE \textsc{Initialize} population with random candidate solutions;
    \STATE \textsc{Evaluate} each candidate;
    \REPEAT
    \STATE \textsc{Select} parents;
    \STATE \textsc{Crossover} pairs of parents to create offspring;
    \STATE \textsc{Mutate} the resulting offspring;
    \STATE \textsc{Evaluate} new candidates;
    \STATE \textsc{Select} individuals for the next generation;
    \UNTIL{\textsc{Termination Condition} is met}
  \end{algorithmic}
\end{algorithm}

There are several papers detailing the application of genetic algorithms to Sudoku \cite{mantere2006solving,sato2010solving,segura2016importance,weiss2009genetic}. For this project, we follow the construction of Segure et al. \cite{segura2016importance}:
\begin{description}
\item[Encoding] The candidate solutions are represented as 81-element arrays containing the numbers 1-9. The candidate solutions are initialized such that each 3-by-3 block contains  the numbers 1-9 exactly once. This leaves only the row and column constraints to check.
\item[Evaluation] Each candidate solution is evaluated by taking the sum of the number of row and column repetitions. An additional penalty of 100 times the number of row and column conflicts is imposed. The goal is to minimize this fitness value, and the exact solution has a fitness value of 0.
\item[Parent Selection] Two parents are selected by a pair of binary tournaments. In each tournament, two random candidates are selected from the population, and the candidate with the better fitness score is selected to be a parent.
\item[Recombination] The recombination selects entire 3-by-3 blocks from the parents to create the offspring. This maintains that each block contains the numbers 1-9 exactly once.
\item[Mutation] The mutation operator swaps two non-fixed elements within a block.
\item[Survivor Selection] We evaluate several survivor selection mechanism and investigate their impact on diversity.
\item[Termination Condition] The genetic algorithm was allowed to run for a fixed number of generations or until the exact solution (fitness value = 0) is found.
\end{description}
Segura et al. noted the importance of maintaining diversity in the solution population when trying to solve Sudoku puzzzles with genetic algorithms \cite{segura2016importance}. They analyze the performance of several different survivor selection mechanisms in maintaining diversity.

\subsection{Topological Data Analysis Mapper Algorithm}
The TDA Mapper algorithm was developed by Singh, M\'{e}moli and Carlsson \cite{singh2007topological}.
The purpose of the TDA mapper algorithm is to allow a method to visualize higher dimensional data in a manageable fashion.
Inspired by the Reeb graph, the mapper utilizes topological properties to extract information from the shape of the data.
The TDA mapper algorithm consists of these basic steps:
\begin{itemize}
 \item Obtain and preprocess the data into a manageable format.
 \item Use a filter function to map the data onto one (or possibly two) dimensions.
 \item Cover the image of the data by overlapping intervals (patches for two dimensions). The preimage of these intervals (patches) create overlapping bins in the data.
 \item Cluster each overlapping bin separately.
 \item Create a graph from the results. Each vertex corresponds to a cluster, and edges are placed between intersecting clusters.
\end{itemize}
The TDA mapper algorithm allows us to visualize our data as a lower dimensional graph, to which we can use topology to examine and draw conclusions.
\section{Results}
\section{Discussion}
\section{Conclusion}
\section{Acknowledgement}

The authors would like to acknowledge the TDA Mapper course taught
by Dr. Isabel Darcy Spring 2018. Also, the authors would like thank
Cole Stiegler for the countless conversations we had about implementing
genetic algorithms.

\section{Author Contribution}

Gregory Tanner developed the Matlab codes for solving Sudoku puzzles
with genetic algorithm. He contributed to all of the sections of this project report.

Brice Merwine contributed to the background section.

\section{Funding Sources and Conflicts of Interest}

Gregory Tanner is supported by a fellowship from the University of
Iowa Graduate College. He is conflicted about the amount of time that
he has spent on the genetic algorithms for Sudoku puzzle problem.

\bibliographystyle{plain}
\bibliography{sudoku}

\end{document}


    \filetitle{namedmat}{Create a new matrix with named rows and columns}{namedmat/namedmat}

	\paragraph{Syntax}\label{syntax}

\begin{verbatim}
X = namedmat(X,RowNames,ColNames)
X = namedmat(X,Names)
\end{verbatim}

\paragraph{Input arguments}\label{input-arguments}

\begin{itemize}
\item
  \texttt{X} {[} numeric {]} - Matrix or multidimensional array.
\item
  \texttt{RowNames} {[} cellstr {]} - Names for individual rows of
  \texttt{X}.
\item
  \texttt{ColNames} {[} cellstr {]} - Names for individual columns of
  \texttt{X}.
\item
  \texttt{Names} {[} cellstr {]} - Names for both rows and columns of
  \texttt{X}.
\end{itemize}

\paragraph{Output arguments}\label{output-arguments}

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{X} {[} namedmat {]} - Matrix with named rows and columns.
\end{itemize}

\paragraph{Description}\label{description}

Namedmat objects are used by some of the IRIS functions to preserve the
names of variables that relate to individual rows and columns, such as
in

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  \texttt{acf}, the autocovariance and autocorrelation functions,
\item
  \texttt{xsf}, the power spectrum and spectral density functions,
\item
  \texttt{fmse}, the forecast mean square error fuctions,
\item
  etc.
\end{itemize}

You can use the function \href{namedmat/select}{\texttt{select}} to
extract submatrices by referring to a selection of names.

Namedmat matrices derives from the built-in double class of objects, and
hence you can use any operators and functions on them that are available
for double objects.

\paragraph{Example}\label{example}


%% Copyright (C) 2011, Gostai S.A.S.
%%
%% This software is provided "as is" without warranty of any kind,
%% either expressed or implied, including but not limited to the
%% implied warranties of fitness for a particular purpose.
%%
%% See the LICENSE file for more information.

\section{Vector}

\subsection{Prototypes}
\begin{refObjects}
\item[Object]
\end{refObjects}

\subsection{Construction}

The Vector constructor can be either be given a single List (of Floats), or
any number of Floats.

Vector can be constructed by using either Vector.new, or the literal syntax
\lstinline|< >|. However only a subset of the possible expressions are
acceted inside this syntax: boolean operators are not allowed.

\begin{urbiscript}
Vector;
[00000140] <>

Vector.new();
[00000146] <>

Vector.new(1.1);
[00000147] <1.1>

Vector.new(1.1, 2.2, 3.3);
[00000155] <1.1, 2.2, 3.3>

Vector.new("123");
[00000174:error] !!! unexpected "123", expected a Float

Vector.new([]);
[00000187] <>

Vector.new([1, 2, 3, 4, 5]);
[00000189] <1, 2, 3, 4, 5>

Vector.new(["123"]);
[00000193:error] !!! unexpected "123", expected a Float

<1, 1>;
[00000147] <1, 1>

var x = 1|;
<1+1, x+2>;
[00000000] <2, 3>
\end{urbiscript}

\subsection{Slots}

\begin{urbiscriptapi}
\item['*'](<that>)%
  A Vector whose members are member-wise products of \this and \that.  The
  argument \that must either be a Vector of same dimension, or a Float.
\begin{urbiassert}
Vector              * Vector              == Vector;
Vector.new(1, 2, 3) * Vector.new(5, 6, 7) == Vector.new(5, 12, 21);
Vector.new(1, 2, 3) * 3                   == Vector.new(3,  6,  9);

Vector.new(1, 2) * Vector.new(0);
[00000601:error] !!! *: incompatible vector sizes: 2, 1
\end{urbiassert}

\item['+'](<that>)%
  A Vector whose members are member-wise sums of \this and \that.  The
  argument \that must either be a Vector of same dimension, or a Float.
\begin{urbiassert}
Vector              + Vector              == Vector;
<1, 2, 3> + <5, 6, 7> == <6, 8, 10>;
<1, 2, 3> + 3                   == <4, 5,  6>;

<1, 2> + <0>;
[00000601:error] !!! +: incompatible vector sizes: 2, 1
\end{urbiassert}

\item['-'](<that>)%
  A Vector whose members are member-wise subtractions of \this and \that.
  The argument \that must either be a Vector of same dimension, or a Float.
\begin{urbiassert}
Vector              - Vector              == Vector;
<1, 2, 3> - <5, 6, 7> == <-4, -4, -4>;
<1, 2, 3> - 3                   == <-2, -1,  0>;

Vector.new(1, 2) - Vector.new(0);
[00000601:error] !!! -: incompatible vector sizes: 2, 1
\end{urbiassert}

\item['/'](<that>)%
  A Vector whose members are member-wise divisions of \this and \that.  The
  argument \that must either be a Vector of same dimension, or a Float.
\begin{urbiassert}
Vector              / Vector              == Vector;
<6, 4, 1> / <3, 2, 1> == <2, 2, 1>;
<9, 6, 3> / 3                   == <3, 2, 1>;

<1, 2> / <1>;
[00000601:error] !!! /: incompatible vector sizes: 2, 1
\end{urbiassert}

\item['<'](<that>)%
  Whether \this is less than the \that Vector.  This is the lexicographic
  comparison: \this is ``less than'' \that if, from left to right, one of
  its member is ``less than'' the corresponding member of \that:

\begin{urbiassert}
   <0, 0, 0> < <0, 0, 1>;
 !(<0, 0, 1> < <0, 0, 0>);

   <0, 1, 2> < <0, 2, 1>;
 !(<0, 2, 1> < <0, 1, 2>);

   <1, 1, 1> < <2>;
 !(<2>       < <1, 1, 1>);

 !(<0, 1, 2> < <0, 1, 2>);
\end{urbiassert}

  \noindent
  or \that is a prefix (strict) of \this:

\begin{urbiassert}
           <> < <0>;
  !(      <0> < <>);

       <0, 1> < <0, 1, 2>;
  !(<0, 1, 2> < <0, 1>);

  !(<0, 1, 2> < <0, 1, 2>);
\end{urbiassert}

Since Vector derives from \refObject{Orderable}, the other order-based
operators are defined.

\begin{urbiassert}
        <> <= <>;
        <> <= <0, 1, 2>;
 <0, 1, 2> <= <0, 1, 2>;

        <> >= <>;
 <0, 1, 2> >= <>;
 <0, 1, 2> >= <0, 1, 2>;
 <0, 1, 2> >= <0, 0, 2>;

       !(<> > <>);
  <0, 1, 2> > <>;
!(<0, 1, 2> > <0, 1, 2>);
  <0, 1, 2> > <0, 0, 2>;
\end{urbiassert}

\item['=='](<that>)%
  Whether \this and \that have the same size, and members.
\begin{urbiassert}
   <> == <>;
   <1, 2, 3> == <1, 2, 3>;
 !(<1, 2, 3> == <1, 2>);
 !(<1, 2, 3> == <3, 2, 1>);
\end{urbiassert}

\item|'[]'|(<index>)%
  The value stored at \var{index}.
\begin{urbiassert}
var v = <1, 2, 3>;

v[ 0] == 1; v[ 1] == 2; v[ 2] == 3;
v[-3] == 1; v[-2] == 2; v[-1] == 3;

v[4];
[00000100:error] !!! []: invalid index: 4
\end{urbiassert}

\item|'[]='|(<index>, <value>)%
  Set the value stored at \var{index} to \var{value} and return it.
\begin{urbiassert}
var v = <0, 0, 0>;

(v[ 0] = 1) == 1; (v[ 1] = 2) == 2; (v[ 2] = 3) == 3;
 v[ 0]      == 1;  v[ 1]      == 2;  v[ 2]      == 3;

(v[-3] = 4) == 4; (v[-2] = 5) == 5; (v[-1] = 6) == 6;
 v[-3]      == 4;  v[-2]      == 5;  v[-1]      == 6;

v[4] = 7;
[00000100:error] !!! []=: invalid index: 4
\end{urbiassert}

\item[asString]%
\begin{urbiassert}
  <>.asString() == "<>";
  <1, 2>.asString() == "<1, 2>";
  <1, 2, 3.4>.asString() == "<1, 2, 3.4>";

\end{urbiassert}

\item[asList]%
  Return this as a list.
\begin{urbiassert}
  <>.asList() == [];
  <1,-1>.asList() == [1, -1];
\end{urbiassert}

\item[asVector]%
  Return \this.
\begin{urbiassert}
var v = Vector.new();
v.asVector() === v;
\end{urbiassert}

\item[combAdd](<that>)%
  A \refObject{Matrix} \var{res} such that
  \lstinline|\var{res}[\var{i}, \var{j}] = this[i] + \var{that}[j]|, for all
  \lstinline|i| in the range of \this, and \lstinline|j| in the range of
  \that.
\begin{urbiassert}
<0, 1, 2>.combAdd(<0, 10, 20>)
  == Matrix.new([ 0, 10, 20],
                [ 1, 11, 21],
                [ 2, 12, 22]);
\end{urbiassert}

\item[combDiv](<that>)%
  A \refObject{Matrix} \var{res} such that
  \lstinline|\var{res}[\var{i}, \var{j}] = this[i] / \var{that}[j]|, for all
  \lstinline|i| in the range of \this, and \lstinline|j| in the range of
  \that.
\begin{urbiassert}
<10, 20>.combDiv(<2, 5, 10>)
  == Matrix.new([  5, 2, 1],
                [ 10, 4, 2]);
\end{urbiassert}

\item[combMul](<that>)%
  A \refObject{Matrix} \var{res} such that
  \lstinline|\var{res}[\var{i}, \var{j}] = this[i] * \var{that}[j]|, for all
  \lstinline|i| in the range of \this, and \lstinline|j| in the range of
  \that.
\begin{urbiassert}
<1, 2, 3, 4>.combMul(<5, 6, 7>)
  == Matrix.new([ 5,  6,  7],
                [10, 12, 14],
                [15, 18, 21],
                [20, 24, 28]);
\end{urbiassert}

\item[combSub](<that>)%
  A \refObject{Matrix} \var{res} such that
  \lstinline|\var{res}[\var{i}, \var{j}] = this[i] - \var{that}[j]|, for all
  \lstinline|i| in the range of \this, and \lstinline|j| in the range of
  \that.
\begin{urbiassert}
<-1, 0, +1>.combSub(<-2, 0, +2>)
  == Matrix.new([1, -1, -3],
                [2,  0, -2],
                [3,  1, -1]);
\end{urbiassert}

\item[distance](<that>)%
  The (Euclidean) distance between \this and \that: (Euclidean) norm of
  \lstinline|this - \var{that}|.  They must have equal dimensions.
\begin{urbiassert}
  <>.distance(<>) == 0;
  <0, 0>.distance(<3, 4>) == 5;
  <3, 4>.distance(<0, 0>) == 5;
\end{urbiassert}

\begin{urbiscript}
<0>.distance(<1, 2>);
[00000319:error] !!! distance: incompatible vector sizes: 1, 2

<1, 2>.distance(<0>);
[00000334:error] !!! distance: incompatible vector sizes: 2, 1
\end{urbiscript}

\item[norm]%
  The (Euclidean) norm of \this: square root of the sum of the square of the
  members.
\begin{urbiassert}
 <>.norm == 0;
 <0>.norm == 0;
 <1>.norm == 1;
 <1, 1>.norm == 2.sqrt();
 <0, 0, 0, 0>.norm == 0;
 <1, 1, 1, 1>.norm == 2;
\end{urbiassert}

\item[resize](<dim>)%
  Change the dimensions of \this, using 0 for possibly new members.  Return
  \this.
\begin{urbiscript}
// Check that <1, 2> is equal to the Vector composed of values,
// when resized the number of values.
function resized(var values[])
{
  var m = <1, 2>;
  var res = Vector.new(values);
  // Resize returns this...
  m.resize(res.size) === m;
  // ...and does resize.
  m == res;
}|;

assert
{
  resized();
  resized(1);
  resized(1, 2);
  resized(1, 2, 0);
};
\end{urbiscript}

\item[scalarEQ](<that>)%
  A Vector whose members are 0 or 1 depending on the equality of the
  corresponding members of \this and \that.
\begin{urbiassert}
  <1, 2, 3>.scalarEQ(<3, 2, 1>) == <0, 1, 0>;
\end{urbiassert}
  \this and \that must have equal sizes.
\begin{urbiscript}
<1, 2>.scalarEQ(<0>);
[00000601:error] !!! scalarEQ: incompatible vector sizes: 2, 1
\end{urbiscript}

\item[scalarGE](<that>)%
  A Vector whose members are 0 or 1 if the corresponding member of \this is
  greater than or equal to the one of \that.
\begin{urbiassert}
  <1, 2, 3>.scalarGE(<3, 2, 1>) == <0, 1, 1>;
\end{urbiassert}

  \this and \that must have equal sizes.
\begin{urbiscript}
<1, 2>.scalarGE(<0>);
[00000601:error] !!! scalarGE: incompatible vector sizes: 2, 1
\end{urbiscript}

\item[scalarGT](<that>)%
  A Vector whose members are 0 or 1 if the corresponding member of \this is
  greater than to the one of \that.
\begin{urbiassert}
  <1, 2, 3>.scalarGT(<3, 2, 1>) == <0, 0, 1>;
\end{urbiassert}

  \this and \that must have equal sizes.
\begin{urbiscript}
<1, 2>.scalarGT(<0>);
[00000601:error] !!! scalarGT: incompatible vector sizes: 2, 1
\end{urbiscript}

\item[scalarLE](<that>)%
  A Vector whose members are 0 or 1 if the corresponding member of \this is
  less than or equal to the one of \that.
\begin{urbiassert}
  <1, 2, 3>.scalarLE(<3, 2, 1>) == <1, 1, 0>;
\end{urbiassert}

  \this and \that must have equal sizes.
\begin{urbiscript}
<1, 2>.scalarLE(<0>);
[00000601:error] !!! scalarLE: incompatible vector sizes: 2, 1
\end{urbiscript}

\item[scalarLT](<that>)%
  A Vector whose members are 0 or 1 if the corresponding member of \this is
  less than to the one of \that.
\begin{urbiassert}
  <1, 2, 3>.scalarLT(<3, 2, 1>) == <1, 0, 0>;
\end{urbiassert}

  \this and \that must have equal sizes.
\begin{urbiscript}
<1, 2>.scalarLT(<0>);
[00000601:error] !!! scalarLT: incompatible vector sizes: 2, 1
\end{urbiscript}

\item[set](<list>)%
  Change the members of \this, and return \this.
\begin{urbiassert}
var v = <1, 2, 3>;
v.set([10, 20]) === v;
v == <10, 20>;
\end{urbiassert}

\item[size]%
  The size of the vector.
\begin{urbiassert}
                      <>.size == 0;
                     <0>.size == 1;
Vector.new(0, 1, 2, 3)  .size == 4;
Vector.new([0, 1, 2, 3]).size == 4;
\end{urbiassert}

\item[sum]%
  The sum of the values stored in \this.
\begin{urbiassert}
<>            .sum() == 0;
<1>           .sum() == 1;
<0, 1, 2, 3>  .sum() == 6;
\end{urbiassert}

\item[trueIndexes]%
  A Vector whose values are the indexes of \this whose value is non-null.
\begin{urbiassert}
<>.trueIndexes() == <>;
<1, 0, 1, 0, 0, 1>.trueIndexes() == <0, 2, 5>;
\end{urbiassert}

\item[zip](<others>)%
  Zip this vector with the given list of other vectors, which can be of different sizes.

\begin{urbiassert}
 <0,3>.zip([<1, 4>, <2, 5>]) == <0, 1, 2, 3, 4, 5>
\end{urbiassert}

\item[serialize](<wordSize>, <littleEndian>)%
  Serialize to binary integral data.

\begin{urbiassert}
  <1, 2>.serialize(2, false) == "\x01\x00\x02\x00";
  <1, 2>.serialize(2, true)  == "\x00\x01\x00\x02";
\end{urbiassert}

\item[type]%
  \lstinline|"Vector"|.
\begin{urbiassert}
Vector.type == "Vector";
<>.type == "Vector";
\end{urbiassert}
\end{urbiscriptapi}

%%% Local Variables:
%%% coding: utf-8
%%% mode: latex
%%% TeX-master: "../urbi-sdk"
%%% ispell-dictionary: "american"
%%% ispell-personal-dictionary: "../urbi.dict"
%%% fill-column: 76
%%% End:


\documentclass{ecnreport}

\stud{EMARO2 / ARIA-ROBA}
\topic{Advanced Visual Geometry}

\begin{document}

\inserttitle{Advanced Visual Geometry}

\insertsubtitle{Lab 1: Homography-based visual odometry}

\section{Content of this lab}

The goal of this lab is to perform Augmented Reality (AR) from a sequence of images.\\
The only information that we have is that the camera is observing a mostly planar environment,
where we want to display the 3D model of a robot (AR), see \Fig{fig:ar} for an overview.

\begin{figure}[h!]
\centering\label{fig:ar}
 \includegraphics[width=.5\linewidth]{ar}
 \caption{Current image with 3D robot AR display}
\end{figure}

AR needs a 3D transform between the camera and the world frame. By doing homography-based visual odometry (VO), we can do this pose estimation
with regards to a reference 3D plane. \\
The goal is thus to load the video file, and go through the images with all the necessary steps to perform AR. Two libraries will be used to do so:
\begin{itemize}
 \item OpenCV 3 to read images from files or camera, perform low-level image processing\footnote{Open source Computer Vision, http://opencv.org}. We use version 3 as it includes
 the homography matrix decomposition.
 \item ViSP to manipulate 3D points, camera pose and use vectors and matrices\footnote{Visual Servoing Platform, http://visp.inria.fr}
\end{itemize}
The actual classes that are used are detailed in Appendix \ref{sec:classes}.

This lab is available on GitHub. The package can be downloaded through git and compiled with the sequence:
\begin{center}\cppstyle
\begin{lstlisting}
 git clone https://github.com/oKermorgant/ecn_visualodom.git
 cd ecn_visualodom
 mkdir build
 cd build
 cmake ..
 make
\end{lstlisting}
\end{center}

The video should be downloaded from my website in the lab directory:
\begin{center}\cppstyle
\begin{lstlisting}
 wget http://pagesperso.ls2n.fr/~kermorgant-o/files/armen.mp4
\end{lstlisting}
\end{center}

It may be useful to use an IDE like Qt Creator, to do so you have to launch it from the command line then:
\begin{itemize}
 \item Open project and load the \texttt{CMakeLists.txt} file
 \item Set the \texttt{build} folder as the build folder
\end{itemize}

\subsection{Structure of the \texttt{ecn\_visualodom} folder}

The folder has the classical structure of a C++ project:
\begin{figure}[h]\centering
\begin{minipage}{.05\linewidth} ~ \end{minipage}
\begin{minipage}{.75\linewidth}
 \dirtree{%
.1 ecn\_visualodom.
.2 include.
.3 ecn\_visualodom.
.4 ar\_display.h\DTcomment{augmented reality code}.
.4 video\_loop.h\DTcomment{load and read video file}.
.4 visual\_odom.h\DTcomment{VO class header}.
.2 src.
.3 visual\_odom.cpp\DTcomment{VO class to be modified}.
.2 armen.mp4\DTcomment{video file}.
.2 CMakeLists.txt\DTcomment{CMake file}.
.2 vo.cpp\DTcomment{main file to be modified}.
}
\end{minipage}
%\begin{minipage}{.2\linewidth} ~ \end{minipage}
\caption{Files used by the package}
\end{figure}

The only files to be modified are \texttt{visual\_odom.cpp} that is the visual odometry class and performs visual odometry between two consecutive frames, and \texttt{vo.cpp} that is the main
C++ file and uses visual odometry to estimate the current pose of the camera with regards to the world frame.

\subsection{Expected work}

The goal is to implement an homography-based visual odometry and test it on the \texttt{armen.mp4} video.
The main steps are already written in the code as comment sections. The \texttt{VisualOdom} class will be doing most of the job, except for the initial pose estimation.
Dedicated OpenCV of ViSP classes or functions will also do most of the job and the goal of the lab is also to get used to them.

The next section details the homography-based visual odometry algorithm and its most important steps.

\def\n{\mathbf{n}}
\def\t{\mathbf{t}}
\section{Homography-based visual odometry}

The basis of the visual odometry from homography is to compute an homography from two views of the same plane.
If the equation of the plane is written $\X^T\n = d$ in the first camera frame, then the homography matrix is $\H = \R + \t\n^T/d$
where $(\t, \R)$ express the transform from camera 1 to camera 2 as shown in \Fig{fig:homog}.

\begin{figure}[h!]
\centering\label{fig:homog}
 \includegraphics[width=.5\linewidth]{homog}
 \caption{Two views of a given 3D plane links 3 transforms.}
\end{figure}
However, in order to display any 3D model with AR, an initial pose $\cMo$ has to be estimated for the initial camera. We first recall the relative
odometry before giving clues about the initial pose estimation.

\subsection{Relative odometry from homography}

The core algorithm is to compute the relative odometry, that is the transform between the two camera frames. It corresponds to the method \texttt{VisualOdom::process}.
The algorithm to follow is:
\begin{enumerate}
  \item Convert image to gray level
 \item Detect and compute keypoint descriptors in the new image
 \item Match keypoints with the ones from the previous image
 \item With RANSAC, compute homography and also get matches inliners
 \item Decompose homography to get $(\t,\R,\n)$ candidates\\
  A method in OpenCV
will give us all candidates (usually 4) under the form of 3 vectors of dimension 4: translations, rotations and normal to the plane. Candidates
are stored under a \texttt{vector} of \texttt{Homography}, a custom structure used to regroup $(\t,\R,\n)$ (see \Sec{sec:homog}).
 \item Prune candidates that give a negative Z for at least 1 point \\ The corresponding loop is already in the code but the condition to consider a candidate to be valid or not has to be defined.
 \item There still may be two candidates, keep the one that has the normal $\n$ closer to the estimated normal
\end{enumerate}
The last step shows that a guess for the normal has to be given in order to find the best candidate homography. This can be done with the \texttt{VisualOdom::setNormalGuess} in the main code (around line 24). In our case we assume
we observe a horizontal plane with a camera also placed horizontally. This is sufficient to have a corse estimate of the normal to the plane in the camera frame.

At the end of the whole sequence, we have a homography decomposition $(\t,\R,\n)$ without the scale factor. Actually OpenCV gives us $\t/d$ as $\t$ as they cannot be separated without
extra information. If we have an estimation of the value $d$, we can easily compute the true translation with $d.\t$. This $d$ estimation is stored in the \texttt{VisualOdom} class as \texttt{d\_guess}.

The final step is to prepare for the next image: the parameters $(d,\n)$ of the plane equation have to be rewritten in the frame of camera 2.
\begin{enumerate}
 \item Updating $\n$ is only a matter of frame change as we have $\R$.
 \item Updating $d$ can be done with only one point, so in practice we compute the new $d$ from all the points and then take the mean value.
\end{enumerate}
We now detail how to get an initial guess for $d$.

\subsection{Initial plane parameter from assumed translation}
\label{sec:init}

The scale factor is given by the size of the 3D model to be displayed. In practice this amounts to fix the initial translation ${}^c\t_o = (-0.1,-0.1,0.7)$.
This translation can be used to have a first estimation of the plane parameter $d$ after the first homography has been computed.
Indeed, in this case we have the normal to the plane and we can just set $d = \n^T{}^c\t_o$. This value can then be used to rescale the relative transform
that was extracted from the homography.
In the code, this corresponds to the line \texttt{if(d\_guess == 0)}, where we do not yet have an estimate on $d$.

\subsection{Overall algorithm}

By combining the relative transform from homography and the initial guess from known translation, after the second image we can have the whole information:
\begin{enumerate}
 \item Get unscaled transform from initial homography, this gives us $(\t,\R)$ between the cameras and the normal $\n$ to the plane in the first camera frame.
 \item This transform can be scaled from the known initial translation ${}^c\t_o$
 \item Get the rotation matrix corresponding to the Z-axis of the plane aligning with the $\n$ axis of the camera frame (\texttt{VisualOdom::getRotationFromNormal}).
 \item Build the full transform $\cMo(0)$ for the first image (variable \texttt{cMo0})
\end{enumerate}

After this initialization, the scale factor will be updated at each iteration from the previous value and the current camera pose just has to be updated from the previous one and the relative
transform found by the homography.

In practice, we may experience a scale drift and perform all homographies with regards to the initial image.

\appendix
\section{Main classes and tools}\label{sec:classes}

\subsection{ViSP classes}

This library includes many tools for linear algebra, especially for 3D transformations.
The documentation is found here: \url{http://visp-doc.inria.fr/doxygen/visp-daily/classes.html}.\\
The main classes from ViSP (at least in this lab) are:
\begin{itemize}
\item \texttt{vpMatrix} represents a classical matrix, can then be transposed, inversed (or pseudo-inversed), multiplied with a vector, etc.
\item \texttt{vpColVector} is a column vector with classical mathematical properties.
\item \texttt{vpHomogeneousMatrix} is a $4\times 4$ 3d transform matrix. They can be multiplied to compose transforms.
\end{itemize}
These class can be declared and used as follows:
\begin{center}\cppstyle
\begin{lstlisting}
       vpMatrix M(2,6); 	// matrix of dim. 2x6
       M[0][0] = M[1][1] = 1;	// element-wise assignment
       vpColVector v(6);	// column vector of dim. 6
       v[0] = 1;		// element-wise assignment
       M*v;			// matrix-vector multiplication
\end{lstlisting}
\end{center}

\subsection{The \texttt{Homography} structure}
\label{sec:homog}

This structure is a simple object that regroups values for $(\t,\R,\n)$. From an instance \texttt{H}, they can be accessed with \texttt{H.t},
\texttt{H.R} and \texttt{H.n}. \texttt{t} and \texttt{n} are \texttt{vpColVector} while \texttt{R} is a \texttt{vpRotationMatrix}.

\subsection{The \texttt{VisualOdom} class}

This class does most of the job (at least when you add the correct missing code). It is initialized from the camera parameters and a flag telling if the homography
should be computed relative to the initial image or relative to the previous image (inducing scale drift).\\
The existing methods are:
\begin{itemize}
 \item \texttt{bool process(cv::Mat \&, vpHomogeneousMatrix \&M)} \\
 Main method, processes a new image and returns the corresponding transform. Returns True if everything went fine.
 \item \texttt{void getRotationFromNormal(vpRotationMatrix \&)}: give the rotation matrix between the plane frame and the camera frame. Can only be used
 if at least one homography was computed.
\end{itemize}
The current estimate of the homography plane is defined from \texttt{n\_guess} and \texttt{d\_guess}.

Most of the variables are already defined, the attributes of the class can be read in \texttt{visual\_odom.h}. In particular,
these useful variables are already available as class attributes:
\begin{itemize}
\item Stored image \texttt{im1}, image that can be used for gray-level conversion \texttt{img}
 \item Keypoints (\texttt{kp1, kp2}) and their descriptors (\texttt{des1, des2})
 \item Keypoint detector and descriptor: \texttt{akaze}
 \item Matcher and matches (\texttt{matcher, matches})
 \item Calibration matrices: \texttt{Kcv} for OpenCV functions, \texttt{K} and \texttt{Ki} (inverse) for ViSP matrix multiplication
 \item Homography matrix (\texttt{Hp}, OpenCV format) and RANSAC mask for inliers (\texttt{mask})
 \item Vector of homography structures \texttt{H} used to analyze the candidates and prune them if needed.
\end{itemize}

\end{document}


\documentclass{article}
\usepackage[margin=1.3in]{geometry}
\usepackage{hyperref}
\usepackage{../actuarial}
\usepackage{spedygiorgio-lifecon}

\begin{document}

\section{Motivation}

Originally motivated by \href{https://github.com/spedygiorgio/lifecontingencies/blob/master/vignettes/lifecon.sty}{spedygiorgio's} \texttt{lifecon.sty}, this package mimics its behavior for existing commands and extends it to a certain extent.

\section{Inherited from \texttt{lifecon}}

The following commands are provided for backward compatibility:
\begin{center}
    \begin{verbatim}
        \lcroof{n}
        \lcterm{a}{x}{n}
        \lctermadj{a}{x}{n}
        \lcend{a}{x}{n}
        \lcfirst{a}{x}{y},  \lcfirst[u]{a}{x}{y}
        \lcsecond{a}{x}{y}, \lcsecond[u]{a}{x}{y}
        \lccomptwo{a}{x}{y}{z}
        \lccompthree{a}{x}{y}{z}{w}
        \surstat{a}{x}{n}
        \defsurstat{a}{x}{n}
        \anndue{x}{n}, \anncon{x}{n}, \annimm{x}{n}
        \termins{x}{n},  \insend{x}{n},  \pureend{x}{n}
        \terminsc{x}{n}, \insendc{x}{n}, \pureendc{x}{n}
    \end{verbatim}
\end{center}
%
Styling of \verb"\lcroof" has been replaced with that of \verb"\actuarialangle", since the former is subscripted, unlike the latter.
\begin{center}
    \renewcommand{\arraystretch}{1.4}
    \begin{tabular}{| l | c | c |}
        \hline
        Command               & Old Rendering   & New Rendering  \\ \hline
        $\verb"\lcroof{n}i"$  & $\xlcroof{n}i$  & $\lcroof{n}i$  \\ \hline
    \end{tabular}
\end{center}

The following have been unchanged:
\begin{center}
    \renewcommand{\arraystretch}{1.4}
    \begin{tabular}{| l | c | c |}
        \hline
        Command                             & Old Rendering                   & New Rendering                  \\ \hline
        \verb"\lcterm{a}{x}{n}"             & $\xlcterm{a}{x}{n}$             & $\lcterm{a}{x}{n}$             \\ \hline
        \verb"\lctermadj{a}{x}{n}"          & $\xlctermadj{a}{x}{n}$          & $\lctermadj{a}{x}{n}$          \\ \hline
        \verb"\lcend{a}{x}{n}"              & $\xlcend{a}{x}{n}$              & $\lcend{a}{x}{n}$              \\ \hline
        \verb"\lcfirst{a}{x}{y}"            & $\xlcfirst{a}{x}{y}$            & $\lcfirst{a}{x}{y}$            \\ \hline
        \verb"\lcsecond{a}{x}{y}"           & $\xlcsecond{a}{x}{y}$           & $\lcsecond{a}{x}{y}$           \\ \hline
        \verb"\lccomptwo{a}{x}{y}{z}"       & $\xlccomptwo{a}{x}{y}{z}$       & $\lccomptwo{a}{x}{y}{z}$       \\ \hline
        \verb"\lccompthree{a}{x}{y}{z}{w}"  & $\xlccompthree{a}{x}{y}{z}{w}$  & $\lccompthree{a}{x}{y}{z}{w}$  \\ \hline
    \end{tabular}
\end{center}

The following commands have a slight change in styling:
\begin{center}
    \renewcommand{\arraystretch}{1.4}
    \begin{tabular}{| l | c | c |}
        \hline
        Command                      & Old Rendering                  & New Rendering     \\ \hline
        \verb"\surstat{a}{x}{n}"     & $\xsurstat{a}{x}{n}$     & $\surstat{a}{x}{n}$     \\[2ex] \hline
        \verb"\defsurstat{a}{x}{n}"  & $\xdefsurstat{a}{x}{n}$  & $\defsurstat{a}{x}{n}$  \\[2ex] \hline
    \end{tabular}
\end{center}

Some common life annuity / insurance types:
\begin{center}
    \renewcommand{\arraystretch}{1.4}
    \begin{tabular}{| l | l | c | c |}
        \hline
        Description                & Command                 & Old Rendering       & New Rendering      \\ \hline
        Annuity due                & \verb"\anndue{x}{n}"    & $\xanndue{x}{n}$    & $\anndue{x}{n}$    \\ \hline
        Annuity immediate          & \verb"\annimm{x}{n}"    & $\xannimm{x}{n}$    & $\annimm{x}{n}$    \\ \hline
        Continuous annuity         & \verb"\anncon{x}{n}"    & $\xanncon{x}{n}$    & $\anncon{x}{n}$    \\ \hline
        Discreet term insurance    & \verb"\termins{x}{n}"   & $\xtermins{x}{n}$   & $\termins{x}{n}$   \\ \hline
        Discreet endowment         & \verb"\insend{x}{n}"    & $\xinsend{x}{n}$    & $\insend{x}{n}$    \\ \hline
        Discreet pure endowment    & \verb"\pureend{x}{n}"   & $\xpureend{x}{n}$   & $\pureend{x}{n}$   \\ \hline
        Continuous term insurance  & \verb"\terminsc{x}{n}"  & $\xterminsc{x}{n}$  & $\terminsc{x}{n}$  \\ \hline
        Continuous endowment       & \verb"\insendc{x}{n}"   & $\xinsendc{x}{n}$   & $\insendc{x}{n}$   \\ \hline
        Continuous pure endowment  & \verb"\pureendc{x}{n}"  & $\xpureendc{x}{n}$  & $\pureendc{x}{n}$  \\ \hline
    \end{tabular}
\end{center}
Note the change in notation for pure endowment from $\xpureendc{x}{n}$ to $\pureendc{x}{n}$.

\section{In spirit of \texttt{lifecon}}

The following commands have been added with naming inspired by \texttt{lifecon}:
\begin{center}
    \renewcommand{\arraystretch}{1.4}
    \begin{tabular}{| l | l | c |}
        \hline
        New Command                & Inspired By                 & Rendering                 \\ \hline
        \verb"\lcdue{b}{x}{n}"     & \verb"\anndue{x}{n}"        & $\lcdue{b}{x}{n}$         \\ \hline
        \verb"\lcimm{b}{x}{n}"     & \verb"\annimm{x}{n}"        & $\lcimm{b}{x}{n}$         \\ \hline
        \verb"\lccon{b}{x}{n}"     & \verb"\anncon{x}{n}"        & $\lccon{b}{x}{n}$         \\ \hline
                                   & \verb"\lcterm{b}{x}{n}"     & $\lcterm{b}{x}{n}$        \\ \hline
                                   & \verb"\lctermadj{b}{x}{n}"  & $\lctermadj{b}{x}{n}$     \\ \hline
                                   & \verb"\lcend{b}{x}{n}"      & $\lcend{b}{x}{n}$         \\ \hline
        \verb"\lc{w}{x}{t}"        &                             & $\lc{w}{x}{t}$            \\ \hline
        \verb"\lcp{x}{t}"          &                             & $\lcp{x}{t}$              \\ \hline
        \verb"\lcq{x}{t}"          &                             & $\lcq{x}{t}$              \\ \hline
        \verb"\lcpterm{x}{n}{t}"   &                             & $\lcpterm{x}{n}{t}$       \\ \hline
        \verb"\lcqterm{x}{n}{t}"   &                             & $\lcqterm{x}{n}{t}$       \\ \hline
        \verb"\accomplete{w}"      &                             & $\accomplete{w}$          \\ \hline
        \verb"\acdefer{w}{m}{k}"   &                             & $\acdefer{w}{m}{k}$       \\ \hline
        \verb"\lcelife{x}"         & Complete life expectancy    & $\lcelife{x}$             \\ \hline
        \verb"\lcelifeterm{x}{n}"  &                             & $\lcelifeterm{x}{n}$      \\ \hline
        \verb"\lcecurt{x}"         & Curtate life expectancy     & $\lcecurt{x}$             \\ \hline
        \verb"\lcecurtterm{x}{n}"  &                             & $\lcecurtterm{x}{n}$      \\ \hline
    \end{tabular}
\end{center}

\newpage

\section{Cashflows}

To create cashflow figures, use the \texttt{cf} command:
\begin{center}
    \verb"\cf{length}{}{node pairs}{arrow pairs}"
\end{center}
or, if you want to specify scale (default is $1.5$),
\begin{center}
    \verb"\cf[scale]{length}{}{node pairs}{arrow pairs}"
\end{center}
The node (arrow) pairs should be of the form
\[
    x_1 \verb"/" \ell _1, \cdots , x_n \verb"/" \ell _n
\]
where $x_1, \cdots , x_n$ are the $x$-coordinates of the nodes (arrows), and $\ell _1, \cdots , \ell _n$ are the corresponding labels.

For example, the following is the result of
\begin{center}
    \verb"\cf[1]{3.5}{0/$0$, 1/$1$, 3/$3$}{1/$C_1$, 2/$C_2$}"
    \verb"\cf{3.5}{0/$0$, 1/$1$, 3/$3$}{1/$C_1$, 2/$C_2$}"
\end{center}
%
\begin{center}
    \cf[1]{3.5}{0/$0$, 1/$1$, 3/$3$}{1/$C_1$, 2/$C_2$}
    \cf{3.5}{0/$0$, 1/$1$, 3/$3$}{1/$C_1$, 2/$C_2$}
\end{center}

Another example is $a _{\lcroof{n} i}$, the present value of the following cashflow:
\[
    \cf[1]{6.2}{0/$0$, 1/$1$, 2/$2$, 3/$\cdots $, 4/$n - 1$, 5/$\phantom{1}n\phantom{1}$}{1/$1$, 2/$1$, 3/$\cdots $, 4/$1$, 5/$1$}
\]
and $\ddot{a} _{\lcroof{n} i}$, the present value of the following cashflow:
\[
    \cf[1]{6.2}{0/$0$, 1/$1$, 2/$2$, 3/$\cdots $, 4/$n - 1$, 5/$\phantom{1}n\phantom{1}$}{0/$1$, 1/$1$, 2/$1$, 3/$\cdots $, 4/$1$}
\]

\end{document}


\par
\chapter{{\tt Chv}: Block chevron}
\par
The {\tt Chv} object is used to store and operate on a {\it front}
during a sparse factorization.
The {\tt Chv} object can contain either double precision real or
complex data.
A front is a portion of a matrix, shaded grey in the diagram below.
\begin{center}
\makebox{
% \psfig{file=simple.eps,width=1.0in,height=1.00in}
\psfig{file=../../Chv/doc/simple.eps,width=1.0in,height=1.00in}
}
\end{center}
We use the word ``chevron'' to describe the front, because if you
rotate the figure $45^\circ$ clockwise the shaded region resembles
the chevron insignia of enlisted personnel in the armed forces.
Similar matrices are also known as ``arrowhead'' matrices, but we
have found the ``chevron'' has a simpler abbreviation.
We use the adjective ``block'' to emphasize that the chevron object
may have multiple entries of the diagonal of the matrix.
A ``single'' chevron (which is one way we assemble entries from a
matrix into this data structure) contains a single entry from the
diagonal of the matrix.
\par
The shaded region in the diagram above will normally be sparse,
i.e., many of the entries might be zero.
There are three logical blocks to the {\tt Chv} object:
a nonempty square (1,1) block in the upper left corner,
and (possibly empty) (1,2) and (2,1) blocks in the upper right
and lower left corners.
To conserve space and minimize work on logically zero elements,
we store only rows of the lower part and columns of the upper part
that have (or may have) nonzero elements.
(Note, a particular row or column may
have zero elements, but normally there will be nonzeros in each row
and column that we store.)
\par
{\tt Chv} objects come in three types --- symmetric, Hermitian and
nonsymmetric.
When an object is symmetric or Hermitian, we only store the upper
triangle.
There is one limitation, perhaps unnecessary,
that we put on the {\tt Chv} object ---
the number of rows in the (2,1) block and number of columns
in the (1,2) block are equal.
The {\tt Chv} object is used within the context of a factorization
of a sparse matrix that is assumed to have symmetric structure.
If we ever extend the code to handle a true nonsymmetric structure
factorization (e.g., {\sc umfpack} and {\sc superlu}), then we can
modify the {\tt Chv} object to handle unequal rows and columns.
\par
During a factorization,
a front has to take part in four distinct operations.
\begin{enumerate}
\item
Assemble entries from the original matrix (or matrix pencil).
(See the {\tt Chv\_addChevron()} method.)
\item
Accumulate updates from descendant fronts.
(See the {\tt Chv\_update\{S,H,N\}()} methods.)
\item
Assemble any postponed data from its children fronts.
(See the {\tt Chv\_assemblePostponedData()} method.)
\item
Compute the factorization of the completely assembled front.
(See the {\tt Chv\_factor()} method.)
\end{enumerate}
\par
The implementor of a front object has a great deal of freedom to
design the underlying data structures.
We have chosen to store the entries in each single chevron
in contiguous memory --- the first entry of a chevron is in
the last row of the front, the last entry of a chevron is
in the last column of the front.
The figure below shows the storage locations for the
entries --- on the left is a nonsymmetric chevron, on the right is
a symmetric or hermitian chevron.
\begin{center}
\makebox{
% \psfig{file=simple2.eps,width=2.2in,height=1.00in}
\psfig{file=../../Chv/doc/simple2.eps,width=2.2in,height=1.00in}
}
\end{center}
\par
Any storage format has advantages and disadvantages.
\begin{itemize}
\item[{\bf con}]
Moving along the diagonal is a nonconstant stride through memory.
The same holds for moving along a row in the lower part and along a
column in the upper part.
While the strides are nonconstant, they are easily determined,
particularly when starting in the first chevron.
This affects the search methods that look for a pivot in the (1,1)
block, the method that evaluates a pivot,
the swap methods that swap rows and columns,
and the methods that extract the entries from the chevron to be
stored in the factor matrix.
\item[{{\bf pro}}]
Moving along a row in the upper part and along a column in the
lower part uses a unit stride.
This is useful when performing an update to the remaining part of
the front after a pivot element has been selected.
\item[{\bf pro}]
The assembly of data, be it from the original matrix stored by
chevrons, aggregate update fronts from other processes in a
parallel factorization, or postponed data when pivoting for
stability is used can be done in a straightforward manner.
\end{itemize}
\par
The chevron object exists within the context of a larger global
matrix, and so needs indices to define its rows and columns.
For a symmetric or Hermitian matrix, we only store the column
indices.
For a nonsymmetric matrix, we store the both the row and column
indices.
This second case may seem unnecessary, since we assume that the
larger global matrix has symmetric structure.
However, during a factorization with pivoting enabled,
a pivot element may be chosen from anywhere in the (1,1) block,
so the row indices and column indices may no longer be identical.
\par
A {\tt Chv} object is inherently a serial, single threaded object,
meaning it is designed so that only one thread or process ``owns''
or operates on a particular {\tt Chv} object.
A {\tt Chv} object is an ``atom'' of communication.
It stores postponed rows and columns to be assembled in a parent
front.
It might have to be written to and read from a file in an
out-of-core implementation.
In a distributed environment, it is communicated between processes.
For these reasons, we designed the object so that its data
(the scalars that describe its dimensions, id and type,
the row and column indices, and its entries) are found in
contiguous storage managed by a {\tt DV} object.
A file operation can be done with a single read or write,
a message can be sent without packing and unpacking data,
or defining a new datatype.
Managing working storage for a number of {\tt Chv} objects
is now simpler.
\par
When the {\tt Chv} object contains double precision {\it complex} data,
it stores and operates on them as double precision entries.
We follow the FORTRAN convention that the real and imaginary part
of a complex number are stored consecutively, the real part first
followed by the imaginary number.
In the above complex nonsymmetric matrix,
the third diagonal entry is found
at location 38 {\it in terms of the complex numbers}, but its real
and imaginary parts are found in locations 2*38 = 76 and 2*38+1 = 77
of the double precision vector that stores the entries.
Computations are done in a mix of subroutine calls
(see {\tt Utilites/ZV.h}) and by expanding the complex arithmetic
into real arithmetic.
\par
The {\tt Chv} object ``knows'' about the {\tt IV}, {\tt DV} and
{\tt ZV} vector objects (for {\tt int}, {\tt double} and
{\tt double complex} data types),
the {\tt A2} object for dense 2-D arrays,
and the {\tt SubMtx} object for dense or sparse 2-D submatrices.
These {\tt IV}, {\tt DV}, {\tt ZV}, {\tt A2} and {\tt SubMtx} objects
are subordinate to the {\tt Chv} object.


\section{Overview}
This report contains figures related to the calibration
process of autocorrelator data from Odin-SMR.\\
\newline
Topics examined are:\\
\newline
Calibration of sky signals\\
The statistics of calibrated sky signals seems to be fine
except that mean and median spectra deviates from 0 K
(overestimation of sky signal with up to\(\sim\)0.3 K).
The reason for this should most likely be due to that
the gain varies (for some reason) in a systematic non-linear manner
in such a way that linear interpolation
of reference signals give rise to a systematic error
in the calibration procedure.\\
\newline
Spectral feature in high altitude spectrum\\
The spectral features seen in high altitude spectra are
examined. Spectra are sorted in temperature bins
using hotload temperature as a reference.
It is shown that the phase of the signal seen in high
altitude spectra varies with temperature.
%Thus it seems possible to remove this spectral
%feature from spectra in the calibration procedure by something like:\\
%*first perform the ``standard'' calibration
%*create a table with results from high
%altitude measurements and e.g. hotload temperatures
%*Perform a second calibration
%\\
\clearpage
\newpage

\section{Calibration of sky signals}
In this section results from the calibration of sky signals
from AC2 (stratospheric mode 1) and AC1 (stratospheric mode 2)
are shown. The shape and statistics of calibrated skysignal
spectra from several orbits are explored.

The calibration of sky signals is done by:
\begin{equation}
\label{eq:skysig}
T^{'}_{sky}=\frac{c_{sky}-c^{'}_{sky}}{g^{'}}+T_{sky}\approx(\frac{g}{g^{'}}-1)T_{sys},
\end{equation}
where \(T^{'}_{sky}\) is the estimation of the brightness temperature
of the sky signal, \(c_{sky}\approx g(T_{sys}+T_{sky})\approx gT_{sys}\) is the measured sky signal,
 \(c^{'}_{sky}\) is the reference estimated sky signal
which is retrieved using linear interpolation w.r.t. time using
the measured skysignals around the target \(c_{sky}\),
\(g\) is the true
gain, and \(g^{'}\) is the estimated gain, \(T_{sys}\) is the system
noise temperature.

Equation~\ref{eq:skysig} gives that, even if the gain varies
linearly with time and that we can estimate \(g^{'}=g+\Delta g\) with
an error \(\Delta g\) that is gaussian distributed and has zero mean,
we would expect the average sky signal spectrum to deviate from
0 K. The simple reason for this is that a positive and negative
error in gain will not totally cancel out, i.e.
\(\frac{g}{g+\Delta g} \neq \frac{g}{g-\Delta g}\).
However, in this case the median spectrum would be very close to
0 K.
In this section it is shown that both mean and median of calibrated
skysignal spectra deviates from 0 K.

\clearpage
\newpage

\subsection{AC2}
\begin{figure}[!t]
\centering
\includegraphics[scale=0.35]{ac2skycal1.png}\\
\caption{The upper panel shows a mean spectrum of calibrated
skysignals from AC2 stratospheric mode 1.
The lower panel show a standard deviation spectrum
and percentiles spectra.}
\label{fig:study3ac2a}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.35]{ac2skycal2.png}\\
\caption{Time series of various data from part of an orbit.
The upper (first) panel shows hotload temperatures.
The second panel shows tangent altitudes.
The third panel shows zerolags of skysignals for band 1 of AC2.
The fourth panel shows integration times.
The lower panel shows band 1 average calibrated brightness temperatues.}
\label{fig:study3ac2b}
\end{figure}

The upper panel of Figure~\ref{fig:study3ac2a} shows a mean spectrum
of calibrated sky signals from several orbits. It can clearly be seen
that this spectrum deviates from 0 K (approximately the true brightness
temperature of the sky signal).
The lower panel shows some additional statistics.
The standard deviation of the spectrum is around 2 K,
which agrees well with the expected theoretical noise level
(\(\Delta T =T_{sys}/\sqrt{B*\tau} \approx 3000 K / \sqrt{2MHz*1s}=2.1 K\)).
The percentiles (for example the 25 and 75) are fairly evenly
displaced from the 50\% percentile (median),
which means that the errors are at least close to gaussian
distributed.
The median has the same pattern as the mean (which is hard to see
due to the scale).

The reason for the median deviation from 0 K is most likely due to
some systematic gain variations, i.e. the gain does not vary
completely linearly with time between three sky signals
measurements.

%Equation~\ref{eq:skysig} gives that, even if the gain varies
%linearly with time and that we can estimate \(g^{'}=g+\Delta g\) with
%an error \(\Delta g\) that is gaussian distributed and has zero mean,
%we would expect the average sky signal spectrum to deviate from
%zero. The simple reason for this is that a positive and negative
%error in gain will not totally cancel out, i.e.
%\(\frac{g}{g+\Delta g} \neq \frac{g}{g-\Delta g}\).
%However, since \(\Delta g\) in general is very small this
%does not explain the shape of the median spectrum in Figure~\ref{fig:ac2a}.

Figure~\ref{fig:study3ac2b} show time series of various data from
part of an orbit.
The middle panel shows the variation of zerolags for band 1
of AC2 (the variation of zerolags from other bands looks similiar).
On a short time scale (over one scan down and up) the zerolags increases
until the 4 seconds integration time starts. Then zerolags decreases
during the period with four seconds integration times.
It seems that for the time period when zerolags increases
the increase is not totally linear in time.

This means that on average we probably make a systematic
error or underestimation of \(c^{'}_{sky}\) in the calibration
procedure, which means that we overestimate \(T^{'}_{sky}\)
(see Equation~\ref{eq:skysig}).
To overcome this problem a possible solution would be to use a weighted
quadratic interpolation as we have earlier discussed.

\clearpage
\newpage
\subsection{AC1}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.35]{ac1skycal1.png}\\
\caption{The upper panel shows a mean spectrum of calibrated
skysignals from AC1 stratospheric mode 2.
The lower panel show a standard deviation spectrum
and percentiles spectra.}
\label{fig:study3ac1a}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.35]{ac1skycal2.png}\\
\caption{Time series of various data from part of an orbit.
The upper (first) panel shows hotload temperatures.
The second panel shows tangent altitudes.
The third panel shows zerolags of skysignals for band 3 of AC1.
The fourth panel shows integration times.
The lower panel shows band 1 average calibrated brightness temperatues.}
\label{fig:study3ac1b}
\end{figure}

Figures~\ref{fig:study3ac1a} and~\ref{fig:study3ac1b} show corresponding
data as Figures~\ref{fig:study3ac2a} and~\ref{fig:study3ac2b}
but for AC1 (stratospheric mode 2).
The results look very similiar for AC1 as for AC2.
The statistics of calibrated sky signals looks as expected
except that mean and median values deviates from 0 K
with around 0.25 K (Figure~\ref{fig:study3ac1a}),
except the two problematic bands in the lower part of the
spectrum.
Similiar pattern of short time scale variations in zerolag
as for AC2 is obsereved (Figure~\ref{fig:study3ac1b}).

\clearpage
\newpage
\section{High altitude spectra}
\begin{figure}[!t]
\centering
\includegraphics[scale=0.35]{ac1highalt.png}\\
\caption{The upper panel show median of high altitude (60-120 km)
spectra for different temperatures for AC1 stratospheric mode 2.
The lower panel shows fits to spectra in the upper panel.}
\label{fig:study3ac1c}
\end{figure}

\begin{figure}[!t]
\centering
\includegraphics[scale=0.35]{ac2highalt.png}\\
\caption{The upper panel show median of high altitude (60-120 km)
spectra for different temperatures for AC2 stratospheric mode 1.
The lower panel shows fits to spectra in the upper panel.}
\label{fig:study3ac2c}
\end{figure}

In this section high altitude spectra from AC1 and AC2 are explored.
We know from earlier studies that these spectra contains
spectral features even though we do not expect this.
This spectral features should come from that either the sky signal
or the target signal is perturbed. Most likely it comes from ripple on the
sky signal. Regardless where it comes from, it should be possible to remove
this spectral feature in the calibration process. Although, the way to
properly remove it depends on where it comes from.

However, in this section we look at the temperature dependence
of the spectral features. Figures~\ref{fig:study3ac1c} and~\ref{fig:study3ac2c}
shows median of calibrated high altitude measurements from around
200 orbits from 2009-08-24 to 2009-09-24.
The data is sorted in temperature bins using the hotload temperature
as reference temperature.
Figure~\ref{fig:study3ac1c} shows that the phase of the signal seen in AC1
high altitude measurements varies with temperature.
This effect can also be seen in Figure~\ref{fig:study3ac2c} for AC2
although it is not so clear as for AC1.


\section{The \maxseq algorithm}
\Label{sec:maxseq}

In this section we consider the function \maxseq \cite[Ch.~3]{ACSLTutorial})
which is very similar to the function \specref{maxelement}.
The main difference between \maxseq and \maxelement is that
\maxseq returns the maximum value (not just the index of it).
Therefore, it requires a \emph{non-empty} range as an argument.

Of course, \maxseq can easily be implemented using \implref{maxelementii}.
Moreover, relying only on the formal specification of \specref{maxelementii},
we are also able to deductively verify the correctness of this implementation.
Thus, we have a simple example of \emph{modular verification} in the following sense:
\begin{quote}
Any implementation of \maxelementii that is separately
 proven to implement the contract \specref{maxelementii}
 makes \maxseq behave correctly.
 Once the contracts have been defined, the function \maxelementii
 could be implemented in parallel, or just after \maxseq,
 without affecting the verification of \maxseq.
\end{quote}

\subsection{Formal specification of \maxseq}

The following listing shows the formal specification of \specref{maxseq}.

\input{Listings/max_seq.h.tex}

Using the first \inl{requires}-clause we express that \maxseq needs a \emph{non-empty} range as input.
Our postconditions
formalize that \maxseq indeed returns the maximum value of the range.

%\clearpage

\subsection{Implementation of \maxseq}

The implementation of \implref{maxseq} consists of a simple call to \implref{maxelementii}.
Since \maxseq requires a non-empty range the call of \maxelementii
returns an index to a maximum value in the range.
The fact that \maxelementii returns the smallest index is of no importance
in this context.

\input{Listings/max_seq.c.tex}

\clearpage