\documentclass[12pt]{article}

\usepackage{epsf}

\title{rCBF Analysis Using MATLAB}
\author{Mark Wolforth \and Greg Ward \and Sean Marrett}
\date{15 November, 1994}
%\psdraft
\def\code#1{{\tt #1}}

% ttdescription - a description-like environment where item descriptions are
% typeset using "\tt", followed by a colon

\def\ttlabel#1{{\tt #1: }}
\newenvironment{ttdescription}[1]
{\newbox\holder
 \setbox\holder=\hbox{\ttlabel#1}
 \dimen0=\wd\holder
 \begin{list}{}
 {\labelsep=-0.25in
  \rightmargin=0.25in
  \leftmargin=\dimen0
  \addtolength{\leftmargin}{0.25in}
  \labelwidth=\leftmargin
  \let\makelabel\ttlabel}}%     this commented is needed to hide the newline
{\end{list}}

\begin{document}

\maketitle
%\newpage

\tableofcontents

%--------------------------------------------------------------
\newpage
\section{Introduction}

This document is the user manual for the rCBF (regional Cerebral
Blood Flow) package developed at the Montreal Neurological Institute
McConnell Brain Imaging Centre during the summer of 1993.  This
kinetic analysis package runs under MATLAB, in conjunction with EMMA
(Extensible MATLAB Medical Analysis), a package developed at the same
time.

The rCBF package described in this document performs a full
two-compartment analysis of cerebral blood flow, including performing
blood delay and dispersion correction.  It is intended as a working
example for future developers of MATLAB analysis packages, in
addition to being a useful analysis tool.  Therefore, this document
places more emphasis on the structure and organization of the
software than on the actual use of the software.

The authors would like to thank Sean Marrett for being the driving
force behind this project.  He provided invaluable guidance when all
seemed lost.

%--------------------------------------------------------------
\newpage
\section{Mathematical Analysis}

\subsection{Introduction}

The two-compartment cerebral blood flow model can be characterized by
the following three equations:

\begin{equation}
\frac{dM}{dt} = K_{1}C_{a}(t) - k_{2}M(t)      \label{eq:2comp1}
\end{equation}
\begin{equation}
M(t) = K_{1}C_{a}(t) \otimes e^{-k_{2}t}       \label{eq:2comp2}
\end{equation}
\begin{equation}
A(t) = M(t) + C_{a}(t)V_{0}                    \label{eq:2comp3}
\end{equation}

In these equations, $A(t)$ is the PET data collected over a set of
frames, $C_{a}(t)$ is the delay and dispersion corrected arterial
blood sample data, and $M(t)$ is the radioactive tracer activity
present in cerebral tissue.  We know both $A(t)$ and $C_{a}(t)$, but
cannot know $M(t)$ without knowing $V_{0}$.

One additional point to consider is that these equations are written
for continuous functions.  However, the PET data that is actually
available is average activity across each frame.  Therefore, in
order to solve the equations, we must average the non PET data
across frames.  By combining equations (\ref{eq:2comp2}) and
(\ref{eq:2comp3}), and averaging the non PET data over frames, we
get:

\begin{equation}
A^{*}(t) = \frac{\int\limits_{T_1}^{T_2} \left( K_{1} \left[ C_{a}(t) \otimes
  e^{-k_{2}t} \right] + C_{a}(t)V_{0} \right) dt}{T_{2} - T_{1}}
%A^{*}(t) = {{\int\limits_{T_1}^{T_2} \left( K_{1} \left[ C_{a}(t) \otimes
%e^{-k_{2}t} \right] + C_{a}(t)V_{0} \right) dt} \over {T_{2} - T_{1}}}
\label{eq:2comp4}
\end{equation}

where $A^{*}(t)$ is the PET data that is actually collected (by
definition, averaged over frames), and ${\int_{T_1}^{T_2}dt} / {(T_2 -
T_1)}$ performs an averaging over frames ($T_1$ is the frame start
time, $T_2$ is the frame stop time, and the integral is evaluated for
each frame).

We wish to solve equation (\ref{eq:2comp4}) for $K_{1}$, $k_{2}$, and
$V_{0}$.  Of course, one approach would be to try to perform an
explicit least squares curve fitting.  However, this approach would be
quite computationally intensive since the fitting would need to be
performed for every pixel of a $128 \times 128$ pixel image.  Fortunately,
there is a method of solution that gives good results with reduced
computational difficulty.

\subsection{Double-Weighted Integration Method}

\label{sec:double_weight}

Since the time required to perform a least squares curve fitting would
be prohibitive, a simpler approach to solving the problem is required.
One technique is to use a weighted integration method.  We initially
approached the problem by assuming that $V_{0}$ was negligibly small,
in which case the $C_{a}V_{0}$ term is eliminated from equation
(\ref{eq:2comp4}).  Taking equation (\ref{eq:2comp4}) with $C_{a}V_0$
eliminated, and integrating both sides from time 0 to the end of the
last frame, we get:

\begin{equation}
\int_{0}^{T} A^{*}(t) dt = K_{1} \int_{0}^{T} \frac{\int_{T_1}^{T_2}
\left[ C_{a}(u) \otimes e^{-k_{2}u} \right] du}{T_2 - T_1} dt
\end{equation}

We can then take this equation, and divide it by a weighted version
of itself:

\begin{equation}
\frac{\int_{0}^{T} A^{*}(t) dt}{\int_{0}^{T} A^{*}(t) t dt} =
\frac{K_{1} \int_{0}^{T} \frac{\int_{T_1}^{T_2} \left[ C_{a}(u)
\otimes e^{-k_{2}u} \right] du}{T_2 - T_1} dt}{K_{1} \int_{0}^{T}
\frac{\int_{T_1}^{T_2} \left[ C_{a}(u) \otimes e^{-k_{2}u} \right]
du}{T_2 - T_1} t dt}
\label{eq:1comp}
\end{equation}

$K_{1}$ cancels out of this equation, leaving us with an equation
that only involves $k_{2}$.  The left side of equation
(\ref{eq:1comp}) is easily evaluated by integrating the PET data.
The right side of equation (\ref{eq:1comp}) is not easily solved for
$k_{2}$, so a different approach was taken.  A look-up table was
generated relating values of $k_{2}$ to resulting values of the
right hand side of equation (\ref{eq:1comp}).  A linear
interpolation was then performed to choose values of $k_{2}$ from
this look-up table for each point in the left hand side of equation
(\ref{eq:1comp}).

\subsection{Triple-Weighted Integration Method}

In order to model the complete two-compartment system, we must be able
to solve equation (\ref{eq:2comp4}).  In section
\ref{sec:double_weight},
we solved the equation by multiplying by two different weights and
then dividing, and we can take a similar approach with the full
two-compartment equation.  We can weight equation (\ref{eq:2comp4})
with {\em three} different weights and then integrate:

\begin{equation}
\int_{0}^{T} w_{1}A^{*}(t)dt = K_{1} \int_{0}^{T} w_{1}
\frac{\int_{T_1}^{T_2} \left[ C_{a}(u) \otimes e^{-k_{2}u} \right]
du}{T_2 - T_1} dt + V_{0} \int_{0}^{T}w_{1} \frac{\int_{T_1}^{T_2}
C_{a}(u) du}{T_2 - T_1} dt \label{eq:fullweight1}
\end{equation}

\begin{equation}
\int_{0}^{T} w_{2}A^{*}(t)dt = K_{1} \int_{0}^{T} w_{2}
\frac{\int_{T_1}^{T_2} \left[ C_{a}(u) \otimes e^{-k_{2}u} \right]
du}{T_2 - T_1} dt + V_{0} \int_{0}^{T}w_{2} \frac{\int_{T_1}^{T_2}
C_{a}(u) du}{T_2 - T_1} dt \label{eq:fullweight2}
\end{equation}

\begin{equation}
\int_{0}^{T} w_{3}A^{*}(t)dt = K_{1} \int_{0}^{T} w_{3}
\frac{\int_{T_1}^{T_2} \left[ C_{a}(u) \otimes e^{-k_{2}u} \right]
du}{T_2 - T_1} dt + V_{0} \int_{0}^{T}w_{3} \frac{\int_{T_1}^{T_2}
C_{a}(u) du}{T_2 - T_1} dt \label{eq:fullweight3}
\end{equation}

By multiplying equation (\ref{eq:fullweight1}) by $V_{0}
\int_{0}^{T} w_{3} {(\int_{T_1}^{T_2}C_{a}(u)du)}/{(T_2 - T_1)} dt$
and equation (\ref{eq:fullweight3}) by $V_{0} \int_{0}^{T} w_{1}
{(\int_{T_1}^{T_2}C_{a}(u)du)}/{(T_2 - T_1)} dt$, and then
subtracting the two, we may eliminate the $V_{0}$ term.  A similar
operation can be performed on equation (\ref{eq:fullweight2}) and
equation (\ref{eq:fullweight3}).  This leaves two equations that do
not contain $V_{0}$.  They may then be divided to produce:

%
\begin{equation}
\hspace*{-1.0cm}
\frac{
\begin{array}{lcr}
\multicolumn{2}{l}{
\int_{0}^{T}\!\!w_{3}(t) \frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 - T_1)} dt \cdot
\int_{0}^{T}\!\!w_{1}(t)A^{*}(t)dt\,\,-}&\\
&\multicolumn{2}{r} {\int_{0}^{T}\!\!w_{1}(t)
\frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 - T_1)} dt \cdot
\int_{0}^{T}\!\!w_{3}(t)A^{*}(t)dt}\end{array}
}
{
\begin{array}{lcr}
\multicolumn{2}{l}
{\int_{0}^{T}\!\!w_{3}(t) \frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 - T_1)} dt \cdot
\int_{0}^{T}\!\!w_{2}(t)A^{*}(t)dt\,\,-}&\\
&\multicolumn{2}{r}
{\int_{0}^{T}\!\!w_{2}(t) \frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 - T_1)} dt \cdot
\int_{0}^{T}\!\!w_{3}(t)A^{*}(t)dt}\end{array}
}
 =
\frac{
K_{1} \left\{\!\!\!\! \begin{array}{c}
\begin{array}{lcr}\multicolumn{2}{l}
{\int_{0}^{T}\!\!w_{3}(t) \frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 -
T_1)} dt \cdot
\int_{0}^{T}\!\!w_{1}(t) \frac{(\int_{T_1}^{T_2}C_{a}(u) \otimes
e^{-k_{2}u} du)}{(T_2 - T_1)}\, dt\,\,-}&
\\
&\multicolumn{2}{r} {\int_{0}^{T}\!\!w_{1}(t)
\frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 - T_1)} dt \cdot
\int_{0}^{T}\!\!w_{3}(t)  \frac{(\int_{T_1}^{T_2}C_{a}(u) \otimes
e^{-k_{2}u} du)}{(T_2 - T_1)}\, dt}
\end{array} \end{array} \!\!\!\! \right\} }
{
K_{1} \left\{ \!\!\!\! \begin{array}{c}
\begin{array}{lcr}
\multicolumn{2}{l}{\int_{0}^{T}\!\!w_{3}(t) \frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 - T_1)} dt \cdot
\int_{0}^{T}\!\!w_{2}(t) \frac{(\int_{T_1}^{T_2}C_{a}(u) \otimes
e^{-k_{2}u} du)}{(T_2 - T_1)}\, dt\,\,-} &
\\
&\multicolumn{2}{r}{\int_{0}^{T}\!\!w_{2}(t)
\frac{(\int_{T_1}^{T_2}C_{a}(u)du)}{(T_2 - T_1)} dt \cdot
\int_{0}^{T}\!\!w_{3}(t)  \frac{(\int_{T_1}^{T_2}C_{a}(u) \otimes
e^{-k_{2}u} du)}{(T_2 - T_1)}\, dt} \end{array} \end{array} \!\!\!\!
\right\} }
\label{eq:k1two}
\end{equation}

The $K_{1}$ term cancels out of both the numerator and denominator of
equation (\ref{eq:k1two}), leaving an equation that only involves
$k_{2}$.  As with the equation in section \ref{sec:double_weight},
this is very difficult to solve for $k_{2}$.  Therefore, a look-up
table was again used.  Once the table matching values of $k_{2}$ with
values of the right hand side of equation (\ref{eq:k1two}) has been
created, we may evaluate $k_{2}$ through simple lookup.  With the
$k_{2}$ data computed, finding $K_{1}$ is simply a matter of
evaluating either the numerator or denominator of equation
(\ref{eq:k1two}) without cancelling $K_{1}$.  With both $K_{1}$ and
$k_{2}$ known, we may find $V_{0}$ by evaluating equation
(\ref{eq:2comp4}).

\subsection{Delay and Dispersion Correction}
\label{sec:blood_correction}

Since the blood samples used to estimate $C_a(t)$ are taken from the
subject's arm, the activity data gathered from them must be corrected
for delay and dispersion within the body.  In order to perform the
delay correction, we used the technique of Iida, by performing a
least squares fitting of the equation:
\begin{equation}
A^{*}(t) = \frac{\int\limits_{T_1}^{T_2} \left( \alpha \left[ C_a(t) \otimes
  e^{-\beta t} \right] + \gamma C_a(t) \right) dt} {T_2 - T_1}
\label{eq:delay_correct}
\end{equation}
where $A^{*}(t)$ in this case is the average activity over grey
matter, $\int_{T_1}^{T_2}dt$ represents integration over frames,
$\alpha$, $\beta$, and $\gamma$ are the fitting parameters, and
$C_a(t)$ is the blood data.  The delay itself enters this equation by
generating $C_a(t)$ from:
\begin{equation}
C_a(t) = \bar{g}(t+\delta)
\label{eq:blood_delay}
\end{equation}

The function $\bar{g}$ is the result of performing dispersion
correction on the blood sample data.  This is represented by the
equation:
\begin{equation}
\bar{g}(t) = g(t) + \tau \frac{dg}{dt}
\label{eq:dispersion_correct}
\end{equation}
which is an implicit deconvolution of the equation:
\begin{equation}
g(t) = \bar{g}(t) \otimes \left[ \frac{1}{\tau} e^{\frac{-t}{\tau}}
\right]
\end{equation}

%--------------------------------------------------------------
\newpage
\section{MATLAB Implementation}

\subsection{Introduction}

The previous section described the mathematical model used to
represent cerebral blood flow.  Both the simplified one-compartment
model (neglecting $V_0$), and the full two-compartment model were
implemented numerically in MATLAB.

\subsection{Program Structure}

\begin{figure}
\centerline{\setlength{\epsfysize}{3.0in} \epsffile{flow.ps}}
\caption{General program flow for rCBF analysis}
\end{figure}

The diagram in figure 1 shows the general flow of performing rCBF
analysis using MATLAB.  First, the blood data is prepared for
analysis by performing delay and dispersion correction.  Next the
lookup tables used in the analysis are calculated.  Finally, the
actual images are generated through table lookup using the lookup
tables computed in the previous step.

\begin{figure}
\centerline{\setlength{\epsfysize}{2.0in} \epsffile{structure.ps}}
\caption{Structure of rcbf2}
\end{figure}

Of course, the actual program implementation is slightly more complex
than this.  Figure 2 shows the full structure of the \code{rcbf2}
MATLAB function, which performs a full two-compartment rCBF analysis.
All of the main functions that are called by \code{rcbf2} are shown.
The \code{resampleblood} function returns the blood data to
\code{rcbf2} in an evenly sampled time domain (sampled every $1/2$
second).  This blood data is then passed to \code{correctblood},
which performs dispersion correction, and then delay correction by
calling \code{fit\_b\_curve}.  Finally, useful lookup tables are
calculated by \code{findintconvo}.

\subsection{Annotated Program Listings}

This section contains listings of all of the MATLAB programs
comprising the rCBF package.  Each program is broken into functional
sections, which are presented immediately after the description of
that section.  Note that the code presented here is not {\em exactly}
what you will see if you type, for example, \code{type rcbf2.m} in
MATLAB.  In the interests of concentrating on the numerical analysis,
we have generally neglected code dealing with processing input
arguments, reporting progress, and making some operations optional.
Nevertheless, if you are writing MATLAB programs to perform similar
analyses, it can be instructional to read this code and its
accompanying comments.

\subsubsection{RCBF1}
\label{sec:rcbf1_listing}

\begin{enumerate}

\item The function declaration line.  The output arguments \code{K1}
  and \code{k2} are both whole images: that is, for $128 \times 128$
  PET data, they will be column vectors with 16,384 elements.
  \code{filename} is the name of the MINC file to process,
  \code{slice} specifies which slice from the file to process, and
  \code{progress} indicates whether or not the program should print
  progress information as it goes.  \code{filename} and \code{slice}
  are both required; if \code{progress} is not given, it defaults to 1
  (``true'').
\begin{verbatim}
function [K1,k2] = rcbf1 (filename, slice, progress)
\end{verbatim}

\item Get the images and image information.  This includes all of the
  frames for the slice being analyzed, the frame start times, the
  frame lengths, the mid-frame times, and the blood data.  The frame
  time information is returned by simple enquiries with the data
  handle \code{img} returned by \code{openimage}.  The blood data is
  returned by \code{resampleblood}, which gives the blood data in an
  evenly sampled time domain (every half second).  The blood data is
  then cross-calibration corrected by multiplying by the factor
  \code{XCAL}.  The cross-calibration converts from ${\rm Bq} /
  {\rm g_{blood}}$ to ${\rm nCi} / {\rm mL_{blood}}$, taking into
  account the calibration between the well counter and the PET
  scanner.  In order to maintain consistent units throughout the
  analysis, this data must then be converted from ${\rm nCi / ml_{blood}}$
  {\em back} to ${\rm Bq} / {\rm g_{blood}}$.  The actual PET
  images are then retrieved, and the units are again converted to
  ${\rm Bq} / {\rm g_{tissue}}$.  Any negative values present in
  the images are set to zero.
\begin{verbatim}
img = openimage(filename);
FrameTimes = getimageinfo (img, 'FrameTimes');
FrameLengths = getimageinfo (img, 'FrameLengths');
MidFTimes = FrameTimes + (FrameLengths / 2);

[g_even, ts_even] = resampleblood (img, 'even');

% Apply the cross-calibration factor, and convert back to Bq/g_blood
XCAL = 0.11;
g_even = g_even*XCAL*37/1.05;

Ca_even = g_even;                % no delay/dispersion correction

PET = getimages (img, slice, 1:length(FrameTimes));
PET = PET * 37 / 1.05;           % convert to decay / (g_tissue * sec)
PET = PET .* (PET > 0);          % set all negative values to zero
ImLen = size (PET, 1);           % num of rows = length of image
\end{verbatim}

\item Calculate some useful integrals that are used several times in
  the rest of the program.  \code{PET\_int1}, and \code{PET\_int2} are
  weighted integrals of the PET data across frames (integrated with
  respect to time).  In particular, \code{PET\_int1} is the numerator
  of the left-hand-side of equation \ref{eq:1comp}, and
  \code{PET\_int2} is the denominator.  To get clean images out of the
  analysis, we wish to set all points outside of the head to zero.
  Therefore, we create a simple mask, and apply it to the weighted
  integrals.  Note the use of \code{rescale} to perform an
  ``in-place'' multiplication on \code{PET\_int1}.  This has the same
  effect as the more conventional MATLAB
  \verb|PET_int1 = PET_int1 .* mask|,
  but without making a copy of \code{PET\_int1}.
\begin{verbatim}
PET_int1 = trapz (MidFTimes, PET')';
PET_int2 = trapz (MidFTimes, PET' .* (MidFTimes * ones(1,ImLen)))';

mask = PET_int1 > mean (PET_int1);
rescale (PET_int1, mask);
rescale (PET_int2, mask);
\end{verbatim}

\item Calculate the left hand side of equation (\ref{eq:1comp}).
\begin{verbatim}
rL = PET_int1 ./ PET_int2;
\end{verbatim}

\item Assign the $k_2$ values to be used in the lookup table, and then
generate some more useful weighted integrals.  \code{findintconvo}
computes the function
\begin{equation}
C_{a}(t) \otimes e^{-k_{2}t}
\end{equation}
at all points in the evenly-resampled time domain \code{ts\_even}.
Then, it integrates across each individual frame (which run from $T_1$
to $T_2$; $T_1$ and $T_2$ in the following formula are implicitly
functions of the frame).  Then, the weighted integrals across {\em all} frames
are computed:
\begin{equation}
\int_{0}^{T} \frac
  {\int_{T_1}^{T_2} \left[ C_{a}(u) \otimes e^{-k_{2}u} \right] du}
  {T_2 - T_1}
  w_i dt
\label{eq:convint}
\end{equation}
Here, $w_i$ is the weighting function; for the double-weighted
analysis it is either $1$ or $t$ as in the right hand side of equation
(\ref{eq:1comp}).

Then, since we wish to relate $k_2$ to the values of these integrals,
\code{findintconvo} computes equation \ref{eq:convint} at a wide range
of values of $k_2$ (supplied by the argument \code{k2\_lookup}) for
each weighting function $w_i$.  (For the double-weighted method, $w_1
= 1$ and $w_2 = t$.)  Note that the supplied value of
\code{k2\_lookup} implies an assumption that no voxel in the image
will have a $k_2$ value outside the range $0 \ldots 3\,
{\rm min}^{-1}$.)  See section \ref{sec:findintconvo_listing} for
information on the internal details of \code{findintconvo}.

\begin{verbatim}
k2_lookup = (0:0.02:3) / 60;
[conv_int1, conv_int2] = findintconvo (Ca_even, ts_even, k2_lookup,...
                            MidFTimes, FrameLengths, 1, MidFTimes);
\end{verbatim}

\item Calculate the right side of equation (\ref{eq:1comp}).
\begin{verbatim}
rR = conv_int1 ./ conv_int2;
\end{verbatim}

\item Generate the $k_2$ image through table lookup.  This is where we
  make use of the lookup tables generated in \code{findintconvo} for
  great time savings: \code{findintconvo} only has to compute equation
  \ref{eq:convint} (a comparatively slow operation) a few hundred
  times, but for that effort we get 16,384 values of $k_2$ very
  quickly.
\begin{verbatim}
k2 = lookup(rR, k2_lookup, rL);
\end{verbatim}

\item Generate the $K_1$ image through table lookup and division.
  \code{k2\_conv\_ints} contains the values of equation \ref{eq:convint}
  at the actual values of $k_2$ for this image, rather than at the
  artificial set \code{k2\_lookup}.  This step is where we solve the
  numerator of equation \ref{eq:1comp} for $K_1$.
\begin{verbatim}
k2_conv_ints = lookup (k2_lookup, conv_int1, k2);
K1 = PET_int1 ./ k2_conv_ints;
\end{verbatim}

\item Clean up the $K_1$ image by setting any NaN's and infinities to
zero, and close the image data set.
\begin{verbatim}
nuke = find (isnan (K1) | isinf (K1));
K1 (nuke) = zeros (size (nuke));
closeimage (img);
\end{verbatim}

\item Finally, $K_1$ is converted from the internal units [${\rm
    g_{blood} / g_{tissue}}$] to the standard units for rCBF
  analysis [${\rm mL_{blood} / (100\, g_{tissue} \cdot min)}$].
\begin{verbatim}
rescale (K1, 100*60/1.05);
\end{verbatim}

\end{enumerate}

\subsubsection{RCBF2}
\label{sec:rcbf2_listing}

\code{RCBF2} is essentially an extension of \code{RCBF1} with the
addition of a third weighting function (needed to calculate $V_0$) and
correction for the delay and dispersion of blood.  Also, RCBF2
allows the user to specify a list of slices (as a vector) rather than
requiring a scalar \code{slice}.  This means that we add a loop
through all desired slices, so some of the code is rearranged to avoid
redoing the same work several times in the loop.

\begin{enumerate}
\item The function declaration line.  The output arguments \code{K1},
  \code{k2}, and \code{V0} will all be whole images---that is, for
  $128 \times 128$ PET data, they will be matrices with 16,384
  elements per column, and one column per slice processed.
  \code{delta} will contain the blood delay term $\delta$ for each
  specified slice.

  Of the input arguments, only \code{filename} (the name of the MINC
  volume to process) and \code{slices} (the list of slices to process)
  are required.  The other three are boolean variables (i.e., they
  should be scalars with a value of either 0 or 1) that default to
  ``true'' (1).  \code{progress} controls whether RCBF2 prints
  progress information; \code{correction} decides whether or not it
  performs correction of the blood data for delay and dispersion; and
  \code{batch} controls whether selection of the mask used for
  delay/dispersion correction should be interactive or automatic (the
  default).  The latter two should {\em not} be changed when RCBF2 is
  being used for real data analysis, and are merely provided to speed
  things up when debugging.
  \begin{verbatim}
function [K1,k2,V0,delta] = rcbf2_slice ...
         (filename, slices, progress, correction, batch)
  \end{verbatim}

\item Initialize the matrices that will hold the $K_1$, $k_2$, and
  $V_0$ images, as well as the vector to hold the value of $\delta$
  (the blood delay from equation \ref{eq:blood_delay}) for each slice.
  \begin{verbatim}
total_slices = length(slices);
K1 = zeros(16384,total_slices);
k2 = zeros(16384,total_slices);
V0 = zeros(16384,total_slices);
delta = zeros(1,total_slices);
  \end{verbatim}

\item Open the volume and get some preliminary information on frame
  times and lengths.
  \begin{verbatim}
img = openimage(filename);
if (getimageinfo (img, 'time') == 0)
   error ('Study is non-dynamic');
end

FrameTimes = getimageinfo (img, 'FrameTimes');
FrameLengths = getimageinfo (img, 'FrameLengths');
MidFTimes = FrameTimes + (FrameLengths / 2);
  \end{verbatim}

\item Read the blood data, perform cross-calibration, and convert
  units.  (See explanation in section \ref{sec:rcbf1_listing}.)
  \begin{verbatim}
[g_even, ts_even] = resampleblood (img, 'even');
XCAL = 0.11;
rescale(g_even, (XCAL*37/1.05));
  \end{verbatim}

\item Create the weighting functions, $w_1$, $w_2$, and $w_3$ from
  equations \ref{eq:fullweight1}--\ref{eq:fullweight3}.  Also here we
  initialize the list of $k_2$ values from which the lookup table will
  be generated.

  \begin{verbatim}
w1 = ones(length(MidFTimes), 1);
w2 = MidFTimes;
w3 = sqrt (MidFTimes);

k2_lookup = (-10:0.05:10) / 60;
  \end{verbatim}

\item At this point, we start the processing that is specific to each
  slice: read the PET data, perform delay/dispersion correction,
  generate the lookup table, and solve equation \ref{eq:k1two}.  Thus,
  we loop through all user-specified slices:
  \begin{verbatim}
for current_slice = 1:total_slices
  \end{verbatim}

\item Read in the PET data for the current slice, and rescale it
  to convert from ${\rm nCi/mL_{tissue}}$ to ${\rm Bq/g_{tissue}}$.
  \begin{verbatim}
PET = getimages (img, slices(current_slice), 1:length(FrameTimes), PET);
rescale (PET, (37/1.05));
  \end{verbatim}

\item Compute the weighted integrals of the PET data.
  \begin{verbatim}
PET_int1 = ntrapz (MidFTimes, PET, w1);
PET_int2 = ntrapz (MidFTimes, PET, w2);
PET_int3 = ntrapz (MidFTimes, PET, w3);
  \end{verbatim}

  This uses \code{ntrapz}, the CMEX version of \code{trapz}, which has
  the useful feature of allowing a weighting function to be supplied.
  Thus, the first line of code above is equivalent to (but faster and
  less memory-intensive than)
  \begin{verbatim}
weight = ones (16384,1) * w1';
PETweighted = PET .* weight;
PET_int1 = trapz (MidFTimes, PETweighted');
  \end{verbatim}

\item Generate a simple mask based on \code{PET\_int1} (which is
  simply the PET data averaged across all frames), and mask using
  \code{rescale}.  Also, \code{mask} is cleared for memory efficiency.
  \begin{verbatim}
mask = PET_int1 > mean(PET_int1);
rescale (PET_int1, mask);
rescale (PET_int2, mask);
rescale (PET_int3, mask);
clear mask;
  \end{verbatim}

  The next three steps perform delay/dispersion correction of the
  blood data (see section \ref{sec:blood_correction}).

%  In the actual
%  program, this code is in an \code{if (correction)} statement, making
%  blood correction optional.  This detail has been omitted here.

\item First, create a mask that is used to select gray matter only;
  the mask is a variation on that used to mask the weighted PET
  integrals above.  That is, simply select all voxels whose values are
  greater than some constant times the mean of \code{PET\_int1}.  If
  non-interactive mode is on (i.e.  \code{batch} = 1, the default
  behaviour), then this constant is hard-coded to 1.8\footnote{This
    constant was empirically selected because it works fairly well
    with ${\rm H_{2}\,^{15}O}$ CBF data.}; otherwise, the function
  \code{getmask} is run.  This allows the user to select the threshold
  value while displaying the resulting, masked PET data.
  \begin{verbatim}
if (batch)
  mask = PET_int1 > (1.8*mean(PET_int1));
else
  mask = getmask (PET_int1);
end
  \end{verbatim}

\item Use the mask to get the mean of all gray-matter voxels.
  Thus, we reduce the dynamic PET data (16,384 voxels sampled at
  $n$ points in time) to a single time-activity curve (average of
  gray-matter activity at $n$ points in time).
  \begin{verbatim}
A = (mean (PET (find(mask),:)))';
clear mask;
  \end{verbatim}

\item The actual delay/dispersion correction is performed by
  \code{correctblood}.  See sections \ref{sec:blood_correction}, and
  \ref{sec:correctblood_listing} for information on (respectively) the
  theoretical basis and the implementation of delay/dispersion
  correction.
  \begin{verbatim}
[ts_even, Ca_even, delta(:,current_slice)] = correctblood ...
    (A, FrameTimes, FrameLengths, g_even, ts_even, progress);
  \end{verbatim}

\item Generate tables of the three weighted integrals of $Ca(t)
  \otimes e^{-k_{2}t}$.  (Actually, we generate tables of this
  expression integrated across each individual frame, then integrated
  across all frames; the procedure is identical to that used in RCBF1
  except for the addition of a third weighting function and the
  greatly expanded range of possible values for $k_2$.)
  \begin{verbatim}
[conv_int1,conv_int2,conv_int3] = findintconvo (Ca_even,ts_even,...
   k2_lookup, MidFTimes, FrameLengths, 1, w2, w3);
  \end{verbatim}

\item Generate some additional useful integrals.  These are used more
  than once in the subsequent code, and so are calculated in advance
  to speed up the computation.  \code{Ca\_mft} is the blood data
  averaged over each frame.  This is taken as the value of the blood
  data at the mid-frame time.  Note that we must detect when the blood
  data does not cover all the frames that the PET data does; this is
  made easy because \code{nframeint} does the work for us.  In
  particular, if the start time of any frame (some element of
  \code{FrameTimes}) is less than the start time of blood data
  [\code{ts\_even(1)}], then \code{nframeint} returns \code{NaN}
  (not-a-number) in the element of \code{Ca\_mft} corresponding to that
  frame.  Similarly, if the end time of any frame (some element of
  \code{FrameTimes+FrameLengths}) is greater than the end time of
  blood data [\code{ts\_even(length(ts\_even))}], then \code{NaN}
  is also returned.  The frames that fall outside of the blood data
  are then not used in generating the weighted integrals of the blood data.
\begin{verbatim}
Ca_mft = nframeint (ts_even, Ca_even, FrameTimes, FrameLengths);
select = ~isnan(Ca_mft);

if (sum(select) ~= length(FrameTimes))
  disp('Warning: blood data does not span frames.');
end

Ca_int1 = ntrapz(MidFTimes(select), Ca_mft(select), w1(select));
Ca_int2 = ntrapz(MidFTimes(select), Ca_mft(select), w2(select));
Ca_int3 = ntrapz(MidFTimes(select), Ca_mft(select), w3(select));
\end{verbatim}

\item Generate the lookup table relating $k_2$ to values of the right
hand side of equation (\ref{eq:k1two}).  We also calculate the left
hand side of equation (\ref{eq:k1two}), which will be used in the
generation of a $k_2$ image.  Here, we see the value of precomputing
all the terms of \code{rL} and \code{rR}---not only is the code fairly
straightforward [as long as you understand the correspondence between
the variables \code{Ca\_int{\it i\/}}, \code{PET\_int{\it i\/}} and
\code{conv\_int{\it i\/}}, and the terms of equation (\ref{eq:k1two})],
but the computation of \code{rL} and \code{rR} is very fast.

Note that since \code{PET\_int{\it i\/}} is an image (i.e. it contains
a value for each voxel in the slice), and \code{Ca\_int{\it i\/}} is a
scalar, then \code{rL} will be an image.  However,
\code{conv\_int{\it i\/}} is a lookup table keyed on
\code{k2\_lookup}; that is, there it contains one value for every
value of $k_2$ presumed possible.  Thus, \code{rR} will be also be a
lookup table keyed on \code{k2\_lookup}.
\begin{verbatim}
rL = ((Ca_int3 * PET_int1) - (Ca_int1 * PET_int3)) ./ ...
      ((Ca_int3 * PET_int2) - (Ca_int2 * PET_int3));

rR = ((Ca_int3 * conv_int1) - (Ca_int1 * conv_int3)) ./ ...
      ((Ca_int3 * conv_int2) - (Ca_int2 * conv_int3));
\end{verbatim}

\item Since \code{rL} and \code{rR} are the left- and right-hand-sides
  of equation (\ref{eq:k1two}), we can use their equality to find
  $k_2$ for every voxel.  That is, we know \code{rL} for every voxel,
  and we know \code{rR} for a certain set of values of $k_2$.  Thus,
  we can use \code{rR} to interpolate values of $k_2$.  First,
  however, we must invert the current relationship between
  \code{k2\_lookup} and \code{rR}; that is, we must make
  \code{k2\_lookup} a lookup table keyed on the values of \code{rR}.
  MATLAB's \code{sort} function makes this quite easy: we can sort
  \code{rR} and get a vector containing the ``sort order'' in one
  step.  Since we need \code{k2\_lookup} in its original order later
  on, we make a copy called \code{k2\_sorted} (even though it's now
  scrambled) that is ordered according to \code{rR}.
\begin{verbatim}
[rR,sort_order] = sort (rR);
k2_sorted = k2_lookup (sort_order);
\end{verbatim}

\item Generate the $k_2$ image, through a simple table lookup.
Values of $k_2$ are chosen by finding the value of $k_2$ where
\code{rL} and \code{rR} are equal.
\begin{verbatim}
k2 = lookup(rR, k2_sorted, rL);
\end{verbatim}

\item Generate the $K_1$ image by evaluating the numerator of
equation (\ref{eq:k1two}).  All of the time consuming calculations
have already been performed, and we can evaluate the $\int_{0}^{T} w
(\int_{T_1}^{T_2} Ca(u) \otimes e^{-k_{2}u} du)/(T_2 - T_1) dt$ terms
through table lookup.
\begin{verbatim}
K1_numer = ((Ca_int3*PET_int1) - (Ca_int1 * PET_int3));
K1_denom = (Ca_int3 * lookup(k2_lookup,conv_int1,k2)) - ...
           (Ca_int1 * lookup(k2_lookup,conv_int3,k2));
K1 = K1_numer ./ K1_denom;
\end{verbatim}

\item Generate the $V_0$ image by evaluating equation
(\ref{eq:fullweight1}) directly.  Once again, we may get values for
the complicated part of the equation through simple table lookup.
\begin{verbatim}
V0 = (PET_int1 - (K1 .* lookup(k2_lookup,conv_int1,k2))) / Ca_int1;
\end{verbatim}

\item Clean up the images by removing NaN's and infinities (setting
them to zero).
\begin{verbatim}
nuke = find (isnan (K1));
K1 (nuke) = zeros (size (nuke));
nuke = find (isinf (K1));
K1 (nuke) = zeros (size (nuke));

nuke = find (isnan (V0));
V0 (nuke) = zeros (size (nuke));
nuke = find (isinf (V0));
V0 (nuke) = zeros (size (nuke));
\end{verbatim}

\item Convert from the units used internally to the standard units for
  rCBF analysis.
  \begin{verbatim}
rescale (K1, 100*60/1.05);
rescale (k2, 60);
rescale (V0, 100/1.05);
  \end{verbatim}

\item Finally, close the image file so that everything gets cleaned
up nicely.
\begin{verbatim}
closeimage (img);
\end{verbatim}

\end{enumerate}

\subsubsection{CORRECTBLOOD}
\label{sec:correctblood_listing}

\begin{enumerate}

\item Function declaration and input/output arguments:
  \begin{verbatim}
function [new_ts_even, Ca_even, delta] = correctblood ...
      (A, FrameTimes, FrameLengths, g_even, ts_even, options)
  \end{verbatim}
The input arguments are:
%
\begin{ttdescription}{FrameLengths}
  \item[A] PET activity versus time, averaged across grey matter and
    sampled at the mid-frame times
  \item[FrameTimes] the start time for each frame (in seconds,
    relative to the study start time)
  \item[FrameLengths] the length of each frame (in seconds)
  \item[g\_even] blood data, resampled at an evenly-spaced time domain
  \item[ts\_even] the time domain at which \code{g\_even} is sampled
\end{ttdescription}
The output arguments are:
\begin{ttdescription}{FrameLengths}
\item[new\_ts\_even] Generally the same as \code{ts\_even}, with some
  elements possibly chopped off from the end due to shifting of the
  time scale.
\item[Ca\_even] \code{g\_even} after correction for blood dispersion
  and delay.
\item[delta] The computed delay correction $\delta$, in seconds.
\end{ttdescription}

\item Do the initial setup: calculate the mid-frame times, and find
  frames that fall in the first 60 seconds of the study.  (Although
  the blood data is corrected over the entire study, the delay
  correction is based on the PET data from the first 60 seconds only,
  since the PET time-activity-curve is relatively flat by $t=60$.)
  because
\begin{verbatim}
MidFTimes = FrameTimes + FrameLengths/2;
first60 = find (FrameTimes < 60);       % all frames in first
numframes = length(FrameTimes);         %  minute only
\end{verbatim}

\item Perform delay dispersion; we use \code{deriv} to compute a
  smoothed version of \code{g\_even} and its first derivative, and
  then replace \code{g\_even} with the dispersion-corrected
  blood data ($\bar g$ in equation \ref{eq:dispersion_correct}).
\begin{verbatim}
[smooth_g_even, deriv_g] = ...
     deriv (3, length(ts_even), g_even, (ts_even(2)-ts_even(1)));
smooth_g_even(length(smooth_g_even)) = [];
deriv_g(length(deriv_g)) = [];
ts_even(length(smooth_g_even)) = [];

g_even = smooth_g_even + tau*deriv_g;
\end{verbatim}

\item At this point, we are ready to start the delay
  correction---i.e., we will find the value of $\delta$ that gives a
  function $C_a (t)$ that best fits the PET activity $A^{*}(t)$ in
  equation \ref{eq:blood_delay}.  However, there are three other
  unknowns in equation \ref{eq:blood_delay}, and it was found that a
  full four-parameter fit was highly unstable.  Therefore, we select a
  fixed set of values for $\delta$, perform multiple three-parameter
  fits (for $\alpha$, $\beta$, and $\gamma$), and select the value of
  $\delta$ which resulted in the best fit.

  First, we prepare for the repeated fits.  The fixed set of
  $\delta$-values is selected; we initialize \code{rss} and
  \code{params} (used to select the value of $\delta$ which resulted in
  the best fit); and select values of $\alpha$, $\beta$, and $\gamma$
  to start the fitting.  These values are selected as being fairly
  representative of real data
  [$\alpha = 0.6 {\rm mL_{blood} / (100 \, g_{tissue} \cdot min)}$,
   $\beta = \alpha / 0.8$, and $\gamma = 0.03 \, {\rm g_{blood}/g_{tissue}}$],
  but with $\alpha$ converted to our internal units of
  ${\rm g_{blood} / (g_{tissue} \cdot sec)}$ and $\beta$ to $1/sec$.
  The \code{init} vector holds these values of $\alpha$, $\beta$, and
  $\gamma$.
\begin{verbatim}
deltas = -5:1:10;
init = [.0001 .000125 .03];
rss = zeros (length(deltas), 1);
params = zeros (length(deltas), 3);
\end{verbatim}

\item Now enter the loop through the values of $\delta$ in
  \code{deltas}.  The first step is to copy the current element,
  \code{deltas(i)}, to \code{delta}; this is done solely to make the
  code easier to read.
  \begin{verbatim}
for i = 1:length(deltas)
   delta = deltas (i);
  \end{verbatim}

\item Now inside the loop, we perform a three-parameter fit for the
  current value of $\delta$.  This is done by first computing
  \code{shifted\_g\_even}, which is the current ``guess'' at $C_a (t)$
  (see equation \ref{eq:blood_delay}).  Note that the shifted
  activity is computed from \code{g\_even}, which at this point
  contains $\bar g (t)$, the dispersion-corrected blood data (equation
  \ref{eq:dispersion_correct}).
\begin{verbatim}
   shifted_g_even = lookup ((ts_even-delta), g_even, ts_even);
   g_select = find (~isnan (shifted_g_even));
\end{verbatim}

\item Now perform the fit.  The function \code{delaycorrect}
  encapsulates the entire fitting procedure into one function; this is
  equivalent to having one user-supplied function that evaluates the
  function to minimize, and another function (such as \code{fmins}) to
  iteratively evaluate and minimize this function.  However, because
  this method of delay correction was found to be extremely slow,
  \code{delaycorrect} was written entirely in C as a special case.

\begin{verbatim}
   final = delaycorrect (init, ...
                         shifted_g_even(g_select), ...
                         ts_even(g_select), ...
                         A, FrameTimes, FrameLengths);
\end{verbatim}

\item Save the fit results ($\alpha$, $\beta$, and $\gamma$) and
  compute the residual (sum of the squares of the differences between
  the data points and points on the fitted curve) for this value of
  $\delta$.  (\code{fit\_b\_curve} simply calls \code{b\_curve} to
  compute the right-hand-side of equation \ref{eq:delay_correct}, the
  ``blood curve,'' for the current values of $\alpha$, $\beta$,
  $\gamma$, and $\delta$, at each mid-frame time.  Then, it finds the
  differences between this and the points on the PET activity curve
  \code{A}, and returns the sum of the squares of these differences.
  This is saved to the vector \code{rss}.
\begin{verbatim}
   params (i,:) = final;
   rss(i) = fit_b_curve (final, ...
              shifted_g_even(g_select), ts_even(g_select), ...
              A, FrameTimes, FrameLengths);
\end{verbatim}

\item Finally, we re-use the current values of $\alpha$, $\beta$,
  $\gamma$ as initial values for the next fit and end the \code{for} loop.
\begin{verbatim}
   init = final;
end      % for delta
\end{verbatim}

\item At this point, we have a vector of residual sums of squares (a single
  number estimating the goodness-of-fit for each value of $\delta$).
  To select the ``winning'' $\delta$, we simply find the minimum of
  this vector.
\begin{verbatim}
[err, where] = min (rss);
delta = deltas (where);
\end{verbatim}

\item Now that we have a value for \code{delta}, perform the actual
delay correction (shift the blood data).  We must also remove NaN's
from the new data.  These appear if \code{lookup} cannot perform a
lookup at a point (i.e., there is no corresponding point in the table).
They will therefore occur at the end points, where \code{ts\_even}
does not span \code{(ts\_even-delta)}.
\begin{verbatim}
Ca_even = lookup ((ts_even-delta), g_even, ts_even);

nuke = find(isnan(Ca_even));
Ca_even(nuke) = [];
\end{verbatim}

\item And finally, make \code{new\_ts\_even} a truncated copy of
  \code{ts\_even} that fits \code{Ca\_even} and reflects the loss of
  information due to resampling at the very end of the data.
\begin{verbatim}
new_ts_even = ts_even;
new_ts_even(nuke) = [];
\end{verbatim}
\end{enumerate}

\subsubsection{FINDINTCONVO}
\label{sec:findintconvo_listing}

\code{findintconvo} (``find integrals of convolutions'') computes the
values of
\begin{equation}
\label{eq:conv_int}
  \int_{0}^{T} \frac{\int\limits_{T_1}^{T_2}
    \left[ C_{a}(u) \otimes e^{-k_{2}u} \right] du}{T_2 - T_1} \, w_i \, dt
\end{equation}
at many different values of $k_2$, for up to three weighting functions
$w_i$.  Here, $T_1$ and $T_2$ represent the start and end time any
particular frame; in concrete terms, the inner integrand is just the
average of $C_{a}(u) \otimes e^{-k_{2}u}$ across each frame, and is
computed once for each frame.  The outer integral then integrates across
all frames to arrive at a single value for each weighting function
$w_i$ and each value of $k_2$.

\begin{enumerate}
%
\item The function declaration line.
\begin{verbatim}
function [int1, int2, int3] = ...
   findintconvo (Ca_even, ts_even, k2_lookup,...
                 midftimes, flengths, w1, w2, w3, progress)
\end{verbatim}
The input arguments are:
\begin{ttdescription}{midftimes}
\item[Ca\_even]the blood data resampled at an evenly-spaced time
  domain.  Usually, this is as returned by \code{resampleblood}, and
  possibly delay- and dispersion-corrected by \code{correctblood}.
\item[ts\_even]the time domain at which \code{Ca\_even} was resampled.
\item[k2\_lookup]the list of $k_2$ values at which to evaluate equation
  \ref{eq:conv_int}.  The output will consist of one value per
  weighting function per value of $k_2$.
\item[midftimes]the mid-frame times (used to perform the
  frame-by-frame integration).
\item[flengths]the length of each frame (also used in the
  frame-by-frame integration).
\item[w1,w2,w3]the three weighting functions $w_i$.  \code{w1} must be
  supplied, but if it is an empty matrix, then a weighting function of
  1 is assumed.  \code{w2} and \code{w3} are not required, and if they
  are not given, then \code{int2} and \code{int3} (respectively) will
  not be defined in the output.  Generally, the weighting funtions are
  simple functions of $t$ such as 1, $t$, or $t^2$.
\item[progress]an optional argument indicating whether progress should
  be reported (in the form of printing a dot when the weighted
  integrals for each value of $k_2$ have been computed).  This is
  quite useful, as \code{findintconvo} is one of the most
  time-consuming steps of RCBF analysis.
\end{ttdescription}

The output arguments \code{int1}, \code{int2}, and \code{int3} are
simply vectors containing the value of equation \ref{eq:conv_int} for
the three different weighting functions; each element of these vectors
corresponds to one value of $k_2$ as supplied in \code{k2\_lookup}.

\item Do some initial setup.  We need to get the sizes of various
vectors, and initialize vectors that we will fill element by element
later.  Initializing vectors to all zero before filling them allows
better memory management by MATLAB.
\begin{verbatim}
NumEvenTimes = length(ts_even);
NumFrames = length(midftimes);
fstart = midftimes - (flengths / 2);

TableSize = length (k2_lookup);
integrand = zeros (NumFrames, 1);

if (nargin >= 6); int1 = zeros (1, TableSize); end;
if (nargin >= 7); int2 = zeros (1, TableSize); end;
if (nargin == 8); int3 = zeros (1, TableSize); end;

% if w1 is empty, assume that it should be all ones

if isempty (w1)
   w1 = ones (size(NumFrames));
end
\end{verbatim}

\item Calculate each element of the integrals, one at a time.
Unfortunately, there does not seem to be any way to vectorize this
operation, and it must therefore be performed within an inefficient
\code{for} loop.

\begin{verbatim}
for i = 1:TableSize
\end{verbatim}

\item First calculate the innermost terms of equation
  \ref{eq:conv_int}.  \code{exp\_fun} is $e^{-k_2 t}$, and \code{convo}
  is $C_a (t) \otimes e^{-k_2 t}$.  We then perform the inner
  integration, i.e. average across all frames.  This is performed by
  \code{nframeint}, a special CMEX routine that has been carefully
  optimised for this very common operation in RCBF analysis.  Type
  \code{help nframeints} in MATLAB for more information.
\begin{verbatim}
   exp_fun = exp(-k2_lookup(i) * ts_even);
   convo = nconv(Ca_even, exp_fun, ts_even(2) - ts_even(1));

   integrand = nframeint (ts_even, convo(1:length(ts_even)),...
                          fstart, flengths);
\end{verbatim}

\item Find any frames that are not completely covered by the
  \code{ts\_even} time domain.  \code{nframeint} actually does this
  for us, returning NaN (not-a-number) in any such element of its
  output vector.  Thus, we only use data from frames that are {\em
  not} equal to NaN, selected using the built-in \code{isnan}
  function.
\begin{verbatim}
   select = ~isnan(integrand);
\end{verbatim}

\item Now we calculate the outer integral (the weighted integral
  across all frames) for each weighting function with the current
  value of $k_2$.  Again, we use a CMEX routine to enhance
  performance; \code{ntrapz} is a replacement for MATLAB's
  \code{trapz} function that is much faster, as well as having an
  optional argument to allow weighting of the integrand.  Note the use
  of \code{select} to make sure that we only use frames actually
  spanned by the blood data.
\begin{verbatim}
  int1 (i) = ntrapz(midftimes(select), integrand(select), w1(select));
  int2 (i) = ntrapz(midftimes(select), integrand(select), w2(select));
  int3 (i) = ntrapz(midftimes(select), integrand(select), w3(select));
\end{verbatim}
(We have omitted the code that makes \code{w2} and \code{w3}
optional in favour of concentrating on the numerical analysis.)

\item End the \code{for} loop.
\begin{verbatim}
end
\end{verbatim}

\end{enumerate}

\subsubsection{B\_CURVE}

\code{bcurve} computes the right-hand-side of equation
\ref{eq:delay_correct}, that is,
\begin{equation}
\frac{\int\limits_{T_1}^{T_2}
  \left( \alpha
    \left[ C_a(t) \otimes  e^{-\beta t} \right]
  + \gamma C_a(t) \right) dt} {T_2 - T_1}
\label{eq:b_curve}
\end{equation}
In the early stages of the development of RCBF, \code{b\_curve} was
used in the non-linear fitting required for delay correction.  Now,
the entire fitting procedure for delay correction is encapsulated in
the CMEX routine \code{delaycorrect}.  However, \code{delaycorrect}
simply performs one fit (optimising $\alpha$, $\beta$, and $\gamma$
for a single value of $\delta$); it is called multiple times, and
\code{b\_curve} is used to pick which value of $\delta$ resulted in
the best fit (in the least squares sense).  In particular, we wish to
satisfy equation \ref{eq:delay_correct}; therefore, the sum of the
squares of the differences between its two sides ($A^{*} (t)$ and
equation \ref{eq:b_curve}) for a particular value of $\delta$ is
computed, and the value of $\delta$ that results in the smallest
residual is picked as the delay factor.  The finding of the residual
is actually done in \code{fit\_b\_curve}, which due to its simplicity
(it has only two line of interesting code, one of which is a call to
\code{b\_curve}) is not shown here.

\begin{enumerate}

\item Input and output arguments:
\begin{verbatim}
function integral = b_curve ...
    (args, shifted_g_even, ts_even, A, fstart, flengths)
\end{verbatim}
  The output argument \code{integral} is just the values of equation
  \ref{eq:b_curve} after frame-by-frame integration, i.e. there is one
  number for each frame.

  The input arguments are
  \begin{ttdescription}{flengths}
  \item[args]a three element vector containing $\alpha$, $\beta$, and
    $\gamma$ from equation \ref{eq:b_curve}.  Keep in mind in the
    following code that \code{args(1)} is $\alpha$, \code{args(1)} is
    $\beta$, and \code{args(1)} is $\gamma$.
  \item[g\_even]the blood data resampled at an evenly-spaced time
    domain, and possibly shifted by some delay factor $\delta$.  We
    are not interested here in what that value of $\delta$ is,
    however.
  \item[ts\_even]the evenly-spaced time domain at which \code{g\_even}
    is sampled.
  \item[A]the PET activity, averaged over gray matter, for the current
    slice.  (This isn't actually used in \code{b\_curve}, but the
    argument is still here for historical reasons and to make calls
    to \code{b\_curve} and \code{fit\_b\_curve} look the same.)
  \item[fstart]the frame start times.
  \item[flengths]the frame lengths.
  \end{ttdescription}

\item Evaluate the first term of the integrand in equation \ref{eq:b_curve}.
\begin{verbatim}
expthing = exp(-args(2)*ts_even);
c = nconv(shifted_g_even,expthing,ts_even(2)-ts_even(1));
c = c (1:length(ts_even));
i1 = args(1)*c;                   % alpha * (convolution)
\end{verbatim}

\item Evaluate the second term of the integrand, and the two terms
  together to get the integrand, \code{i}.
\begin{verbatim}
i2 = args(3)*shifted_g_even;            % gamma * g(t - delta)

i = i1+i2;
\end{verbatim}

\item Perform the frame-by-frame integration.
\begin{verbatim}
integral = nframeint (ts_even, i, fstart, flengths);
\end{verbatim}

\item Clean up any NaN's that have cropped up by setting them to zero.
Also, truncate the function to whatever length \code{A} is.
\begin{verbatim}
nuke = find (isnan (integral));
integral (nuke) = zeros (size (nuke));

integral = integral (1:length(A));
\end{verbatim}
\end{enumerate}

%--------------------------------------------------------------
\newpage
\section{Using the rCBF Package}

\subsection{Preparing Blood Data}

The EMMA function \code{resampleblood} that is used in rCBF to get
the blood data expects the data to either be included in the image
MINC file, or to be contained in a netCDF file with a \code{.bnc}
ending.

In order to assist the user by creating the \code{.bnc} file, there
is a utility called \code{bloodtonc}.  This program takes a
\code{.cnt} file, and converts it to a \code{.bnc} file that will be
read by the rCBF package.

To perform the conversion, use FTP to transfer the \code{.cnt} file
from the VAX to the SGI using ASCII mode.  Next, type:

\begin{verbatim}

     bloodtonc filename.cnt filename.bnc

\end{verbatim}

where \code{filename} is the name of the file (eg.
\code{arnaud\_20547}).  In order for \code{resampleblood} to find the
\code{.bnc} file, it must be in the same directory as the \code{.mnc}
file that contains the images.  Therefore, make sure that they are in
the same directory before performing the analysis using rCBF.

\subsection{Doing the Analysis}

Once the blood and image files are prepared, the analysis can be
performed.  Start MATLAB by typing \code{matlab} at the shell prompt.
Starting the analysis is very straightforward.  You may type
\code{help rcbf2} to get information on running the rCBF package.
Basically, \code{rcbf2} is a MATLAB function that returns a $K_1$,
$k_2$, and $V_0$ image, as well as the delay found during blood delay
correction.  It requires the name of the MINC file that contains the
images, and the number of the slice to analyze.  Therefore, if we
wished to analyze slice 12 of \code{arnaud\_20547.mnc}, we would call
\code{rcbf2} as:
%
\begin{verbatim}
     [K1, k2, V0, delay] = rcbf2('arnaud_20547.mnc', 12);
\end{verbatim}
%
In this case, the semi-colon at the end is {\em very} important since
\code{rcbf2} will return the entire images.  If the semi-colon is
omitted, the $K_1$, $k_2$, and $V_0$ values for every pixel will be
echoed to the screen, which takes a considerable amount of time.

Once the images have been generated, they may be manipulated using
any of the normal EMMA tools (viewed with \code{viewimage}, saved
with \code{putimages}, etc.).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%    TEMPORARILY END THE DOCUMENT HERE    %%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\end{document}

%--------------------------------------------------------------
\newpage
\section{MATLAB Functions}

\input{rcbf-help}

\end{document}


\documentclass{article}
\usepackage{graphicx}
\usepackage{subfigure}
\usepackage{fancyhdr}
\usepackage{extramarks}
\usepackage{amsmath}
\usepackage{amsthm}
\usepackage{amsfonts}
\usepackage{tikz}
\usepackage[plain]{algorithm}
\usepackage{algpseudocode}
\usepackage{fancyvrb}
\usepackage{multirow}
\usepackage{booktabs}
\usetikzlibrary{automata,positioning}

%
% Basic Document Settings
%

\topmargin=-0.45in
\evensidemargin=0in
\oddsidemargin=0in
\textwidth=6.5in
\textheight=9.0in
\headsep=0.25in

\linespread{1.1}

\pagestyle{fancy}
\lhead{\hmwkAuthorName}
\chead{\hmwkClass\ : \hmwkTitle}
\rhead{\firstxmark}
\lfoot{\lastxmark}
\cfoot{\thepage}

\renewcommand\headrulewidth{0.4pt}
\renewcommand\footrulewidth{0.4pt}

\setlength\parindent{0pt}

%
% Create Problem Sections
%

\newcommand{\enterProblemHeader}[1]{
    \nobreak\extramarks{}{Problem \arabic{#1} continued on next page\ldots}\nobreak{}
    \nobreak\extramarks{Problem \arabic{#1} (continued)}{Problem \arabic{#1} continued on next page\ldots}\nobreak{}
}

\newcommand{\exitProblemHeader}[1]{
    \nobreak\extramarks{Problem \arabic{#1} (continued)}{Problem \arabic{#1} continued on next page\ldots}\nobreak{}
    \stepcounter{#1}
    \nobreak\extramarks{Problem \arabic{#1}}{}\nobreak{}
}

\setcounter{secnumdepth}{0}
\newcounter{partCounter}
\newcounter{homeworkProblemCounter}
\setcounter{homeworkProblemCounter}{1}
\nobreak\extramarks{Problem \arabic{homeworkProblemCounter}}{}\nobreak{}

%
% Homework Problem Environment
%
% This environment takes an optional argument. When given, it will adjust the
% problem counter. This is useful for when the problems given for your
% assignment aren't sequential. See the last 3 problems of this template for an
% example.
%
\newenvironment{homeworkProblem}[1][-1]{
    \ifnum#1>0
        \setcounter{homeworkProblemCounter}{#1}
    \fi
    \section{Problem \arabic{homeworkProblemCounter}}
    \setcounter{partCounter}{1}
    \enterProblemHeader{homeworkProblemCounter}
}{
    \exitProblemHeader{homeworkProblemCounter}
}

%
% Homework Details
%   - Title
%   - Due date
%   - Class
%   - Section/Time
%   - Instructor
%   - Author
%

\newcommand{\hmwkTitle}{Homework\ \# 3}
\newcommand{\hmwkDueDate}{\today}
\newcommand{\hmwkClass}{MATH6644 Iterative Methods}
\newcommand{\hmwkClassTime}{}
\newcommand{\hmwkClassInstructor}{}
\newcommand{\hmwkAuthorName}{Komahan Boopathy}

%
% Title Page
%

\title{
    \vspace{2in}
    \textmd{\textbf{\hmwkClass:\ \hmwkTitle}}\\
    \normalsize\vspace{0.1in}\small{\hmwkDueDate}\\
    %\vspace{0.1in}\large{\textit{\hmwkClassInstructor\ \hmwkClassTime}}
    \vspace{3in}
}

\author{\textbf{\Large\hmwkAuthorName}}
\date{}

\renewcommand{\part}[1]{\textbf{\large Part \Alph{partCounter}}\stepcounter{partCounter}\\}

%
% Various Helper Commands
%

% Useful for algorithms
\newcommand{\alg}[1]{\textsc{\bfseries \footnotesize #1}}

% For derivatives
\newcommand{\deriv}[1]{\frac{\mathrm{d}}{\mathrm{d}x} (#1)}

% For partial derivatives
\newcommand{\pderiv}[2]{\frac{\partial #1}{\partial #2}}

% Integral dx
\newcommand{\dx}{\mathrm{d}x}

% Alias for the Solution section header
\newcommand{\solution}{\textbf{\large Solution}}

% Probability commands: Expectation, Variance, Covariance, Bias
\newcommand{\E}{\mathrm{E}}
\newcommand{\Var}{\mathrm{Var}}
\newcommand{\Cov}{\mathrm{Cov}}
\newcommand{\Bias}{\mathrm{Bias}}

\begin{document}
\maketitle
\thispagestyle{empty}

\pagebreak
\begin{homeworkProblem}

  \emph{Let $A$ be a nonsingular matrix with all singular values in the
    interval $(1 , 2)$.  Estimate the number of CGNR iteration required
    to reduce the relative residual by a factor of $10^{-4}$.}

  \medskip

  Let $m$ be the number of \underline{pure conjugate gradient}
  iterations required to reduce the error to $\epsilon=10^{-4}$ of the
  initial error.  We have
  $$ ||e||_{A}^{m+1} \le \left( \dfrac{\sqrt{\kappa(A)}-1}{\sqrt{\kappa(A)}+1} \right)^{m+1} ||e||_{A}^{0} $$

  Taking logarithm on both sides:
  $$ (m + 1) \ln \left( \dfrac{\sqrt{\kappa(A)}-1}{\sqrt{\kappa(A)}+1}
  \right) \ge \ln \left( {\dfrac{||e||_{A}^{m+1}}{||e||_{A}^{0}}}
  \right)
  $$

  Rearrange to find the unknown $m$
  $$
  m \ge \dfrac{\ln {\epsilon}}{\left( \dfrac{\sqrt{\kappa(A)}-1}{\sqrt{\kappa(A)}+1} \right)} - 1
  $$

  Now, modifying this relation for \textit{CGNE} method gives the
  following:
  $$
  m \ge \dfrac{\ln {\epsilon}}{\left( \dfrac{\sqrt{\kappa(A^TA)}-1}{\sqrt{\kappa(A^TA)}+1} \right)} - 1
  $$

  Using the relation $\kappa(A)^2 \approx \kappa(A^TA)$, for
  general matrix $A$, one gets

  $$
  m \ge \dfrac{\ln {\epsilon}}{\left( \dfrac{{\kappa(A)}-1}{{\kappa(A)}+1} \right)} - 1
  $$

  This is same as the number of iterations required for \emph{steepest
    descent method}. In this case, the condition number $\kappa(A^TA)
  \approx \dfrac{|\lambda_{max}|^2}{|\lambda_{min}|^2} = \dfrac{4}{1}
  = 4$.  The required relative reduction in error is $10^{-4}$. Using
  this information
  $$
  m \ge \dfrac{\ln {10^{-4}}}{\ln \dfrac{\sqrt{4}-1}{\sqrt{4}+1}} - 1 = 8.38 \approx 9
  $$

  \end{homeworkProblem}

\pagebreak

\begin{homeworkProblem}
  \emph{Carry  out  (without  the  help  of  computers)  the  GMRES  method  to  the  following
    linear system $Ax = b$, where
    $$ A =
    \begin{bmatrix}
      0 &  0 & 0 & 0 & 1 \\
      1 &  0 & 0 & 0 & 0 \\
      0 &  1 & 0 & 0 & 0 \\
      0 &  0 & 1 & 0 & 0 \\
      0 &  0 & 0 & 1 & 0 \\
    \end{bmatrix},
    b =
    \begin{bmatrix}
      1 \\
      0 \\
      0 \\
      0 \\
      0 \\
    \end{bmatrix},
    x^{(0)} =
    \begin{bmatrix}
      0 \\
      0 \\
      0 \\
      0 \\
      0 \\
    \end{bmatrix}.
    $$
  }
\end{homeworkProblem}

\pagebreak

\begin{homeworkProblem}
  \emph{Let $A$ be the skew-symmetric matrix
    $$ A =
    \begin{bmatrix}
      0 & 1 \\
      -1 & 0 \\
    \end{bmatrix}
    \times I_{n/2},$$
    that is an $n \times n$ block diagonal matrix with $ 2 \times 2$ blocks.
    \begin{enumerate}
    \item Show A is normal
    \item Is A positive definite? Explain your reason.
    \item Can you use CGS to compute the solution of $Ax=b$, where $b$
      is the first unit vector (the first element is one and others are
      zero)? If yes, how many iterations will it be convergent, if not
      why.
    \end{enumerate}
  }

  \paragraph{a. Is $A$ normal?}

  The square matrix $A$ is a $n \times n$ block-diagonal matrix with
  $2 \times 2$ blocks. It is normal as $AA^T = A^TA$. We can easily
  see that $AA^T = A^TA = I_{n\times n}$, for $n = 2, 4 \ldots$.

  \paragraph{b. Positive definite?}

  The matrix is not positive-definite. Consider an arbitrary non-zero
  vector $x = [1 1]^T$ and compute $x^TAx$ which turns out to be
  zero. Therefore the matrix is not positive definite.

  \paragraph{c. Convergence}
  The eigenvalues are $\pm i$. The singular values of $A$ are 1 (of
  multiplicity $n$).  The convergence of CGNE depends only on the
  singular values of $A$ (not on the eigenvalues of $A$).  It
  converges in \underline{one step} if all the singular values of A
  are equal, which is true in this case. Thus it is ideal to use CGNE
  for this problem.

\end{homeworkProblem}

\pagebreak

\begin{homeworkProblem}
  \emph{Write your code of CGNE to solve two $n \times n$ linear
    systems $Ax=b$ and $By=b$ where
    $$
    A =
    \begin{bmatrix}
      0  & 1  &  0  &  \ldots  & 1 \\
      0  & 0  &  1  &  \ldots  & 0 \\
      \vdots  & \vdots & \vdots & \ddots & \vdots \\
      0  & 0  &  0  &  \ldots  & 1 \\
      1  & 0  &  0  &  \ldots  & 0 \\
    \end{bmatrix},
    B =
    \begin{bmatrix}
      M_1  &      &     &   &  \\
      & M_2  &     &   &  \\
      &  & \ddots  \\
      &  &  & M_{n/2}
    \end{bmatrix},
    b =
    \begin{bmatrix}
      1 \\
      0 \\
      \vdots \\
      0 \\
    \end{bmatrix},
    $$ and $x^{(0)} = 0$.  In $M_i$ in $B$ is a $ 2 \times 2$ block
    matrix given by
    $$
    M_j =
    \begin{bmatrix}
      1  & j-1 \\
      0  & 1 \\
    \end{bmatrix}.
    $$ Compute the solution with $n = 1000$. Comment on your results.
  }

  \paragraph{Solution:}~\smallskip

  \begin{table}[H]
    \caption{CGNE/\textbf{CGNR} with \underline{$x^{0}=0$} and tolerance of $10^{-8}$.} \medskip
    \centering
    \begin{tabular}{c|c|c}
      \toprule
      case   &  $Ax=b$  & $By=b$ \\
      \midrule
      solution & $x=[0,1,0,\ldots,0]^T$ & $y=[1,0,0,\ldots,0]^T$ \\
      number of iterations & 2/\textbf{2} & 1/\textbf{1} \\
      \bottomrule
    \end{tabular}
    \label{tab:summary1}
  \end{table}

  \begin{minipage}{\textwidth}
    \begin{table}[H]
      \caption{CGNE/\textbf{CGNR} with \underline{$x^{0}=10^{-2}$} and tolerance of $10^{-8}$.} \medskip
      \centering
      \begin{tabular}{c|c|c}
        \toprule case & $Ax=b$ & $By=b$ \\ \midrule
        solution\footnote{I have replaced very small entries in the
          solution vector close to zero with 0 for cleaner
          presentation.}  & $x=[0,1,0,\ldots,0]^T$ &
        $y=[1,0,0,\ldots,0]^T$ \\ number of iterations & 3/\textbf{3} & 46417/\textbf{45055}
        \\ \bottomrule
      \end{tabular}
      \label{tab:summary2}
    \end{table}
  \end{minipage}

\begin{itemize}
\item As it can be seen from Table~\ref{tab:summary1} and
  Table~\ref{tab:summary2}, the CGNE (and also CGNR) method takes just
  a few iterations (2 or 3) to converge to the solution for the first
  linear system $Ax=b$. This is due to the nature of the singular
  values of the system $A$, reflecting in terms of convergence.  For
  $Ax=b$ the range of singular values are $[0.618,1.618]$, which is
  narrow and therefore better convergence.

\item For the second linear system $By=b$, we encounter an encounter
  an interesting scenario where it takes just one iteration to
  converge as shown in the first Table~\ref{tab:summary1}. This has
  happened only because we picked the $x^{0} = 0 \rightarrow r^0 = b -
  A (0) = b$ as the initial guess and the iteration stopped right
  away. However, this lucky choice of initial guess is not to be
  mistaken for the convergence properties of CGNE/CGNR. This becomes
  evident with another intial vector $x^{0}$ as shown in
  Table~\ref{tab:summary2}, where it takes substantially more
  iterations for these methods to converge to the specified tolerance.
  The eigenvalues are of $B$ are all just 1's (1000 in multiplicity).
  The distribution of singular values is in a wider range of
  $[2\times10^{-3}, 500]$ theoretically. As noted in the previous
  problem, the singular values of the matrix $B$ drives the
  convergence of the CGNE/CGNR method. The actual singular matrix of
  the values of the $1000 \times 1000$ matrix is calculated to have
  the range $[2 \times 10^{-3}, 499.0]$ verifying the theoretical
  estimates. This wide spread of the singular values affects
  convergence.

\item CGNE and CGNR exhibit similar performances
\end{itemize}

\end{homeworkProblem}

\end{document}


% LaTeX source for ``Python for Informatics: Exploring Information''
% Copyright (c)  2010-  Charles R. Severance, All Rights Reserved

\chapter{Strings}
\label{strings}

\section{A string is a sequence}
\index{sequence}
\index{character}
\index{bracket operator}
\index{operator!bracket}

A string is a {\bf sequence} of characters.
You can access the characters one at a time with the
bracket operator:

\beforeverb
\begin{verbatim}
>>> fruit = 'banana'
>>> letter = fruit[1]
\end{verbatim}
\afterverb
%
\index{index}
The second statement extracts the character at index position 1 from the
{\tt fruit} variable and assigns it to the {\tt letter} variable.

The expression in brackets is called an {\bf index}.
The index indicates which character in the sequence you
want (hence the name).

But you might not get what you expect:

\beforeverb
\begin{verbatim}
>>> print letter
a
\end{verbatim}
\afterverb
%
For most people, the first letter of \verb"'banana'" is {\tt b}, not
{\tt a}.  But in Python, the index is an offset from the
beginning of the string, and the offset of the first letter is zero.

\beforeverb
\begin{verbatim}
>>> letter = fruit[0]
>>> print letter
b
\end{verbatim}
\afterverb
%
So {\tt b} is the 0th letter (``zero-eth'') of \verb"'banana'", {\tt a}
is the 1th letter (``one-eth''), and {\tt n} is the 2th (``two-eth'')
letter.

\beforefig
\centerline{\includegraphics[height=0.50in]{figs2/string.eps}}
\afterfig

\index{index!starting at zero}
\index{zero, index starting at}

You can use any expression, including variables and operators, as an
index, but the value of the index has to be an integer.  Otherwise you
get:

\index{index}
\index{exception!TypeError}
\index{TypeError}

\beforeverb
\begin{verbatim}
>>> letter = fruit[1.5]
TypeError: string indices must be integers
\end{verbatim}
\afterverb
%

\section{Getting the length of a string using {\tt len}}

\index{len function}
\index{function!len}

{\tt len} is a built-in function that returns the number of characters
in a string:

\beforeverb
\begin{verbatim}
>>> fruit = 'banana'
>>> len(fruit)
6
\end{verbatim}
\afterverb
%
To get the last letter of a string, you might be tempted to try something
like this:

\index{exception!IndexError}
\index{IndexError}

\beforeverb
\begin{verbatim}
>>> length = len(fruit)
>>> last = fruit[length]
IndexError: string index out of range
\end{verbatim}
\afterverb
%
The reason for the {\tt IndexError} is that there is no letter in {\tt
'banana'} with the index 6.  Since we started counting at zero, the
six letters are numbered 0 to 5.  To get the last character, you have
to subtract 1 from {\tt length}:

\beforeverb
\begin{verbatim}
>>> last = fruit[length-1]
>>> print last
a
\end{verbatim}
\afterverb
%
Alternatively, you can use negative indices, which count backward from
the end of the string.  The expression {\tt fruit[-1]} yields the last
letter, {\tt fruit[-2]} yields the second to last, and so on.

\index{index!negative}
\index{negative index}

\section{Traversal through a string with a loop}
\label{for}

\index{traversal}
\index{loop!traversal}
\index{for loop}
\index{loop!for}
\index{statement!for}
\index{traversal}

A lot of computations involve processing a string one character at a
time.  Often they start at the beginning, select each character in
turn, do something to it, and continue until the end.  This pattern of
processing is called a {\bf traversal}.  One way to write a traversal
is with a {\tt while} loop:

\beforeverb
\begin{verbatim}
index = 0
while index < len(fruit):
    letter = fruit[index]
    print letter
    index = index + 1
\end{verbatim}
\afterverb
%
This loop traverses the string and displays each letter on a line by
itself.  The loop condition is {\tt index < len(fruit)}, so
when {\tt index} is equal to the length of the string, the
condition is false, and the body of the loop is not executed.  The
last character accessed is the one with the index {\tt len(fruit)-1},
which is the last character in the string.

\begin{ex}
Write a {\tt while} loop that starts at the last character in the string
and works its way backwards to the first character in the string,
printing each letter on a separate line, except backwards.
\end{ex}

Another way to write a traversal is with a {\tt for} loop:

\beforeverb
\begin{verbatim}
for char in fruit:
    print char
\end{verbatim}
\afterverb
%
Each time through the loop, the next character in the string is assigned
to the variable {\tt char}.  The loop continues until no characters are
left.

\section{String slices}
\label{slice}

\index{slice operator}
\index{operator!slice}
\index{index!slice}
\index{string!slice}
\index{slice!string}

A segment of a string is called a {\bf slice}.  Selecting a slice is
similar to selecting a character:

\beforeverb
\begin{verbatim}
>>> s = 'Monty Python'
>>> print s[0:5]
Monty
>>> print s[6:12]
Python
\end{verbatim}
\afterverb
%
The operator {\tt [n:m]} returns the part of the string from the
``n-eth'' character to the ``m-eth'' character, including the first but
excluding the last.

If you omit the first index (before the colon), the slice starts at
the beginning of the string.  If you omit the second index, the slice
goes to the end of the string:

\beforeverb
\begin{verbatim}
>>> fruit = 'banana'
>>> fruit[:3]
'ban'
>>> fruit[3:]
'ana'
\end{verbatim}
\afterverb
%
If the first index is greater than or equal to the second the result
is an {\bf empty string}, represented by two quotation marks:

\index{quotation mark}

\beforeverb
\begin{verbatim}
>>> fruit = 'banana'
>>> fruit[3:3]
''
\end{verbatim}
\afterverb
%
An empty string contains no characters and has length 0, but other
than that, it is the same as any other string.

\begin{ex}
Given that {\tt fruit} is a string, what does
{\tt fruit[:]} mean?

\index{copy!slice}
\index{slice!copy}

\end{ex}

\section{Strings are immutable}
\index{mutability}
\index{immutability}
\index{string!immutable}

It is tempting to use the {\tt []} operator on the left side of an
assignment, with the intention of changing a character in a string.
For example:

\index{TypeError}
\index{exception!TypeError}

\beforeverb
\begin{verbatim}
>>> greeting = 'Hello, world!'
>>> greeting[0] = 'J'
TypeError: object does not support item assignment
\end{verbatim}
\afterverb
%
The ``object'' in this case is the string and the ``item'' is
the character you tried to assign.  For now, an {\bf object} is
the same thing as a value, but we will refine that definition
later.  An {\bf item} is one of the values in a sequence.

\index{object}
\index{item assignment}
\index{assignment!item}
\index{immutability}

The reason for the error is that
strings are {\bf immutable}, which means you can't change an
existing string.  The best you can do is create a new string
that is a variation on the original:

\beforeverb
\begin{verbatim}
>>> greeting = 'Hello, world!'
>>> new_greeting = 'J' + greeting[1:]
>>> print new_greeting
Jello, world!
\end{verbatim}
\afterverb
%
This example concatenates a new first letter onto
a slice of {\tt greeting}.  It has no effect on
the original string.

\index{concatenation}

\section{Looping and counting}
\label{counter}

\index{counter}
\index{counting and looping}
\index{looping and counting}
\index{looping!with strings}

The following program counts the number of times the letter {\tt a}
appears in a string:

\beforeverb
\begin{verbatim}
word = 'banana'
count = 0
for letter in word:
    if letter == 'a':
        count = count + 1
print count
\end{verbatim}
\afterverb
%
This program demonstrates another pattern of computation called a {\bf
counter}.  The variable {\tt count} is initialized to 0 and then
incremented each time an {\tt a} is found.
When the loop exits, {\tt count}
contains the result---the total number of {\tt a}'s.

\begin{ex}
\index{encapsulation}

Encapsulate this code in a function named {\tt
count}, and generalize it so that it accepts the string and the
letter as arguments.
\end{ex}

\section{The {\tt in} operator}
\label{inboth}

\index{in operator}
\index{operator!in}
\index{boolean operator}
\index{operator!boolean}

The word {\tt in} is a boolean operator that takes two strings and
returns {\tt True} if the first appears as a substring in the second:

\beforeverb
\begin{verbatim}
>>> 'a' in 'banana'
True
>>> 'seed' in 'banana'
False
\end{verbatim}
\afterverb
%

\section{String comparison}

\index{string!comparison}
\index{comparison!string}

The comparison operators work on strings.  To see if two strings are equal:

\beforeverb
\begin{verbatim}
if word == 'banana':
    print  'All right, bananas.'
\end{verbatim}
\afterverb
%
Other comparison operations are useful for putting words in alphabetical
order:

\beforeverb
\begin{verbatim}
if word < 'banana':
    print 'Your word,' + word + ', comes before banana.'
elif word > 'banana':
    print 'Your word,' + word + ', comes after banana.'
else:
    print 'All right, bananas.'
\end{verbatim}
\afterverb
%
Python does not handle uppercase and lowercase letters the same way
that people do.  All the uppercase letters come before all the
lowercase letters, so:

\beforeverb
\begin{verbatim}
Your word, Pineapple, comes before banana.
\end{verbatim}
\afterverb
%
A common way to address this problem is to convert strings to a
standard format, such as all lowercase, before performing the
comparison.  Keep that in mind in case you have to defend yourself
against a man armed with a Pineapple.

\section{{\tt string} methods}

Strings are an example of Python {\bf objects}.  An object contains
both data (the actual string itself) and {\bf methods}, which
are effectively functions that are built into the object and
are available to any {\bf instance} of the object.

Python has a function called {\tt dir} which lists the methods available
for an object.  The {\tt type} function shows the type of an object
and the {\tt dir} function shows the available methods.

\beforeverb
\begin{verbatim}
>>> stuff = 'Hello world'
>>> type(stuff)
<type 'str'>
>>> dir(stuff)
['capitalize', 'center', 'count', 'decode', 'encode',
'endswith', 'expandtabs', 'find', 'format', 'index',
'isalnum', 'isalpha', 'isdigit', 'islower', 'isspace',
'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip',
'partition', 'replace', 'rfind', 'rindex', 'rjust',
'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines',
'startswith', 'strip', 'swapcase', 'title', 'translate',
'upper', 'zfill']
>>> help(str.capitalize)
Help on method_descriptor:

capitalize(...)
    S.capitalize() -> string

    Return a copy of the string S with only its first character
    capitalized.
>>>
\end{verbatim}
\afterverb
%

While the {\tt dir} function lists the methods, and you
can use {\tt help} to get some simple documentation on a method,
a better source of documentation for string methods would be
\url{https://docs.python.org/2/library/stdtypes.html#string-methods}.

Calling a {\bf method} is similar to calling a function---it
takes arguments and returns a value---but the syntax is different.
We call a method by appending the method name to the variable name
using the period as a delimiter.

For example, the
method {\tt upper} takes a string and returns a new string with
all uppercase letters:

\index{method}
\index{string!method}

Instead of the function syntax {\tt upper(word)}, it uses
the method syntax {\tt word.upper()}.

\index{dot notation}

\beforeverb
\begin{verbatim}
>>> word = 'banana'
>>> new_word = word.upper()
>>> print new_word
BANANA
\end{verbatim}
\afterverb
%
This form of dot notation specifies the name of the method, {\tt
upper}, and the name of the string to apply the method to, {\tt
word}.  The empty parentheses indicate that this method takes no
argument.

\index{parentheses!empty}

A method call is called an {\bf invocation}; in this case, we would
say that we are invoking {\tt upper} on the {\tt word}.

\index{invocation}

For example, there is a string method named {\tt find} that
searches for the position of one string within another:

\beforeverb
\begin{verbatim}
>>> word = 'banana'
>>> index = word.find('a')
>>> print index
1
\end{verbatim}
\afterverb
%
In this example, we invoke {\tt find} on {\tt word} and pass
the letter we are looking for as a parameter.

The {\tt find} method can find substrings as well as characters:

\beforeverb
\begin{verbatim}
>>> word.find('na')
2
\end{verbatim}
\afterverb
%
It can take as a second argument the index where it should start:

\index{optional argument}
\index{argument!optional}

\beforeverb
\begin{verbatim}
>>> word.find('na', 3)
4
\end{verbatim}
\afterverb
%
One common task is to remove white space (spaces, tabs, or newlines) from
the beginning and end of a string using the {\tt strip} method:

\beforeverb
\begin{verbatim}
>>> line = '  Here we go  '
>>> line.strip()
'Here we go'
\end{verbatim}
\afterverb
%
Some methods such as {\bf startswith} return boolean values.

\beforeverb
\begin{verbatim}
>>> line = 'Please have a nice day'
>>> line.startswith('Please')
True
>>> line.startswith('p')
False
\end{verbatim}
\afterverb
%
You will note that {\tt startswith} requires case to match, so sometimes
we take a line and map it all to lowercase before we do any checking
using the {\tt lower} method.

\beforeverb
\begin{verbatim}
>>> line = 'Please have a nice day'
>>> line.startswith('p')
False
>>> line.lower()
'please have a nice day'
>>> line.lower().startswith('p')
True
\end{verbatim}
\afterverb
%
In the last example, the method {\tt lower} is called
and then we use {\tt startswith}
to see if the resulting lowercase string
starts with the letter ``p''.  As long as we are careful
with the order, we can make multiple method calls in a
single expression.

\begin{ex}
\index{count method}
\index{method!count}

There is a string method called {\tt count} that is similar
to the function in the previous exercise.  Read the documentation
of this method at
\url{https://docs.python.org/2/library/stdtypes.html#string-methods}
and write an invocation that counts the number of times the
letter a  occurs
in \verb"'banana'".
\end{ex}

\section{Parsing strings}

Often, we want to look into a string and find a substring.  For example
if we were presented a series of lines formatted as follows:

\beforeverb
\begin{alltt}
From stephen.marquard@{\bf uct.ac.za} Sat Jan  5 09:14:16 2008
\end{alltt}
\afterverb

and we wanted to pull out only the second half of the address (i.e.,
{\tt uct.ac.za}) from each line, we can do this by using the {\tt find}
method and string slicing.

First, we will find the position of the at-sign in the string.  Then we will
find the position of the first space \emph{after} the at-sign.  And then we
will use string slicing to extract the portion of the string which we
are looking for.

\beforeverb
\begin{verbatim}
>>> data = 'From stephen.marquard@uct.ac.za Sat Jan  5 09:14:16 2008'
>>> atpos = data.find('@')
>>> print atpos
21
>>> sppos = data.find(' ',atpos)
>>> print sppos
31
>>> host = data[atpos+1:sppos]
>>> print host
uct.ac.za
>>>
\end{verbatim}
\afterverb
%
We use a version of the {\tt find} method which allows us to specify
a position in the string where we want {\tt find} to start looking.
When we slice, we extract the characters
from ``one beyond the at-sign through up to \emph{but not including} the
space character''.

The documentation for the {\tt find} method is available at
\url{https://docs.python.org/2/library/stdtypes.html#string-methods}.

\section{Format operator}

\index{format operator}
\index{operator!format}

The {\bf format operator}, {\tt \%}
allows us to construct strings, replacing parts of the strings
with the data stored in variables.
When applied to integers, {\tt \%} is the modulus operator.  But
when the first operand is a string, {\tt \%} is the format operator.

\index{format string}

The first operand is the {\bf format string}, which contains
one or more {\bf format sequences} that specify how
the second operand is formatted.  The result is a string.

\index{format sequence}

For example, the format sequence \verb"'%d'" means that
the second operand should be formatted as an
integer ({\tt d} stands for ``decimal''):

\beforeverb
\begin{verbatim}
>>> camels = 42
>>> '%d' % camels
'42'
\end{verbatim}
\afterverb
%
The result is the string \verb"'42'", which is not to be confused
with the integer value {\tt 42}.

A format sequence can appear anywhere in the string,
so you can embed a value in a sentence:

\beforeverb
\begin{verbatim}
>>> camels = 42
>>> 'I have spotted %d camels.' % camels
'I have spotted 42 camels.'
\end{verbatim}
\afterverb
%
If there is more than one format sequence in the string,
the second argument has to be a tuple\footnote{A tuple is a
sequence of comma-separated values inside a pair of parenthesis.
We will cover tuples in Chapter 10}.  Each format sequence is
matched with an element of the tuple, in order.

The following example uses \verb"'%d'" to format an integer,
\verb"'%g'" to format
a floating-point number (don't ask why), and \verb"'%s'" to format
a string:

\beforeverb
\begin{verbatim}
>>> 'In %d years I have spotted %g %s.' % (3, 0.1, 'camels')
'In 3 years I have spotted 0.1 camels.'
\end{verbatim}
\afterverb
%
The number of elements in the tuple must match the number
of format sequences in the string.  The types of the
elements also must match the format sequences:

\index{exception!TypeError}
\index{TypeError}

\beforeverb
\begin{verbatim}
>>> '%d %d %d' % (1, 2)
TypeError: not enough arguments for format string
>>> '%d' % 'dollars'
TypeError: illegal argument type for built-in operation
\end{verbatim}
\afterverb
%
In the first example, there aren't enough elements; in the
second, the element is the wrong type.

The format operator is powerful, but it can be difficult to use.  You
can read more about it at
\url{https://docs.python.org/2/library/stdtypes.html#string-formatting}.

% You can specify the number of digits as part of the format sequence.
% For example, the sequence \verb"'%8.2f'"
% formats a floating-point number to be 8 characters long, with
% 2 digits after the decimal point:

% \beforeverb
% \begin{verbatim}
% >>> '%8.2f' % 3.14159
% '    3.14'
% \end{verbatim}
% \afterverb
% %
% The result takes up eight spaces with two
% digits after the decimal point.

\section{Debugging}
\index{debugging}

A skill that you should cultivate as you program is always
asking yourself, ``What could go wrong here?'' or alternatively,
``What crazy thing might our user do to crash our (seemingly)
perfect program?''

For example, look at the program which we used to demonstrate
the {\tt while} loop in the chapter on iteration:

\beforeverb
\begin{verbatim}
while True:
    line = raw_input('> ')
    if line[0] == '#' :
        continue
    if line == 'done':
        break
    print line

print 'Done!'
\end{verbatim}
\afterverb
%
Look what happens when the user enters an empty line of input:

\beforeverb
\begin{verbatim}
> hello there
hello there
> # don't print this
> print this!
print this!
>
Traceback (most recent call last):
  File "copytildone.py", line 3, in <module>
    if line[0] == '#' :
\end{verbatim}
\afterverb
%
The code works fine until it is presented an empty line.  Then
there is no zero-th character, so we get a traceback.  There are two
solutions to this to make line three ``safe'' even if the line is
empty.

One possibility is to simply use the {\tt startswith} method
which returns {\tt False} if the string is empty.

\beforeverb
\begin{verbatim}
    if line.startswith('#') :
\end{verbatim}
\afterverb
%
\index{guardian pattern}
\index{pattern!guardian}
Another way is to safely write the {\tt if} statement using the {\bf guardian}
pattern and make sure the second logical expression is evaluated
only where there is at least one character in the string.:

\beforeverb
\begin{verbatim}
    if len(line) > 0 and line[0] == '#' :
\end{verbatim}
\afterverb
%

\section{Glossary}

\begin{description}

\item[counter:] A variable used to count something, usually initialized
to zero and then incremented.
\index{counter}

\item[empty string:] A string with no characters and length 0, represented
by two quotation marks.
\index{empty string}

\item[format operator:] An operator, {\tt \%}, that takes a format
string and a tuple and generates a string that includes
the elements of the tuple formatted as specified by the format string.
\index{format operator}
\index{operator!format}

\item[format sequence:] A sequence of characters in a format string,
like {\tt \%d}, that specifies how a value should be formatted.
\index{format sequence}

\item[format string:] A string, used with the format operator, that
contains format sequences.
\index{format string}

\item[flag:] A boolean variable used to indicate whether a condition
is true.
\index{flag}

\item[invocation:] A statement that calls a method.
\index{invocation}

\item[immutable:] The property of a sequence whose items cannot
be assigned.
\index{immutability}

\item[index:] An integer value used to select an item in
a sequence, such as a character in a string.
\index{index}

\item[item:] One of the values in a sequence.
\index{item}

\item[method:] A function that is associated with an object and called
using dot notation.
\index{method}

\item[object:] Something a variable can refer to.  For now,
you can use ``object'' and ``value'' interchangeably.
\index{object}

\item[search:] A pattern of traversal that stops
when it finds what it is looking for.
\index{search pattern}
\index{pattern!search}

\item[sequence:] An ordered set; that is, a set of
values where each value is identified by an integer index.
\index{sequence}

\item[slice:] A part of a string specified by a range of indices.
\index{slice}

\item[traverse:] To iterate through the items in a sequence,
performing a similar operation on each.
\index{traversal}

\end{description}

\section{Exercises}

\begin{ex}
Take the following Python code that stores a string:`

\beforeverb
\begin{alltt}
str = 'X-DSPAM-Confidence: {\bf 0.8475}'
\end{alltt}
\afterverb

Use {\tt find} and string slicing to extract the portion
of the string after the colon character and then use the
{\tt float} function to convert the extracted string
into a floating point number.

\end{ex}

\begin{ex}
\index{string method}
\index{method!string}

Read the documentation of the string methods at
\url{https://docs.python.org/2/library/stdtypes.html#string-methods}.
You might want to experiment with some of them to make sure
you understand how they work.  {\tt strip} and
{\tt replace} are particularly useful.

The documentation uses a syntax that might be confusing.
For example, in \verb"find(sub[, start[, end]])", the brackets
indicate optional arguments.  So {\tt sub} is required, but
{\tt start} is optional, and if you include {\tt start},
then {\tt end} is optional.
\end{ex}