% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/PM_opt.R
\name{PM_opt}
\alias{PM_opt}
\title{Optimal Sample Times}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}

Contains optimal sampling times for a given model and dosage regimen.
}
\details{
This object contains
the methods to create and results from optimal sampling algorithms.
Currently the only option multiple-model optimization.
This algorithm calculates the
requested number of sample times where the concentration time profiles
are the most separated, thereby minimizing the risk of choosing the incorrect
Bayesian posterior for an individual. Future updates will add D-optimal
sampling times.
}
\references{
Bayard, David S. & and Neely, Michael. (2017). Experiment
Design for Nonparametric
Models Based on Minimizing Bayes Risk: Application to Voriconazole.
\emph{Journal of Pharmacokinetics and Pharmacodynamics}, \bold{44}(2): 95–111.
\url{https://doi.org/10.1007/s10928-016-9498-5}.
}
\author{
Michael Neely
}
\section{Public fields}{
  \if{html}{\out{<div class="r6-fields">}}
  \describe{
    \item{\code{sampleTime}}{The optimal sample times, based on requested \code{type}
argument to \verb{$new} creation method.}

    \item{\code{bayesRisk}}{Only present for MM-optimal sampling.
The Bayesian risk of mis-classifying a subject based on
the sample times.  This is more useful for comparisons between sampling
strategies, with minimization the goal.}

    \item{\code{simdata}}{A \link{PM_sim} object with the simulated profiles}

    \item{\code{mmInt}}{A list with the \code{mmInt} values, \code{NULL} if \code{mmInt} argument
to \verb{$new} is missing.}
  }
  \if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
  \itemize{
    \item \href{#method-PM_opt-initialize}{\code{PM_opt$new()}}
    \item \href{#method-PM_opt-plot}{\code{PM_opt$plot()}}
    \item \href{#method-PM_opt-print}{\code{PM_opt$print()}}
    \item \href{#method-PM_opt-clone}{\code{PM_opt$clone()}}
  }
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_opt-initialize"></a>}}
\if{latex}{\out{\hypertarget{method-PM_opt-initialize}{}}}
\subsection{\code{PM_opt$new()}}{
  \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}

Determine optimal sample times which are the most informative about the
model parameters.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_opt$new(
  poppar,
  model,
  data,
  nsamp = 1,
  weight = list(none = 1),
  predInt = 0.5,
  mmInt,
  algorithm = "mm",
  outeq = 1,
  ...
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{poppar}}{There are several choices for the population parameters.
\itemize{
\item A \link{PM_sim} object, in which case the simulated data will be used to calculate optimal sampling times.
Here \code{model} and \code{data} are not required, as they will be extracted from the \link{PM_sim} object.
\item A \link{PM_result} loaded with \link{PM_load}, in which case the \verb{$final} field
will be used, e.g. \code{run1 <- PM_load(1)} and \code{poppar = run1}.
\item A \link{PM_final} object, typically as a field in a \link{PM_result}, e.g.,
\code{poppar = run1$final}.
\item A data frame of support points in rows, where the columns contain the parameter values for each support point.
The first row has the parameter names.
Compatible \code{model} and \code{data} objects must be specified to simulate the output profiles from each support point.
\item A list containing three items in this order,
but of any name: vector of weights, vector of mean parameter values, and a
covariance matrix. If only one distribution is to be specified the
\code{weights} vector should be of length 1 and contain a 1. If multiple
distributions are to be sampled, the \code{weights} vector should be of
length equal to the number of distributions and its values should sum to 1,
e.g. \code{c(0.25,0.05,0.7)}.  The means matrix may be a vector for a
single distribution, or a matrix with \code{length(weights)} rows and
number of columns equal to the number of parameters.
Compatible \code{model} and \code{data} objects must be specified to simulate the output profiles from the support points
generated by sampling from the specified distributions.
}}
      \item{\code{model}}{A \link{PM_model} object, required or optional depending on the \code{poppar} argument.
\itemize{
\item When \code{poppar} is a \link{PM_sim} object, \code{model} is ignored.
\item When \code{poppar} is a \link{PM_result} object, \code{model} is optional.
If missing, the model from the \verb{$model} field of the \link{PM_result} will be used. If specified, \code{model}
must be compatible with the primary support point parameter names and values in \code{poppar}.
\item When \code{poppar} is a \link{PM_final} object, \code{model} is mandatory and must be compatible with the
primary support point parameter names and values in \code{poppar}.
\item When \code{poppar} is a data frame of support points, \code{model} is mandatory and must be compatible with the
parameter names and values in the data frame.
\item When \code{poppar} is a list of weights, means, and covariance, \code{model} is mandatory and must be compatible with the
parameter names and values.
}}
      \item{\code{data}}{A \link{PM_data} object, required or optional depending on the \code{poppar} argument.
\itemize{
\item When \code{poppar} is a \link{PM_sim} object, \code{data} is ignored.
\item When \code{poppar} is a \link{PM_result} object, \code{data} is optional. If missing, the data from the \verb{$data} field of the \link{PM_result} will be used.
If specified, \code{data} must be compatible with the model that is either in the \link{PM_result} or as specified by \code{model}.
\item When \code{poppar} is a \link{PM_final} object, \code{data} is mandatory and must be compatible with the model that is specified by \code{model}.
\item When \code{poppar} is a data frame of support points, \code{data} is mandatory and must be compatible with the model that is specified by \code{model}.
\item When \code{poppar} is a list of weights, means, and covariance, \code{data} is mandatory and must be compatible with the model that is specified by \code{model}.
}

For any choice of \code{data}, the value for outputs
can be coded as any number(s) other than -99.
The number(s) will be replaced in the simulator output with the simulated values. Good practice is to use -1 for out values to be simulated.}
      \item{\code{nsamp}}{The number of MM-optimal sample times to compute; default
is 1, but can be any number.  Values >4 will take an exponentially longer time.}
      \item{\code{weight}}{List whose names indicate the type of weighting, and
values indicate the relative weight. Values should sum to 1.
Names can be any of the following:
\itemize{
\item \strong{none} The default. MMopt times will be chosen to maximally discriminate all responses at all times.
\item \strong{AUC} MMopt times will be chosen to maximally discriminate AUC, regardless of the shape of the response profile.
\item \strong{max} MMopt times will be chosen to maximally discriminate maximum, regardless of the shape of the response profile.
\item \strong{min} MMopt times will be chosen to maximally discriminate minimum, regardless of the shape of the response profile.
}

Any combination of AUC, max, and min can be chosen.  If "none" is specified, other
weight types will be ignored and the relative value will be set to 1.
For example,\code{list(auc = 0.5,max = 0.5)} or \code{list(auc = 0.2, min = 0.8)}.
The default is \code{list(none = 1)}.}
      \item{\code{predInt}}{The interval in fractional hours for simulated predicted outputs at times other than those specified in the template \code{data}.
The default is 0.5, which means there will be simulated outputs every 30 minutes from time 0 up
to the maximal time in the template file.  You may also specify \code{predInt}
as a vector of 3 values, e.g. \code{c(1,4,1)}, similar to the R command \link{seq}, where the
first value is the start time, the second is the stop time, and the third is the
step value.  Outputs for times specified in the template file will also be simulated.
To simulate outputs \emph{only} at the output times in the template data (i.e. EVID=0 events), use \code{predInt = 0}.
Note that the maximum number of predictions total is 594, so the interval must be sufficiently large to accommodate this for a given
number of output equations and total time to simulate over.  If \code{predInt} is set so that this cap is exceeded, predictions will be truncated.}
      \item{\code{mmInt}}{Specify the time intervals from which MMopt times can be selected.
These should only include simulated times specified by \code{predInt}.}
      \item{\code{algorithm}}{Optimal sampling algorithm. Currently not modifiable and
the only option is "mm".}
      \item{\code{outeq}}{Output equation to optimize}
      \item{\code{...}}{Other parameters to pass to \link{PM_sim}$new(). Most are not necessary,
but \code{usePost = TRUE} can be used to calculate individual MMopt times.
In this case, the number of posterior distributions contained in
\code{poppar$final$postPoints} needs to match the number of subjects in \code{data}.
You can also pass \code{include} and \code{exclude} to limit the subjects used in
\code{data}. This will work whether \code{usePost} is \code{TRUE} or \code{FALSE}.
Note that the following arguments to \link{PM_sim}$new cannot be modified.
\itemize{
\item \code{nsim} is zero
\item \code{outname} is "MMsim"
\item \code{combine} is \code{TRUE}
}}
      \item{\code{clean}}{Boolean parameter to specify whether temporary files made in the
course of the simulation run should be deleted. Defaults to \code{TRUE}.
This is primarily used for debugging.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    Currently, the only option is the multiple-model optimization algorithm.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_opt-plot"></a>}}
\if{latex}{\out{\hypertarget{method-PM_opt-plot}{}}}
\subsection{\code{PM_opt$plot()}}{
  Plot method
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_opt$plot(...)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{...}}{Arguments passed to \link{plot.PM_opt}}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    See \link{plot.PM_opt}.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_opt-print"></a>}}
\if{latex}{\out{\hypertarget{method-PM_opt-print}{}}}
\subsection{\code{PM_opt$print()}}{
  Print method
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_opt$print()}
    \if{html}{\out{</div>}}
  }
  \subsection{Returns}{
    Prints the optimal sampling times and Bayes Risk.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_opt-clone"></a>}}
\if{latex}{\out{\hypertarget{method-PM_opt-clone}{}}}
\subsection{\code{PM_opt$clone()}}{
  The objects of this class are cloneable with this method.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_opt$clone(deep = FALSE)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{deep}}{Whether to make a deep clone.}
    }
    \if{html}{\out{</div>}}
  }
}

}
