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

Contains final cycle information from run.
}
\details{
The \link{PM_final} object is both a data field within a \link{PM_result}, and itself an R6 object
comprising data fields and associated methods suitable for analysis and plotting of
final cycle parameters.

Because \link{PM_final} objects are automatically added to the \link{PM_result} at the end of a
successful run, it is generally not necessary for users to generate \link{PM_final} objects
themselves.

The main results are contained in the \verb{$data} field,
and it is this field which is passed to the \verb{$plot} and \verb{$summary} methods.
You can use this \verb{$data} field for custom manipulations, e.g. \code{probs <- run1$final$data$popPoints |> select(prob)}.
This will select the probabilities of the support points.
If you are unfamiliar with the base R \verb{|>} pipe function, type \code{help("|>")}
into the R console for documentation and examples.

To provide a more traditional experience in R,
the \verb{$data} field is also separated by list items into the other data fields within the R6 object,
e.g. \code{popMean} or \code{nsub}. This
allows you to access them in an S3 way, e.g. \code{run1$final$popMean} if \code{run1} is a
\link{PM_result} object.
}
\author{
Michael Neely, Julian Otalvaro
}
\section{Public fields}{
  \if{html}{\out{<div class="r6-fields">}}
  \describe{
    \item{\code{data}}{A list with the following elements, which can also be extracted by name.
\itemize{
\item \strong{popPoints} (NPAG only) Data frame of the final cycle joint population density of grid points
with column names equal to the name of each random parameter plus \emph{prob} for the
associated probability of that point
\item \strong{popMean} The final cycle mean for each random parameter distribution
\item \strong{popSD} The final cycle standard deviation for each random parameter distribution
\item \strong{popCV} The final cycle coefficient of variation (SD/Mean) for each random parameter distribution
\item \strong{popVar} The final cycle variance for each random parameter distribution
\item \strong{popCov} The final cycle random parameter covariance matrix
\item \strong{popCor} The final cycle random parameter correlation matrix
\item \strong{popMed} The final cycle median values for each random parameter,
i.e. those that have unknown mean and unknown variance, both of which are
fitted during the run
\item \strong{postPoints} (NPAG only) Data frame of posterior population points for each of the first 100 subject,
with columns id, point, parameters and probability.  The first column is the subject, the second column has the population
point number, followed by the values for the parameters in that point and the probability.
\item \strong{postMean} A \emph{nsub} x \emph{npar} data frame containing
the means of the posterior distributions for each parameter.
\item \strong{postSD} A \emph{nsub} x \emph{npar} data frame containing
the SDs of the posterior distributions for each parameter.
\item \strong{postVar} A \emph{nsub} x \emph{npar} data frame containing
the variances of the posterior distributions for each parameter.
\item \strong{postCov} NPAG only: An list of length \emph{nsub}, each element with an \emph{npar} x \emph{npar} data frame
that contains the posterior parameter value covariances for that subject.
\item \strong{postCor} NPAG only: An list of length \emph{nsub}, each element with an \emph{npar} x \emph{npar} data frame
that contains the posterior parameter value correlations for that subject.
\item \strong{postMed} A \emph{nsub} x \emph{npar} data frame containing
the medians of the posterior distributions for each parameter.
\item \strong{shrinkage} A data frame with the shrinkage for each parameter.
\item \strong{gridpts} (NPAG only) Initial number of support points
\item \strong{nsub} Number of subjects
\item \strong{ab} Tibble/data frame of boundaries for random parameter values with columns: name, lower, upper.
}}
  }
  \if{html}{\out{</div>}}
}
\section{Active bindings}{
  \if{html}{\out{<div class="r6-active-bindings">}}
  \describe{
    \item{\code{popPoints}}{(NPAG only) Data frame of the final cycle joint population density of grid points
with column names equal to the name of each random parameter plus \emph{prob} for the
associated probability of that point}

    \item{\code{popMean}}{The final cycle mean for each random parameter distribution}

    \item{\code{popSD}}{The final cycle standard deviation for each random parameter distribution}

    \item{\code{popCV}}{The final cycle coefficient of variation (SD/Mean) for each random parameter distribution}

    \item{\code{popVar}}{The final cycle variance for each random parameter distribution}

    \item{\code{popCov}}{The final cycle random parameter covariance matrix}

    \item{\code{popCor}}{The final cycle random parameter correlation matrix}

    \item{\code{popMed}}{The final cycle median values for each random parameter,
i.e. those that have unknown mean and unknown variance, both of which are
fitted during the run}

    \item{\code{postPoints}}{(NPAG only) Data frame of posterior population points for each of the first 100 subject,
with columns id, point, parameters and probability.  The first column is the subject, the second column has the population
point number, followed by the values for the parameters in that point and the probability.}

    \item{\code{postMean}}{A \emph{nsub} x \emph{npar} data frame containing
the means of the posterior distributions for each parameter.}

    \item{\code{postSD}}{A \emph{nsub} x \emph{npar} data frame containing
the SDs of the posterior distributions for each parameter.}

    \item{\code{postVar}}{A \emph{nsub} x \emph{npar} data frame containing
the variances of the posterior distributions for each parameter.}

    \item{\code{postCov}}{NPAG only: An list of length \emph{nsub}, each element with an \emph{npar} x \emph{npar} data frame
that contains the posterior parameter value covariances for that subject.}

    \item{\code{postCor}}{NPAG only: An list of length \emph{nsub}, each element with an \emph{npar} x \emph{npar} data frame
that contains the posterior parameter value correlations for that subject.}

    \item{\code{postMed}}{A \emph{nsub} x \emph{npar} data frame containing
the medians of the posterior distributions for each parameter.*}

    \item{\code{shrinkage}}{A data frame with the shrinkage for each parameter.
The total population variance for a parameter
is comprised of variance(EBE) plus average variance(EBD),
where each subject's EBE is the Empirical Bayes Estimate or mean posterior value
for the parameter. EBD is the Empirical Bayes Distribution, or
the full Bayesian posterior parameter value distribution for each subject.

The typical definition of \eqn{\eta} shrinkage is
\eqn{[1 - \frac{SD(\eta)}{\omega}]} or \eqn{[1 - \frac{var(\eta)}{\omega^2}]},
where \eqn{\eta} is the EBE and \eqn{\omega^2} is the population variance of \eqn{\eta}.

In parametric modeling approaches \eqn{\eta} is the interindividual variability around
the typical (mean) value of the parameter in the population, usually referred to
as \eqn{\theta}. In nonparametric approaches, there is no assumption of normality, so
\eqn{\eta} simply becomes each subject's mean parameter value estimate.

Here is how Pmetrics derives and then calculates shrinkage for a given parameter.
\deqn{popVar = var(EBE) + mean(var(EBD))}
\deqn{1 = \frac{var(EBE)}{popVar} + \frac{mean(var(EBD)}{popVar}}
\deqn{1 - \frac{var(EBE)}{popVar} = \frac{mean(var(EBD))}{popVar}}
\deqn{shrinkage = \frac{mean(var(EBD))}{popVar}}
Shrinkage is therefore a fraction between 0 and 1. If Bayesian posterior distributions are wide
for a given parameter and \eqn{mean(var(EBD))} is high due to sparse or uninformative sampling,
then most of the population variance is due
to this variance and shrinkage is high, i.e., individual posterior estimates (EBE)
shrink towards the population mean. Be aware, however, that a Bayesian posterior
parameter value distribution for a given subject who is sparsely sampled may also
be a single support point with no variance. Therefore EBD under nonparametric
assumptions is not always large with uninformative sampling. This means that shrinkage
is not as readily interpretable in nonparametric population modeling.

An alternative is to consider the number of support points relative to the number
of subjects. Highly informed, distinct subjects will result in the maximum possible
number of support points, \emph{N}, which is the same as the number of subjects.
In contrast, badly undersampled subjects can result in only one support point.
There is no formal criterion for this statistic, but it can be used in combination
with shrinkage to assess the information content of the data.}

    \item{\code{gridpts}}{(NPAG only) Initial number of support points}

    \item{\code{nsub}}{Number of subjects}

    \item{\code{ab}}{Matrix of boundaries for random parameter values}
  }
  \if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
  \itemize{
    \item \href{#method-PM_final-initialize}{\code{PM_final$new()}}
    \item \href{#method-PM_final-plot}{\code{PM_final$plot()}}
    \item \href{#method-PM_final-summary}{\code{PM_final$summary()}}
    \item \href{#method-PM_final-clone}{\code{PM_final$clone()}}
  }
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-PM_final-initialize"></a>}}
\if{latex}{\out{\hypertarget{method-PM_final-initialize}{}}}
\subsection{\code{PM_final$new()}}{
  Create new object populated with final cycle information
  \subsection{Usage}{
    \if{html}{\out{<div class="r">}}
    \preformatted{PM_final$new(PMdata = NULL, path = ".", ...)}
    \if{html}{\out{</div>}}
  }
  \subsection{Arguments}{
    \if{html}{\out{<div class="arguments">}}
    \describe{
      \item{\code{PMdata}}{include Saved, parsed output of prior run, used when source files are not available.
.}
      \item{\code{path}}{include Path to the folder containing the raw results of the run. Default is the current working directory.
.}
      \item{\code{...}}{Not currently used.}
    }
    \if{html}{\out{</div>}}
  }
  \subsection{Details}{
    Creation of new \code{PM_final} object is automatic and not generally necessary
for the user to do.
  }
}

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

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

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

}
