\section{Preface}

Sequence analysis is one of the major subjects of bioinformatics. Several existing libraries combine the representation of biological sequences with exact and approximate pattern matching as well as alignment algorithms. We present Jstacs, an open source Java library, which focuses on the statistical analysis of biological sequences instead. Jstacs comprises an efficient representation of sequence data and provides implementations of many statistical models with generative and discriminative approaches for parameter learning. Using Jstacs, classifiers can be assessed and compared on test datasets or by cross-validation experiments evaluating several performance measures. Due to its strictly object-oriented design Jstacs is easy to use and readily extensible.

Jstacs is a joint project of the groups \href{http://www.informatik.uni-halle.de/arbeitsgruppen/bioinformatik/}{Bioinformatics} and \href{http://www.informatik.uni-halle.de/arbeitsgruppen/mustererkennung/}{Pattern Recognition and Bioinformatics} at the \href{http://www.informatik.uni-halle.de/}{Institute of Computer Science} of \href{http://www.uni-halle.de/}{Martin Luther University Halle-Wittenberg} and the \href{http://dig.ipk-gatersleben.de/}{Research Group Data Inspection} at the \href{http://www.ipk-gatersleben.de/}{Leibniz Institute of Plant Genetics and Crop Plant Research}.

Jstacs is listed in the \href{http://mloss.org/software/}{machine learning open-source software (mloss)} repository.

The complete API documentation can be found at \url{\APIhome}.

\subsection{General structure of Jstacs}

A coarse view on the structure of Jstacs is presented in Figure~\ref{fig:classes}.
Being a library for statistical analysis and classification of sequence data, Jstacs is organized around the abstract class \AbstractClassifier, the interface \StatMod~and its two sub-interfaces \TrainSM, and \DiffSM.

\begin{figure}
\input{classes.tex}
\caption{Part of the class structure of Jstacs. Interfaces are depicted in red, abstract classes in blue, concrete classes in green, and enums in orange. Continuous transitions represent inheritance, whereas arrows represent usage. \label{fig:classes}}
\end{figure}

\StatMod s represent statistical models in general, which can compute the log-likelihood of a given input sequence and define prior densities on their parameters. The abstract implementation \AbstractTrainSM~of \TrainSM is the base class of many generatively learned models such as Bayesian networks, hidden Markov models, or mixture models, and can be learned from a single input data set. In constrast, \DiffSM s provide all facilities for numerical optimization of parameters, which is especially necessary for discriminative parameter learning. The abstract base class of all \DiffSM~implementations is \AbstractDiffSM. Currently, \DiffSM s include Bayesian networks, Markov models, a ZOOPS model, and mixture models.

\AbstractClassifier~defines the general properties of a classifier. Its sub-class \AbstractScoreBasedClassifier~adds additional methods for the classification of sequences based on a sequence and class-specific score.
Two concrete sub-classes of \AbstractScoreBasedClassifier~are the \TrainSMBasedClassifier, which works on \TrainSM s, and the \GenDisMixClassifier, which works on \DiffSM.

\AbstractClassifier s can be assessed either on dedicated training and test data sets or in \ClassifierAssessment s like \KFoldCrossValidation~or \RepeatedHoldOutExperiment. The performance measures used in such an assessment are collected in \PerformanceMeasureParameterSet s containing sub-classes of the abstract class \AbstractPerformanceMeasure.

A more detailed view on all of these classes will be given in the remainder of this cookbook.

\subsection{About this cookbook}

This document is not a cookbook in the sense of a collection of recipes. The intention of this cookbook is rather to learn how to cook with the ingredients and tools provided by Jstacs.

Nonetheless, we present a collection of recipes in the last section, where you find the code of executable code examples that can also be downloaded \href{http://www.jstacs.de/downloads/recipes.zip}{as a zip file}.

We are aware that a library of this size seems daunting on first sight -- and on second sight as well. However, we hope that despite the inevitable complexity and size of such a library, this cookbook may help to get a picture of the structure, design principles, and capabilities of Jstacs.

This cookbook is structured as follows: in the section ``\nameref{data}'', we explain how data are represented in Jstacs, and how you can read data from files. 

In section ``\nameref{sec:xmlparres}'', we present some facilities, an XML parser and the representation of parameters and results, that are used frequently within Jstacs and are necessary for the following parts. 

In section ``\nameref{sequenceScore}'', we present sequence scores, statistical models, and their sub-interfaces and sub-classes. We explain the methods defined in these interfaces and classes, and we show how you can create and use their existing implementations.

In section ``\nameref{classifier}'', we explain classifiers and assessment of classifiers using different performance measures.

In section ``\nameref{Optimization}'', we present the facilities for numerical optimization.

In section ``\nameref{goodies}'', we list utility classes and methods, that we think might be of help for your own implementations.

Finally, in section ``\nameref{recipes}'', we give a number of executable code examples that may serve as a starting point of your own classes and applications.
