\HeaderA{forwsim}{Forward Simulation to evaluate sequential boundaries in 1 group binomial design.}{forwsim}
\keyword{~kwd1}{forwsim}
\begin{Description}\relax
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.
\end{Description}
\begin{Usage}
\begin{verbatim}
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)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{dta.N}] Batch size. Posterior moments are obtained after every \code{dta.N} patients have been recruited into each treatment arm.
\item[\code{th.u}] Prior for success probability \code{theta \textasciitilde{} Beta(th.u,th.v)}.
\item[\code{th.v}] Prior for success probability \code{theta \textasciitilde{} Beta(th.u,th.v)}.
\item[\code{th.au}] Hyperprior \code{th.u \textasciitilde{} 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[\code{th.bu}] Hyperprior \code{th.u \textasciitilde{} 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[\code{th.av}] Hyperprior \code{th.v \textasciitilde{} 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[\code{th.bv}] Hyperprior \code{th.v \textasciitilde{} 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[\code{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[\code{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[\code{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[\code{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[\code{dsg.patlimit}] Maximum number of patients available at any time point. The default \code{-1} means there's no limit. 
\item[\code{dsg.kini}] Initial number of treatments.
\item[\code{dsg.c0}] Coefficient for utility function representing the fixed cost of performing a phase III study. See Details section.
\item[\code{dsg.c1}] Coefficient for utility function representing the sampling cost of 1 patient. See Details section. 
\item[\code{dsg.c2}] Coefficient for utility function representing the pay-off for significant phase III result. See Details section.
\item[\code{dsg.p0}] Value of theta under H0 for phase III (e.g. success probability for standard of care)
\item[\code{dsg.a}] Type I error to be used when designing future studies (used for sample size calculation).
\item[\code{dsg.b}] Type II error to be used when designing future studies (used for sample size calculation).
\item[\code{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[\code{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[\code{mc.nsim}] Number of forward simulations.
\item[\code{mc.nt}] Time horizon in forward simulation expressed in number of batches.
\item[\code{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[\code{b0grid}] Grid on \code{b0}, specified as initial term, final term and number of points in the grid.
\item[\code{b1grid}] Grid on \code{b0}, specified as initial term, final term and number of points in the grid.
\item[\code{b2grid}] Grid on \code{b0}, specified as initial term, final term and number of points in the grid.
\item[\code{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[\code{dir}] Directory where output files will be written to.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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.
\end{Details}
\begin{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.

\begin{ldescription}
\item[\code{init.dsg}] Design specification. The values of all the arguments passed to the function are saved to this file.
\item[\code{b0.sim}] Sequence of values of \code{b0} that were used to construct the grid.
\item[\code{b1.sim}] Sequence of values of \code{b1} that were used to construct the grid.
\item[\code{b2.sim}] Sequence of values of \code{b2} that were used to construct the grid.
\item[\code{dt.sim}] Mean number of patients tested with each treatment.
\item[\code{errorI.sim}] Estimated type I error rates.
\item[\code{errorII.sim}] Estimated type II error rates.
\item[\code{mc.dsg}] Number of treatments in each simulation.
\item[\code{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[\code{n3.sim}] Mean sample size of future confirmatory study amongst treatments that were recommended for further study.
\item[\code{nreco.sim}] Mean number of recommended treatments.
\item[\code{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[\code{pB.sim}] Mean posterior probability that future trial gives significant result.
\item[\code{term.sim}] Terminal decisions and posterior moments for sample trajectories indicated in \code{uhat.save}.
\item[\code{th.dsg}] Values of the success probability \code{theta} used in each of the simulations.
\item[\code{traj.dsg}] Some sample posterior moment trajectories saved for the boundary indicated in \code{uhat.save}.
\item[\code{U.sim}] Estimated expected utility.
\end{ldescription}
\end{Value}
\begin{Author}\relax
David Rossell, Peter Mueller.
\end{Author}
\begin{References}\relax
Rossell D, Mueller P, Rosner G. Screening Designs for Drug Development.
\end{References}
\begin{SeeAlso}\relax
\LinkA{read.forwsim}{read.forwsim}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}

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

\end{ExampleCode}
\end{Examples}

