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

PM_model objects contain the variables, covariates, equations and
error models necessary to run a population analysis.
}
\details{
PM_model objects are one of two fundamental objects in Pmetrics, along with
\code{\link[=PM_data]{PM_data()}} objects. Defining a PM_model allows for fitting it to the data
via the \verb{$fit()} method to conduct a
population analysis, i.e. estimating the probability distribution of model equation
paramter values in the population. The PM_model object is created using the
a model building app (coming soon), by defining a list
directly in R, or by reading a model text file. When reading a model text file,
the list code is generated and copied to the clipboard for pasting in to scripts.
Model files will be deprecated in future versions of Pmetrics.

Use \code{PM_model$from_dsl()} to create a model directly from pharmsol DSL text.
The DSL defines the model structure. The \code{pri} and \code{err} arguments provide
the Pmetrics parameter ranges and error models.
}
\section{Create a model from DSL}{


\if{html}{\out{<div class="sourceCode">}}\preformatted{PM_model$from_dsl(
  dsl,
  pri,
  err,
  input_map = NULL,
  solver = NULL,
  quiet = FALSE
)
}\if{html}{\out{</div>}}

\code{dsl} is one character string containing the model source. \code{input_map} is an
optional named integer vector that maps DSL route names to Pmetrics \code{INPUT}
values. Routes named \code{input_1}, \code{input_2}, and so on are mapped automatically.

\strong{Some notes on the example at the end of this help page:}
\itemize{
\item It's a complete example of a three compartment model with delayed absorption.
\item We show the method of defining the model first and embedding the \code{PM_model$new()} within
a \code{dontrun} block to avoid automatic compilation.
\item Since this model can also be solved analytically with algebra, we could have used
\code{eqn = function(){three_comp_bolus}}.
}
}

\examples{

mod_list <- list(
  pri = list(
    CL = ab(10, 200),
    V0 = ab(0, 100),
    ka = ab(0, 3),
    k23 = ab(0, 5),
    k32 = ab(0, 5),
    lag1 = ab(0, 2)
  ),
  cov = list(
    wt = interp()
  ),
  sec = function() {
    V <- V0 * (wt / 70)
    ke <- CL / V # define here to make eqn simpler
  },
  eqn = function() {
    dx[1] <- -ka * x[1]
    dx[2] <- rateiv[1] + ka * x[1] - (ke + k23) * x[2] + k32 * x[3]
    dx[3] <- k23 * x[2] - k32 * x[3]
    dx[4] <- x[1] / V
  },
  lag = function() {
    tlag[1] <- lag1
  },
  out = function() {
    y[1] <- x[1] / V
    y[2] <- x[4] # AUC, not fitted to any data, not required
  },
  err = list(
    proportional(2, c(0.1, 0.15, 0, 0)) # only applies to y[1]
  )
)

\dontrun{
mod <- PM_model$new(mod_list)
}

}
\author{
Michael Neely
}
\section{Public fields}{
  \if{html}{\out{<div class="r6-fields">}}
  \describe{
    \item{\code{model_list}}{A list containing the model components built by translating
the original arguments into Rust}

    \item{\code{arg_list}}{A list containing the original arguments passed to the model}

    \item{\code{binary_path}}{Deprecated. Retained as \code{NULL} for backward compatibility;
models are no longer compiled to a binary. See the \code{dsl} field.}

    \item{\code{dsl}}{The model definition rendered as pharmsol DSL source, used by the
Rust backend to JIT-compile the model at run time.}

    \item{\code{input_remap}}{A list describing data label changes required by the
DSL model. Each element is a list with \code{kind}, \code{from}, and \code{to}.}
  }
  \if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
  \itemize{
    \item \href{#method-PM_model-initialize}{\code{PM_model$new()}}
    \item \href{#method-PM_model-print}{\code{PM_model$print()}}
    \item \href{#method-PM_model-plot}{\code{PM_model$plot()}}
    \item \href{#method-PM_model-fit}{\code{PM_model$fit()}}
    \item \href{#method-PM_model-map}{\code{PM_model$map()}}
    \item \href{#method-PM_model-sim}{\code{PM_model$sim()}}
    \item \href{#method-PM_model-compile}{\code{PM_model$compile()}}
    \item \href{#method-PM_model-save}{\code{PM_model$save()}}
    \item \href{#method-PM_model-copy}{\code{PM_model$copy()}}
    \item \href{#method-PM_model-clone}{\code{PM_model$clone()}}
  }
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-initialize"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-initialize}{}}}
\subsection{\code{PM_model$new()}}{
  This is the method to create a new \code{PM_model} object.

The first argument allows creation of a model from a variety of pre-existing
sources, and if used, all the subsequent arguments will be ignored. If a model
is defined on the fly, the arguments form the building blocks. Blocks are of two types:
\itemize{
\item \strong{Lists} define \emph{primary parameters}, \emph{covariates},
and \emph{error models}. These
portions of the model have specific and defined creator functions and no additional
R code is permissible. They take this form:

\if{html}{\out{<div class="sourceCode">}}\preformatted{block_name = list(
  var1 = creator(),
  var2 = creator()
)
}\if{html}{\out{</div>}}

Note the comma separating the creator functions, "\verb{c(}" to open the vector and "\verb{)}" to close the vector.
Names are case-insensitive and are converted to lowercase for Rust.
\item \strong{Functions} define the other parts of the model, including \emph{secondary (global)
equations}, \emph{model equations} (e.g. ODEs), \emph{lag time}, \emph{bioavailability}, \emph{initial conditions},
and \emph{outputs}. These parts of the model are defined as R functions without arguments,
but whose body contains any permissible R code.

\if{html}{\out{<div class="sourceCode">}}\preformatted{block_name = function() \{

 # any valid R code
 # can use primary or secondary parameters and covariates
 # lines are not separated by commas

\}
}\if{html}{\out{</div>}}

Note the absence of arguments between the "\verb{()}", the opening curly brace "\verb{\{}" to start
the function body and the closing curly brace "\verb{\}}" to end the body.
Again, all R code will be converted to lowercase prior to translation into Rust.
}

\strong{Important:} All models must have \code{pri}, \code{eqn}, \code{out}, and \code{err} blocks.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$new(
  x = NULL,
  pri = NULL,
  cov = NULL,
  sec = NULL,
  eqn = NULL,
  lag = NULL,
  fa = NULL,
  ini = NULL,
  out = NULL,
  err = NULL,
  solver = NULL,
  ...,
  .dsl = NULL,
  .input_map = NULL
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{x}}{An optional argument, but if specified, all the subsequent
arguments will be ignored. \code{x} creates a \code{PM_model} from
existing appropriate input, which can be one of the following:
\itemize{
\item Quoted name of a model text file in the
working directory which will be read and passed to Rust engine. \strong{Note:} Model
text files are being deprecated in future versions of Pmetrics.
\item List that defines the model directly in R. This will be in the same format as if
all the subsequent arguments were used. For example:

\if{html}{\out{<div class="sourceCode">}}\preformatted{mod_list <- list(
 pri = list(...),
 eqn = function()\{...\},
 out = function()\{...\},
 err = c(...)
)
mod <- PM_model$new(mod_list)
}\if{html}{\out{</div>}}
\item \code{PM_model} object, which will simply rebuild it, e.g. carrying on the
prior example: \code{PM_model$new(mod)}
}

See the user manual \code{\link[=PM_manual]{PM_manual()}} for more help on directly defining models in R.}
      \item{\code{pri}}{The first of the arguments used if \code{x} is not specified. This is
a named list of primary parameters, which are the model parameters that
are estimated in the population analysis. They are specified
by one of two creator functions: \code{\link[=ab]{ab()}} or \code{\link[=msd]{msd()}}. For example,

\if{html}{\out{<div class="sourceCode">}}\preformatted{pri = list(
  Ke = ab(0, 5),
  V = msd(100, 10)
)
}\if{html}{\out{</div>}}

The \code{\link[=ab]{ab()}} creator specifies the
initial range \verb{[a, b]} of the parameter, while the \code{\link[=msd]{msd()}} creator specifies
the initial mean and standard deviation of the parameter.}
      \item{\code{cov}}{A list whose names are some or all of the covariates in the data file.
Unlike prior versions of Pmetrics, as of 3.0.0, they do not have to be listed in the same order
as in the data file, and they do not need to be all present.
\strong{Only those covariates you wish to use in model equations or analyze for relationships to model parameters need to be declared here.}
Values for each element in the covariate vector are the \code{\link[=interp]{interp()}} creator function to declare
how each covariate is interpolated between entries in the data. The default argument
for \code{\link[=interp]{interp()}} is "lm" which means that values will be linearly interpolated
between entries, like the R linear model function \code{\link[stats:lm]{stats::lm()}}. The alternative is "none",
which holds the covariate value the same as the previous entry until it changes,
i.e., a carry-forward strategy.

For example:

\if{html}{\out{<div class="sourceCode">}}\preformatted{cov = list(
  wt = interp(), # will be linear by default
  visit = interp("none")
)
}\if{html}{\out{</div>}}

Note that \code{wt = interp()} is equivalent to \code{wt = interp("lm")}, since "lm" is the default.}
      \item{\code{sec}}{A function defining the secondary (global) equations in the model. Values
are not estimated for these equations but they are available to every other block in the model.
For example:

\if{html}{\out{<div class="sourceCode">}}\preformatted{sec = function() \{
  V = V0 * (wt/70)
\}
}\if{html}{\out{</div>}}

Note that the function
must be defined with no arguments between the parentheses,
and the body \strong{must be in R syntax}. Any number of lines and R code, e.g.
\code{if} - \verb{else} statements, etc. are permissible.}
      \item{\code{eqn}}{A function defining the model equations. The function must have no arguments.
The body of the function may contain three kinds of equations, written in R syntax.
\itemize{
\item \strong{Implicit equations} referenced by calling the name of a Pmetrics model library object
detailed in \code{\link[=model_lib]{model_lib()}}. The Pmetrics model library contains a number of template models
solved analytically (algebraically) and may include user-defined models. For example, to use
a two-compartment model with intavenous input:

\if{html}{\out{<div class="sourceCode">}}\preformatted{eqn = function()\{
 two_comp_iv
\}
}\if{html}{\out{</div>}}

Required parameters for library models are listed for each model and must be
included in model blocks exactly as named. For example, in a one-compartment model
\code{Ke} is a required parameter. Thus, if \code{Ke} is a function of a covariate called "crcl",
here is a code snippet illustrating the inclusion of the required parameter.

\if{html}{\out{<div class="sourceCode">}}\preformatted{mod <- PM_model$new(
  pri = list(
    ke0 = ab(0, 5),
    v = ab(0, 100)
  ),
  cov = list(
    crcl = interp()
  ),
  eqn = function()\{
    one_comp
    ke = ke0 * crcl # the required parameter, ke, is defined
  \},
  ... # more model blocks, including out, err
)
}\if{html}{\out{</div>}}
\item \strong{Explicit equations} are ordinary differential equations that directly define a model.
Use the following notation in equations:
\itemize{
\item \code{dx[i]} for the change in amount with respect to time (i.e., \eqn{dx/dt}),
where \code{i} is the compartment number,
\item \code{x[i]} for the compartment amount, where \code{i} is the compartment number.
\item \code{rateiv[j]} for the infusion rate of input \code{j}, where \code{j} is the input number
in the data corresponding to doses for that input.
\item Bolus doses are indicated by \code{DUR = 0} for dose events in the
data. Currently only one bolus input is allowed, which goes into compartment 1
and is not modifiable. It does not appear in the differential equations.

For example,

\if{html}{\out{<div class="sourceCode">}}\preformatted{eqn = function() \{
 dx[1] = -ka * x[1]
 dx[2] = rateiv[1] + ka * x[1] - ke * x[2]
\}
}\if{html}{\out{</div>}}
}
\item \strong{Additional equations} in R code can be defined in this block, which are similar to
the \code{sec} block, but will only be available within the \code{eqn} block as opposed
to global availability when defined in \code{sec}. They can be added to either
}}
      \item{\code{lag}}{A function defining the lag time (delayed absorption) for the bolus input.
The function must have no arguments,
and the equations must be defined
in R syntax The equations must be defined in the form of
\code{lag[i] = par}, where \code{lag[i]} is the lag for drug (input) \code{i} and
\code{par} is the lag parameter used in the \code{pri} block.

For example, if
\code{antacid} is a covariate in the data file, and \code{lag1} is a primary parameter,
this code could be used to model delayed absorption if an antacid is present.

\if{html}{\out{<div class="sourceCode">}}\preformatted{lag = function() \{
  lag[1] = if(antacid == 1) lag1 else 0
\}
}\if{html}{\out{</div>}}

As for \code{eqn}, additional equations in R code can be defined in this block,
but will only be available within the \code{lag} block.}
      \item{\code{fa}}{A function defining the bioavailability (fraction absorbed) equations,
similar to \code{lag}.

Example:

\if{html}{\out{<div class="sourceCode">}}\preformatted{fa = function() \{
  fa[1] = if(antacid == 1) fa1 else 1
\}
}\if{html}{\out{</div>}}

As for \code{eqn}, additional equations in R code can be defined in this block,
but will only be available within the \code{fa} block.}
      \item{\code{ini}}{A function defining the initial conditions for a compartment
in the model. Structure is similar to \code{lag} and \code{fa}.

Example:

\if{html}{\out{<div class="sourceCode">}}\preformatted{ini = function() \{
  x[2] = init2 * V
\}
}\if{html}{\out{</div>}}

This sets the initial amount of drug in compartment 2 to the value
of a covariate \code{init2} multiplied by the volume of the compartment,
\code{V}, assuming \code{V} is either a primary parameter or defined in the
\code{sec} block.

As for \code{eqn}, additional equations in R code can be defined in this block,
but will only be available within the \code{ini} block.}
      \item{\code{out}}{A function defining the output equations, which are the predictions
from the model. The function must have no arguments,
and the equations for predictions must be defined
in R syntax.

Use the following notation in equations:
\itemize{
\item \code{y[i]} for the predicted value, where \code{i} is the output equation number,
typically corresponding to an observation with \code{outeq = i} in the data, but not
always (see \strong{Note} below).
\item \code{x[j]} for the compartment amount, where \code{j} is the compartment number.
}

As with all function blocks, secondary equations are permitted,
but will be specific to the \code{out} block.

For example,

\if{html}{\out{<div class="sourceCode">}}\preformatted{out = function() \{
  V = V0 * wt # only needed if not included in sec block
  y[1] = x[1]/V
  #Vp and Vm must be defined in pri or sec blocks
  y[2] = x[2]/Vp
  y[3] = x[3]/Vm
\}
}\if{html}{\out{</div>}}

This assumes \code{V}, \code{Vp}, and \code{Vm} are either primary parameters or defined in the
\code{sec} block.

\strong{Note} that as of Pmetrics 3.0.0, you can have more output equations
than values for \code{outeq} in the data. This is not possible with prior
versions of Pmetrics. Outputs without corresponding observations
are not used in the fitting, but do generate predictions.
For example, this snippet is part of a model that calculates AUC:

\if{html}{\out{<div class="sourceCode">}}\preformatted{eqn = function()\{
  dx[1] = -ka * x[1]
  dx[2] = rateiv[1] + ka * x[1] - ke * x[2]
  dx[3] = x[2] - x[3]
  dx[4] = x[1] / v
\},
out = function()\{
  y[1] = x[1]/v
  y[2] = x[4]
\},
err = list(
 proportional(2, c(0.1, 0.15, 0, 0))
)
}\if{html}{\out{</div>}}

If the data only contain observations for \code{y[1]}, i.e. the concentration
of drug in the plasma compartment with \code{outeq = 1}, the model will
use that information to optimize the parameter values, but will also
generate predictions for \code{y[2]}, which is the AUC of the drug in compartment 1,
even though there is no \code{outeq = 2} in the data. There is only one \code{err}
equation since there is only one source of observations: plasma concentration.
AUC (\code{y[2]}) is not fitted to any observations; it is a calculation based on
the model state, given the optimized parameter values. It's not required, but
shown here for illustrative purposes.}
      \item{\code{err}}{An unammed vector of error models for each of the output equations
with observations, i.e. those that have an \code{outeq} number associated with them in
the data.
Each error model is defined by the \code{\link[=proportional]{proportional()}} creator or
the \code{\link[=additive]{additive()}} creator, relative to the observation error.
For example, if there are three output equations corresponding to three
sources of observations in the data, the error models
could be defined as:

\if{html}{\out{<div class="sourceCode">}}\preformatted{err = list(
  proportional(2, c(0.1, 0.15, 0, 0)),
  proportional(3, c(0.05, 0.1, 0, 0), outeq = 2),
  additive(1, c(0.2, 0.25, 0, 0), outeq = 3)
)
}\if{html}{\out{</div>}}

This defines the first two output equations to have proportional error
with initial values of 2 and 3, respectively, and the third output equation
to have additive error with initial value of 1. Each output is measured by
a different assay with different error characteristics. Note that you must specify
which outeq corresponds to the values, with a default \code{outeq = 1}, which is not required
if there is only one output equation.}
      \item{\code{solver}}{Optional ODE solver for user-defined ODE models.
Supported values are "BDF", "TRBDF2", "ESDIRK34", and "TSIT45".
This is ignored for analytical library models.}
      \item{\code{...}}{Not currently used.}
      \item{\code{.dsl}}{Internal DSL source used by \code{PM_model$from_dsl()}.}
      \item{\code{.input_map}}{Internal route mapping used by \code{PM_model$from_dsl()}.}
    }
    \if{html}{\out{</div>}}
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-print"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-print}{}}}
\subsection{\code{PM_model$print()}}{
  Print the model summary.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$print(...)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{...}}{Not used.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    This method prints a summary of the model.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-plot"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-plot}{}}}
\subsection{\code{PM_model$plot()}}{
  Plot the model.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$plot(...)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{...}}{Additional arguments passed to the plot function.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    This method plots the model using the
\code{\link[=plot.PM_model]{plot.PM_model()}} function.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-fit"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-fit}{}}}
\subsection{\code{PM_model$fit()}}{
  This is the main method to run a population analysis.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$fit(
  data = NULL,
  path = ".",
  run = NULL,
  include = NULL,
  exclude = NULL,
  cycles = 100,
  prior = "sobol",
  points = 100,
  idelta = 0.1,
  tad = 0,
  seed = 23,
  overwrite = FALSE,
  algorithm = "NPAG",
  report = getPMoptions("report_template"),
  quiet = FALSE
)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{data}}{Either the name of a  \link{PM_data}
object in memory or the quoted filename (with or without a path) of a Pmetrics
data file. If the path is not specified, the file is assumed to be in the current working directory,
unless the \code{path} argument below is also specified as a global option for the fit.
The file will be used to create a \link{PM_data}
object on the fly. However, if created on the fly, this object
will not be available to other
methods or other instances of \verb{$fit()}.}
      \item{\code{path}}{Optional full path or relative path from current working directory
to the folder where \code{data} and \code{model} are located if specified as filenames without
their own paths,
and where the output will be saved. Default is the current working directory.}
      \item{\code{run}}{Specify the run number of the output folder.  Default if missing is the next available number.}
      \item{\code{include}}{Vector of subject id values in the data file to include in the analysis.
The default (missing) is all.}
      \item{\code{exclude}}{A vector of subject IDs to exclude in the analysis, e.g. \code{c(4,6:14,16:20)}}
      \item{\code{cycles}}{Number of cycles to run. Default is 100.}
      \item{\code{prior}}{The distribution for the initial support points, which can be
one of several options.
\itemize{
\item The default is "sobol", which is a semi-random distribution. This is the distribution
typically used when fitting a new model to the data. An example of this is
on our \href{https://www.lapk.org/images/sobol_3d_plot.html}{website}.
}

The following all specify non-random, informative prior distributions. They
are useful for either continuing a previous
run which did not converge or for fitting a model to new data, whether to simply
calculate Bayesian posteriors with \code{cycles = 0} or to revise the model to a new
covergence with the new data.
\itemize{
\item The name of a suitable \link{PM_result} object from a prior run loaded with \link{PM_load}.
This starts from the non-uniform, informative distribution obtained at the end of a prior NPAG run.
Example: \verb{run1 <- PM_load(1); fit1$run(prior = run1)}.
\item A character string with the filename of a csv file containing a prior distribution with
format as for 'theta.csv' in the output folder of a prior run: column headers are parameter
names, and rows are the support point values. A final column with probabilities
for each support point is not necessary, but if present will be ignored, as these
probabilities are calculated by the engine. Note that the parameter names must match the
names of the primary variables in the model. Example: \code{fit1$run(prior = "mytheta.csv")}.
\item The number of a previous run with \code{theta.csv} in the output folder which will be read
as for the filename option above. Example: \code{fit1$run(prior = 2)}.
\item A data frame obtained from reading an approriate file, such that the data frame
is in the required format described in the filename option above. Example:
\verb{mytheta <- read_csv("mytheta.csv"); fit1$run(prior = mytheta)}.
}}
      \item{\code{points}}{The number of initial support points if one of
the semi-random, uniform distributions are selected in the \code{prior} argument
above. Default is 100. The initial points are
spread through the hyperspace defined by the random parameter ranges
and begin the search for the optimal
parameter value distribution (support points) in the population.
If there are fewer than 2 points per unit range for any parameter,
Pmetrics will suggest the minimum number of points that should be tried.
The greater the initial number of points, the less chance of
missing the globally maximally likely parameter value distribution,
but the slower the run.}
      \item{\code{idelta}}{How often to generate posterior predictions in units of time.
Default is 0.1, which means a prediction is generated every 0.1 hours (6 minutes)
if the unit of time is hours. Predictions are made at this interval until the time
of the last event (dose or observation) or until \code{tad} if that value is greater
than the time of the last dose or observation in the data.}
      \item{\code{tad}}{Length of time after the last dose event to add additional predictions
at frequency \code{idelta}.  Default is 0, which means no additional predictions
beyond the last dose, assuming the dose is the last event. . If the
last observation in the data is after \code{tad}, then a prediction will be generated at
time = \code{tad} after the last dose}
      \item{\code{seed}}{Seed used if \code{prior = "sobol"}. Ignored otherwise.}
      \item{\code{overwrite}}{Boolean operator to overwrite existing run result folders.  Default is \code{FALSE}.}
      \item{\code{algorithm}}{The algorithm to use for the run.  Default is "NPAG" for the \strong{N}on-\strong{P}arametric \strong{A}daptive \strong{G}rid. Alternatives: "NPOD".}
      \item{\code{report}}{If missing, the default Pmetrics report mode specified by
\link{getPMoptions} is used. Otherwise, choose \code{"app"}, \code{"plotly"},
\code{"ggplot"}, or \code{"none"}.}
      \item{\code{quiet}}{Boolean operator to suppress messages during the run.  Default is \code{FALSE}.}
      \item{\code{intern}}{Run NPAG in the R console without a batch script.  Default is TRUE.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    As of Pmetrics 3.0.0, models contain compiled code to fit
the model equations to the data, optimizing the parameter
value probability distributions in the population to
maximize their likelihood, or more precisely, minimize
the objective function, which is -2*log-likelihood.

The \verb{$fit()} method is the means of running that compiled
code to conduct to fitting procedure. At a minimum, it requires
a \link{PM_data} object, which can be created with
\code{PM_data$new()}. There are a number of additional arguments
to control the fitting procedure, such as the number of cycles
to run, the initial number of support points,
and the algorithm to use, among others.

The \verb{$fit()} method is the descendant of the legacy
\link{NPrun} function, which is maintained as a wrapper to \verb{$fit()}
for backwards compatibility.
  }
  \subsection{Returns}{
    A successful run will result in creation of a new folder in the working
directory with the results inside the folder.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-map"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-map}{}}}
\subsection{\code{PM_model$map()}}{
  Calculate posteriors from a fitted model.
#' @details
This method calculates posteriors from a compiled model. It is not necessary to have
run the model first, but it is necessary to have an informative prior distribution.
This prior will typically be the result of a previous run, but may also be a file
containing support points, with each column named as a parameter in the model plus a final column
for probability.  Each row contains values for the parameters and the associated probability for
those parameter values.  The file can be saved as a csv file.

To calculate the posteriors, \code{map()} calls the \code{fit()} method with the \code{cycles} argument set to 0
and the \code{algorithm} argument set to "POSTPROB". If \code{data} are not provided as an argument to
\code{map()}, the model's \code{data} field is used instead. If \code{data} is provided, it must be a
\link{PM_data} object or the pathname of a file which can be loaded as a \link{PM_data} object.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$map(...)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{...}}{Arguments passed to the \code{fit} method. Note that the \code{cycles} argument is set to 0,
and the \code{algorithm} argument is set to "POSTPROB" automatically.}
    }
    \if{html}{\out{</div>}}
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-sim"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-sim}{}}}
\subsection{\code{PM_model$sim()}}{
  Simulate data from the model using a set of parameter values.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$sim(data, theta, quiet = FALSE)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{data}}{A \link{PM_data} object containing the dosing and observation information.}
      \item{\code{theta}}{A matrix of parameter values to use for the simulation.
The \code{theta} matrix should have the same number of columns as the number of primary parameters in the model.
Each row of \code{theta} represents a different set of parameter values.}
      \item{\code{quiet}}{Logical, if TRUE, suppresses messages during simulation.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    This method simulates output from the model using a set of parameter values
provided in the \code{theta} matrix and the template for dosing/observations in
the \code{data} object.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-compile"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-compile}{}}}
\subsection{\code{PM_model$compile()}}{
  Render the model to pharmsol DSL source.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$compile(quiet = FALSE)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{quiet}}{Logical, if TRUE, suppresses messages.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    This method generates the pharmsol DSL representation of the model and
stores it in the \code{dsl} field. The Rust backend JIT-compiles this source at
run time, so no Rust toolchain or separate compilation step is required.
The method name is retained for backward compatibility.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-save"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-save}{}}}
\subsection{\code{PM_model$save()}}{
  Save model to file (deprecated).
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$save()}
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    This method is deprecated. Existing or manually created model files may be read with \code{PM_model$new(filename)},
but including model code in scripts is preferred, as this makes models used in runs transparent and more easily edited.
Use the \code{PM_model$copy()} method instead to copy the model code to the clipboard and paste into scripts.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-copy"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-copy}{}}}
\subsection{\code{PM_model$copy()}}{
  Copy model code to clipboard.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$copy()}
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    This method copies the R code to create the model to the clipboard.
This is useful for saving the model code in a script.
  }
}

\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_model-clone"></a>}}
\if{latex}{\out{\hypertarget{method-PM_model-clone}{}}}
\subsection{\code{PM_model$clone()}}{
  The objects of this class are cloneable with this method.
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_model$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>}}
  }
}

}
