% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/select_mtpi2_mtd.R
\name{select_mtpi2_mtd}
\alias{select_mtpi2_mtd}
\title{Select dose by mTPI2's MTD-choosing algorithm.}
\usage{
select_mtpi2_mtd(
  parent_selector_factory,
  when = c("finally", "always"),
  target = NULL,
  exclusion_certainty,
  alpha = 1,
  beta = 1,
  ...
)
}
\arguments{
\item{parent_selector_factory}{Object of type \code{\link{selector_factory}}.}

\item{when}{Either of: 'finally' to select dose only when the parent
dose-selector has finished, by returning continue() == FALSE; or 'always'
to use this dose-selection algorithm for every dose decision. As per the
authors' original intentions, the default is 'finally'.}

\item{target}{We seek a dose with this probability of toxicity. If not
provided, the value will be sought from the parent dose-selector.}

\item{exclusion_certainty}{Numeric, threshold posterior certainty required to
exclude a dose for being excessively toxic. The authors discuss values in the
range 0.7 - 0.95. Set to a value > 1 to suppress the dose exclusion
mechanism. The authors use the Greek letter xi for this parameter.}

\item{alpha}{First shape parameter of the beta prior distribution on the
probability of toxicity.}

\item{beta}{Second shape parameter of the beta prior distribution on the
probability of toxicity.}

\item{...}{Extra args are passed onwards.}
}
\value{
an object of type \code{\link{selector_factory}}.
}
\description{
This method selects dose by the algorithm for identifying the maximum
tolerable dose (MTD) described in Guo et al. (2017). This class is intended
to be used when a mTPI2 trial has reached its maximum sample size. Thus, it
intends to make the final dose recommendation after the regular mTPI2 dose
selection algorithm, as implemented by \code{\link{get_mtpi2}}, including any
additional behaviours that govern stopping (etc), has gracefully concluded a
dose-finding trial. However, the class can be used in any scenario where
there is a target toxicity rate. See Examples. Note - this class will not
override the parent dose selector when the parent is advocating no dose. Thus
this class will not reinstate a dangerous dose.
}
\examples{
# This class is intended to make the final dose selection in a mTPI2 trial:
target <- 0.25
model <- get_mtpi2(num_doses = 5, target = target,
                   epsilon1 = 0.05, epsilon2 = 0.05,
                   exclusion_certainty = 0.95) \%>\%
  stop_at_n(n = 12) \%>\%
  select_mtpi2_mtd(exclusion_certainty = 0.95)

outcomes <- '1NNN 2NTN 2NNN 3NTT'
model \%>\% fit(outcomes) \%>\% recommended_dose()

# However, since behaviour is modular in this package, we can use this method
# to select dose at every dose decision if we wanted:
model2 <- get_mtpi2(num_doses = 5, target = target,
                    epsilon1 = 0.05, epsilon2 = 0.05,
                    exclusion_certainty = 0.95) \%>\%
  select_mtpi2_mtd(when = 'always', exclusion_certainty = 0.95)
model2 \%>\% fit('1NNT') \%>\% recommended_dose()
model2 \%>\% fit('1NNN 2NNT') \%>\% recommended_dose()

# and with any underlying model:
skeleton <- c(0.05, 0.1, 0.25, 0.4, 0.6)
model3 <- get_dfcrm(skeleton = skeleton, target = target) \%>\%
  select_mtpi2_mtd(when = 'always', exclusion_certainty = 0.95)
model3 \%>\% fit('1NNT') \%>\% recommended_dose()
model3 \%>\% fit('1NNN 2NNT') \%>\% recommended_dose()

}
\references{
Guo, W., Wang, SJ., Yang, S., Lynn, H., Ji, Y. (2017).
A Bayesian Interval Dose-Finding Design Addressing Ockham's Razor: mTPI-2.
https://doi.org/10.1016/j.cct.2017.04.006
}
