\name{forwsim}
\alias{forwsim}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{ Forward Simulation to evaluate sequential boundaries in 1 group binomial design. }
\description{
  Estimates the expected utility of using boundaries on the posterior (mean,standard deviation) space as a stopping criteria
in a sequential experiment with 1 group binomial data. 
The utility can incorporate the fixed cost of performing a study, sampling cost and a pay-off if a future confirmatory study
gives significant results. See Details section for more information about the utility.

Also, empirical type I & II error rates, sample size and other quantities are saved. 
Each boundary being identified by \code{(b0,b1,b2)}, the utility is estimated for a grid containing combinations of \code{(b0,b1,b2)} values.
}
\usage{
forwsim(dta.N = 2, th.u = 1, th.v = 1, th.au = 3, th.bu = 1, th.av = 3, th.bv = 1, dsg.uth = 0, dsg.hyper = FALSE, dsg.pool = FALSE, 
dsg.logsd = TRUE, dsg.patlimit = -1, dsg.kini = 1, dsg.c0 = 0, dsg.c1 = 1, dsg.c2 = 10000, dsg.p0 = 0.5, dsg.a = 0.05, dsg.b = 0.1, dsg.s0 = 0.05, dsg.s1 = 0.1, 
mc.nsim = 100, mc.nt = 100, mc.pk = c(0.7, 0.2, 0.05, 0.05), b0grid = c(0.5, 0.9, 20), b1grid = c(0.7, 1.7, 20), b2grid = c(0, 0.8, 20), 
uhat.bsave = rep(1, 3), dir)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{dta.N}{ Batch size. Posterior moments are obtained after every \code{dta.N} patients have been recruited into each treatment arm.}
\item{th.u}{ Prior for success probability \code{theta ~ Beta(th.u,th.v)}.}
\item{th.v}{ Prior for success probability \code{theta ~ Beta(th.u,th.v)}.}
\item{th.au}{ Hyperprior \code{th.u ~ Gamma(th.au,th.bu)} (mean is \code{th.au/th.bu}). Ignored if \code{dsg.hyper} and \code{dsg.pool} set to \code{FALSE}.}
\item{th.bu}{ Hyperprior \code{th.u ~ Gamma(th.au,th.bu)} (mean is \code{th.au/th.bu}). Ignored if \code{dsg.hyper} and \code{dsg.pool} set to \code{FALSE}.}
\item{th.av}{ Hyperprior \code{th.v ~ Gamma(th.av,th.bv)} (mean is \code{th.av/th.bv}). Ignored if \code{dsg.hyper} and \code{dsg.pool} set to \code{FALSE}.}
\item{th.bv}{ Hyperprior \code{th.v ~ Gamma(th.av,th.bv)} (mean is \code{th.av/th.bv}). Ignored if \code{dsg.hyper} and \code{dsg.pool} set to \code{FALSE}.}
\item{dsg.uth}{ Indicates what utility function to use. 0: use posterior mean in utility evaluation; 1: use true theta; 2: drop terms related to a future study from utility. See Details section.}
\item{dsg.hyper}{ If set to \code{TRUE} hyper-parameters \code{th.u,th.v} are fixed in the simulation. If set to \code{FALSE} \code{u,v} are simulated from hyper-priors.}
\item{dsg.pool}{ If set to \code{TRUE} at the time of analysis pooling is performed (via empirical Bayes). If set to \code{FALSE} hyper-prior is ignored at the time of analysis.}
\item{dsg.logsd}{ If set to \code{TRUE} the decision boundaries are linear in log(SD). If set to \code{FALSE} boundaries are linear in SD}
\item{dsg.patlimit}{ Maximum number of patients available at any time point. The default \code{-1} means there's no limit. }
\item{dsg.kini}{ Initial number of treatments.}
\item{dsg.c0}{ Coefficient for utility function representing the fixed cost of performing a phase III study. See Details section.}
\item{dsg.c1}{ Coefficient for utility function representing the sampling cost of 1 patient. See Details section. }
\item{dsg.c2}{ Coefficient for utility function representing the pay-off for significant phase III result. See Details section.}
\item{dsg.p0}{ Value of theta under H0 for phase III (e.g. success probability for standard of care)}
\item{dsg.a}{ Type I error to be used when designing future studies (used for sample size calculation).}
\item{dsg.b}{ Type II error to be used when designing future studies (used for sample size calculation).}
\item{dsg.s0}{ Value of the posterior standard deviation (in log scale) at which the upper and lower boundaries cross, i.e. any treatment with posterior SD < \code{dsg.c0} is terminated.}
\item{dsg.s1}{ \code{b1} and \code{b2} are the values of the upper and lower boundaries when posterior SD is equal to \code{dsg-s1}.}
\item{mc.nsim}{ Number of forward simulations.}
\item{mc.nt}{ Time horizon in forward simulation expressed in number of batches.}
\item{mc.pk}{ Vector indicating probabilities of 0,1,2... new treatments arising at any point in time. Set to \code{1} for no new treatments to arise.}
\item{b0grid}{ Grid on \code{b0}, specified as initial term, final term and number of points in the grid.}
\item{b1grid}{ Grid on \code{b0}, specified as initial term, final term and number of points in the grid.}
\item{b2grid}{ Grid on \code{b0}, specified as initial term, final term and number of points in the grid.}
\item{uhat.bsave}{ Index for \code{b0grid,b1grid,b2grid}. For the corresponding \code{(b0,b1,b2)} value extra information will be saved (trajectories, posterior moments etc.)}
\item{dir}{ Directory where output files will be written to.}
}
\details{

Three different forms for the utility function are available to the user by specifying the parameter \code{dsg.uth}.

\code{dsg.uth==0: utility = - c1*(nb. pat. in screening study) + (c2*P(significant result in future study|data)*(E(theta|data)-dsg.p0) - c0)*I(future study is performed)}

\code{dsg.uth==1: utility = - c1*(nb. pat. in screening study) + (c2*P(significant result in future study|data)*(theta-dsg.p0) - c0)*I(future study is performed)}

\code{dsg.uth==2: utility = - c1*(nb. pat. in screening study)}

The simulation starts with \code{dsg.kini} treatments, with new treatments arising over time with probabilities specified by \code{dsg.pk}.
For each treatment a success probability is generated from a Beta prior with parameters \code{(th.u,th.v)},
which in turn are drawn from Gamma hyper-priors if \code{dsg.hyper} is set to \code{TRUE} and they're fixed if \code{dsg.hyper} is set to \code{FALSE}.
Then data is observed for each treatment in batches of \code{dta.N} until the time horizon of \code{mc.nt} batches is reached.

Each time \code{dta.N} new observations are available, posterior moments for each treatment are compared with the boundaries.
A treatment is stopped whenever either the upper or lower boundary is crossed, and at that time a terminal decision is taken:
to recommend the treament for further study or to discard it.
If \code{dsg.uth} is set to 1 or 2 a treatment recommended whenever the expected benefits of conducting a further study are higher
than the expected costs. If \code{dsg.uth} is set to 3 a treatment is recommended if its posterior moments trajectory crossed the
upper boundary and discarded if it crossed the lower boundary.

}
\value{
No results are returned directly; instead they are saved in file into the directory specified by \code{dir}.
Use function \code{read.forwsim} to read in the results.

  \item{init.dsg}{Design specification. The values of all the arguments passed to the function are saved to this file.}
  \item{b0.sim}{Sequence of values of \code{b0} that were used to construct the grid.}
  \item{b1.sim}{Sequence of values of \code{b1} that were used to construct the grid.}
  \item{b2.sim}{Sequence of values of \code{b2} that were used to construct the grid.}
  \item{dt.sim}{Mean number of patients tested with each treatment.}
  \item{errorI.sim}{Estimated type I error rates.}
  \item{errorII.sim}{Estimated type II error rates.}
  \item{mc.dsg}{Number of treatments in each simulation.}
  \item{mse.sim}{Estimated Mean Squared Error. When a treatment is stopped the squared difference between the posterior mean and the true parameter value is computed, and the mean over all treatments and simulations is saved in this file.}
  \item{n3.sim}{Mean sample size of future confirmatory study amongst treatments that were recommended for further study.}
  \item{nreco.sim}{Mean number of recommended treatments.}
  \item{ntoreco.sim}{Mean number of patients / number of recommended treatments. Since number of recommended treatments can be zero, this quantity can be \code{Inf}. To avoid this problem increase the time horizon \code{mc.nt}}
  \item{pB.sim}{Mean posterior probability that future trial gives significant result.}
  \item{term.sim}{Terminal decisions and posterior moments for sample trajectories indicated in \code{uhat.save}.}
  \item{th.dsg}{Values of the success probability \code{theta} used in each of the simulations.}
  \item{traj.dsg}{Some sample posterior moment trajectories saved for the boundary indicated in \code{uhat.save}.}
  \item{U.sim}{Estimated expected utility.}

}
\references{ Rossell D, Mueller P, Rosner G. Screening Designs for Drug Development. }
\author{ David Rossell, Peter Mueller. }
\seealso{ \link{read.forwsim} }

\examples{

dir <- 'c:/projects/forwsim'                                            #set directory where results will be saved

# run forward simulation
forwsim(dta.N=2,th.u=1,th.v=1,th.au=3,th.bu=1,th.av=3,th.bv=1,dsg.uth=0,dsg.hyper=TRUE,dsg.pool=TRUE,dsg.logsd=FALSE,dsg.kini=1,
dsg.c0=0,dsg.c1=1,dsg.c2=10000,dsg.p0=0.5,dsg.a=.05,dsg.b=.1,dsg.s0=.05,dsg.s1=.1,mc.nsim=1,mc.nt=100,mc.pk=c(.7,.2,.05,.05),
b0grid=c(.5,.9,20),b1grid=c(.7,1.7,20),b2grid=c(0,.8,20),uhat.bsave=c(8,5,14),dir)

sim1 <- read.forwsim(dir)                                               #read forward simulation results

opt1 <- optbound(sim1,errImax=1,errIImax=1,util='u',smooth=FALSE)       #unconstrained optimization

}
\keyword{ ~kwd1 }% at least one, from doc/KEYWORDS

