% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/augmentLHS.R
\name{augmentLHS}
\alias{augmentLHS}
\title{Augment a Latin Hypercube Design}
\usage{
augmentLHS(lhs, m = 1)
}
\arguments{
\item{lhs}{The Latin Hypercube Design to which points are to be added.
Contains an existing latin hypercube design with a number of rows equal
to the points in the design (simulations) and a number of columns equal
to the number of variables (parameters).  The values of each cell must be
between 0 and 1 and uniformly distributed}

\item{m}{The number of additional points to add to matrix \code{lhs}}
}
\value{
An \code{n} by \code{k} Latin Hypercube Sample matrix with values
uniformly distributed on [0,1]
}
\description{
Augments an existing Latin Hypercube Sample, adding points to the design, while
maintaining the \emph{latin} properties of the design.
}
\details{
Augments an existing Latin Hypercube Sample, adding points to the design, while
maintaining the \emph{latin} properties of the design.  Augmentation is perfomed
in a random manner.

The algorithm used by this function has the following steps.
First, create a new matrix to hold the candidate points after the design has
been re-partitioned into \eqn{(n+m)^{2}}{(n+m)^2} cells, where n is number of
points in the original \code{lhs} matrix.  Then randomly sweep through each
column (1\ldots\code{k}) in the repartitioned design to find the missing cells.
For each column (variable), randomly search for an empty row, generate a
random value that fits in that row, record the value in the new matrix.
The new matrix can contain more filled cells than \code{m} unles \eqn{m = 2n},
in which case the new matrix will contain exactly \code{m} filled cells.
Finally, keep only the first m rows of the new matrix.  It is guaranteed to
have \code{m} full rows in the new matrix.  The deleted rows are partially full.
The additional candidate points are selected randomly due to the random search
for empty cells.
}
\examples{
set.seed(1234)
a <- randomLHS(4,3)
b <- augmentLHS(a, 2)
}
\references{
Stein, M.  (1987) Large Sample Properties of Simulations Using Latin
Hypercube Sampling. \emph{Technometrics}. \bold{29}, 143--151.
}
\seealso{
[randomLHS()], [geneticLHS()], [improvedLHS()], [maximinLHS()],
and [optimumLHS()] to generate Latin Hypercube Samples.  [optAugmentLHS()]
and [optSeededLHS()] to modify and augment existing designs.
}
\author{
Rob Carnell
}
\keyword{design}
