\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}
\usepackage{bbm}
\usepackage{amsfonts}
\usepackage{aastex}
\usepackage{amssymb}
\usepackage{physics}
\usepackage{geometry}
\usepackage{fancyhdr}
\usepackage{subcaption}
\usepackage{siunitx}
\usepackage{textgreek}
\usepackage{slashed}
\usepackage{varioref}
\usepackage{hyperref}
\hypersetup{colorlinks=true, citecolor=blue, urlcolor=blue, linkcolor=black}
\usepackage{cleveref}
%\usepackage{caption}
\usepackage{tcolorbox}
\usepackage{tensor}
\usepackage[T1]{fontenc}
\usepackage{kpfonts}%  for math
%\usepackage[scaled=0.8]{beramono}
\usepackage[scaled=0.85]{DejaVuSansMono}
\usepackage[mono=false,oldstyle]{libertine}%  serif and sans serif
\usepackage{listings}
\usepackage{xcolor}
\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.58,0,0.82}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}

\lstdefinestyle{mystyle}{
    backgroundcolor=\color{backcolour},
    commentstyle=\color{codegreen},
    keywordstyle=\color{magenta},
    numberstyle=\tiny\color{codegray},
    stringstyle=\color{codepurple},
    basicstyle=\ttfamily\footnotesize,
    breakatwhitespace=false,
    breaklines=true,
    captionpos=b,
    keepspaces=true,
    numbers=left,
    numbersep=5pt,
    showspaces=false,
    showstringspaces=false,
    showtabs=false,
    tabsize=2
}

\lstset{style=mystyle}
\usepackage{natbib}
\bibliographystyle{mnras}
\newcommand{\matlab}{\textsc{matlab}}
\newcommand{\tempo}{\textsc{tempo}2}
\newcommand{\libstempo}{\textsc{libstempo}}
\newcommand{\glitchhmm}{\texttt{glitch\_hmm}}
\title{Using the HMM glitch detector}
\author{Liam Dunn, Andrew Melatos, Sofia Suvorova, Bill Moran, Rob Evans}

\begin{document}
\maketitle
\tableofcontents
\section{Introduction}
This document outlines the use of \glitchhmm{}, a hidden Markov Model (HMM)-based pulsar glitch detection code which is described in detail by \citet{MelatosDunn2020}.
The purpose of \glitchhmm{} is to provide a quantitative framework for the detection of pulsar glitches based on time of arrival (ToA) data.
The package consists of three components:
\begin{itemize}
    \item A core MATLAB component which contains the HMM implementation (\texttt{matlab\_code\_logs/} in the repository).
    \item A Python library which takes a \texttt{.par} and \texttt{.tim} file and constructs an  HMM to be passed to the MATLAB code (\texttt{pulsar\_hmm/} in the repository).
    \item A Python wrapper which provides a \texttt{.ini} file-based interface to the above two components (\texttt{hmm\_wrapper/} in the repository).
\end{itemize}

The main system requirements are the following:
\begin{itemize}
    \item Python 3
    \item A recent version of MATLAB (tested with 2018b+), with Image Processing Toolbox installed
    \item \tempo{}
    \item \libstempo{}
\end{itemize}

\section{Method overview}
This section provides an overview of the methodology and algorithms used in \glitchhmm{}.
A comprehensive treatment is given by \citet{MelatosDunn2020}.

\subsection{Hidden Markov models in general}
\label{subsec:hmms_general}
Hidden Markov models (HMMs) provide a framework for analysing the evolution of a system whose underlying dynamics are \emph{Markovian} (memoryless) and which is observed indirectly (the true state of the system is \emph{hidden}).
The system is taken to be discrete in time, with snapshots taken at times in the set $\{t_1, t_2, \ldots, t_{N_T}\}$.
The hidden state of the system is denoted $q(t_n)$ and can take on $N_Q$ distinct values.
The evolution of the hidden state of the system is determined by a transition matrix \begin{equation} A_{q_j q_i} = \Pr[q(t_{n+1}) = q_j \mid q(t_n) = q_i]. \end{equation}
An observation of the system yields a result $o(t_n)$.
Note that the result of an observation is not necessarily drawn from a discrete set.
The probability of an observation $o(t_n)$ given that the system is in the state $q(t_n) = q_i$ is referred to as the emission probability, and is given by \begin{equation} L_{o(t_n)q_i} = \Pr[o(t_n) \mid q(t_n) = q_i]. \end{equation}

A realisation of an HMM yields a sequence of hidden states $Q_{1:N_T} = \left\{q(t_1), q(t_2), \ldots, q(t_{N_T})\right\}$ and a sequence of observations $O_{1:N_T} = \left\{o(t_1), o(t_2), \ldots, o(t_{N_T})\right\}$.
The total probability of a particular $Q_{1:N_T}$ given the observations $O_{1:N_T}$ can be written as \begin{equation} \Pr(Q_{1:N_T} \mid O_{1:N_T}) = \Pi_{q(t_1)}L_{o(t_1)q(t_1)}\prod_{n=2}^{N_T}A_{q(t_n)q(t_{n-1})}L_{o(t_n)q(t_n)}, \end{equation}
where $\Pi_{q(t_1)}$ is the probability that the state is initalised in the state $q(t_1)$.

\subsection{Timing pulsars with hidden Markov models}
\label{subsec:hmms_timing}
To apply the HMM framework described in the Section \ref{subsec:hmms_general} to pulsar timing, we first identify the set of hidden states $\{q_i\}$ with a discrete grid of $(f, \dot{f})$ pairs which encode the instantaneous spin frequency and its first time derivative.
The grid is uniformly spaced in both directions, with $\eta_f$ and $\eta_{\dot{f}}$ denoting the space between adjacent grid points in the $f$ and $\dot{f}$ directions respectively.

We also stipulate that measurements of the system occur at each ToA measurement, and the observational datum at each timestep is the time elapsed since the last ToA measurement, i.e. $o(t_n) = t_n - t_{n-1} \equiv x_n$.
The values of $f$ and $\dot{f}$ are combined with fixed secular values $f_\text{LS}$ and $\dot{f}_\text{LS}$ measured at a reference epoch $T_0$ to give the full phase evolution \begin{equation} \Phi(t_n; f, f_\text{LS}, \dot{f}, \dot{f}_\text{LS}) = \left[f + f_\text{LS} + \dot{f}_\text{LS}(t_n-T_0)\right]x_n - \frac{1}{2}\left(\dot{f} + \dot{f}_\text{LS}\right)x_n^2. \end{equation}
The minus sign in the second term arises because we use a backwards Taylor expansion.
A secular second frequency derivative $\ddot{f}_\text{LS}$ can also be included.

The emission probability $L_{x_n q_i}$ is calculated based on the fact that the number of cycles elapsed during each ToA gap should be an integer.
This is implemented mathematically using a von Mises distribution, the precise mathematical form is given in equation 3 of \citet{DunnMelatos2022}.
The two main contributions to the variance of $\Phi(t_n; \ldots)$ are the measurement uncertainty on the ToAs, and the phase uncertainty due to the discrete gridding in $f$ and $\dot{f}$.

The evolution of the pulsar's hidden state during the gap between consecutive ToAs in the absence of a glitch is not assumed to be deterministic: we allow for some wandering in $f$ and $\dot{f}$ due to timing noise.
The default model assumes that he timing noise is driven by a white-noise torque derivative.
An explicit expression for $A_{q_j q_i}$ using this model is given by equations 10--13 and B7--B11 of \citet{MelatosDunn2020}, which also includes further discussion of this timing noise model in Section 3.4.
We also have the option to construct a model with a glitch included during a particular ToA gap.
If the model includes a glitch during a particular ToA gap, the transition matrix for that gap is modified so that the pulsar transitions with equal probability from the state $(f, \dot{f})$ to all available states $(f', \dot{f}')$ satisfying $f' > f + \dot{f}x_n$.

\subsection{Computations}
In this section we briefly describe the most common computations carried out using the HMM pulsar timing framework.
A general overview and description of common algorithms using HMMs can be found in \citet{Rabiner1989}, and further detailed descriptions of the algorithms used in this package can be found in Appendix A of \citet{MelatosDunn2020}.

Broadly speaking, there are two kinds of questions that \glitchhmm{} can be used to tackle: are there any glitches in a stretch of pulsar timing data, and what is the evolution of $f$ and $\dot{f}$ over that stretch?
These two questions are tackled through two closely related algorithms, the forward and forward-backward algorithms respectively.

\subsubsection{Glitch detection}
\label{subsec:glitch_det}
The question of glitch detection is framed as a question of Bayesian model selection.
Let $M_0$ denote the model which includes no glitches, and $M_1(k)$ denote the model which includes a glitch during the $k$th ToA gap.
For a given HMM $M$, the forward algorithm computes the model evidence $\Pr[O_{1:N_T} \mid M]$ [see Appendix A.1 of \citet{MelatosDunn2020}].
Then we can compute the Bayes factors \begin{equation} K_1(k) = \frac{\Pr[O_{1:N_T} \mid M_1(k)]}{\Pr[O_{1:N_T} \mid M_0]}. \end{equation}
Glitch candidates occur when $K_1(k)$ exceeds a predetermined threshold $K_\text{th}$, by default set at $10^{1/2}$ to achieve a false alarm rate of approximately 1\% \citep{MelatosDunn2020}.
A greedy procedure may be used to account for the possibility of multiple glitches in a stretch of data, as described in Section 4.2 of \citet{MelatosDunn2020}.

\subsubsection{Hidden state evolution}
\label{subsec:hidden_evo}
The evolution of $f$ and $\dot{f}$ is analysed through the hidden state posterior distribution $\gamma_{q_i}(t_n) = \Pr[q(t_n) = q_i \mid O_{1:N_T}]$, computed using the forward-backward algorithm [see Appendix A2 of \citet{MelatosDunn2020}].
The full posterior distribution is available as an analysis output, but it is typically more convenient to consider the posterior distributions on $f$ and $\dot{f}$ alone (marginalising over the other), denoted by $\gamma_f(t_n)$ and $\gamma_{\dot{f}}(t_n)$ respectively.
A point estimate of the evolution of $f$, $\hat{f}(t_n)$, can then be obtained by simply taking the maximum of $\gamma_f(t_n)$ at each timestep.
An analogous computation provides $\hat{\dot{f}}(t_n)$.

\section{Choosing parameters}
Putting \glitchhmm{} into practice requires the user to choose a number of parameters on a per-analysis basis.
This section describes some considerations and rules of thumb to help guide the user.

\subsection{Domain of interest}
\label{subsec:doi}
The domain of interest (DOI) refers to the set of allowed $f$ and $\dot{f}$ states in the HMM.
Recall that the hidden states specify deviations away from a secular trend (see Section \ref{subsec:hmms_timing}), so that $f = \dot{f} = 0$ indicates that the pulsar is precisely following the phase evolution specified by $f_\text{LS}$, $\dot{f}_\text{LS}$, and $T_0$.
The DOI is always set up as a uniform grid, and the boundaries and grid spacing are both important parameters.

Both the $f$ and $\dot{f}$ intervals covered by the DOI (denoted $[f_-, f_+]$ and $[\dot{f}_-, \dot{f}_+]$ respectively) must be chosen to accommodate both wandering due to timing noise and any possible glitches.
Providing a universal prescription for choosing the DOI boundaries is not feasible, but \citet{DunnMelatos2022} found that for a broad range of pulsars a frequency range of $[f_-, f_+] = [-3 \times 10^{-7}\,\mathrm{Hz}, 3 \times 10^{-7}\,\mathrm{Hz}]$ and a frequency derivative range of $[0.1\dot{f}_\text{LS}, -0.1\dot{f}_\text{LS}]$ was appropriate.
In the case where a glitch is in fact present in the data it may be necessary to increase $f_+$ to accomodate the frequency jump.

The DOI is discretised with uniform spacing in $f$ and $\dot{f}$, with spacings denoted $\eta_f$ and $\eta_{\dot{f}}$ respectively.
The choice of $\eta_{\dot{f}}$ is connected to the level of timing noise in the pulsar -- see Section \ref{subsec:tn}.
At this stage a reliable way of measuring the timing noise and turning this into a value for $\eta_{\dot{f}}$ is not at hand, and a more ad hoc method is unfortunately needed.
For example, \citet{DunnMelatos2022} chose \begin{equation} \eta_{\dot{f}} = \frac{\dot{f}_+ - \dot{f}_-}{11}, \end{equation} in combination with the prescription for $\dot{f}_{+,-}$ noted in the previous paragraph. Hence the DOI was always discretised into 11 $\dot{f}$ bins, with the bin width increasing as the magnitude of $\dot{f}_\text{LS}$ increased.
A rule of thumb for choosing $\eta_f$ depends in turn on the value of $\eta_{\dot{f}}$: it is a good idea for $\eta_f$ to be chosen so that the typical change in frequency due to a non-zero $\dot{f}$ is larger than $\eta_f$, i.e. \begin{equation} \eta_f \approx 2\eta_{\dot{f}}\langle x_n \rangle \end{equation} where $\langle x_n \rangle$ is the mean ToA gap in the dataset.
This assumes that $\eta_{\dot{f}}$ is the smallest possible non-zero value of $\dot{f}$ in the DOI, which will typically be the case.
\subsection{Timing noise}
\label{subsec:tn}
By default, \glitchhmm{} assumes that timing noise in the pulsar is driven by a white noise term in the second frequency derivative, viz. \begin{equation} \frac{\dd^2f}{\dd t^2} = \xi(t),\quad \langle\xi(t)\xi(t')\rangle = \sigma^2\delta(t-t').\label{eqn:tn}\end{equation}
This model is not intended to be a universal choice, but it has been tested on both synthetic data which includes timing noise of a manifestly different form (white noise term in frequency derivative, see \citealt{MelatosDunn2020}) and real data sets from a variety of pulsars \citep{Lower2021, DunnMelatos2022} (though note in the former reference it was found that modifying the timing noise model to include white noise in the frequency derivative instead was appropriate for a few pulsars).

The magnitude of the timing noise included in the HMM is controlled by the $\sigma$ parameter in (\ref{eqn:tn}), which has units of $\mathrm{Hz}\,\mathrm{s}^{-3/2}$.
By default, its value depends on the value of $\eta_{\dot{f}}$ (see \ref{subsec:doi}) as \begin{equation} \sigma = \eta_{\dot{f}}\langle x_n\rangle^{-1/2}\end{equation} where $\langle x_n\rangle$ is the mean ToA gap in the dataset.
The rationale behind this choice is described in 6.1 of \citet{MelatosDunn2020}.
This value can be overridden if desired -- see Listing \ref{lst:eg_ini}.

\section{Using \texttt{hmm\_wrapper}}
\label{sec:hmm_wrapper}
For the most part, analyses should be run through the scripts in \texttt{hmm\_wrapper/}, principally \texttt{run\_hmm.py}.
These scripts depend on the \texttt{pulsar\_hmm} package included in this repository --- you can install that package by running \texttt{pip install .} inside the \texttt{pulsar\_hmm/} folder.

\texttt{run\_hmm.py} takes three command-line inputs: \texttt{-\/-par}, which specifies the \texttt{.par} file to be used, \texttt{-\/-tim}, which specifies the \texttt{.tim} file to be used, and \texttt{-\/-ini}, which specifies the \texttt{.ini} file to be used.
The \texttt{.par} and \texttt{.tim} files should be \tempo{}-style files.
An example \texttt{.ini} file is shown in Listing \ref{lst:eg_ini} below.
\begin{lstlisting}[caption=Example \texttt{.ini} file, label={lst:eg_ini}]
# This section specifies the "domain of interest" (DOI), the allowed range of frequency and frequency
# derivative, and the spacing between grid points for each.
[doi]
# Minimum allowed frequency in Hz
freq_min = -3e-7
# Maximum allowed frequency in Hz
freq_max = 3e-6
# Spacing between frequency grid points in Hz
dfreq = 1e-8
# Minimum allowed frequency derivative in  Hz/s
fdot_min = -1e-15
# Maximum allowed frequency derivative in  Hz/s
fdot_max = 1e-15
# Spacing between frequency derivative grid points in Hz/s
dfdot = 1e-16

# This section contains any parameters related to the inclusion of timing noise in the HMM
[tn]
# Override default value of sigma specified in equation 8 (commented out for the purposes of the demo)
#sigma = 1e-20

# This section specifies any restrictions on the ToAs to be used
[toas]
# ToAs before mjd_min will not be used
mjd_min = 58514
# ToAs after mjd_max will not be used
mjd_max = 58700
# ToAs separated by less than min_toa_gap days will be discarded
min_toa_gap = 1

# This section specifies where to find the relevant MATLAB code. Paths must be absolute.
[matlab]
# The path to the core MATLAB implementation (matlab_code_logs/ in the repository)
matlab_path = /fred/oz022/ldunn_glitch/glitch_hmm/matlab_code_logs_stable
# The path to the appropriate MATLAB wrapper script (usually hmm_wrapper/do_matlab_analysis.m)
matlab_wrapper = /fred/oz022/ldunn_glitch/glitch_hmm/hmm_wrapper/do_matlab_analysis.m

# This section specifies the location of the analysis output. Paths must be absolute.
[out]
# All output files will begin with this prefix
out_prefix = /fred/oz022/ldunn_glitch/glitch_hmm/hmm_wrapper/demo/results/J1452-6036_
\end{lstlisting}

There is an example analysis waiting to be run in \texttt{hmm\_wrapper/demo/}. It uses data from {PSR J${1452-6036}$} released by the UTMOST collaboration in their first public data release \citep{LowerBailes2020}, the entirety of which can be found \href{https://github.com/Molonglo/TimingDataRelease1}{here}.
To run this demo, first edit \texttt{demo.ini} in that directory so that the variables \texttt{matlab\_path}, \texttt{matlab\_wrapper}, \texttt{working\_prefix}, and \texttt{out\_prefix} are appropriately set (noting that all paths must be absolute, not relative).
Also, make sure the directories referred to in \texttt{working\_prefix} and \texttt{out\_prefix} exist.
Then, from the \texttt{hmm\_wrapper/demo/} directory, run the analysis:
\begin{lstlisting}
$ python ../run_hmm.py --par J1452-6036.par --tim J1452-6036.tim --ini demo.ini
\end{lstlisting}
When the analysis has finished, several files will appear in the directory specified by \texttt{out\_prefix}.
The next section discusses these analysis results in detail.
\section{Output}
The analysis run by \texttt{run\_hmm.py} (see Section \ref{sec:hmm_wrapper}) produces quite a few output files, which are described in this section.
In the following, we will refer to output files by their name \emph{excluding} \texttt{out\_prefix}.

\subsection{\texttt{res.dat}}
This file contains the essential details of any glitch candidates which were found in the analysis.
Each row corresponds to a glitch candidate, in descending order of significance.
The first column gives the index of the ToA gap containing the glitch candidate, and the second column gives the (natural) log Bayes factor of the glitch candidate.

\subsection{\texttt{\{f, fdot\}\_path.dat}}
These files contain  the maximum \emph{a posteriori} values of $f$ and $\dot{f}$ during each ToA gap, calculated using the model which includes all glitch candidates above the threshold.
Plots of these paths are also produced as \texttt{\{f, fdot\}\_path.pdf}.

\subsection{\texttt{\{f, fdot\}\_posterior.dat}}
These files contain the natural logarithms of the marginalised $f$ and $\dot{f}$ posteriors during each ToA gap.
Each row corresponds to a frequency (derivative) bin, in ascending order.
Plots of these posteriors are also produced as \texttt{\{f, fdot\}\_posterior.pdf}.

\subsection{\texttt{bfs.dat}}
This file contains the log Bayes factors computed in the course of the model selection procedure described in Section 4 of \citet{MelatosDunn2020}.
The procedure is a greedy one, so each iteration corresponds to calculation of new Bayes factors comparing models with all of the glitches of the most-preferred model from the previous iteration, plus one new glitch.
Plots showing the Bayes factors at each iteration are also produced, named \texttt{bfs\_i.pdf} where \texttt{i} is the iteration.

\subsection{\texttt{analysis.mat}}
Thie file contains a MATLAB workspace with the results of the analysis.
This workspace contains all of the above data products, plus a few others which are not dumped by default.
The following is a list of important variables found in that workspace, along with a brief description:
\begin{itemize}
    \item \texttt{max\_BFs} --- contains the maximum log Bayes factors obtained in each iteration of the greedy glitch detection algorithm.
    \item \texttt{all\_BFs} -- contains all log Bayes factors calculated in each iteration of the greedy glitch detection algorithm.
    \item \texttt{fdots} --- contains the frequency derivatives in the domain of interest (DOI).
    \item \texttt{freqs} --- contains the frequencies in the DOI.
    \item \texttt{full\_posterior} --- contains the unmarginalised posterior on frequency and frequency derivative for the model selected by the glitch detection procedure.
    \item \texttt{fdot\_posterior} --- contains \texttt{full\_posterior} after marginalistaion over frequency.
    \item \texttt{freq\_posterior} --- contains \texttt{full\_posterior} after marginalistaion over frequency derivative.
    \item \texttt{glitches} --- contains the indexes of the ToA gaps during which a glitch was detected.
    \item \texttt{kappa\_per\_toa} --- contains $\kappa$ for each ToA gap, defined as the reciprocal of the squared phase uncertainty across each ToA gap (measured in radians).
    \item \texttt{path} --- contains the maximum \emph{a posteriori} path in frequency derivative (first column) and frequency (second column), calculated using the model returned from the glitch detection algorithm.
    \item \texttt{residuals} --- contains the phase residuals of \texttt{path}, measured in cycles.
\end{itemize}

\subsection{Plots}
In addition to the ASCII and \texttt{.mat} files described in the rest of this section, \glitchhmm{} also generates a number of plots in \texttt{.pdf} format.
In this subsection we describe those plots and show example plots generated from the PSR J1452$-$6036 analysis in \texttt{hmm\_wrapper/demo/}.
We emphasise that these plots are generated for convenience, and are not necessarily intended to be publication-quality -- all the data from which they are derived are available in the files described in the rest of this section.

\subsubsection{\texttt{bfs\_i.pdf}}
These plots show the log Bayes factors generated by successive iterations of the greedy model selection procedure used to detect glitches (see Section \ref{subsec:glitch_det}).
\texttt{bfs\_0.pdf} shows the first iteration, \texttt{bfs\_1.pdf} the second, and so on.
The plots generated for the PSR J1452$-$6036 example analysis are shown in Fig. \ref{fig:eg_bfs}.
\begin{figure}
    \centering
    \includegraphics[width=0.5\textwidth]{figures/J1452-6036_bfs_0.pdf}
    \includegraphics[width=0.5\textwidth]{figures/J1452-6036_bfs_1.pdf}
    \includegraphics[width=0.5\textwidth]{figures/J1452-6036_bfs_2.pdf}
    \caption{Example \texttt{bfs\_i.pdf} plots from the demo PSR J1452$-$6036 analysis. \texttt{bfs\_0.pdf} is shown in the top panel, \texttt{bfs\_1.pdf} in the middle, and \texttt{bfs\_2.pdf} (the terminating step) in the bottom panel.}
    \label{fig:eg_bfs}
\end{figure}

\subsubsection{\texttt{\{f, fdot\}\_path.pdf}}
These plots show the sequence of most likely hidden $f$ and $\dot{f}$ states at each timestep (see Section \ref{subsec:hidden_evo}).
The plots generated for the PSR J1452$-$6036 example analysis are shown in Fig. \ref{fig:eg_paths}.
\begin{figure}
    \centering
    \includegraphics[width=0.49\textwidth]{figures/J1452-6036_f_path.pdf}
    \includegraphics[width=0.49\textwidth]{figures/J1452-6036_fdot_path.pdf}
    \caption{Pointwise most likely paths $\hat{f}(t_n)$ \emph{(left)} and $\hat{\dot{f}}(t_n)$ \emph{(right)} from the demo PSR J1452$-$6036 analysis.}
    \label{fig:eg_paths}
\end{figure}

\subsubsection{\texttt{\{f, fdot\}\_posterior.pdf}}
These plots show heatmaps of the marginalised $f$ and $\dot{f}$ posterior probability densities, denoted $\gamma_f$ and $\gamma_{\dot{f}}$ respectively (see Section \ref{subsec:hidden_evo}).
We plot the heatmap of $\ln[\gamma_f]$ rather than $\gamma_f$ directly because $\gamma_f$ is frequently very strongly peaked, and heatmaps of $\gamma_f$ thus do not display well.
\begin{figure}
    \centering
    \includegraphics[width=0.49\textwidth]{figures/J1452-6036_f_posterior.pdf}
    \includegraphics[width=0.49\textwidth]{figures/J1452-6036_fdot_posterior.pdf}
    \caption{Heatmaps of $\ln[\gamma_f(t_n)]$ \emph{(left)} and $\gamma_{\dot{f}}(t_n)$ \emph{(right)} from the demo PSR J1452$-$6036 analysis.}
    \label{fig:my_label}
\end{figure}
\bibliography{refs}{}
\end{document}


% !TeX spellcheck = en_GB
\section{Integrated Vapour Transport}
\label{sec:dim:atm_riv}
An atmospheric river (AR) is a filament structure of intense moisture transport from the tropics to higher latitudes. Heavy precipitation can be associated with it, because the air is warm and moist. This can often be observed at mountain ranges at west coasts such as in Norway \citep{azad_extreme_2017}. Due to orographic lifting the moisture will be released and follow high amounts of precipitation.
\\
An atmospheric river is characterised if the integrated vapour transport shows values higher than \SI{250}{\IVT} and a continuous region larger than \SI{2000}{\km} \citep{rutz_climatological_2014}.
\\
The integrated vapour transport (IVT, \Cref{sec:weather:atm_riv}) was calculated from the ECMWF data as followed:
\begin{align}
IVT = \frac{1}{g} \int\limits_{p_{sfc}}^{\SI{100}{\hPa}} q \mathbf{V} dp \qquad [\SI{}{\IVT}]
\label{eq:IVT}
\end{align}
where $g$ is the standard gravity, $q$ the specific humidity, and $\mathbf{V}$ the total wind vector at each pressure level $p$. The numerical, trapezoidal integration is performed by using data from the surface pressure $p_{sfc}$ to \SI{850}{\hPa} in \SI{50}{\hPa} intervals and from \SIrange{700}{100}{\hPa} in \SI{100}{\hPa} intervals.
%%%%%%%%%%%%

%%% NAO %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{North Atlantic Oscillation}
It has long been known that precipitation and temperature fluctuations occur during European winter in connection with NAO (North Atlantic Oscillation). The NAO is a redistribution of atmospheric mass between the North Atlantic high (Azores high), and the polar low (Iceland low).
The NAO index is defined as the gradient between the sea level pressure of the Azores high and the Icelandic low during the winter months (December - March) \citep{hurrell_decadal_1995}. Positive index shows the deepening of the Icelandic low and a strengthening of the Azores high and negative indexes respectively \citep{uvo_analysis_2003}.
\\
Positive NAO is associated with stronger westerlies than usual across the middle latitudes of the Atlantic \citep{uvo_analysis_2003}. In addition, more moisture is transported to Scandinavia \citep{hurrell_decadal_1995}. A positive NAO during winter is often associated with higher temperatures than normal and with an increase in precipitation in northern Europe and low temperatures in southern Europe \citep{uvo_analysis_2003}.


Since each \ecoli{} \isol{} in \cplop{} has a \pyro{} of two separate \itsshort{} regions\footnote{see \autoref{sec:background:isolates}}, we effectively have two \compfuncs{} between datapoints (\isols{}), complicating our use of \kNN{}.
\kNN{} provides \cplop{} biologists a transparent and intuitive way of understanding the \spec{} classification it asserts, so we find that it will be a usefully insightful .
Applying \kNN{} to \cplop{} \isols{} gives us two lists, one for each \itsshort{} region, that we must make a single \spec{} classification from.
In order to accommodate multiple \compfuncs{}, we need a strategy to resolve multiple \knnlong{} lists.
Rather than create a new similarity metric out of a pair of similarity scores, which may deviate from the inherent nature of the \compfunc{}, we choose to update the \kNN{} method with four different ways of selecting the resultant category label: the \kraplong{} (\krap{}).
%We propose the \krap{}, four strategies to resolve these multiple \knnlong{} lists that multiple \compfuncs{} result in.
%Furthermore, \kNN{} provides \cplop{} biologists a transparent and intuitive way of understanding the \spec{} classification it asserts.
We describe these four methods, the evaluation criteria we judge them by, and their results below.

\section{Methodology}\label{sec:methodology:krap}

In what follows, we generalize our problem. Given \UNKNOWN{} and \KNOWN{}, two library objects (\isols{}), and a collection of \compfuncs{}, \COMP{}$=(\COMP{}_1,\ldots \COMP{}_m)$, with $m > 1$, comparing \UNKNOWN{} to \KNOWN{} gives us a collection of values:
$\COMP{}(\UNKNOWN{},\KNOWN{}) = (\COMP{}_1(\UNKNOWN{},\KNOWN{}),\ldots,\COMP{}_m(\UNKNOWN{},\KNOWN{}))$.
All four resolution procedures described in this section work with such a generalized representation of \isols{} and \compfuncs{} between them.

Given an unknown \isol{} \UNKNOWN{}, a library of classified\footnote{A ``classified \isol{}'' is an \isol{} for which the \spec{} has been identified in the database.} \isols{} \LIB{}, and a set of \compfuncs{} \COMP{}, we compare \UNKNOWN{} to each object in \LIB{} using each \compfunc{} in \COMP{}. To resolve these \compfuncs{}, we propose four algorithms:

\subsection{Comparing \Isols{}}
Comparing \isols{} to each other is of primary interest to biologists using \cplop{}.
%Of primary interest to the biologists using \cplop{} is comparing \isols{} to each other.
\cplop{} represents each \isol{} by a pair of mutually incomparable \pyros{}: one for each of the two \itsshort{} regions.
As a result, given \isols{} $I_1, I_2$, we can represent each as a pair of pyroprint vectors
\[I_1 = (\vec{q}_1, \vec{q}_2) \text{ and } I_2 = (\vec{r}_1, \vec{r}_2),
\]
where $\vec{q}_1 \text{ and } \vec{r}_1$ are respectively $I_1 \text{ and } I_2$'s \Ssixt{} \pyro{} and $\vec{q}_2 \text{ and } \vec{r}_2$ are respectively $I_1 \text{ and } I_2$'s \Sfive{} \pyro{} \cite{Black2014121}. Since \pyro{}s from different regions are incomparable, comparing \isol{}s must be done as follows:
\[
\COMP{}(I_1, I_2) = (\pcfunclabel(\vec{q}_1, \vec{r}_1), \pcfunclabel(\vec{q}_2, \vec{r}_2)),
\]
where $\pcfunclabel(\cdot,\cdot)$ is between \pyros{} of the same \itsshort{} region and is the \pearson{}. Thus, when comparing \isol{}s, we effectively have two different similarity metrics, one for each \itsshort{} region:
\[
\COMP{}(I_1, I_2) = (\COMPsixt{}(I_1, I_2), \COMPfive{}(I_1, I_2)).
\]

\input{algorithms/comparison}

%%%%%%%%%% FILTER %%%%%%%%%%
\subsection{\a{} Filtering}\index{\a{} filtering}
Our first modification to \kNN{} is an additional condition at step \ref{knn:filter}, after finding the \knnlong{}:
\begin{enumerate}
\setcounter{enumi}{3}
\item Consider only the top $k$ entries in $N$ above threshold $\alpha$
\end{enumerate}
The $\alpha$ threshold allows biologists to filter out neighbors that are among the $k$ closest, but too dissimilar to compare.
When comparing multiple \pyro{}s of the same region of a single \isol{} for quality control, the \pearson{} between them is strictly above 0.995.
As a result, for many other studies --- not necessarily MST-focused --- \cplop{} researchers use a \pearson{} of 0.990 or above to define a strain of \ecoli{}.
Filtering by some value near this may give more accurate results and provides an intuitive way to relate these lists to other studies.

Using the example from Figures~\ref{fig:knn-graph} and \ref{fig:knn}, \autoref{fig:alpha-filter} shows how when using \kNN{} where \k{} = 9, we can further restrict the \knnlong{} list if we believe \kNN{} should ignore any datapoints outside of \a{}.
For \autoref{fig:alpha-filter}, \euclid{} is the chosen \compfunc{} and using an \a{} threshold to filter means we filter any datapoints from the \knnlong{} list if the similarity value is \textit{above} \a{}.
\cplop{} uses \pyros{} as datapoints and the \pearson{} to compare \pyros{};
the \pearson{} similarity value ranges from -1 to 1, where a \pearson{} close to 1 denotes highly similar datapoints.
Thus, filtering using an \a{} threshold on \pearson{} values requires filtering datapoints that are \textit{below} \a{}.
\autoref{alg:filter} describes this process in pseudocode.

\begin{figure}
\centering
\begin{tabular}{|c|c|c|c|}             \hline
    \k{} & Class   & Position & Similarity    \\ \hline
         & \unknownchar{}& (5,5) & 0.000       \\ \hline\hline
  \rowcolor{\bcolor}  1    & \bchar{}      & (6,6) & 1.414       \\ \hline
  \rowcolor{\acolor}  \ac2    & \ac\achar{}      & \ac(3,6) & \ac2.236       \\ \hline
  \rowcolor{\acolor}  \ac3    & \ac\achar{}      & \ac(4,7) & \ac2.236       \\ \hline
  \rowcolor{\ccolor}  4    & \cchar{}      & (3,3) & 2.828       \\ \hline
  \rowcolor{\bcolor}  5    & \bchar{}      & (8,5) & 3.000       \\ \hline
  \rowcolor{\bcolor}  6    & \bchar{}      & (6,8) & 3.162       \\ \hline
  \rowcolor{\ccolor}  7    & \cchar{}      & (3,2) & 3.606       \\ \hline
  \rowcolor{gray}  8    & \cchar{}      & (1,3) & 4.472       \\ \hline
  \rowcolor{gray}  9    & \cchar{}      & (1,1) & 5.657       \\ \hline
  %\rowcolor{\acolor} \ac10    & \ac\achar{}      & \ac(1,10) & \ac6.403       \\ \hline
\end{tabular}
\caption{For \k{} = 9, filtering the \knnlong{} by \a{} = 4.000 ends up dropping the last two datapoints (marked in gray) off of the list, changing the resultant classification from \cchar{} to \bchar{}. In the case of \euclid{}, using \a{} means we filter any \euclid{} \textit{above} \a{}.}
\label{fig:alpha-filter}
\end{figure}

\input{algorithms/filter}

%%%%%%%%%% MEAN %%%%%%%%%%
\subsection{\rmean{}}
\rmean{} combines the result of the two comparisons between two \isols{} in order to build a single \knnlong{} list, from which simple \kNN{} proceeds to classify.
Combining the similarity values from the two \compfuncs{} is simply a mapping from the two similarity values to a single value.
Arithmetic mean, geometric mean, and \euclid{} are examples, but we chose to use \euclid{}.
\autoref{fig:meanwise:example} depicts an example classifying an unknown \isol{} \UNKNOWN{} using the arithmetic mean as the mean function.

\begin{figure}
\centering
\begin{tabular}{c|c|c|c|c|c}
    \k{} & \Isol{} $x$ & \Spec{} & $\pcsixt(u,x)$ & $\pcfive{}(u,x)$ & $\mathit{mean}(\pcsixt{}, \pcfive{})$  \\ \hline\hline
    1 & $a$ & Cat       & 0.994 & 0.991 &  0.993 \\ \hline
    2 & $b$ & Dog       & 0.990 & 0.994 &  0.992 \\ \hline
    3 & $c$ & Dog       & 0.995 & 0.989 &  0.992 \\ \hline
    4 & $d$ & Chicken   & 0.985 & 0.987 &  0.986 \\ \hline
    5 & $e$ & Cat       & 0.980 & 0.990 &  0.985 \\ \hline
    6 & $f$ & Cat       & 0.978 & 0.990 &  0.984 \\ \hline
    7 & $g$ & Cat       & 0.980 & 0.984 &  0.982 \\ \hline
    8 & $h$ & Chicken   & 0.952 & 0.960 &  0.956 \\ \hline
    %9 & $i$ & Chicken   & 0.952 & 0.946 &  0.948 \\ \hline
\end{tabular}
\caption{An example classifying an unknown \isol{} \UNKNOWN{} using \rmean{} with \k{} = 8, where the mean function is the arithmetic average of the two \pcfunclabel{} values.}
\label{fig:meanwise:example}
\end{figure}

Formally: For \UNKNOWN{} and a $\SOMEPYRO\in\LIB{}$, we take the mean of the result of all of the \compfuncs{} and build a single \knnlong{} list from it.
The mean can be any metric mapping $\R\times\R\rightarrow\R$ and in the investigated implementation, we use the \euclid{}, also known as the $L^2$ norm.
A single \knnlong{} list results from this algorithm that we filter by $k$ and $\alpha$ and use to classify the unknown.
\autoref{alg:mean} describes this process in pseudocode.
\input{algorithms/mean}

%%%%%%%%%% WINNER %%%%%%%%%%
\subsection{\rwinner{}}
\rwinner{} performs \kNN{} classification on the two \knnlong{} lists resulting from the two \compfuncs{}, \pcfunclabel{} on \Ssixt{} and \pcfunclabel{} on \Sfive{}, picking the \spec{} with the highest number of instances in its original list.
In this way, the strategy picks the ``winning'' classification from the two lists.
\autoref{fig:winner:example} shows how this works.

\begin{figure}
\centering
\subfloat[A \k{} = 8 nearest neighbors list for the \Ssixt{} region of an unknown \isol{}.]{
\begin{tabular}{c|c}
     \k{} (\Ssixt{}) & \Spec{}  \\ \hline \hline
     1 & Bat \\ \hline
     2 & Bat \\ \hline
     3 & Cat \\ \hline
     4 & Pigeon \\ \hline
     5 & Pigeon \\ \hline
     6 & Human \\ \hline
     7 & Human \\ \hline
     8 & Bat \\ \hline
\end{tabular}
}
\quad
\subfloat[A \k{} = 8 nearest neighbors list for the \Sfive{} region of an unknown \isol{}.]{
\begin{tabular}{c|c}
     \k{} (\Sfive{}) & \Spec{}  \\ \hline \hline
     1 & Pigeon \\ \hline
     2 & Bat \\ \hline
     3 & Cat \\ \hline
     4 & Pigeon \\ \hline
     5 & Bat \\ \hline
     6 & Pigeon \\ \hline
     7 & Cat \\ \hline
     8 & Pigeon \\ \hline
\end{tabular}
}
\caption{In this example of \rwinner{} for \k{} = 8, \kNN{} on the \Ssixt{} region results in a classification of Bat, since there are 3 bats in its \knnlong{} list and \kNN{} on \Sfive{} results in Pigeon, since there are 4 Pigeons in its \knnlong{} list. The classification resulting from these two lists is Pigeon, since Pigeon shows up more in its original list.}
\label{fig:winner:example}
\end{figure}

Formally: For each \compfunc{}, we make a \knnlong{} list and filter by $k$ and $\alpha$ accordingly.
Once we finish building each \compfunc{}'s \knnlong{} list, we find the most plural classification from each list and track the number of times that classification shows up in that list.
Then, we classify $u$ based off the classification that has the highest number in its corresponding list.
\autoref{alg:winner} describes this process in pseudocode.
\input{algorithms/winner}

%%%%%%%%%% UNION %%%%%%%%%%
\subsection{\runion{}}
\runion{} builds a list that is the union of both \knnlong{} lists, classifying the unknown as the most dominant species in the resulting union
It may be that the most dominant \spec{} in each list is different, but a second or third most dominant \spec{} may be more appropriate since it shows up in both lists.
\autoref{fig:union:example} shows an example of this.

In \autoref{fig:union:example}, Figures~\ref{fig:union:example:ssixt} and \ref{fig:union:example:sfive} show the \knnlong{} lists for \Ssixt{} and \Sfive{} respectively.
The dominant \spec{} in each are Human, with 5 instances, and Turkey, with 4 instances.
Combining these into a union of the two in \autoref{fig:union:example:union}\footnote{The union depicted in \autoref{fig:union:example:union} contains the original \k{} for clarity of entry source. These values can help with tie breaking as well, if breaking ties based on average position, or lowest \k{}.}, we see that the dominant \spec{} is Dog with 6 instances in the union, due to the 3 instances of Dog in each \itsshort{} \knnlong{} list.

\begin{figure}
\centering
\subfloat[A \k{} = 8 nearest neighbors list for the \Ssixt{} region of an unknown \isol{}.]{\label{fig:union:example:ssixt}
\begin{tabular}{c|c}
     \k{} (\Ssixt{}) & \Spec{}  \\ \hline \hline
     1 & Dog \\ \hline
     2 & Human \\ \hline
     3 & Human \\ \hline
     4 & Human \\ \hline
     5 & Dog \\ \hline
     6 & Dog \\ \hline
     7 & Human \\ \hline
     8 & Human \\ \hline
\end{tabular}
}
\quad
\subfloat[A \k{} = 8 nearest neighbors list for the \Sfive{} region of an unknown \isol{}.]{\label{fig:union:example:sfive}
\begin{tabular}{c|c}
     \k{} (\Sfive{}) & \Spec{}  \\ \hline \hline
     1 & Turkey \\ \hline
     2 & Dog \\ \hline
     3 & Dog \\ \hline
     4 & Turkey \\ \hline
     5 & Turkey \\ \hline
     6 & Dog \\ \hline
     7 & Turkey \\ \hline
     8 & Cow \\ \hline
\end{tabular}
}
\\
\subfloat[Resulting union of the \knnlong{} lists from each \itsshort{} region.]{
\begin{tabular}{c|c|c}
    Region      & \k{}  & \Spec{}\\ \hline \hline
    \Ssixt{}    & 1     & Dog \\ \hline
    \Sfive{}    & 1     & Turkey \\ \hline
    \Ssixt{}    & 2     & Human \\ \hline
    \Sfive{}    & 2     & Dog \\ \hline
    \Ssixt{}    & 3     & Human \\ \hline
    \Sfive{}    & 3     & Dog \\ \hline
    \Ssixt{}    & 4     & Human \\ \hline
    \Sfive{}    & 4     & Turkey \\ \hline
    \Ssixt{}    & 5     & Dog \\ \hline
    \Sfive{}    & 5     & Turkey \\ \hline
    \Ssixt{}    & 6     & Dog \\ \hline
    \Sfive{}    & 6     & Dog \\ \hline
    \Ssixt{}    & 7     & Human \\ \hline
    \Sfive{}    & 7     & Turkey \\ \hline
    \Ssixt{}    & 8     & Human \\ \hline
    \Sfive{}    & 8     & Cow \\ \hline
\end{tabular}
}
\quad
\subfloat[\Spec{} counts of all three lists, \Ssixt{}, \Sfive{}, and the union of the two.]{\label{fig:union:example:union}
\begin{tabular}{c|c|c}
List & \Spec{} & Count \\\hline \hline
\Ssixt{} & Human & 5 \\\hline
\Ssixt{} & Dog & 3 \\\hline \hline
\Sfive{} & Turkey & 4 \\\hline
\Sfive{} & Dog & 3 \\\hline
\Sfive{} & Cow & 1 \\\hline \hline
Union & Dog & 6 \\\hline
Union & Human & 5 \\\hline
Union & Turkey & 4 \\\hline
Union & Cow & 2 \\\hline
\end{tabular}
}
\caption{In this example of \runion{} for \k{} = 8, we see that when considering each \itsshort{} \knnlong{} list separately, there are two different dominant \spec{}.
}
\label{fig:union:example}
\end{figure}

Formally: For each \compfunc{}, we make a \knnlong{} list and filter by $k$ and $\alpha$ accordingly.
After building each \knnlong{} list, we combine the lists into a set, keeping track of the original list position for tie-breaking.
From this set, which we dub the union, we count the classifications present in the union and classify $u$ as the most plural in the union of the lists, compared to the other lists.
\autoref{alg:union} describes this process in pseudocode.
\input{algorithms/union}

%%%%%%%%%% INTERSECTION %%%%%%%%%%
\subsection{\rintersect{}}
\rintersect{} works to build a single set of size \k{}, called the intersection, consisting only of \isols{} that appear in both \itsshort{} \knnlong{} lists.
It does this by initially querying for each \itsshort{} region, expanding the list until the intersection is the required size --- \k{}.
This is the most complicated and restrictive of the resolution strategies, possibly requiring \a{} filtering in order to restrict the search.
Filtering by \a{} means the construction on the intersection stops if expanding the \knnlong{} means going outsidethe \a{} threshold, which may result in an intersection that is smaller than \k{}\footnote{Since the same is true for natural \kNN{}, we find this acceptable.}.

\autoref{fig:intersection:example} shows how this strategy proceeds.
In \autoref{fig:intersection:example:ssixt}, we see that there are many Cows in the \Ssixt{} \knnlong{} list, but few of those \isols{} show up in the \Sfive{} \knnlong{} list in \autoref{fig:intersection:example:sfive}.
We then build the intersection, shown in \autoref{fig:intersection:example:intersection}, but there are not enough common \isols{} to make a \k{}=8 sized intersection, so we must extend the initial lists to 13 in order to find enough common \isols{}.
Once we have found enough common \isols{}, \kNN{} can proceed normally on the intersection.

\begin{figure}
\centering
\subfloat[A \k{} = 8 nearest neighbors list including (fabricated) \isol{} IDs for the \Ssixt{} region of an unknown \isol{}, extended in order to find \isols{} in common with the \Sfive{} list, which are bold.]{\label{fig:intersection:example:ssixt}
\begin{tabular}{c|c|c}
 \k{} (\Ssixt{}) & \Isol{} ID & \Spec{} \\ \hline \hline
 \bf 1      &\bf  5823 &\bf Pig \\ \hline
 \bf 2      &\bf  2833 &\bf Pig \\ \hline
 3          &     8873 & Cow \\ \hline
 \bf 4      &\bf  5939 & \bf Cow \\ \hline
 5          &     6156 & Cow \\ \hline
 6          &     3676 & Human \\ \hline
 7          &     7853 & Cow \\ \hline
 \bf 8      &\bf  5331 &\bf Cow \\ \hline\hline
 9          &     2189 & Cow \\ \hline
 \bf 10     &\bf  2053 &\bf Pig \\ \hline
 \bf 11     &\bf  8962 &\bf Pig \\ \hline
 \bf 12     &\bf  3813 &\bf Human \\ \hline
 \bf 13     &\bf  8173 &\bf Pig \\ \hline
\end{tabular}
}
\quad
\subfloat[A \k{} = 8 nearest neighbors list including (fabricated) \isol{} IDs for the \Sfive{} region of an unknown \isol{}, extended in order to find \isols{} in common with the \Ssixt{} list, which are bold.]{\label{fig:intersection:example:sfive}
\begin{tabular}{c|c|c}
 \k{} (\Ssixt{}) & \Isol{} ID & \Spec{} \\ \hline \hline
 \bf 1      &\bf   2833 &\bf Pig \\ \hline
 2          &      2916 & Cow \\ \hline
 \bf 3      &\bf   3813 &\bf Human \\ \hline
 \bf 4      &\bf   5939 &\bf Cow \\ \hline
 5          &      6854 & Dog \\ \hline
 \bf 6      &\bf   5823 &\bf Pig \\ \hline
 \bf 7      &\bf   2053 &\bf Pig \\ \hline
 8          &      8485 & Dog \\ \hline \hline
 \bf 9      &\bf   8173 &\bf Pig \\ \hline
 10         &      6497 & Human \\ \hline
 11         &      9208 & Cow \\ \hline
 \bf 12     &\bf   5331 &\bf Cow \\ \hline
 \bf 13     &\bf   8962 &\bf Pig \\ \hline
\end{tabular}
}
\\
\subfloat[Common isolates in the \Ssixt{} and \Sfive{} \knnlong{} lists, sorted by average \k{}.]{\label{fig:intersection:example:intersection}
\begin{tabular}{c|c|c|c}
\k{} (\Ssixt{}) & \k{} (\Sfive{}) & \Isol{} ID & \Spec{} \\ \hline \hline
 2  & 1 & 2833 & Pig \\ \hline %1.5
 1  & 6 & 5823 & Pig \\ \hline %3.5
 4 & 4 & 5939 & Cow \\ \hline %4
 12 & 3 & 3813 & Human \\ \hline %7.5
 10 & 7 & 2053 & Pig \\ \hline %8.5
 8 & 12 & 5331 & Cow \\ \hline %10
 13 & 9 & 8173 & Pig \\ \hline %11
 11 & 13 & 8962 & Pig \\ \hline %12
\end{tabular}
}
\caption{An example \rintersect{} for \k{} = 8 showing how the original \knnlong{} lists did not have enough \isols{} --- 8 are needed --- in common, but when extended out to 15, there are 8 common \isols{}. From here, classification can proceed to classify the unknown as the most dominant \spec{} in the intersection, Pig.}
\label{fig:intersection:example}
\end{figure}

For each \compfunc{}, we make a \knnlong{} list and filter by $k$ and $\alpha$ accordingly, but ensure that we do not lose track of the entire sorted list of results.
After building each \knnlong{} list, we inspect each list for common \isol{}s.
We add \isol{}s that appear in every list into a set that we call the intersection.
If the size of the intersection is $k$, then we are done.
Otherwise, we increase the length of our individual lists by $\delta$ and search for common \isol{}.
This process repeats until the size of the intersection is $k$, or all of the \isol{}s in the individual lists are below threshold $\alpha$.
\autoref{alg:intersection} describes this function in pseudocode.
\input{algorithms/intersection}


Consider a smart city that aims at being energy self-sustainable and produce and consume, as much as possible, energy within its geographic area.
Producers are characterized according to their location, the amount of energy in Kilowatts-hour that they can sell, the cost of that energy, and the time window in which they can produce it, with a given service level agreement concerning their availability and fault tolerance.
Consumers are described by their location, their energy requirements during a certain interval of time, the maximum total cost they are ready to pay, and quality of service requirements such as availability and how critical it is to consume this amount of energy.
An energy exchange market is established in order to continuously trade  energy provision/consumption ensuring that all consumers will have the energy they require at every moment.

In our approach, energy producers are modelled as services with associated ``agreed'' SLAs.
In general, we assume that several producers will be able to supply energy for a given period of time given specific  preferences expressed by a consumer.
An energy request is expressed as a query that specifies an energy requirement with QoS preferences independently of the possible producers.
In our example assume that there are several energy provision services ({\sf e$_1$, ... e$_n$}) that can be independent or hubs integrating several energy providers.
Each of them is specified by a clause:
\begin{trivlist}\sf\footnotesize
\item[~$\bullet$ ]   e$_i$ $\equiv$ provider(KW-h, Ecost, rate, location), \textit{SLA}$_i$
\end{trivlist}

Services are deployed in different cloud providers and each service exports an agreed SLA that specifies the economic cost per call, the maximum number of calls that can be done per day, the availability of the service, the average response time when a method is called, the reliability, the privacy of the produced data (whether they can be stored or not), the precision, freshness and provenance of the produced data.
As said in previous sections, some of these measures ({\sf cost/call, maxCall/day}) are static and explicitly specified by the service provider.
In contrast, the other measures should be computed by monitoring the conversations between the service and the applications that contact it.
Cloud providers define also their SLA contracts defining normally subscription contracts that specify, the cost per request ({\sf cost/request}), the volume of data that can be exchanged per month ({\sf I/0 volume/month}), the cost of transferring data or applications within the same data centre or between data centres ({\sf datatransferCost/region}), the storage space ({\sf storageSpace}). For example some cloud providers enable the customer to choose the zone to install PaaS services and deploy applications (e.g. zone 1 is Europe). If the customer wishes to deploy services in zone 1 but store data in zone 2 the transfer cost will change.

\begin{trivlist}\sf\footnotesize
\item[~$\bullet$ ] {\sf agreedSLA:$\langle$cost/call, maxCalls/day, availability, responseTime, reliability, privacy, precision, freshness, provenance$\rangle$}.

 \item[~$\bullet$ ]  {\sf cloudSLA:$\langle$cost/request, I/0 volume/month, datatransferCost/region, storageSpace$\rangle$}.
 \end{trivlist}

Queries may be expressed as Datalog-like programs or an SQL-like expressions, including spatio-temporal attributes and preferences.
For instance, \textit{List of energy providers that can provision 1000 Kwatts/h, in the next 10 seconds, that are close to my city with a cost of 0,50 euros/Kwatt and that are labeled as green?}.
The user preferences statement would include their cloud provider contract and quality preferences:

\begin{trivlist}\sf\footnotesize
\item[~$\bullet$ ]  {\sf cloudSLA:$\langle$0,05 cents per call, 8 Gigabytes I/0 volume/month, free, 1 Giga$\rangle$}.
\item[~$\bullet$ ] {\sf preferencesStatement:$\langle$query total cost,  total responseTime, reliability, freshness, precision, provenance, storage$\rangle$}.
\end{trivlist}

We consider a simplified SLA cloud contract inspired in the lowest contract provided by Azure: {\sf cost of \$0,05 cents per call,  8~GB of I/O volume/month, free data transfer cost within the same region,  01~GB of storage}.
The user is ready to pay maximum {\sf \$5 as total query cost}; she requests that only {\sf green} energy providers are listed (provenance); at least {\sf 85$\%$} of precision of provided data, even if they are not fresh; she requires an availability rate of at least {\sf 90$\%$} and with a response time of {\sf 0,01 seconds}.

Assume that there are four household energy providers that can be queried individually and two hubs that collect information from the community smartmeters.
Hubs will store information about (surplus) energy, available from particular users.
We represent these services by {\sf e$_1$, \dots, e$_4$} and {\sf h$_1$ and h$_2$}.
We also suppose the existence of two free location services exporting the following interface: {\sf loc(IP) $\leftarrow$ $\langle$ X, Y$\rangle$}, meaning that given an IP address it returns a geographic position expressed as a pair of coordinates.
All these services can potentially be combined for answering the query.

 %.  .  .  .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  .
 \paragraph{Derived SLA}
 %.  .  .  .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  .
 Some of the user preferences statement measures are used for defining a dervied SLA that, as said in previous section, will guide the evaluation of the query. These measures are defined as a function of the measures used by the agreed SLAs and by the cloud SLA contract.
\begin{trivlist}\sf\footnotesize
\item[~$\bullet$ ] query total cost: $\sum_{i = 1\dots n}$ cost(s$_i$) + data transfer $\leq$ \$5
 \item[~$\bullet$ ] total response time: of services + data transfer
 \item[~$\bullet$ ] availability: {\em (of services involved)} $\leq$ {\sf 90$\%$},
 \item[~$\bullet$ ] freshness: non
 \item[~$\bullet$ ] precision: {\em avg (precision of services involved)} $\leq$ {\sf 85$\%$}
 \item[~$\bullet$ ] provenance:  all services involved must be $green$
 \item[~$\bullet$ ] storage: {\em partial results size} $\leq 1 Giga$
 \end{trivlist}

%...---... ...---... ...---... ...---... ...---... ...---... ...---... ...---... ...---...
  \paragraph{Computing service compositions}
%...---... ...---... ...---... ...---... ...---... ...---... ...---... ...---... ...---...

Given a a set of services that can possibly be composed and the derived SLA, a service cmposition must be produced.
Some of the inequations of the derived SLA should be included in the service compositions that answer the query.
In the case of our query example the following composition can be used for answering it:
\begin{eqnarray*}
Q_1 &\equiv&
   \langle X_1,Y_1\rangle = loc_1(IP), \\
&& \langle X_2,Y_2 \rangle = loc_1(Eprovider), \\
&& D = distance(\langle X_1,Y_1\rangle, \langle X_2,Y_2\rangle), \\
&& \langle C_1, E_1 \rangle = e_1(\dots), \dots \langle C_4, E_4 \rangle = e_4(\dots), \\
&& D \leq 1.5 \mathsf{Km},\ \ sum(C_1:C_4) \leq 5, \\
&& sum(E_1:E_4) \geq 1000\ \mathsf{kw-h}, \\
&& \mathsf{totalResponseTime}  \leq 10\ \mathsf{seg}
\end{eqnarray*}

  In fact our approach would generate a number $k$ of service compositions, combining as much as possible the services available such that the constraints of the derived SLA are verified.
One challenge of this is to generate incremental queries.

%.  .  .  .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .
\paragraph{Optimizing service compositions execution}
%.  .  .  .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  . .  .  .
A service composition (expressed in a Datalog-like syntax) is then transformed into a query workflow search space consisting of workflows with different control flows and where constraints serve to determine an optimization objective.
In the case of $Q_1$ above, the corresponding search space contains for example a workflow {\sf QW$_1$} where all activities are executed sequentially.
Another one, {\sf QW$_2$}, with parallel activities programming the call to a location service for the user and the energy providers, then a filter activity selecting only services located not farther to 1.5 Km, followed by  parallel activities that compute the total cost of the energy to buy, the total amount of energy.

    Once the search space has been computed the QWs are filtered according to their economic and execution time costs. The QWs that minimize this cost are identified and ordered according to their conformance to the user preferences statement.

% \begin{figure*}
%\includegraphics[width=0.95\textwidth]{figs/exchange.pdf}
%\caption{\label{fig:energyXChange} Energy exchange.}
%\end{figure*}


\section{Multiple hypothesis testing}


    \foldertitle{sstate}{Steady-state objects and functions}{sstate/Contents}

	You can create a steady-state (sstate) object by loading a steady-state
 (sstate) file. The sstate object can be then saved as a stand-alone
 m-file function and repeatedly solved for different parameterisations.

 Sstate methods:

 \paragraph{Constructor}

 \begin{itemize}
 \item
   \href{sstate/sstate}{\texttt{sstate}} - Create new steady-state object
   based on sstate file.
 \end{itemize}

 \paragraph{Compiling stand-alone m-file functions}

 \begin{itemize}
 \item
   \href{sstate/compile}{\texttt{compile}} - Compile an m-file function
   based on a steady-state file.
 \end{itemize}

 \paragraph{Running stand-alone sstate m-file functions}

 \begin{itemize}
 \item
   \href{sstate/standalonemfile}{\texttt{standalonemfile}} - Run a
   compiled stand-alone sstate m-file function.
 \end{itemize}

 \paragraph{Getting on-line help on sstate functions}

 \begin{verbatim}
 help sstate
 help sstate/function_name
 \end{verbatim}


% We want this material to fit on two pages
\small

\chapter*{About the Cover}

Creating the cover image demonstrating the capabilities of the toolkit was a
challenging task.\footnote{The source code for the cover is available from
InsightDocuments/SoftwareGuide/Cover/Source/.} Given that the origins of ITK
are with the Visible Human Project it seemed appropriate to create an image
utilizing the VHP data sets, and it was decided to use the more recently
acquired Visible Woman dataset.  Both the RGB cryosections and the CT scans
were combined in the same scene.

\begin{description}

\item [Removing the Gel.]
The body of the Visible Woman was immersed in a block of gel during the
freezing process. This gel appears as a blue material in the cryogenic data.
To remove the gel, the joint histogram of RGB values was computed. This
resulted in an 3D image of $256\times256\times256$ pixels. The histogram
image was visualized in VolView.\footnote{VolView is a commercial product
from Kitware. It supports ITK plug-ins and is available as a free viewer or
may be licensed with advanced functionality. See
http://www.kitware.com/products/volview.html for information.} The cluster
corresponding to the statistical distribution of blue values was identified
visually, and a separating plane was manually defined in RGB space. The
equation of this plane was subsequently used to discriminate pixels in the
gel from pixels in the anatomical structures. The gel pixels were zeroed out
and the RGB values on the body were preserved.

\item[The Skin.]
The skin was easy to segment once the gel was removed. A simple region
growing algorithm was used requiring seed points in the region previously
occupied by the gel and then set to zero values. An anti-aliasing filter was
applied in order to generate an image of pixel type float where the surface
was represented by the zero set. This data set was exported to VTK where a
contouring filter was used to extract the surface and introduce it in the VTK
visualization pipeline.

\item[The Brain.]
The visible part of the brain represents the surface of the gray matter.  The
brain was segmented using the vector version of the confidence connected
image filter.  This filter implements a region growing algorithm that starts
from a set of seed points and adds neighboring pixels subject to a condition
of homogeneity.

The set of sparse points obtained from the region growing algorithm was
passed through a mathematical morphology dilation in order to close holes and
then through a binary median filter. The binary median filter has the
outstanding characteristic of being very simple in implementation by applying
a sophisticated effect on the image. Qualitatively it is equivalent to a
curvature flow evolution of the iso-contours. In fact the binary median
filter as implemented in ITK is equivalent to the majority filter that
belongs to the family of voting filters classified as a subset of the
\emph{Larger than Life} cellular automata. Finally, the volume resulting from
the median filter was passed through the anti-aliasing image filter. As
before, VTK was used to extract the surface.

\item[The Neck Musculature.]
The neck musculature was not perfectly segmented. Indeed, the resulting
surface is a fusion of muscles, blood vessels and other anatomical
structures. The segmentation was performed by applying the
VectorConfidenceConnectedImageFilter to the cryogenic dataset. Approximately
60 seed points were manually selected and then passed to the filter as
input. The binary mask produced by the filter was dilated with a mathematical
morphology filter and smoothed with the BinaryMedianImageFilter. The
AntiAliasBinaryImageFilter was used at the end to reduce the pixelization
effects prior to the extraction of the iso-surface with vtkContourFilter.

\item[The Skull.]
The skull was segmented from the CT data set and registered to the cryogenic
data. The segmentation was performed by simple thresholding, which was good
enough for the cover image. As a result, most of the bone structures are
actually fused together. This includes the jaw bone and the cervical
vertebrae.

\item[The Eye.]
The eye is charged with symbolism in this image. This is due in part because
the motivation for the toolkit is the analysis of the Visible Human data,
and in part because the name of the toolkit is \emph{Insight}.

The first step in processing the eye was to extract a sub-image of
$60\times60\times60$ pixels centered around the eyeball from the RGB
cryogenic data set. This small volume was then processed with the vector
gradient anisotropic diffusion filter in order to increase the homogeneity of
the pixels in the eyeball.

The smoothed volume was segmented using the
VectorConfidenceConnectedImageFilter using 10 seed points. The resulting
binary mask was dilated with a mathematical morphology filter with a
structuring element of radius one, then smoothed with a binary mean image
filter (equivalent to majority voting cellular automata). Finally the mask
was processed with the AntiAliasBinaryImageFilter in order to generate a
float image with the eyeball contour embedded as a zero set.

\item[Visualization.]
The visualization of the segmentation was done by passing all the binary
masks through the AntiAliasBinaryImageFilter, generating iso-contours with
VTK filters, and then setting up a VTK Tcl script. The skin surface was
clipped using the vtkClipPolyDataFilter using the implicit function
vtkCylinder. The vtkWindowToImageFilter proved to be quite useful for
generating the final high resolution rendering of the scene ($3000\times3000$
pixels).

\item[Cosmetic Postprocessing.]
We have to confess that we used Adobe Photoshop to post-process the image. In
particular, the background of the image was adjusted using Photoshop's color
selection. The overall composition of the image with the cover text and
graphics was also performed using Photoshop.

\end{description}

\normalsize