Estimation
- class openpkpd.estimation.base.EstimationResult(theta_final, omega_final, sigma_final, ofv, converged=False, condition_number=None, eta_shrinkage=<factory>, eps_shrinkage=<factory>, post_hoc_etas=<factory>, ofv_history=<factory>, warnings=<factory>, structured_warnings=<factory>, shrinkage_warnings=<factory>, n_function_evals=0, elapsed_time=0.0, method='', message='', diagnostics=<factory>, n_observations=0, n_subjects=0, _n_parameters=0)[source]
Bases:
objectResult from a completed estimation run.
- Parameters:
theta_final (ndarray)
omega_final (ndarray)
sigma_final (ndarray)
ofv (float)
converged (bool)
condition_number (float | None)
eta_shrinkage (ndarray)
eps_shrinkage (ndarray)
structured_warnings (list[EstimationWarning])
n_function_evals (int)
elapsed_time (float)
method (str)
message (str)
n_observations (int)
n_subjects (int)
_n_parameters (int)
- property n_parameters: int
Number of free parameters in the model.
Counts free THETA elements plus unique free OMEGA and SIGMA elements (lower-triangular, excluding fixed zeros). If
_n_parametershas been set explicitly (e.g. viacompute_n_parameters), that value is returned directly. Otherwise the count is inferred from the matrix shapes.
- property aic: float
Akaike Information Criterion.
AIC = OFV + 2 * n_parameters
where OFV = -2 * log-likelihood.
- property bic: float
Bayesian Information Criterion.
BIC = OFV + ln(n_observations) * n_parameters
Returns inf when n_observations <= 0.
- compute_n_parameters(theta_specs=None, omega_specs=None, sigma_specs=None)[source]
Compute and store n_parameters from specs or infer from matrix shapes.
If spec objects are provided they must expose a
fixedboolean attribute. Elements withfixed=Truedo not contribute to the parameter count. When specs are absent, all elements are treated as free.- Parameters:
theta_specs (
list[Any] |None) – List of ThetaSpec-like objects with afixedattribute, one per THETA element.omega_specs (
list[Any] |None) – List of OmegaSpec-like objects with afixedattribute, one per lower-triangular OMEGA element.sigma_specs (
list[Any] |None) – List of SigmaSpec-like objects with afixedattribute, one per lower-triangular SIGMA element.
- Return type:
- add_structured_warning(code, message, severity=WarningSeverity.WARNING)[source]
Append a structured EstimationWarning and its string representation.
The string form is added to
warningsfor backward compatibility; the typed form is added tostructured_warnings.
- check_omega_conditioning()[source]
Check Omega eigenvalues and condition number; add WARN_001/002/004.
Intended to be called after the M-step or covariance step. A 0×0 or empty Omega (sigma-only models) is silently skipped.
- Return type:
- to_html(path, params=None, title='OpenPKPD Estimation Report', cov_result=None, provenance=None)[source]
Write a self-contained HTML report to path.
Requires a ParameterSet for parameter labels. If params is None, a minimal report (no labels) is generated.
- to_pdf(path, params=None, title='OpenPKPD Estimation Report', cov_result=None, provenance=None)[source]
Write a PDF report to path using the optional GUI dependencies.
- compute_shrinkage(params_at_convergence=None, iwres=None)[source]
Compute ETA and EPS shrinkage with per-ETA breakdown.
- ETA shrinkage for random effect k:
shrinkage_k = 1 - SD(EBE_ik, i = 1..N) / sqrt(omega_kk)
- EPS shrinkage (if IWRES are available):
eps_shrinkage = 1 - SD(IWRES)
A warning is emitted and stored in
shrinkage_warningsfor any ETA whose shrinkage exceeds 30%, as high ETA shrinkage can inflate the apparent precision of parameter estimates and invalidates post-hoc ETA-based analyses.
- compute_deshrinkage_etas()[source]
Return de-shrunken EBEs using the Combes (2013) rescaling correction.
EBEs from FOCE (and to a lesser extent SAEM) are biased toward zero because the posterior mode is shrunk relative to the true individual values. This method rescales each subject’s ETA vector so that the marginal variance matches omega_kk exactly:
eta_adj_ik = eta_ik / (1 − shrinkage_k)
which is equivalent to:
eta_adj_ik = eta_ik × sqrt(omega_kk) / SD(EBEs_k)
The relative ranking of subjects is preserved. Subjects with the same sign as the population mean shift in proportion to their original EBE magnitude.
Returns an empty dict when post-hoc ETAs or shrinkage have not been computed, or when a random effect is fully shrunk (SD(EBEs) ≈ 0).
Reference
Combes F-P, Retout S, Frey N, Mentré F (2013). Prediction of shrinkage of individual parameters using the Bayesian information matrix in nonlinear mixed-effects models with evaluation in pharmacokinetics. Pharm Res 30:2355–2367. https://doi.org/10.1007/s11095-013-1079-3
- __init__(theta_final, omega_final, sigma_final, ofv, converged=False, condition_number=None, eta_shrinkage=<factory>, eps_shrinkage=<factory>, post_hoc_etas=<factory>, ofv_history=<factory>, warnings=<factory>, structured_warnings=<factory>, shrinkage_warnings=<factory>, n_function_evals=0, elapsed_time=0.0, method='', message='', diagnostics=<factory>, n_observations=0, n_subjects=0, _n_parameters=0)
- Parameters:
theta_final (ndarray)
omega_final (ndarray)
sigma_final (ndarray)
ofv (float)
converged (bool)
condition_number (float | None)
eta_shrinkage (ndarray)
eps_shrinkage (ndarray)
structured_warnings (list[EstimationWarning])
n_function_evals (int)
elapsed_time (float)
method (str)
message (str)
n_observations (int)
n_subjects (int)
_n_parameters (int)
- Return type:
None
- class openpkpd.estimation.base.EstimationMethod[source]
Bases:
ABCAbstract base class for estimation methods.
Each method implements estimate() which takes a PopulationModel and initial parameters and returns an EstimationResult.