\documentclass[letterpaper,10pt,oneside]{article}

%\VignetteIndexEntry{Introduction to scaRabee}
%\VignettePackage{scaRabee}

% Load packages
\usepackage{Rd}
\usepackage{ucs}
\usepackage[latin1]{inputenc}
\usepackage{fontenc}
\usepackage{amsmath}    % need for subequations
\usepackage{amsfonts}
\usepackage{amssymb}
\usepackage{graphicx}   % need for figures
\usepackage{verbatim}   % useful for program listings
\usepackage{color}      % use if color is used in text
\usepackage[pdfborder={0 0 0}]{hyperref}   % use for hypertext links, including
                                           % those to external  documents and
                                           % URLs

% Page layout
\oddsidemargin 0.5in \evensidemargin 0.5in \textwidth 6in

% Defines some custom commands
%\newcommand{\code}[1]{\texttt{#1}}
%\newcommand{\pkg}[1]{\code{#1}}
%\newcommand{\R}{\code{R}}
\newcommand{\scaRabee}{\pkg{scaRabee}}
\newcommand{\Matlab}{Matlab\textsuperscript{\textregistered}}
%\newcommand{\email}[1]{\code{#1}}

%\VignetteIndexEntry{User Manual for scaRabee}
%\VignettePackage{scaRabee}

\title{The scaRabee Package: An R-based Tool for Model Simulation and 
  Optimization in Pharmacometrics\\[5mm]
  Version 1.1-2\\[5mm]}
\author{S\'ebastien Bihorel}

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

\begin{center}
  \includegraphics[width=50mm,height=50mm]{scarabee_R.pdf} \\[25mm]
\end{center}

\begin{flushleft}
Copyright\textsuperscript{\copyright} 2009-2011 S\'ebastien Bihorel

Permission is granted to copy, distribute and/or modify this document under the
terms of the GNU Free Documentation License, Version 1.2 or any later version 
published by the Free Software Foundation; with the Invariant Sections being the
Front-Cover Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below). A copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual for \scaRabee{}

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU software.

\end{flushleft}
\pagestyle{headings}

% Table of contents
\cleardoublepage
\tableofcontents

% Some Sweave preamble
<<echo=false>>=
options(width=70)
@

\cleardoublepage
\section{Introduction}
\scaRabee{} is a toolkit for modeling and simulation primarily intended for the 
field of pharmacometrics. It was initially a \R{} port \cite{Rcitation} of 
\pkg{Scarabee}, a Matlab-based application developed for the simulation and 
optimization of pharmacokinetic and/or pharmacodynamic models specified with 
algebraic equations, ordinary or delay differential equations 
\cite{Bihorel.2009}. It is now the only version supported and being developed. 
Since its first release, the \scaRabee{} package has been improved and now 
contains functionnalities, which are not present in the original Matlab version.  

\subsection{Preliminary notice}
This vignette constitutes a user manual for \scaRabee{}. This manual assumes 
that the reader is familiar with the concepts of pharmacokinetic and 
pharmacodynamic modeling and the underlying statistical theories. It is not the
objective of this manual to explain and review those methods and theories. 
Readers who are new to this field are invited to read the excellent introductory
and more advanced books from Gabrielsson and Weiner \cite{Gabrielsson.2007},
Bonate \cite{Bonate.2006} or Ette and Williams \cite{Ette.2007}.

The systems analyzed in \scaRabee{} must be specified, for most parts, using the
\R{} language and all analyses should be executed within the \R{} environment
in interactive or batch mode. Presentations of the \R{} language are out of the
scope of this manual.

\subsection{What's new?}
Version 1.1-2 introduces minor changes to \scaRabee{} related primarily to the
solver of delay differential equation. The \code{dde} solver from the 
\pkg{PBSddesolve} package was replaced by the \code{dede} solver from the 
\pkg{deSolve} package, which is more stable for large and complex model and 
permits easier handling of discontinuities. A bug is the handling of dosing 
history is also fix in this version.

\subsection{How to obtain scaRabee}
\scaRabee{} is available at the Comprehensive R Archive Network and also at
Pmlab (\url{http://code.google.com/p/pmlab/}), a repository for open-source
software solutions in pharmacometrics. The most recent version of \scaRabee{}
can be found in the Downloads section. \scaRabee{} is distributed under a GNU
General Public License version 3. Please, review the terms of this license
before using this package. If this license was not distributed with your copy of
\scaRabee{}, please visit the GNU Project website (\url{http://www.gnu.org/}).

\subsection{Installation and dependencies}
This package is available as source archive. You are invited to read Section
6.3 Installing packages from the R Installation and Administration manual 
\cite{Rinstall.2010} for more details on how to install a source package from a
local .zip or .tar.gz file on your system. Model optimization in \scaRabee{} (as
described in Section \ref{methodo}) relies on functions from the \pkg{neldermead},
\pkg{optimsimplex}, and \pkg{optimbase} packages, which are also distributed 
from CRAN and Pmlab as compressed archives of the source packages.

\subsection{Credits}
\scaRabee{} was written by S\'ebastien Bihorel, alumni of the Paris 5 - Ren\'e 
Descartes University and of the State University of New York (SUNY) at Buffalo,
upon suggestions and contributions from:
\begin{itemize}
  \item{Pawel Wiczling, alumni of SUNY at Buffalo, who shared codes at the basis
    of the first \Matlab{} versions of the \code{fitmle} and \code{fitmle.cov}
    functions,}
  \item{John Harrold, Post-Doctoral Fellow at SUNY at Buffalo, who provided 
    numerous advises during the creation of the \Matlab{} version of
    \scaRabee{},}
  \item{Sihem Ait-Oudhia, alumni of the Paris 5 - Ren\'e Descartes University
    and of SUNY at Buffalo, for her suggestions and support.}
\end{itemize}

The \pkg{neldermead}, \pkg{optimsimplex}, and \pkg{optimbase} packages, used
for parameter optimization in \scaRabee{}, are \R{} ports of the Scilab modules
of the same names which were developed by Michael Baudin at INRIA (Institut
National de Recherche en Informatique et en Automatique) and now at the 
Digit\'eo consortium. More information on Scilab can be found at 
\url{www.scilab.org}.

\subsection{Reporting bugs}
We welcome bug reports, questions, and suggestions concerning any aspect of 
\scaRabee{} functions, documentation, installation, anything... Please email 
them to \code{sb.pmlab@gmail.com}.

For bug reports, please include enough information to allow the maintainer to 
reproduce the problem. Generally speaking, that means:
\begin{itemize}
  \item{your version of \scaRabee{} and the function(s) or manual involved.}
  \item{your version of \R{} and package dependencies.}
  \item{hardware and operating system names and versions.}
  \item{the contents of any data and model files necessary to reproduce the bug.}
  \item{a description of the problem and samples of any erroneous output.}
  \item{any unusual options you gave to configure the problem.}
  \item{anything else that you think would be helpful.}
\end{itemize}

Patches are also most welcome; if possible, please follow the existing coding 
style, comment our faulty code and clearly marked your editions.

\section{Types of analysis performed in \scaRabee{}}
  \label{methodo}
\scaRabee{} allows the optimization and simulation of non-linear systems at the 
population and subject levels but does not implement non-linear mixed effects 
modeling. For each subject included in an analysis, \scaRabee{} allows users to 
split the analysis problem into subproblems (also referred to as treatments), 
while still defining a unique model. This feature is especially useful when data 
obtained from several dose levels or regimens are fitted simultaneously, because 
it avoids the duplication of algebraic or differential equations usually needed 
to accommodate the different dose levels or regimens.

\scaRabee{} allows users to perform three types of analysis: simulations, 
estimations, and direct grid searches.

\subsection{Simulation}
Simulation runs allow to generate detailed model predictions based upon initial 
parameter values provided by the user. \scaRabee{} also produces default overlay
plots of model predictions and actual observations.

\subsection{Estimation}
Estimation runs allow to optimize model parameters based upon the observations,
the structural model and a residual variability model. Model parameters are 
optimized by the method of the maximum likelihood, more precisely by the 
minimization of an objective function defined as the exact negative log 
likelihood of the observed data, given the model structure and a set of
parameter values. The minimization algorithm is based upon the Nelder-Mead 
simplex method, as implemented by the \code{fminsearch} function from the 
\pkg{neldermead} package. The computation of the data likelihood and the 
covariance matrices of primary and secondary parameters are performed as 
described in the Adapt II software user's manual written by D'Argenio and 
Schumitzky \cite{Dargenio.1997}.

The analysis of population data can be performed by na\"ive averaging,
na\"ive pooling, or by the standard two-stage approach \cite{Ette.2007}. Note 
that the standard two-stage approach is automated only since version 1.1-0.

\subsection{Direct grid search}
Direct grid search runs allow to explore the search space of an optimization 
problem around the initial point \(x_0\) of parameter estimates. This 
\scaRabee{} feature automatically creates a grid of search points selected 
around the initial point and evaluates the objective function at each one of 
these search points. The boundaries of the grid are set either by the lower and 
upper boundaries set by the users, or by a vector of factors \(\alpha\) applied 
to \(x_0\) as follows: \([x_{0}/\alpha,x_{0}\times\alpha]\). The number \(npts\) 
of points evaluated for each parameter (or dimension of the optimization 
problem) can also be defined. The total number of points in the grid is 
\(npts^{p_e}\), where \(p_e\) is the number of parameters to be estimated. At 
the end of the search, a table sorted by increasing value of the objective 
function is created. 

This table also reports the feasibility of the objective function at each 
particular search point because the grid search is actually delegated to the 
\code{fmin.gridsearch} function from the \pkg{neldermead} package. This function
is a wrapper around \code{optimbase.gridsearch} from the \pkg{optimbase} package,
which assesses the feasbility of a cost function in addition to calculating its 
value at each particular search point. Because \code{fmin.gridsearch} does not 
accept constraints, the objective function should always be feasible. Additional 
information is available in \code{optimbase.gridsearch} and 
\code{?fmin.gridsearch}.

\section{Getting started}
All \scaRabee{} analyses are typically conducted in analysis-specific folders
and rely on the presence of a given list of files in this working directory. A
typical \scaRabee{} folder, as one created by the \code{scarabee.new} 
function, contains at least the following files:
\begin{description}
  \item[myanalysis.R] the master \R{} script; this file is required to initiate 
    the analysis. Section \ref{editana} describes which parts of the code must 
    be edited.
  \item[data.csv] the data file; this file is a comma-separated table containing
    the dosing and observation data to be used for model simulation or 
    optimization. Section \ref{editdata} describes how this data must be 
    specified.
  \item[initials.csv] the parameter file; this file is a comma-separated table 
    containing the names and values of the model parameters, used for model 
    optimization or as inputs for model  simulation. In the former case, the 
    values provided for each parameters are used as initial estimates for the 
    optimization. Section \ref{editparam}  describes how these parameters must 
    be specified.
  \item[model.txt] the model file ; this file is a text file in which the 
    structural model, residual variability model, and secondary parameter 
    computations are defined. Section \ref{editmodel} describes the syntax that 
    must be applied to edit this file.
\end{description}

While the names of these files correspond to the default assumed by the 
\code{scarabee.new} function, they can be modified at the user's discretion.
In this manual, the default files names are used for the sake of simplicity. 
Finally, please note that you can add any file needed or not for your analysis 
in your analysis folder. The Sections \ref{newanalysis} through \ref{execana} 
offer a step-by-step description of the analysis process. 

\subsection{Creation of a new analysis folder}
  \label{newanalysis}
If you start a brand new data analysis, it is recommended that you open an
interactive \R{} session, and use the \code{scarabee.new} function to create a 
new analysis folder that will contain \code{myanalysis.R}, \code{data.csv}, 
\code{initials.csv}, and \code{model.txt}. It is recommended that you provide 
all arguments of \code{scarabee.new} to better set up the new folder:
\begin {description}
  \item[\code{name}] controls the name of the analysis, which is used as a base 
    name for the master \R{} script file (in place of the default 'myanalysis') 
    and is also inserted after the \$ANALYSIS tag in the model file (see Section
    \ref{editmodel}),
  \item[\code{path}] defines the (absolute or relative) path to the directory to 
    be created; if the \code{path} argument is NULL, then it is coerced to 
    \code{name}, thus causing the (tentative) creation of a new folder named as 
    the \code{name} argument in the current working directory,
  \item[\code{type}] defines whether the analysis is a simulation (default), an 
    estimation, or a direct grid search run,
  \item[\code{method}] defines if the analysis is to be performed at the 
    population (default) or subject level,
  \item[\code{template}] controls which template will be used for 
    \code{model.txt}; templates are available for models defined with algebraic 
    ('explicit'), ordinary differential equations ('ode', default), or delay 
    differential equations ('dde').
\end{description}

Here is an example of \scaRabee{} folder creation:
<<eval=FALSE>>=
require(scaRabee)
scarabee.new(name='myanalysis',
             path = 'some/target/directory/',
             type = 'simulation',
             method = 'population',
             template = 'ode')
@

\subsection{Creation of new models in an on-going analysis}
Alternative models for an on-going analysis might be created in three different 
ways:
\begin{enumerate}
  \item Create copies of the master \R{} script and \code{model.txt} of
    interest in the current working directory. This method is not recommended 
    but should work as long as the new master \R{} script is updated 
    appropriately and the string following the \$ANALYSIS tag in the new model 
    file is different from the one used in the original model.
  \item Create a brand new analysis folder using the method described in Section
    \ref{newanalysis}.
  \item Copy an existing analysis folder to a different location, and make the 
    appropriate deletion of analysis subfolders and report files. 
\end{enumerate}

Regarless of the chosen method, most analysis files require some form of 
modification, that are described in Section \ref{editdata} through
\ref{editana}. Symbols and notations used in those sections as well as in the
\scaRabee{} function man pages are summarized in Table \ref{numtable}.

\begin{table}[h]
  \begin{tabular}{l p{5in} }
    \hline
    Symbol & Definition\\
    \hline
    \(p_{e}\) & Number of parameters to be estimated\\
    \(p_{f}\) & Number of fixed parameters\\
    \(p_{s}\) & Number of secondary parameters to be estimated\\
    \(p_{d}\) & Number of derived parameters\\
    \emph{c} & Number of covariates in the dataset\\
    \emph{n} & Number of subjects in the dataset\\
    \(k_{i}\) & Number of subproblems for the \(i^{th}\) subject \\
    \(b_{ij}\) & Number of bolus events in the \(j^{th}\) subproblem for the
      the \(i^{th}\) subject\\
    \(f_{ij}\) & Number of infusion events in the \(j^{th}\) subproblem for the
      the \(i^{th}\) subject\\
    \(d_{ij}\) & Number of dosing events in the \(j^{th}\) subproblem for the
      the \(i^{th}\) subject (\(b_{ij}\)+\(f_{ij}\))\\
    \(m_{ij}\) & Number of observation times in the \(j^{th}\) subproblem for 
      the \(i^{th}\) subject\\
    \emph{s} & Number of system states \\
    \emph{o} & Number of system outputs\\
    \emph{l} & Number of delays defined for a solution of a system of delayed 
      differential equations\\
    \hline
  \end{tabular}
  \caption{Symbol Definition for Vector and Matrix Dimensions}
  \label{numtable}
\end{table}

\subsection{Editing of the data file}
  \label{editdata}
The data file (named \code{data.csv} by default) contains the dosing information
and endpoint measurements to be modeled or matched against a model simulation. 
It is required for any type of run. The \scaRabee{} data files adopt similar 
structure and standards as those used in programs commonly used in 
pharmacometrics, such as NONMEM \cite{NONMEM.7}, S-SADAPT \cite{Sadapt}, or 
MONOLIX \cite{Kuhn.2005}.

The data must consist of a time-ordered series of dosing and observations events
specific to each subproblem (or treatment; see below) of each subject included 
in the dataset. Blocks of subject/treatment specific data must simply be stacked 
one after the other. The dataset must respect a tabulated, comma-separated value,
format and can be edited in any text editor or spreadsheet. All \scaRabee{} data
files can be saved as any user-defined base name; however, the .csv extension is 
compulsory. The content of the data file must be a full rectangular table, with 
the following structure:
\begin{itemize}
\item{All data variables must be stored in specific columns, each having a 
unique header. A series of variables with reserved names and expected content
must be present, but users can add any number of custom (usually numerical) 
variables. The names and the meanings of the variables required in any 
\scaRabee{} dataset are provided in the following listing, which also includes 
one useful but optional variable:
  \begin{description}
  \item[OMIT] (optional) omission flag. Only the data records with the OMIT
    variable set to 0 are included in the analysis. The OMIT variable is coerced
    to integer numbers by \scaRabee{}.
  \item[ID] subject identifier. A sequence of unique integers starting at 1 is 
    expected to distinguish the subjects in the dataset. The ID variable is 
    coerced to integer numbers by \scaRabee{}.
  \item[TRT] subproblem identifier. This variable must contain integer numbers 
    in \textbf{increasing} order from 1 to \(k_{i}\), the total number
    of subproblems for the \(i^{th}\) subject. If the user decides to define
    different subproblems for one or more individuals, all subproblems are 
    evaluated separetely, but all contribute to the value of objective function 
    for this(ese) individual(s). This feature typically allows users to define 
    simpler systems when modeling different dose levels/regimens, as it avoids 
    e.g. the duplication of the system equations to accomodate data collected at
    multiple dose levels, or the need for a system reset between to treatment 
    period. Therefore, the TRT variable is indistinctly referred to as the 
    subproblem or treatment variable in this manual. All records with a similar 
    TRT value will be considered as part of the same subproblem. The TRT 
    variable is coerced to integer numbers by \scaRabee{}.
  \item[TIME] independent variable. It represents the time since the first 
    event; therefore, TIME should be 0 for the first (dosing or observation) 
    record of each unique treatment of each subject. If this is not the case 
    for at least one treatment for one subject, the dataset is processed by
    \scaRabee{} and a new dataset including the calculated time since first
    event is saved to the working directory and used for the analysis.
  \item[AMT] amount variable. This variable is used to define dosing events in
    combination with the RATE, CMT, and TIME variables. For
    each dosing record, the value set for the AMT variable represents the dose
    administered at the TIME for the record and assigned to the system state 
    defined in the CMT variable (see below). The content of the AMT variable is 
    ignored for observation records.
  \item[RATE] rate variable. This variable is used to define dosing events in
    combination with the AMT, CMT, and TIME variables. For each dosing record,
    the value set for the RATE variable reflects the rate at which the dose 
    AMT is administered into the system state CMT (see below). The RATE variable
    can be set to:
    \begin{description}
      \item[0] to indicate an instantenous input into the system,
      \item[any value > 0] to define the rate of a zero-order input into the system,
      \item[-1] to request the estimation of the rate of a zero-order input 
        into the system, and
      \item[-2] to request the estimation of the duration of a zero-order input 
        into the system.
    \end{description}
    The user cannot request the estimation of the duration for one record, and
    the estimation of the rate for another: -1 and -2 are mutually exclusive 
    across the dataset.
  \item[CMT] compartment variable. This variable represents the system state 
    (\emph{i.e.} a compartment in the standard representation of system in
    pharmacometrics) associated to a dosing record. The CMT variable is ignored
    for observation records. The CMT variable is coerced to integer numbers by 
    \scaRabee{}.
  \item[EVID] event identifier. This variable is used to define the type of 
    record/event. The EVID variable is set to:
    \begin{description}
      \item[0] for observation records, and to
      \item[1] for dosing records.
    \end{description}
    The EVID variable is coerced to integer numbers by \scaRabee{}.
  \item[DV] dependent variable. This variable represents the observed value 
    associated with the record. This value assigned to this variable is ignored
    for dosing records.
  \item[DVID] dependent variable. This variable represents the model output 
    (see Section \ref{editmodel}) associated to an observation record. Although
    DVID could be missing for dosing events and is ignored by \scaRabee{}, if a 
    value is provided, this value must be 0. The DVID variable is coerced to 
    integer numbers by \scaRabee{}.
  \item[MDV] missing dependent variable. This variable must be set to 1 for
    dosing records and to 0 for observation records that are to be included in 
    the analysis dataset. Observation records with a DVID value other than 0 are
    excluded. The DVID variable is coerced to integer numbers by \scaRabee{}.
  \end{description}
}
\item{Any other variable provided in the data file is considered as a covariate.
  The total number \emph{c} of covariates are available for use in selected 
  blocks of code in the model file (see Section \ref{editmodel}).}
\item{Record values set to . or NA are considered missing information by 
  \scaRabee{}.}
\item{All data files must contain at least the header line and two records per
  subproblem for each subject, indicating the beginning and the end of the
  observation intervals.}
\end{itemize}

NONMEM users must be warned that several data standards and variables are not 
implemented in \scaRabee{}, \emph{e.g.} all records set with EVID of 2, 3, or 4 
are ignored by \scaRabee{}, and the CONT, ADDL, II, and SS variables are 
considered as covariates.

\subsection{Editing of the parameter file}
  \label{editparam}
The parameter file (named \code{initials.csv} by default) contains the 
information about the primary model parameters. Derived parameters, \emph{i.e.}
parameters that are needed for model computations but do not need to be 
estimated, can be specified in the \$DERIVED or \$OUTPUT blocks in the model 
section. Secondary parameters, \emph{i.e.} parameters that are typically not 
needed for model computations but fro which precision statistics are required, 
can also be defined in the model file using the \$SECONDARY block of code.

This parameter file is required in all types of runs, and can be edited
in any text editor or spreadsheet. All parameter files must
respect the comma-separated values format but can be saved under any
user-defined name (the .csv extension is compulsory though). The content of
parameter files must be provided as a full \((p_e + p_f + 1) \times{} 6\) 
rectangular table (where \(p_e\) and \(p_e\) are the numbers of fixed and 
estimated parameters), with the following structure:
\begin{itemize}
\item{The first line must contain the headers of each column of your data
  table. This line is provided in the original \code{initials.csv} and should
  typically not be modified.}
\item{There must be 6 columns, ordered as follows:
  \begin{center}
  Parameter, Type, Value, Fixed, Lower bound, Upper bound\\
  \end{center} 
  where Parameter, Type, and Value are the columns of parameter names, types and
  values, Fixed is the column indicating whether a given parameter should be
  estimated or fixed in an estimation analysis, and Lower bound and Upper bound
  are the columns defining the range of values that a given parameter could
  take.}
\item{Each line must contain 6 elements separated by commas. There cannot be
  any missing data in this table.}
\item{The Parameter column can contain numbers or strings of characters,
  representing the name of your model parameters (numbers will be handled as
  strings of characters).}
\item{The Type column must contain single characters, indicating the type of
  each single parameter. There is four types of variables in Scarabee, so only
  four authorized characters:\begin{description}
  \item[P] indicates that the parameter is a structural model parameter.
  \item[L] indicates that the parameter is a delay. This category exists for
    the user convenience in the definition of model with delayed differential
    equations.
  \item[IC] indicates that the parameter is used to define an initial
    condition of a differential equation. This category is a legacy of the 
    original Scarabee Matlab code. It exists for the user convenience in the 
    definition of model with delayed differential equations but is handled 
    exactly the same way as parameters of type 'P'.
  \item[V] indicates that the parameter is used to specify the residual
    variability model.
  \end{description}}
\item{The Value column must contain real numbers, representing the values
  taken by the parameters.}
\item{The Fixed column must contain either 0's or 1's, indicating whether a
  parameter should be fixed (1) or estimated (0) during an estimation analysis.
  This column has no impact on simulation runs.}
\item{The Lower and Upper bounds must contain real numbers, representing the
  range of values that parameters can take. The optimization algorithm
  implemented in \scaRabee{} forces all estimated parameters to remain within
  these defined ranges.}
\item{All parameter files must contain at least a header line and one parameter 
  definition line.}
\end{itemize}

\subsection{Editing of the model file}
  \label{editmodel}
The model file (named \code{model.txt} by default) is a text file in which users 
can specify the structural model, residual variability model, and secondary 
parameter computations. The model file is required for all types of analysis. It
can be modified in any text editor and saved under any user-defined name.

The model file implements a tag-based syntax similar to the one used in NM-TRAN
control streams \cite{NONMEM.7}, S-ADAPT-TRAN \cite{sadapt.tran} or MONOLIX 
\cite{Kuhn.2005} model files. Tags are defined as strings of characters starting 
by the \$ symbol followed by a keyword. At the exception of \$ANALYSIS, each tag
of the listing below marks the beginning of a block of \R{} code defining one 
particular component of the evaluated system. Because of these tags, \scaRabee{} 
model files cannot be interpreted directly by \R{}; their content must first be 
parsed by \scaRabee{}, before each block of \R{} code could be evaluated at 
relevant stages of the analysis process. Within those blocks of code, users can 
call any \R{} function that would be available in their workspace.

Upon creation of a new analysis folder, the model file is pre-filled with the 
tags that are appropriate and required for the specified category of model. The 
complete list of tags required for each category of model is given in Table 
\ref{modeltagtable}.

\begin{table}[h]
  \begin{tabular}{l p{1.45in} p{1.45in} p{1.45in}}
    \hline
    Model category & explicit & ode & dde\\
    \hline
    & \$ANALYSIS & \$ANALYSIS & \$ANALYSIS\\
    & \$OUTPUT & \$DERIVED & \$DERIVED\\
    & \$VARIANCE & \$IC & \$IC\\
    & \$SECONDARY & \$SCALE & \$SCALE\\
    & & \$ODE & \$LAGS\\
    & & \$OUTPUT & \$DDE\\
    & & \$VARIANCE & \$OUTPUT\\
    & & \$SECONDARY & \$VARIANCE\\
    & & & \$SECONDARY\\
    \hline
  \end{tabular}
  \caption{Required tags for model file}
  \label{modeltagtable}
\end{table}

As stated above, users can modify the newly created file in any text editor. 
Note that any tag keyword could be abbreviated to the first three letters of the
keyword, except for \$IC. When a analysis is started (see Section \ref{execana}),
the model file is read, parsed, and checked by \scaRabee{}. If requirements are
not met, the analysis stops and users are invited to check the content of the 
model file. Note that \scaRabee{} determines the category of structural model by
scanning the content of the file for the \$ODE and \$DDE tags: if the \$ODE tag 
is detected, the model is assumed to be defined with ordinary differential 
equations; if the \$DDE tag is detected, the model is assumed to be defined with 
delay differential equations; if both tags are not detected, the model is 
assumed to be defined with algebraic equations. The \$ODE and \$DDE tags cannot 
coexist within the same model file.

\subsubsection{\$ANALYSIS}
The \$ANALYSIS tag allows users to provide a name to the analysis, which is used
to name the folder created to store the results of the analysis (see Section 
\ref{execana}) and the analysis report files. The name extracted by \scaRabee{}
is the first word following the tag.

The \$ANALYSIS tag must be present in all model files, regardless of the 
category of models.

\subsubsection{\$DERIVED}
The \$DERIVED tag is specific to and required for structural models specified 
with ordinary or delay differential equations. It allows users to define derived 
parameters which could be called later within the \$ODE or \$DDE blocks of code. 
Within the \$DERIVED block, users can call any primary parameter defined in the 
parameter file and any covariate name to define new objects. Only the new \R{} 
objects created in the \$DERIVED block will be considered as secondary 
parameters; in other words, all modifications of a primary parameter will be 
ignored. Furthermore, users can choose to leave this block of code empty, if no 
derived parameter is needed.

Although users could choose to define derived parameters within the \$ODE or 
\$DDE blocks, it is computationally more efficient to define them in the 
\$DERIVED block, as this block of code is only evaluated once for each model 
evaluation, while the \$ODE or \$DDE blocks of code are evaluated up to several 
thousands of times.

Note that the \$DERIVED tag is not required (and actually ignored) for models 
specified with algebraic equations, because derived parameters could be defined 
within the \$OUTPUT block without loss of computation efficiency.

\subsubsection{\$IC}
The \$IC tag is specific to and required for structural models specified with 
ordinary or delay differential equations. It allows to define the initial 
conditions of the system of differential equations. Users can call any primary 
or derived parameters within the \$IC block.

\scaRabee{} expects the creation of the \code{init} object, which must be a 
vector containing as many elements as there are states in the system of 
differential equations.

\subsubsection{\$SCALE}
The \$SCALE tag is specific to and required for models specified with ordinary
or delay differential equations. It allows users to scale any instantaneous or
continuous inputs into the system. This is particularly useful when the 
dimensions of the inputs and the associated stated are different, which is the 
case when a dose of drug in mass (g) or amount (mol, IU) is assigned to a state 
modeled as a concentration (g/L, mol/L or IU/L). Users can call any primary or 
derived parameters within the \$SCALE block.

\scaRabee{} expects the creation of the \code{scale} object, which must be a 
scalar or a vector containing as many elements as there are states in the system
of differential equations. Consequently, all inputs into a given system state 
will be scaled identically.

\subsubsection{\$LAGS}
The \$LAGS tag is specific to and required for structural models specified with
delay differential equations. It allows users to define the delays at each the 
system of differential equations should be evaluated. Users can call any primary 
parameter and any derived parameter to define delays within the \$LAGS block.

All primary parameters of type 'L' and all new \R{} objects created in the 
\$LAGS block will be considered as delays. All modifications of a primary or 
derived parameter will be ignored, so users cannot directly set primary or 
derived parameters as systems delays. Except for the parameters of type 'L', all
delay parameters must be derived from previous parameter and be given new names.

Users must define at least one system delay (either as a primary parameter of
type 'L' or as a new \R{} object inside the \$LAGS block) when the structural 
model is defined by delay differential equations.

\subsubsection{\$ODE}
The \$ODE tag is specific to and required for structural models specified with 
ordinary differential equations. It allows users to define the system of 
differential equations. The parameters available to users within the \$ODE block 
are:
\begin{itemize}
  \item{the primary parameters,}
  \item{the derived parameters,}
  \item{\emph{t}, the time of evaluations of the system,}
  \item{\emph{a1}, \dots{}, \(a_s\), the values of the system states at time
    \emph{t}, where \emph{s} is the total number of states, and}
  \item{any covariate name. However, by default, \scaRabee{} does not 
    interpolate the covariate data at time \emph{t}. Users might want to call
    the \code{approx} function for this purpose (see \code{?approx}).}
\end{itemize}

\scaRabee{} expects the creation of the \code{dadt} object, a 
1\(\times\)\emph{s} matrix of system states. Note that it is not necessary to 
include exogenous inputs (boluses and infusions) into the system of differential 
equations, this is automatically done by the code.

\subsubsection{\$DDE}
The \$DDE tag is specific to and required for structural models specified with 
delay differential equations. It allows users to define the system of 
differential equations. The parameters available to users within the \$ODE block 
are:
\begin{itemize}
  \item{the primary parameters,}
  \item{the derived parameters,}
  \item{\emph{t}, the time of evaluations of the system,}
  \item{\emph{a1}, \dots{}, \(a_s\), the values of the system states at time
    \emph{t}, where \emph{s} is the total number of states,}
  \item{\(alag.lag_1\), \dots{}, \(alag.lag_l\), the vector of system states at 
    time \(t-lag_1\), \dots{}, \(t-lag_l\), where \emph{l} is the total number 
    of delays defined in the \$LAGS block of code. To access to the value of a 
    particular system state at a particular delay, users must subset the 
    appropriate \(alag.lag_i\) vector: \emph{e.g.} \(alag.past[3]\) would extract 
    the value of the 3\(^{rd}\) system state at a delay named \code{past}, and}
  \item{any covariate name. However, by default, \scaRabee{} does not 
    interpolate the covariate data at time \emph{t}. Users might want to call
    the \code{approx} function for this purpose (see \code{?approx}).}
\end{itemize}

\scaRabee{} expects the creation of the \code{dadt} object, a 
1\(\times\)\emph{s} matrix of system states. Note that it is not necessary to 
include exogenous inputs (boluses and infusions) into the system of differential
equations, this is automatically done by the code.

\subsubsection{\$OUTPUT}
The \$OUTPUT tag must be present in all model files, regardless of the category 
of models. It allows users to defined the output(s) of the structural model.

In models defined with algebraic equations, the \$OUTPUT block is the place 
where the derived parameters and the structural model should be defined. The 
parameters available to users within the \$OUTPUT block are:
\begin{itemize}
  \item{the primary parameters,}
  \item{\emph{times}, the vector of unique times of observations (or simulated 
    observations),}
  \item{\emph{bolus} and \emph{infusion}, the data frames of bolus and infusion
    dosing records extracted from the data file, and}
  \item{any covariate data. Note that it is only necessary to interpolate the 
    covariate data for simulation or direct grid search runs, as covariate data 
    should be available at any observation time in estimation runs.}
\end{itemize}

In models defined with ordinary or delay differential equations, the \$OUTPUT 
block is the place to define the model output using the predictions from
the integration of the system of differential equations. The parameters 
available to users within the \$OUTPUT block are:
\begin{itemize}
  \item{the primary parameters,}
  \item{the derived parameters,}
  \item{\emph{times}, the vector of unique times of observations (or simulated 
    observations), and}
  \item{\emph{f}, the \(s \times{} m_{ij}\) matrix of system state 
    predictions, where \(m_{ij}\) is the total number of observations in the 
    \(j^{th}\) subproblem for the \(i^{th}\) subject.}
\end{itemize}

\scaRabee{} expects the creation of the \code{y} object, which must be a 
\(o \times{} m_{ij}\) matrix, where \emph{o} is the number of system outputs. 
For any type of run, the data records set with a DVID value of \emph{dvid} will 
be matched against the \(dvid^{th}\) system output. Therefore, the maximum value
of the DVID variable in the dataset must be \emph{o}.

\subsubsection{\$VARIANCE}
The \$VARIANCE tag must be present in all model files, regardless of the 
category of structural model. The presence of a \$VARIANCE tag is required for 
types of runs, except for simulations. The \$VARIANCE block allows users to 
define the residual variability models associated with each structural model 
outputs. The parameters available to users within the \$VARIANCE block are:
\begin{itemize}
  \item{the primary parameters,}
  \item{the derived parameters,}
  \item{\emph{y}, the \(o \times{} m_{ij}\) matrix of structural model 
    predictions, and}
  \item{\emph{ntime}, a scalar which value is set to \(m_{ij}\).}
\end{itemize}

\scaRabee{} expects the creation of the \code{v} object, which must have exactly
the same dimension as the \emph{y} object created in the \$OUTPUT block of code. 
\emph{v} represents the matrix of variance associated with each model prediction.
Typical residual variability models are (assuming \(o=1\)):
\begin{itemize}
  \item{additive variability model with variance 1
<<eval=FALSE>>=
v <- rbind(ones(1,ntime))
@
}
  \item{additive variability model with estimated or fixed standard deviation,
  \emph{SD}:
<<eval=FALSE>>=
v <- rbind((SD^2)*ones(1,ntime))
@
}
  \item{coefficient of variation model with estimated of fixed standard 
  deviation, \emph{CV}:
<<eval=FALSE>>=
v <- rbind((CV^2)*(y[1,]^2))
@
}
  \item{additive and constant coefficient of variation model with estimated or 
    fixed standard deviations, \emph{SD} and \emph{CV}:
<<eval=FALSE>>=
v <- rbind((SD^2)*ones(1,ntime) + (CV^2)*(y[1,]^2))
@
}
\end{itemize}

\subsubsection{\$SECONDARY}
The \$SECONDARY tag is optional for all model files, regardless of the category 
of structural model or run type. It allows users to define \(p_s\) secondary 
parameters for which associated statistics must be computed (typically precision
and parametric confidence interval). The only parameters available to users within 
the \$SECONDARY block are the primary parameters. Only the new \R{} objects 
created in this block will be considered as secondary parameters; in other words, 
all modifications of a primary parameter will be ignored. Furthermore, users can 
choose to leave this block of code empty, if no secondary parameter should be 
computed.

\subsection{Editing of the master scaRabee script}
  \label{editana}
The master \scaRabee{} script (named \code{myanalysis.R} by default) is the \R{}
script that you must execute to perform any analysis. You must edit several 
lines location in a specific section of the file (from line 21 to line 57, or 60
if 'dde' was selected as a template  when \code{scarabee.new} was called) to 
define the settings of your analysis. Any other line of this file should 
typically not be modified. Commented lines within the user-editable section 
explain what and how variable(s) should be defined.
\begin{itemize}
  \item{Line 25: users can choose to define a working directory by adding a 
    valid path within the \code{setwd} function. This is optional but 
    recommended if users work in an interactive \R{} session. If provided, the 
    path to the working directory must contain the files specified in the 
    \code{files} list (see below).}
  \item{Lines 34-36: the \code{data}, \code{param}, and \code{model} levels of 
    the \code{files} list are character variables defining the names of the 
    files where your data, parameters, and model are respectively defined. The 
    default content of these levels matches the name of corresponding files 
    created by \code{scarabee.new}. Users can change those default names.}
  \item{Line 39: the \code{runtype} variable is a character variable, defining
    if the analysis is an estimation, a simulation, or a direct grid search. Any 
    other character string than 'estimation', 'simulation', or 'gridsearch' will 
    cause an early termination of the run and the display of an error message to
    the console or log file.}
  \item{Line 42: the \code{method} variable is a character variable, defining 
    the scope of the analysis. It must be set to 'subject' or 'population'. Any
    other character string will cause an early termination of the run and the 
    display of an error message to the console or log file.} 
  \item{Line 44: the optimization algorithm is designed to return an infinite
    objective function value in case the computation of the objective function 
    at a given point of the multi-dimensional search space returns an error 
    message. This is meant to prevent \R{} from stopping the optimization 
    process. Unfortunately, this will also happen if an execution error occurs 
    during the evaluation of the model or the residual variability functions. 
    The \code{debug} variable allows users to shut down this feature, and 
    identify potential syntax or variable dimension problems in your model or 
    residual variability files. The \code{debug} variable is a logical that can 
    only take TRUE or FALSE as value.}
  \item{Lines 49-50: \code{estim} is a list with two levels, \code{maxiter} and 
    \code{maxfunc}, defining the maximum number of iterations and function
    evaluations during an estimation run. Both must be scalar integers. The 
    default values are 500 and 5000, which should typically allow user's
    problem to converge to a stable point of the search space.}
  \item{Lines 54-55: the \code{npts} and \code{alpha} are variables 
    specific to direct grid search runs. \code{npts} must be an integer greater 
    than 2 and defines the number of points that the grid should contain per 
    dimension (\emph{i.e} variable model parameter). \code{alpha} must be a 
    scalar or a vector of real numbers greater than 1, which give the factor(s) 
    used to calculate the range of evaluation for each dimension of the search 
    grid (see \code{?scarabee.gridsearch} for more details). If \code{alpha} is 
    set to NULL, the lower and upper boundaries set in the parameter file are 
    used to define the range of evaluation for each dimension of the grid.}
\end{itemize}

\subsection{Execution of the master scaRabee script}
  \label{execana}
Once all necessary files have been edited, the analysis can be performed by
executing the master \R{} script. This can be done in two ways:
\begin{itemize}
  \item{from an iteractive \R{} session: we recommend that you set the
    working directory as the path to the analysis folder both in the \R{} 
    session and in the master script (see Section \ref{editana}). Then, type:
    \begin{center}
      \code{source('myanalysis.R')}.
    \end{center}
    You will be asked whether or not you want to change the working directory, 
    press ENTER if this is not the case. At the end of the run, press ENTER
    when prompted to display the different plots generated by \scaRabee{}.}
  \item{from a shell or dos window: navigate to the directory containing the
    master \R{} file of interest, then run the analysis by typing:
    \begin{center}
      \code{R CMD BATCH myanalysis.R}
    \end{center}
    You may add any option you see fit.}
\end{itemize}

In both modes, \scaRabee{} creates a new folder in the working directory which
name has the following structure:
\begin{center}
<myanalysis>.<type>.\#
\end{center}
where <myanalysis> is the string of character directly following the \$ANALYSIS 
tag in the model file, <type> is \code{est} for estimation runs, \code{sim} for 
simulation runs, \code{grid} for direct grid search runs,  and \# is a two-digit
integer.

At the exception of the .Rout file, all run outputs are stored in the newly 
created folder. Additionally, a subfolder called 'run.config.files' is created 
to backup all original analysis files (\code{data.csv}, \code{initials.csv},
\code{model.R}, and \code{myanalysis.R}).

In interactive mode, the run progression will be reported to the console, while 
it is stored to a log file in batch mode. Upon successful completion of the run, 
a termination message is reported and graphical outputs and ASCII text reports 
are produced. Most errors happening during the execution of the master \R{} 
script should stop the run and prevent the creation or the finalization of the 
graphs and report files. Instead, an informative message should be displayed.

\paragraph{Simulation runs\\[3mm]}
Upon successful completion of the run, you should be able to see (in
interactive mode) as many figures as the number of subject-subproblem 
combinations (see Section \ref{scope} for more details about how the scope of 
analysis impacts this number). Those overlay figures represent the predicted
changes in all selected outputs on top of the observed data. As stated above, 
all figures are stored in the newly created folder.

A file called \code{<myanalysis>.simulation.csv} file is also saved in the same
folder. This file lists the values taken by the model outputs at >1001 points
within the studied time interval (typically from the minimum dose event or
observation time to the maximum observation time), for each subproblem of each 
subject (see Section \ref{scope} for more details about the impact of the 
scope of analysis on this file).

\paragraph{Estimation runs\\[3mm]}
Upon successful completion of the run, a figure summarizing the changes in the 
objective function and the estimated parameter values as a function of the 
iteration number is created for each subject and stored in the newly created 
folder. A overlay figure of model predictions and observed data, and a figure 
showing 4 goodness-of-fit plots (predictions vs observations, weighted residuals 
vs time, weighted residuals vs observations, weighted residuals vs predictions) 
for each subproblem of each subject are also created and stored in the same 
folder (see Section \ref{scope} for more details about the impact of the scope 
of analysis on these plots). Starting on \scaRabee{} version 1.1-0, those 
figures are not displayed on screen when the analysis is run in interactive 
mode.

A file called \code{<myanalysis>.report.txt} file is also saved in the same
folder and provides, for each subject in the analysis, a summary of the estimation
run, a summary table of final parameter estimates associated with precision
statistics expressed as a coefficient of variation and a confidence intervals 
(calculated as described in \cite{Dargenio.1997}), the matrices of covariance 
and correlation for primary parameters, plus a summary table of computed 
secondary parameters associated with coefficient of variation and confidence 
intervals (calculated as described in \cite{Dargenio.1997}).

Moreover, a file called \code{<myanalysis>.iterations.csv} is saved in the
folder and provides, in a tabulated format, the values of objective function and
estimated parameters obtained at all iterations for each subject.

A file called \code{<myanalysis>.predictions.csv} is also saved in the folder 
and provides the values of observations, predictions, residuals, variances, and 
weighted residuals for each non-missing observation time, stacked
by subject, subproblem, and model output.

Finally, a file called \code{<myanalysis>.estimates.csv} is also saved in the 
folder and summarizes the final parameter estimates for each subject included in 
the analysis. This file could be helpful to calculate statistics of distribution
of the different parameters in the analysis population.

\paragraph{Direct grid search runs\\[3mm]}
Direct grid search runs include two main steps: the actual grid search, followed 
by a simulation step that is based upon the combination of parameter values that 
provided the lowest objective function value during the grid search. Direct grid 
search runs coerce the scope of the analysis to the population, even though the 
\code{method} variable in the master \scaRabee{} script is set to 'subject'. 
Therefore, the computation of the objective function during the grid search and 
the model predictions obtained during the simulation step are performed at the 
population level (see Section \ref{scope} for more details about the impact of 
the scope of analysis)

The progression of the grid search step is reported on the console in interactive 
mode or in the log file in batch mode. Upon completion of this step, no graph is
created. Instead, a regular simulation run starts and results in the creation of
the standard diagnostic plots mentionned above.

The same files created by standard simulation runs are generated by a direct 
grid search run in the newly created folder. Furthermore, the results of the
grid search are reported in a text file called \code{<myanalysis>.report.txt} 
that is also saved in the newly created folder.

\section{Scope of analysis}
  \label{scope}
\scaRabee{} analysis can be conducted at the subject or population level. Users 
can set this scope of analysis by modifying the \code{method} variable in the 
master \scaRabee{} script, as described in Section \ref{editana}.

When \code{method} is set to 'subject', \scaRabee{} processes and stratifies the
content of the data file assuming that all dosing and observation records with
specific ID values were obtained from different individuals. In this case, 
estimation runs optimize the model parameter separately for each individual, 
starting at the same search point provided by the initial parameter estimates. 
This corresponds to the standard two-stage approach, when the data file actually 
contains data from multiple subjects (\emph{i.e.} multiple unique ID variable 
values can be found in the data file), or to the na\"ive pooling approach, when
the data file only contains data from a single individual (\emph{i.e.} the ID 
variable is set to 1 for all records) \cite{Ette.2007}. Simulation runs 
performed at the subject level evaluate the model for each subproblem/treatment 
of each subject using the same initial parameter estimates. Grid search runs are 
not performed at the individual level, as the \code{method} variable is coerced 
to 'population' for this type of analysis.

When \code{method} is set to 'population', \scaRabee{} processes the content of 
the data file assuming that all observation records were obtained from a single
individual. The dosing history is extracted from the dosing records with an ID 
variable set to 1. In this case, estimation runs optimize the model parameter 
on the global data, starting at the search point provided by the initial 
parameter estimates. This corresponds to the na\"ive pooling approach 
\cite{Ette.2007}. Simulation runs performed at the population level evaluate the
model for all detected subproblems/treatments found in the dataset, using the 
initial parameter estimates. Finally, all grid search runs are performed at the 
population level.

\section{Design information}
\subsection{Solvers of differential equations}
Structural models defined using systems of differential equations require those
systems to be integrated before model outputs could be generated. This step of 
integration is performed using solvers of differential equations, which are the
\code{lsoda} solver from the \pkg{deSolve} package for systems of ordinary 
differential equations and the \code{dde} solver from the \pkg{PBSddesolve} 
package for systems of delay differential equations. Users are invited to 
refer to the documentation of those packages for more information.

\subsection{Implementation of dosing history for model defined with differential equations}
Instantaneous (\emph{i.e.} bolus) and zero-order (\emph{i.e.} infusion) inputs 
are automatically allocated to the appropriate system state by the functions 
evaluating the systems of differential equations (see the source code of 
\code{ode.model} and \code{dde.model} for more details). General rules for the 
implementation of dosing history are provided below.

\paragraph{Input scaling\\[3mm]}
All bolus and infusion input amounts (provided in the AMT variable) must be 
scaled by users. Input scaling is implemented in the \R{} code provided in the 
\$SCALE block of the model file as explained in Section \ref{editmodel}). 
Scaling is particularly useful when the dimensions of the inputs and the
associated stated are different, which is the case when a dose of drug in mass
(g) or amount (mol, IU) is assigned to a state modeled as a concentration (g/L,
mol/L or IU/L).

\paragraph{Bolus inputs\\[3mm]}
The \code{lsoda} solver used for models defined with ordinary differential 
equations does not include any handler of discontinuities. Because bolus inputs 
represents discontinuous events, their implementation require the integration of
the system of differential equations to be performed by steps. When bolus inputs
are detected in the data file, \scaRabee{} splits the global integration 
interval into several continuous integration intervals based upon the dose event 
times. The initial conditions of the system are updated for each integration 
interval by adding the scaled bolus amount (AMT) specified in the data file to 
the value of the state (CMT) at the end of the previous interval (or the 
specified initial conditions in the case of the first interval). Therefore, all 
model predictions made at the time of a bolus assume that this bolus has entered 
the system. Users are thus advised to set the time of pre-dose samples slightly 
before the time of the boluses, to ensure that those samples are handled as 
pre-dose and not post-dose samples.

\paragraph{Infusion inputs\\[3mm]}
The reduction from multiple data files to a single one introduced in the 
version 1.1-0 of \scaRabee{} resulted in major modifications in the automated
processing and assignement of infusions to system states.

Previous versions of \scaRabee{} required infusions to be 'constructed' by
multiple records in a dosing-specific input files. Input rates were then linealy
interpolated between two consecutive time points, allowing for an infusion rate
to change over time. In version 1.1-0 of \scaRabee{}, infusions are documented
as single dosing records in the data file, providing the time of infusion start,
the amount and rate of dosing. The rate is assumed to be constant for the whole 
duration of the infusion. If RATE>0 for the dosing record, the duration is 
calculated as RATE/AMT. If RATE=-1, the rate of infusion is estimated and the 
duration is calculated as R\#/AMT, where R\# is a derived parameter expected to be 
defined in the \$DERIVED block (\# represents the value of the CMT variable set 
for the dosing record). If RATE=-2, the duration of infusion is estimated and 
the rate is calculated as AMT/D\#, where D\# is a derived parameter expected to be
defined in the \$DERIVED block (\# represents the value of the CMT variable set 
for the dosing record).

The following example illustrates the automated dosing allocation in \scaRabee{}.
Let's assume that the system is specified by two ordinary differential equations,
both fixed to zero, and that the data in provided as follows in the dataset:

\begin{center}
  \begin{tabular}{c c c c c c c c c c c}
    \hline
    OMIT & ID & TRT & TIME & AMT & RATE & CMT & EVID & DV & DVID & MDV\\
    \hline
    0 & 1 & 0 & 0 & 0 & 0 & 1 & 0 & 0 & 1 & 0\\
    0 & 1 & 0 & 0 & 1000 & 100 & 1 & 1 & 0 & 0 & 1\\
    0 & 1 & 0 & 0 & 0 & 0 & 2 & 0 & 0 & 1 & 0\\
    0 & 1 & 0 & 15 & 100 & 0 & 2 & 1 & 0 & 0 & 1\\
    0 & 1 & 0 & 20 & 10000 & 50 & 1 & 1 & 0 & 0 & 1\\
    0 & 1 & 0 & 20 & 250 & 0 & 1 & 1 & 0 & 0 & 1\\
    0 & 1 & 0 & 45 & 0 & 0 & 1 & 0 & 0 & 1 & 0\\
    0 & 1 & 0 & 45 & 0 & 0 & 2 & 0 & 0 & 1 & 0\\
    \hline
  \end{tabular}
\end{center}
State 1 receives 1 bolus dose at time 20 and 2 infusions: the first, between 0
and 10, has a constant rate of 100, and a second starts at time 20 and does not 
stop before the last observation. State 2 only receives a bolus dose at time
15. The following graphs show the changes in the infusion rate entering both
states (top graphs), as well as the accumulation of the drug in both states
(bottom graphs).
\begin{center}
  \includegraphics[scale=0.8]{deinputs.png}
\end{center}

\subsection{Implementation of dosing history for model defined with algebraic
equations}
Dosing history cannot be automatically assigned to a model defined with algebraic
equations. However, users can use dosing information in the \$OUTPUT block by 
calling the \code{bolus} and \code{infusion} variable, which each contain the 
TIME, CMT, AMT, RATE variable extracted from the \(d_{ij}\) dosing records 
identified as instantaneous (RATE=0) or zero-order (RATE\(\neq\)0) inputs. 
Relevant data extraction would need to be performed by user-specific code. 

It might also be convenient to carry  dosing information in a covariate 
(\emph{e.g.} DOSE) which could be used in a explicit solution of a specific 
pharmacokinetic model. 
  
As such, it might have occured to users familiar with NONMEM that the 
implementation of models defined with algebraic equations in \scaRabee{} is not 
too different from what NONMEM allows via to the \$ERROR record.

\section{Analysis examples}

This section is designed to illustrate some selected features of \scaRabee{}. 
Eight examples are available as demos using calls such as the following 
(replacing \code{ex} by \code{example1} to \code{example8}):

<<eval=FALSE>>=
demo(ex,package='scaRabee',echo=FALSE)
@

Running these examples will create analysis folders in your working directory.
We recommend that you review their content after their creation.

\subsection{Example 1: Simulation of a model defined with algebraic equations at the 
    population level}
A simple PK/PD model defined with algebraic equatons is simulated at the 
population in this example . The PK model describes the drug concentration 
\(C_p\) using a one-compartment model with linear elimination after a single 2h 
infusion. The response \(E\) is related to \(C_p\) by a direct effect Imax model:
\begin{displaymath}
\begin{array}{l}
  C_p(t) = \frac{infusion \, rate}{CL} \cdot{} \bigg(
     1-H(t-2) \cdot{} \Big(
       1-e^{-\frac{CL}{V_c} \cdot{}(t-2)} 
       \Big)
     - e^{-\frac{CL}{V_c}\cdot{}t}
     \bigg)\\ 
   E(t)= E_0\cdot\Big(1-\frac{I_{max}\cdot{}C_p(t)}{IC_{50}+C_p(t)}\Big)
\end{array}
\end{displaymath}

where \(H\) is the Heaviside function, \(CL\) the elimination clearance, \(V_c\) 
the volume of distribution, \(E_0\) the baseline response, \(I_{max}\) the 
maximum inhibition factor, and \(IC_{50}\) the half-inhibitory concentration.

Note that because this is a simulation, there is no need for a \$VARIANCE block.

\subsection{Example 2: Simulation of inputs into a model defined with ordinary
    differential equations}
This example uses a model defined by a system of 2 ordinary differential 
equations to illustrate how inputs are automatically assigned and scaled to 
system states. Because both states have null initial conditions and gradients,
the output of the model represents the cumulative scaled amount of drug assigned 
to each state based upon the information provided in the dataset.

\subsection{Example 3: Simulation of a model defined with ordinary differential 
    equations at the population level}
    
\begin{center}
  \includegraphics{tmdd.pdf} %[width=50mm,height=50mm]
\end{center}

A target-mediated disposition model for interferon-\(\beta\)1a pharmacokinetics
in monkey was described by Mager and colleagues \cite{Mager.2003}. This model is 
simulated at the population level in example 3 using the following system of 
differential equations:
\begin{displaymath}
  \begin{array}{l l l}
    & SC & IV\\
    \frac{dA_D}{dt}=-k_a\cdot{}A_D & A_D(0)=F\cdot{}D_{SC} & A_D(0)=0\\
    \frac{dA_L}{dt}=k_a\cdot{}A_D - k_{a2}\cdot{}A_L & A_L(0)=0 &
      A_L(0)=0\\
    \frac{dA_P}{dt}=k_{a2}\cdot{}A_L + k_{tp}\cdot{}A_T + k_{off}\cdot{}DR
      - (k_{on}/V_c)\cdot{}A_{P}\cdot{}R - & A_{P}(0)=0 & A_{P}(0)=D_{IV}\\
    \quad{} \quad{} (k_{pt}+k_{loss})\cdot{}A_P & & \\
    \frac{dA_T}{dt}= k_{pt}\cdot{}A_P - k_{tp}\cdot{}A_T & A_{T}(0)=0 & 
      A_{T}(0)=0\\
    \frac{dDR}{dt}=(k_{on}/V_c)\cdot{}A_{P}\cdot{}R - (k_{off}+k_{int})\cdot{}DR 
      & DR(0)=0 & DR(0)=0\\
    R=R_{max}-DR & &\\
  \end{array}
\end{displaymath}

where \(A_D\), \(A_L\), \(A_P\), and \(A_T\) are the amounts of drug in the 
subcutaneous depot, lymph, central, and peripheral compartments and \(DR\) is 
the concentration of drug-receptor complex. The noteworthy features of this 
example are:
\begin{itemize}
  \item how dose information is extracted from the vector of covariate DOSE to 
    define the scaling bioavailability factor \(F\) in the \$DERIVED block,
  \item how the TRT variable is used in the dataset to define the different 
    dosing regimens (3 different dose levels administered by single 
    sub-cutaneous or intravenous dosing), and to avoid the duplication of the 
    model equations, and
  \item how the output of the system of differential equations is subset and
    transformed to just extract the predicted concentration in the central
    compartment in the \$OUTPUT block.
\end{itemize}

\subsection{Example 4: Simulation of a model defined with delay differential 
    equations at the population level}
This example features a 2-compartment model with linear inter-compartment
distribution but with a delayed entry of the drug into the peripheral 
compartment. The system can described by the following equations:
\begin{displaymath}
\begin{array}{l l}
  \frac{dA_P}{dt}=-(k_e+k_{pt})\cdot{}A_P(t) + k_{tp}\cdot{}A_T(t) & A_P(0)=0\\
  \frac{dA_T}{dt}= k_{pt}\cdot{}A_P(t-xyz) - k_{tp}\cdot{}A_T & A_T(0)=0
\end{array}
\end{displaymath}
where \(A_P\) and \(A_T\) are the amounts of drug in the central and peripheral 
compartments and \(xyz\) is the delay of entry into the peripheral compartment.

This system is simulated at the population level assuming repeated bolus 
administrations is the central compartment. The noteworthy features of this 
example are:
\begin{itemize}
  \item how derived rate constants are computed in the \$DERIVED block using the
    clearance and volume parameters defined in the parameter file,
  \item how the delay \(xyz\) is directly available in the system of delay 
    differential equations, because it was defined as a 'L' parameter in the 
    parameter file, and
  \item how a variance model is defined in the \$VARIANCE block but not used for 
    the simulation (this could be useful, if the same model is then used in an
    estimation analysis).
\end{itemize}

\subsection{Example 5: Estimation of a model defined with algebraic equations at 
    the population level}
This example estimates the parameters of the Example 1 model using the 
observations provided in the Example 1 dataset and the na\"ive pooling approach. 
The model file was however modified to include the variance models of the 
concentrations and responses. Note that the concentrations were initially 
log-transformed in the dataset to fit the original data with log residual 
variability model. Consistently, the predicted \(C_P\) concentrations are 
log-transformed before assigned as the first raw of \(y\).

\subsection{Example 6: Simulation of a model defined with ordinary differential 
    equations at the subject level}
\begin{center}
  \includegraphics[width=3.5in]{precursor.pdf}
\end{center}
In this example, a precursor turn-over model is simulated at the subject level. 
The rate of transformation of the precursor \(P\) into response \(R\) is 
inhibited by the drug concentration \(C_p\). The changes in drug concentration,
precursor and response are described by the following equations:
\begin{displaymath}
\begin{array}{l l}
  \frac{dC_P}{dt}=-k_e\cdot{}C_P(t) & C_P(0)=D/V_c\\
  \frac{dP}{dt}= k_{in}-
    k_t\cdot{}(1-\frac{I_{max}\cdot{}C_p}{IC_{50}+C_p})\cdot{}P & P(0)=R_0\\
  \frac{dR}{dt}= k_t\cdot{}(1-\frac{I_{max}\cdot{}C_p}{IC_{50}+C_p})\cdot{}P -
    k_{out}\cdot{}R & R(0)=R_0
\end{array}
\end{displaymath}

\subsection{Example 7: Estimation of a model defined with algebraic equations at 
    the subject level}
WARNING: this example can be time consuming.

This example estimates the parameters of the Example 1 model using the 
observations provided in the Example 1 dataset and the standard two-stage 
approach. The model file was however modified to include the variance models of 
the concentrations and responses. Note that the concentrations were initially 
log-transformed in the dataset to fit the original data with log residual 
variability model. Consistently, the predicted \(C_P\) concentrations are 
log-transformed before assigned as the first raw of \(y\).

\subsection{Example 8: Direct grid search for a model defined with delay 
    differential equations}
WARNING: this example can be time consuming.

This example illustrates how direct grid search can be performed using a 
life-span model for paclitaxel (\(C_P\)) on leukocytes counts in cancer patient
\cite{Krzyzanski.2002}.

\begin{center}
  \includegraphics{leuko.pdf}
\end{center}

Normalized leukocyte counts (\(R_\%\)) collected in one patient were
digitized and a direct grid search run is performed to improve the estimates
roughly chosen for the PD parameters (\(C_P\) is assumed to be accurately
described by the parameter estimates obtained for a 3-compartment model). The
paclitaxel effect is modeled with the following delay differential equation:
\begin{displaymath}
  \begin{matrix}
  \frac{dR_\%}{dt}=k_{in\%} \cdot{} \Big( 
    e^{-\int_{t-T_P-T_M}^{t-T_M} f\big(C_P(z)\big)dz}
    - e^{-\int_{t-T_P-T_M-T_R}^{t-T_M-T_R} f\big(C_P(z)\big)dz}
  \Big)\\
  f\big(C_P\big)=\frac{K_{max} \cdot{} C_P}{KC_{50} + C_P}
  \end{matrix}
\end{displaymath}

The grid is formed by combining 3 grid points per variable parameters (\(T_P\),
\(T_M\), \(K_{max}\) and \(KC_{50}\)) and by setting the scaling factor to 2 for
all parameters. \(T_R\) was fixed as described in \cite{Krzyzanski.2002}. The 
best solutions found by direct grid search is finally compared to the reported 
estimates.

\cleardoublepage
\section{References}
% Bibliography
\bibliographystyle{plain}
\renewcommand*{\refname}{}
\bibliography{scaRabee}

\cleardoublepage
\section{Network of \scaRabee{} functions}
\begin{figure}[h!]
  \begin{center}  
  \includegraphics[trim=25mm 25mm 25mm 25mm,clip]{scaRabee_network_1.pdf}
    \caption{Map of the functions distributed with scaRabee (1/2)}
    \label{scaRabeemap}
  \end{center}
\end{figure}
\begin{figure}[h!]
  \begin{center}
  \includegraphics[angle=-90, trim=25mm 25mm 25mm 25mm,clip]{scaRabee_network_2.pdf}
    \caption{Map of the functions distributed with scaRabee (2/2)}
    \label{scaRabeemap2}
  \end{center}
\end{figure}

\cleardoublepage
\section{Help on \scaRabee{} functions}
\input{scaRabee-package.tex}
\input{bound.parameters.tex}
\input{compute.secondary.tex}
\input{convert.infusion.tex}
\input{create.intervals.tex}
\input{dde.model.tex}
\input{dde.utils.tex}
\input{estimation.plot.tex}
\input{examples.data.tex}
\input{explicit.model.tex}
\input{finalize.grid.report.tex}
\input{finalize.report.tex}
\input{fitmle.cov.tex}
\input{fitmle.tex}
\input{get.cov.matrix.tex}
\input{get.events.tex}
\input{get.layout.tex}
\input{get.param.data.tex}
\input{get.parms.data.tex}
\input{get.secondary.tex}
\input{initialize.report.tex}
\input{ode.model.tex}
\input{ode.utils.tex}
\input{order.param.list.tex}
\input{order.parms.list.tex}
\input{pder.tex}
\input{problem.eval.tex}
\input{residual.report.tex}
\input{scarabee.analysis.tex}
\input{scarabee.check.model.tex}
\input{scarabee.check.reserved.tex}
\input{scarabee.clean.tex}
\input{scarabee.directory.tex}
\input{scarabee.gridsearch.tex}
\input{scarabee.new.tex}
\input{scarabee.read.data.tex}
\input{scarabee.read.model.tex}
\input{scarabee.read.parms.tex}
\input{simulation.plot.tex}
\input{simulation.report.tex}
\input{weighting.tex}


\cleardoublepage
\section{GNU Free Documentation License}
\begin{verbatim}

                GNU Free Documentation License
                 Version 1.3, 3 November 2008


 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <http://fsf.org/>
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.

This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.


1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License.  Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein.  The "Document", below,
refers to any such manual or work.  Any member of the public is a
licensee, and is addressed as "you".  You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall
subject (or to related matters) and contains nothing that could fall
directly within that overall subject.  (Thus, if the Document is in
part a textbook of mathematics, a Secondary Section may not explain
any mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.  If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant.  The Document may contain zero
Invariant Sections.  If the Document does not identify any Invariant
Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.  A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text.  A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification.  Examples of
transparent image formats include PNG, XCF and JPG.  Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

The "publisher" means any person or entity that distributes copies of
the Document to the public.

A section "Entitled XYZ" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language.  (Here XYZ stands for a
specific section name mentioned below, such as "Acknowledgements",
"Dedications", "Endorsements", or "History".)  To "Preserve the Title"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document.  These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no
other conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.


3. COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to
give them a chance to provide you with an updated version of the
Document.


4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct
   from that of the Document, and from those of previous versions
   (which should, if there were any, be listed in the History section
   of the Document).  You may use the same title as a previous version
   if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
   responsible for authorship of the modifications in the Modified
   Version, together with at least five of the principal authors of the
   Document (all of its principal authors, if it has fewer than five),
   unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
   Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
   adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
   giving the public permission to use the Modified Version under the
   terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
   and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add
   to it an item stating at least the title, year, new authors, and
   publisher of the Modified Version as given on the Title Page.  If
   there is no section Entitled "History" in the Document, create one
   stating the title, year, authors, and publisher of the Document as
   given on its Title Page, then add an item describing the Modified
   Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
   public access to a Transparent copy of the Document, and likewise
   the network locations given in the Document for previous versions
   it was based on.  These may be placed in the "History" section.
   You may omit a network location for a work that was published at
   least four years before the Document itself, or if the original
   publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
   Preserve the Title of the section, and preserve in the section all
   the substance and tone of each of the contributor acknowledgements
   and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
   unaltered in their text and in their titles.  Section numbers
   or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements".  Such a section
   may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
   or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.


5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications".  You must delete all sections
Entitled "Endorsements".


6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other
documents released under this License, and replace the individual
copies of this License in the various documents with a single copy
that is included in the collection, provided that you follow the rules
of this License for verbatim copying of each of the documents in all
other respects.

You may extract a single document from such a collection, and
distribute it individually under this License, provided you insert a
copy of this License into the extracted document, and follow this
License in all other respects regarding verbatim copying of that
document.


7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.


8. TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers.  In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.


9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.

Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.

Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.


10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the
GNU Free Documentation License from time to time.  Such new versions
will be similar in spirit to the present version, but may differ in
detail to address new problems or concerns.  See
http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.  If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy's public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.

11. RELICENSING

"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works.  A
public wiki that anybody can edit is an example of such a server.  A
"Massive Multiauthor Collaboration" (or "MMC") contained in the site
means any set of copyrightable works thus published on the MMC site.

"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 
license published by Creative Commons Corporation, a not-for-profit 
corporation with a principal place of business in San Francisco, 
California, as well as future copyleft versions of that license 
published by that same organization.

"Incorporate" means to publish or republish a Document, in whole or in 
part, as part of another Document.

An MMC is "eligible for relicensing" if it is licensed under this 
License, and if all works that were first published under this License 
somewhere other than this MMC, and subsequently incorporated in whole or 
in part into the MMC, (1) had no cover texts or invariant sections, and 
(2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.


ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:

    Copyright (c)  YEAR  YOUR NAME.
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GNU Free Documentation License, Version 1.3
    or any later version published by the Free Software Foundation;
    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
    A copy of the license is included in the section entitled "GNU
    Free Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with...Texts." line with this:

    with the Invariant Sections being LIST THEIR TITLES, with the
    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.

\end{verbatim}

\end{document}
