%% LyX 2.0.3 created this file.  For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[10pt,english]{scrartcl}
\usepackage{lmodern}
\renewcommand{\sfdefault}{lmss}
\renewcommand{\ttdefault}{lmtt}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{listings}
\usepackage[letterpaper]{geometry}
\geometry{verbose,tmargin=1in,bmargin=1in,lmargin=1in,rmargin=1in}
\setlength{\parskip}{\medskipamount}
\setlength{\parindent}{0pt}
\usepackage{color}
\usepackage{array}
\usepackage{float}
\usepackage{calc}
\usepackage{graphicx}
\usepackage{esint}
\usepackage[authoryear]{natbib}

\makeatletter

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands.
\providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
%% Because html converters don't know tabularnewline
\providecommand{\tabularnewline}{\\}
%% A simple dot to overcome graphicx limitations
\newcommand{\lyxdot}{.}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands.
\newcommand{\code}[1]{\texttt{#1}}

\@ifundefined{date}{}{\date{}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands.
\usepackage{multicol}

\usepackage{graphicx}
\usepackage{listings}

\usepackage{color}
\lstset{tabsize=2, breaklines=true, 
  breakatwhitespace=true,
  language=R,
  captionpos=b,
  frame=single,
  framerule=0.2pt,
  framesep=1pt,
  numbers=left,
  numberstyle=\tiny,
  numbersep=5pt,
  showstringspaces=false,
  basicstyle=\footnotesize,
  identifierstyle=\color{magenta},
  keywordstyle=\bfseries,
  commentstyle=\color{darkgreen},
  stringstyle=\color{red},
  backgroundcolor=\color[gray]{0.935}
}

\makeatother

\usepackage{babel}
\begin{document}
\title{}

\noindent %
\begin{tabular}{|>{\centering}p{1.6in}>{\centering}p{3in}>{\centering}p{1.2in}|}
\hline 
\begin{minipage}[c]{1.5in}%
\noindent \begin{center}
\vspace{0pt}\textsc{\Huge \includegraphics[width=1in]{jayhawk}}
\par\end{center}{\Huge \par}

\noindent \begin{center}
http://quant.ku.edu
\par\end{center}%
\end{minipage} & %
\begin{minipage}[c]{2.5in}%
\noindent \begin{center}
\vspace{0pt}\textsc{\Huge }%
\begin{minipage}[t]{1\columnwidth}%
\noindent \begin{center}
\textsc{\Huge KU}\textsc{\huge ant Guides}
\par\end{center}{\huge \par}

\noindent \rule[0.5ex]{1\linewidth}{1pt}%
\end{minipage}
\par\end{center}{\Huge \par}

{\large A Template for KUant Guides written with \LaTeX{}}{\large \par}

\bigskip{}


{\large Johnson, Paul E.}\\
{\large{} }<pauljohn@ku.edu>

\bigskip{}
%
\end{minipage} & %
\framebox{\begin{minipage}[b][1\totalheight][c]{1in}%
\noindent \begin{center}
\vspace{0pt}Guide No.
\par\end{center}

\noindent \begin{center}
XXXX
\par\end{center}%
\end{minipage}}\tabularnewline
\hline 
\end{tabular}

This is abstract of the template \LaTeX{} document for the preparation
of KUant Guides (http://quant.ku.edu). The abstract should include
a general explanation of the guide's topic. 

This template is prepared as a \LyX{} document, KUant-template.lyx,
but it is not necessary to use \LyX{} if one wants to create a \LaTeX{}
document. One can export a \LaTeX{} document from \LyX{}, and so \LaTeX{}
users who prefer to write in ``pure, clean, authentic, and more-virtuous''
\LaTeX{} can do so. (Look for the file KUant-template.tex.)

The design of the ``top matter,'' the part above this abstract,
should not be changed by the author. The author should only see fit
to change
\begin{enumerate}
\item The title of the KUant Guide
\item The author's name \& email
\item The number of the KUant Guide
\end{enumerate}
This is the end of the abstract. The part after this is supposed to
be presented in two column format. 

\begin{multicols}{2}

A KUant Guide is a brief (less than 10 pages) illustration of software
usage for a particular task. 

The most difficult part of using \LaTeX{} to prepare KUant Guides
is that the style guideline requires a two column document. The two
column document is implemented here with the \LaTeX{} package multicol. 

The multicol package is easy to use, but the two column design worstens
a couple of problems that can arise in all \LaTeX{} documents. Simply
put, if the user writes a long equation (or inserts a large graphic),
the equation (or graphic) is not automatically resized to fit in the
column. A figure or an equation that is too large for the space will
``flow'' out of the column borders. That's a common \LaTeX{} problem,
but experienced users are aware of it and, when the document has only
one column, it is easier to navigate. 

A related problem is that floating figures, a staple of ordinary \LaTeX{}
document preparation, are not workable. One can insert a floating
figure in order to obtain a figure label and number, but the position
must not be allowed to float freely. The user should use the ``place
here definitely'' rubric to force the figure into place. 

It is not necessary to use floats for graphic images. A graphic image
can be inserted directly, but it is important for the author to make
sure that the graphic does fit within the space allowed by the column.
That can be done either by editing the graphic file so that its size
is small--say 3 inches or less--or by using the graphic sizing options
in the insert graphic option. A figure that is inserted into a floating
figure may not cause trouble. It should be automatically relocated
by \LaTeX{}.


\subsection*{Equations}

The issue with equations is maddening for all \LaTeX{} novices. After
preparing a beautiful, elaborate formula, the user is dismayed to
find that, in the pdf output, the equation overflows into the margins
and off the page. It is just a (frustrating) fact of life. \LaTeX{}
does not enforce line breaks within equations, so equations can run
off the edge of the page, or, in this case outside the edges of the
column. 

Short equations are going to come out fine, as in 
\begin{equation}
G[x]=\frac{1}{2\sqrt{N}}e^{2}dx.
\end{equation}


Authors who want longer equations must manually introduce line breaks. 

\begin{eqnarray}
F(p_{i}) & = & \int_{-\infty}^{\infty}G(x)dx+\\
 &  & \sum_{i=1}^{N}f(x_{i})\Gamma(k(m+1))+\nonumber \\
 &  & \left(\begin{array}{c}
17\\
9
\end{array}\right)p^{N}(1-p)^{N-k}\nonumber 
\end{eqnarray}


This is one of the few elements of \LaTeX{} that really goes against
the general \LaTeX{} philosophy of leaving the styling and formatting
of output to the \LaTeX{} engine and the publisher's preferred class
files.

What goes wrong if the user writes all of that on one line? The output
flows into the margin and over the edge. 
\begin{equation}
F(p_{i})=\int_{-\infty}^{\infty}G(x)dx+\sum_{i=1}^{N}f(x_{i})\Gamma(k(m+1))+\left(\begin{array}{c}
17\\
9
\end{array}\right)p^{N}(1-p)^{N-k}
\end{equation}


As far as I understand \LaTeX{}, this is an inherent problem (feature?
bug?) with displayed equations. \LaTeX{} lets them flow off the edge
of the paper. Authors must re-format long equations to fit within
the space allowed.


\subsection*{Graphics}

Now, suppose we want to insert a graphic? Ordinarily, in \LaTeX{}
documents, we would not insert graphics at a particular spot. Instead,
we would wrap the graphic inside floating figure environments. 

This is discussed in the \LyX{} User Documentation. Graphics can be
``stuck'' right here. If we don't use figure floats, what happens?
Suppose we have a 6 inch wide image of a jayhawk. We don't have to
manually shrink the image, we can re-scale it on the fly. \LyX{} has
a pull down Insert -> Graphics menus for that. In \LaTeX{}, the markup
would be something like:

\begin{lstlisting}[language={[LaTeX]TeX}]
\includegraphics[width=3in]{jayhawk}
\end{lstlisting}


We write ``jayhawk'' and the \LaTeX{} engine will choose among files
with names like jayhawk.png, jayhawk.eps or jayhawk.png. It does not
wrap it in a ``figure'' thing, it has no caption. There's no Figure
title, no Figure number. Its just a picture, that is pasted in right
here.

All good, as long as the image is small, say 3 inches wide, or less,
it fits inside the column.

\includegraphics[width=3in]{jayhawk}

\LaTeX{} won't stop us from inserting a graphic that does not fit.
If we insert a 4.5 inch wide image, it will flow off the edge, just
like the long equation did.

\includegraphics[width=4.5in]{jayhawk}

Thus authors are behooved to make sure that graphics inserted are
{\Large SMALL} (note my irony of making the word ``small'' large).

Why is that not good enough? Well, as explained in the documentation
for \LyX{}, inserting graphics without wrapping them inside ``figure
floats'' is considered somewhat gauche. We'd rather have a numbered
Figure, something we can refer to without saying ``in the picture
that was inserted two paragraphs ago...''

Unfortunately, ordinary figure or table floats will not work inside
multicolumn documents. The content of the figures just disappears
from the output. It is as if the \LaTeX{} processing system is saying
to us, ``that was such an amateurish thing to do, we are going to
treat it as a joke and ignore it.''

But all is not lost. Ordinary floating figures don't work correctly
inside columns, but we have \emph{two reasonable alternatives}. 
\begin{description}
\item [{Option~1.}] Insert a small figure float and tell \LaTeX{} to place
it ``here''. In the \LaTeX{} markup, that's the H placement option.
Some people say H means ``right here.'' Some say ``here definitely''. 
\end{description}
In \LyX{}, one can use the Insert -> Float -> Figure menu to create
the float. Then one inserts the graphic inside that object. Then right
click on the floating figure and choose the ``here definitely''
placement option. 

In raw \LaTeX{}, the markup that corresponds would be

\begin{lstlisting}[language={[LaTeX]TeX}]
\begin{figure}[H] 
\includegraphics[width=3in]{jayhawk}
\caption{"Here Definitely" Floating a Jayhawk\label{jayfig}}
\end{figure}
\end{lstlisting}


Note the capital H. That's the ``right here'' ``definitely'' ``I
really mean it, I'm not joking'' part. 

\begin{figure}[H]
\includegraphics[width=3in]{jayhawk}

\caption{``Here Definitely'' Floating Jayhawk\label{jayfig}}
\end{figure}


The magic H can work for figure floats that contain any kind of content,
as long as it is narrow enough to fit. \LyX{} has a dialogue to insert
various kinds of documents from various programs as ``external material.''
Here I demonstrate an XFig diagram and, because it is inserted in
a figure environment. This is in Figure \ref{fig:xfig}. The automatic
numbering is very convenient.

\begin{figure}[H]
\resizebox{3in}{!}{\input{concept1.pstex_t}}

\caption{An Xfig Drawing from External Material Dialogue\label{fig:xfig}}
\end{figure}


If we were writing this in raw \LaTeX{}, the markup for that figure
would be

\begin{lstlisting}[language={[LaTeX]TeX},tabsize=4]
\begin{figure}[H] 
\resizebox{3in}{!}{\input{concept1.pdftex_t}}
\caption{An Xfig Drawing from External Material Dialogue} 
\end{figure}
\end{lstlisting}

\begin{description}
\item [{Option~2.}] Use a special figure environment. This will allow
inclusion of large figures, but they will float down to appear on
a separate page, not in the 2 column format.
\end{description}
There is no \LyX{} menu for this special figure, it must be inserted
as raw \LaTeX{}. The only difference is that the environment is now
\code{figure{*}}, rather than \code{figure}.

\begin{figure*} 
\resizebox{6in}{!}{\input{concept1.pdf_t}}
\caption{A Figure* environment floats to another page\label{xfigstar}} 
\end{figure*}

Since that carries the label ``xfigstar'', we can refer to it and
obtain automatic numbering. For example, if we insert the crossreference
as \textbackslash{}ref\{xfigstar\}, we can urge the reader to look
at Figure \ref{xfigstar}.


\subsection*{Code Listings}

Finally some good news! There is a \LaTeX{} package called Listings
and it is extraordinarily customizable. Document-wide preferences
can be set in the document preamble, as I have done in this document.
Individual code listings can be adjusted, of course.

Computer code examples should be inserted within program listings
environments. Those environments WILL wrap long lines.
\begin{lstlisting}[basicstyle={\tiny},breaklines=true,linewidth={3.3in},tabsize=2]
x <- rnorm(100, m = 343, s = 232)
y <- rgamma(100, lamda = 534)
plot(x, y, xlab = "This is the x variable", ylab = "This is the y variable", xlim = c(0, 100), y = c(-100, 2000)
\end{lstlisting}


I fiddled it quite a bit, seems ok. The listings are almost infinitely
customizable. One can set the language, which draws in a pre-set collection
of choices, and then the style can be further customized (for, say,
R code input and R text output). There are pre-defined language settings
for R, SAS, and many other languages.


\section*{Conclusion}

By far, the most difficult part of this exercise is the two-column
design, which complicates the inclusion of equations and figures.
But, once one becomes aware of the issue (it was a complete surprise
to me), the problem can be managed.

I wanted to insert some bibliographic citations, so that future users
might have a fully working example. So, without further ado \citep{aitkin_general_1999},
and \citet[p. 57]{albert_bayesian_2007}, as well as others (\citealp{jackman_bayesian_2009,mccullagh_sampling_2008,mccullagh_generalized_1983}).

The other problem I need to work on is the usage of Sweave for R document
preparation. I'm not sure how well that will integrate into this format.

\bibliographystyle{apalike2}
\bibliography{Stats}


\end{multicols}
\end{document}
