% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sg-gof-par-dist.R
\name{sg_gof_par_dist}
\alias{sg_gof_par_dist}
\title{Plot distributions of individual parameters with optional theoretical density}
\usage{
sg_gof_par_dist(
  fpath_i,
  par_seq = NULL,
  par_type = "Ind",
  n_bins = 30,
  tdist = TRUE,
  plot_type = "DIST"
)
}
\arguments{
\item{fpath_i}{String or sg-fit object. If the string is given, the path to
\code{.Rdata} or \code{.json} file with sg-fit object is expected.}

\item{par_seq}{Vector of strings. Character vector of parameter names to be plotted. If \code{NULL}, all parameters be included. Default is \code{NULL}}

\item{par_type}{String. A character string specifying the type of parameters used for
theoretical distribution overlay (only relevant when \code{plot_type = 'DIST'}
and \code{tdist = TRUE}). If 'Ind' - Individual (default), distributions are shown on the
natural parameter scale assuming log-normal variability. If 'RE' - Random Effect, distributions are shown on the ETA scale,
assuming a normal distribution with mean zero and covariance defined
by \verb{$OMEGAMAT}, without transformation.}

\item{n_bins}{Integer. Number of bins to use in the histogram. Default is 30.}

\item{tdist}{Logical. If \code{TRUE}, overlay theoretical parameter distributions
based on population mean and OMEGA matrix. Default is \code{TRUE}.}

\item{plot_type}{Character string specifying the type of plot to generate.
Options: 'DIST' for parameter distributions (default), 'QQ' for Q-Q plots,
'correlations' for correlation matrix plot.}
}
\value{
A \code{ggplot} object containing histogram(s) of individual parameter distributions, optionally overlaid with theoretical densities.
}
\description{
This function creates histograms of individual parameter estimates,
with optional overlay of the theoretical distribution based on the population parameters and OMEGA matrix.
}
\details{
The function visualizes the distribution of post hoc individual parameter estimates (from \verb{$PATAB}) and optionally compares them with the expected population-level variability using \verb{$SUMTAB$DISTRIBUTION} (see Details).
Shrinkage values are calculated based on \code{ETAshrinkage_var} from \verb{$SUMTAB} and included in facet labels.

Theoretical distributions are generated by sampling from a multivariate normal distribution (mean zero, covariance from \verb{$OMEGAMAT}) and mapping to the individual-parameter scale using typical values  and the \code{DISTRIBUTION} column: \code{logNormal} uses \code{TV * exp(ETA)}, \code{normal} uses \code{TV + ETA}, \code{logitNormal} uses the inverse logit of \code{logit(TV) + ETA}. Parameters with missing or empty \code{DISTRIBUTION} do not get a theoretical curve.
}
\examples{
\donttest{
# Basic usage: distribution plots for all parameters
fpath_i <- system.file("extdata", "simurg_object", "Warfarin_PK.RData", package = "SimuRg")
sg_gof_par_dist(fpath_i = fpath_i)

# Distribution plots for selected parameters (natural scale)
sg_gof_par_dist(fpath_i = fpath_i, par_seq = c("ka", "Cl"))

# Distribution plots with theoretical densities disabled
sg_gof_par_dist(fpath_i = fpath_i, tdist = FALSE)

# Distribution plots for ETA
sg_gof_par_dist(fpath_i = fpath_i, par_seq = c("eta_ka", "eta_Cl"), par_type = "RE")

# Q-Q plots for all ETA parameters
sg_gof_par_dist(fpath_i = fpath_i, plot_type = "QQ")

# Q-Q plot for a specific ETA parameter
sg_gof_par_dist(fpath_i = fpath_i, plot_type = "QQ", par_seq = "eta_ka")

# Correlation matrix for selected parameters
sg_gof_par_dist(fpath_i = fpath_i, plot_type = "correlations")
}
}
