[errorbar] finished?

plotting/lecture/plotting.tex

@@ -509,35 +509,84 @@ the error gives the reader the chance of assessing the reliability of
 the data and get a feeling of possible significance of a
 difference in the average values.
 
-\Matlab{} offers several ways to plot the average and the error. We
+\matlab{} offers several ways to plot the average and the error. We
 will introduce two possible ways.
 \begin{itemize}
-\item The \code[errorbar()]{errorbar} function (figure\,\ref{errorbarplot}).
+\item The \code[errorbar()]{errorbar} function (figure\,\ref{errorbarplot} A, B).
-\item Using the \code[{fill()]{fill} function to draw an area showing
+\item Using the \code[fill()]{fill} function to draw an area showing
-  the spread of the data (figure\,\ref{errorareaplot}).
+  the spread of the data (figure\,\ref{errorbarplot} C).
 \end{itemize}
 
 \subsubsection{Errorbar}
 
 Using the \code[errorbar()]{errorbar} function is rather straight
-forward. In its easiest form, it expects three arguments being the x- and y-values plus the
+forward. In its easiest form, it expects three arguments being the x-
-error.
+and y-values plus the error (line 5 in listing \ref{errorbarlisting},
+note that we provide additional optional arguments to set the
+marker). This form is obviously only suited for symmetric
+distributions. In case the values are symmetrically distributed, a
+separate error for positive and negative deflections from the mean are
+more apt. Accordingly, four arguments are needed (line 12 in listing
+\ref{errorbarlisting}). The first two arguments are the same, the next
+to represent the positive and negative deflections.
+
+By default the \code{errorbar} function does not draw a marker. In the
+examples shown here we provide extra arguments to define that a circle
+is used for that purpose. The line connecting the average values can
+be removed by passing additional arguments. The properties of the
+errorbars themselves (linestyle, linewidth, capsize, etc.) can be
+changed by taking the return argument of \code{errorbar} and changing
+its properties. See the \matlab{} help for more information.
 
 \begin{figure}[ht]
-  \includegraphics[]{} \titlecaption{Adding error bars to a line
+  \includegraphics[width=0.9\linewidth]{errorbars}
-    plot}{\textbf{A} symmetrical error around the mean (e.g. using the
+  \titlecaption{Adding error bars to a line plot}{\textbf{A}
-    standard deviation). \textbf{B} asymmetrical errors (e.g. the
+    symmetrical error around the mean (e.g.\ using the standard
-    lower and upper quartiles). \textbf{C} X- and Y-error. See
+    deviation). \textbf{B} Errorbars of an asymmetrical distribution
-    listing\,\ref{errorbarlisting}}\label{errrorbarplot}
+    of the data (note: the average value is now the median and the
+    errors are the lower and upper quartiles). \textbf{C} A shaded
+    area is used to illustrate the spread of the data. See
+    listing\,\ref{errorbarlisting}}\label{errorbarplot}
 \end{figure}
 
-
+\lstinputlisting[caption={Illustrating estimation errors. Script that
-\begin{figure}[ht]
+    creates \figref{errorbarplot}.},
-  \includegraphics[]{}
+  label=errorbarlisting, firstline=13, lastline=29,
-  \titlecaption{}\label{errrorareaplot}
+  basicstyle=\ttfamily\scriptsize]{errorbarplot.m}
-\end{figure}
+
-
+\subsubsection{Fill}
-
+For a few years now it has become fancy to illustrate the error not
+using errorbars but by drawing a shaded area around the mean. Beside
+their fancyness there is also a real argument in favor of using error
+areas instead of errorbars: In case you have a lot of data points with
+respective errorbars such that they would merge in the figure it is
+cleaner and probably easier to read and handle if one uses an error
+area instead.  To achieve an illustration as shown in
+figure\,\ref{errorbarplot} C, we use the \code{fill} command in
+combination with a standard line plot. The original purpose of
+\code{fill} is to draw a filled polygon. We hence have to provide it
+with the vertex points of the polygon. For each x-value we now have
+two y-values (average minus error and average plus error). Further, we
+want the vertices to be connected in a defined order. One can achieve
+this by going back and forth on the x-axis; we append a reversed
+version of the x-values to the original x-values using the \code{cat}
+and inversion is done using the \code{fliplr} command (line 3 in
+listing \ref{errorbarlisting2}; Depending on the layout of your data
+you may need concatenate along a different dimension of the data and
+use \code{flipud} instead). The y-coordinates of the polygon vertices
+are concatenated in a similar way (line 4). In the example shown here
+we accept the polygon object that is returned by fill (variable p) and
+use it to change a few properties of the polygon. The \emph{FaceAlpha}
+property defines the transparency (or rather the opaqueness) of the
+area. The provided alpha value is a number between 0 and 1 with zero
+leading to invisibility and a value of one to complete
+opaqueness. Finally, we use the normal plot command to draw a line
+connecting the average values.
+
+\lstinputlisting[caption={Illustrating estimation errors. Script that
+    creates \figref{errorbarplot}.}, label=errorbarlisting2,
+  firstline=30,
+  basicstyle=\ttfamily\scriptsize]{errorbarplot.m}
 
 \subsection{Annotations, text}