Package {PFIM}

Type:	Package
Title:	Population Fisher Information Matrix
Version:	8.0
Date:	2026-09-28
Maintainer:	France Mentré <pfim@inserm.fr>
NeedsCompilation:	yes
Description:	Evaluate or optimize designs for nonlinear mixed effects models using the Fisher Information matrix. Supports population, individual, and Bayesian 'FIMs', covariates, inter-occasion variability, and D-optimal search ('Fedorov-Wynn', multiplicative, simplex, 'PSO', 'PGBO').
URL:	http://www.pfim.biostat.fr/
Depends:	R (≥ 4.5.0)
SystemRequirements:	C++17
License:	GPL-3 | file LICENSE
Encoding:	UTF-8
VignetteBuilder:	knitr
Config/build/clean-inst-doc:	FALSE
Imports:	utils, Deriv, methods, deSolve, purrr, stringr, S7 (≥ 0.2.0), Matrix, ggplot2 (≥ 3.5.0), Rcpp, kableExtra, tibble, scales, stats, rmarkdown, rlang, knitr, tools, grDevices
Suggests:	testthat (≥ 3.2.3), withr
LinkingTo:	Rcpp, RcppArmadillo
Config/testthat/edition:	3
Collate:	'CovariateModelEquation.R' 'Additive.R' 'Administration.R' 'AdministrationConstraints.R' 'Fim.R' 'Model.R' 'Arm.R' 'model-type-dispatch.R' 'pfim-project-access.R' 'PFIMProject.R' 'pfim-fim-report-render.R' 'BayesianFim.R' 'Covariate.R' 'CategoricalCovariate.R' 'CategoricalCovariateWithIOV.R' 'ModelError.R' 'Combined1.R' 'Combined2.R' 'Constant.R' 'Evaluation.R' 'CovariateTest.R' 'Design.R' 'Distribution.R' 'Exponential.R' 'Optimization.R' 'FedorovWynnAlgorithm.R' 'IndividualFim.R' 'LibraryOfModels.R' 'LibraryOfPDModels.R' 'LibraryOfPKModels.R' 'LogNormal.R' 'ModelODE.R' 'ModelAnalytic.R' 'ModelInfusion.R' 'ModelAnalyticInfusion.R' 'ModelAnalyticInfusionSteadyState.R' 'ModelAnalyticSteadyState.R' 'ModelODEInfusion.R' 'ModelODEInfusionDoseInEquation.R' 'ModelParameter.R' 'MultiplicativeAlgorithm.R' 'Normal.R' 'PFIM-package.R' 'PGBOAlgorithm.R' 'PSOAlgorithm.R' 'PopulationFim.R' 'Proportional.R' 'RcppExports.R' 'SamplingTimeConstraints.R' 'SamplingTimes.R' 'SimplexAlgorithm.R' 'covariate-test-power.R' 'covariates-fim-indbayes.R' 'covariates-fim.R' 'evaluation-accessors.R' 'evaluation-plots.R' 'evaluation-report-kable.R' 'evaluation-report.R' 'model-analytic-eval.R' 'model-covariates.R' 'model-error-variance.R' 'model-gradient.R' 'model-library-remap.R' 'model-ode-bolus-simulate.R' 'model-ode-bolus.R' 'model-variance.R' 'pfim-utils.R' 'pfim-arm-constraints.R' 'pfim-constraint-grid.R' 'pfim-constraints-helpers.R' 'pfim-continuous-opt.R' 'pfim-errors.R' 'pfim-model-registry.R' 'pfim-registry.R' 'pfim-extensions.R' 'pfim-fim-cache.R' 'pfim-fim-labels.R' 'pfim-fim-optimal-arms.R' 'pfim-fim-optimizer-wiring.R' 'pfim-flat-sampling-layout.R' 'pfim-gradient-perf.R' 'pfim-linear-algebra.R' 'pfim-multi-design-opt.R' 'pfim-plot-perf.R' 'pfim-rd-examples.R' 'pfim-session.R' 'pfim-subject-fim.R' 'population-fim-variance.R' 's7-reexports.R' 'zzz.R'
Config/roxygen2/version:	8.1.0
Packaged:	2026-09-28 13:20:43 UTC; MrLer
Author:	Romain Leroux [aut], France Mentré [cre], Antoine Croxo [ctb], Jérémy Seurat [ctb]
Repository:	CRAN
Date/Publication:	2026-09-28 14:50:21 UTC

Population Fisher Information for Design Evaluation and Optimization in NLME Models

Description

Nonlinear mixed-effects models (NLMEM) are widely used in model-based drug development. The population Fisher information matrix (FIM) is an efficient alternative to clinical trial simulation for optimizing study designs. **PFIM 8.0** is an R package using the **S7** object system to evaluate and optimize population designs from the FIM.

PFIM includes libraries of PK and PD models (S7 classes): bolus, infusion, first-order absorption, one- and two-compartment structures, linear or Michaelis-Menten elimination, direct and turnover PD models, and combined PK/PD models. Users may also supply custom analytical or ODE models; set modelClass explicitly or use pfim_resolve_model_class. The FIM is computed by first-order linearization with a block-diagonal structure. Population, individual and Bayesian FIMs are available; the Bayesian FIM provides shrinkage predictions. Covariate effects can be tested with covariateTest. Design optimization under the D-criterion uses the simplex algorithm (Nelder-Mead), the multiplicative algorithm, Fedorov-Wynn, PSO (Particle Swarm Optimization) and PGBO (Population Genetics Based Optimizer).

User API

Constructors: Evaluation, Optimization, Arm, Design, ModelParameter, residual-error and distribution classes, FIM types, and algorithm classes. Verbs: run, Report, defineFim, definePKModel, definePKPDModel, getSE/getRSE/getFisherMatrix/getDcriterion/getShrinkage, plotEvaluation/plotSE/plotRSE/plotSensitivityIndices/plotWeights/plotFrequencies, showFIM, covariateTest. Session: pfim_get_option, pfim_set_option, pfim_reset_session. Pipeline helpers (evaluateDesign, optimizeDesign, ...) are internal.

Documentation

Package source, issues, and vignettes are available at http://www.pfim.biostat.fr/.

Session options

pfim_set_option / pfim_get_option; pfim_reset_session clears caches. See ?pfim_set_option for fim.cache, constraints.maxTasks, and performance options.

Covariates and inter-occasion variability

Categorical covariates and inter-occasion variability (IOV) are supported for population, individual and Bayesian FIMs; covariate effect tests use the population FIM. The number of occasions is inferred automatically from the model. Results are shown via show(), plots (ggplot2), and HTML reports.

Author(s)

Author of PFIM 8.0: Romain Leroux romain.leroux@inserm.fr (ORCID).

Contributors: Jérémy Seurat jeremy.seurat@inserm.fr, Antoine Croxo antoine.croxo@inserm.fr.

Maintainer: France Mentré pfim@inserm.fr (ORCID).

References

Dumont C, Lestini G, Le Nagard H, Comets E, Nguyen TT, et al. PFIM 4.0, an extended R program for design evaluation and optimization in nonlinear mixed-effect models. Comput Methods Programs Biomed. 2018;156:217-29.

Chambers JM. Object-Oriented Programming, Functional Programming and R. Stat Sci. 2014;29:167-80.

Nelder JA, Mead R. A simplex method for function minimization. Comput J. 1965;7:308-13.

Seurat J, Tang Y, Mentré F, Nguyen TT. Finding optimal design in nonlinear mixed effect models using multiplicative algorithms. Comput Methods Programs Biomed. 2021;207:106126.

Fedorov VV. Theory of Optimal Experiments. Academic Press, New York, 1972.

Eberhart RC, Kennedy J. A new optimizer using particle swarm theory. Proc. of the Sixth International Symposium on Micro Machine and Human Science, Nagoya, 4-6 October 1995, 39-43.

Le Nagard H, Chao L, Tenaillon O. The emergence of complexity and restricted pleiotropy in adapting networks. BMC Evol Biol. 2011;11:326.

Wickham H. ggplot2: Elegant Graphics for Data Analysis, Springer-Verlag New York, 2016.

See Also

Useful links:

• http://www.pfim.biostat.fr/

Additive

Description

Additive covariate link: theta(cov) = mu * (1 + beta * cov).

Usage

Additive(beta = 0, combinedEffect = 0, value = 0)

Arguments

Value

An S7 object of class Additive.

Examples

Additive(beta = 1, combinedEffect = 0.2)

Administration

Description

Dosing regimen for one outcome: dose amounts, times, infusion duration, and optional inter-dose interval (tau) for repeated dosing or steady state.

When timeDose has length 1 and dose is longer, solvers treat that as a shared administration time (see .alignAdministrationDosing).

Usage

Administration(
  outcome = character(0),
  timeDose = numeric(0),
  dose = numeric(0),
  Tinf = numeric(0),
  tau = 0
)

Arguments

Value

An S7 object of class Administration.

Examples

Administration(outcome = "RespPK", timeDose = 0, dose = 100)

AdministrationConstraints

Description

Allowed dose values per outcome when optimizing or reporting designs.

Used by generateDosesCombination() to build the discrete dose grid for Fedorov-Wynn / multiplicative algorithms (and constraint reports).

Usage

AdministrationConstraints(outcome = character(0), doses = list())

Arguments

Value

An S7 object of class AdministrationConstraints.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(AdministrationConstraints)

Arm

Description

One experimental arm: subjects, dosing, sampling times, and slots filled during design evaluation (model predictions, gradients, variance, FIM).

Usage

Arm(
  name = character(0),
  size = numeric(0),
  administrations = list(),
  initialConditions = list(),
  initialCondition = NULL,
  samplingTimes = list(),
  administrationsConstraints = list(),
  samplingTimesConstraints = list(),
  evaluationModel = list(),
  evaluationGradients = list(),
  evaluationVariance = list(),
  evaluationFim = NULL
)

Arguments

Value

An S7 object of class Arm.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
arm = prop(prop(ev, "designs")[[1L]], "arms")[[1L]]
length(prop(prop(arm, "samplingTimes")[[1L]], "samplings"))

BayesianFim

Description

Bayesian Fisher information matrix with shrinkage on random effects.

First-order linearization on the random-effect scale. Covariate beta is not a subject parameter (MAP conditions on \beta) and is omitted. Across strata / arms, subject FIMs keep their prior and are aggregated by averaging covariances: \bar C = \sum w_s M_s^{-1}, M_{\mathrm{eff}}=\bar C^{-1}. A positive weight on a non-identifiable protocol yields Inf SE for the null-space parameters. This covariance mixture is not comparable to summing Fisher matrices (PFIM 6 / PopED on this case).

With IOV (\gamma>0), each occasion uses the marginal FO residual V_k = R_k + F_k\,\mathrm{diag}(\gamma^2)\,F_k^\top on the \eta-scale (equivalent to the \eta block of the augmented (\eta,\kappa) system).

Usage

BayesianFim(
  fisherMatrix = numeric(0),
  fixedEffects = numeric(0),
  varianceEffects = numeric(0),
  SEAndRSE = list(),
  condNumberFixedEffects = 0,
  condNumberVarianceEffects = 0,
  shrinkage = numeric(0),
  singularFim = FALSE
)

Arguments

Value

A BayesianFim object (filled by run()).

Examples

## Not run: 
vignette("Example01")

## End(Not run)

CategoricalCovariate

Description

The class CategoricalCovariate represents a fixed categorical covariate (constant across occasions): binary or multi-level group membership (sex, genotype, centre, ...).

The constructor validates that categoriesProportions sums to 1 (within floating-point tolerance) before creating the object.

Usage

CategoricalCovariate(name, categories, categoriesProportions, effects = list())

Arguments

Value

An S7 object of class CategoricalCovariate.

Examples

CategoricalCovariate(
  name = "Sex", categories = c("M", "F"),
  categoriesProportions = c(0.5, 0.5)
)

CategoricalCovariateWithIOV

Description

The class CategoricalCovariateWithIOV represents a categorical covariate that varies across occasions (inter-occasion variability design).

Typical use: crossover treatment sequences (AB/BA), period effects, etc.

Each element of sequences is a character vector of category labels, one per occasion. sequencesProportions gives the fraction of subjects following each sequence and must sum to 1.

Usage

CategoricalCovariateWithIOV(
  name,
  categories,
  sequences,
  sequencesProportions,
  effects = list()
)

Arguments

Value

An S7 object of class CategoricalCovariateWithIOV.

Examples

CategoricalCovariateWithIOV(
  name = "Trt",
  categories = c("A", "B"),
  sequences = list(c("A", "B"), c("B", "A")),
  sequencesProportions = c(0.5, 0.5)
)

Combined1

Description

Combined residual error (additive + proportional SD): variance (sigmaInter + sigmaSlope * f^{cError})^2.

Usage

Combined1(
  output = character(0),
  sigmaInter = 0,
  sigmaSlope = 0,
  sigmaInterFixed = FALSE,
  sigmaSlopeFixed = FALSE,
  cError = 1,
  ...
)

Arguments

Value

An S7 object of class Combined1.

Examples

Combined1(output = "RespPK", sigmaInter = 0.5, sigmaSlope = 0.1)

Combined2

Description

Combined residual error with independent additive and proportional SDs: variance sigmaInter^2 + (sigmaSlope * f^{cError})^2. Matches PopED y*(1+e_prop)+e_add when both sigmas are residual SDs.

Usage

Combined2(
  output = character(0),
  sigmaInter = 0,
  sigmaSlope = 0,
  sigmaInterFixed = FALSE,
  sigmaSlopeFixed = FALSE,
  cError = 1,
  ...
)

Arguments

Value

An S7 object of class Combined2.

Examples

Combined2(output = "RespPK", sigmaInter = 0.5, sigmaSlope = 0.1)

Constant

Description

Pure additive residual error: V = sigmaInter^2 (combined1 with sigmaSlope locked to 0).

Usage

Constant(
  output = character(0),
  sigmaInter = 0,
  sigmaSlope = 0,
  sigmaInterFixed = FALSE,
  sigmaSlopeFixed = FALSE,
  cError = 1,
  ...
)

Arguments

Value

An S7 object of class Constant.

Examples

Constant(output = "RespPK", sigmaInter = 0.1)

Covariate

Description

The class Covariate is the base class for all covariate types.

The constructor doubles as a smart factory: when categories is supplied it dispatches to the correct concrete subclass:

• sequences + sequencesProportions -> CategoricalCovariateWithIOV

• categoriesProportions -> CategoricalCovariate

• otherwise -> plain Covariate

Usage

Covariate(
  name,
  effects = list(),
  categories = NULL,
  categoriesProportions = NULL,
  sequences = NULL,
  sequencesProportions = NULL
)

Arguments

Value

An S7 object of class Covariate.

Examples

Covariate(name = "Sex", categories = c("M", "F"),
categoriesProportions = c(0.5, 0.5), effects = list(F = c(V = log(1.2))))

CovariateModelEquation

Description

The class CovariateModelEquation is the base class for the two covariate structural equations supported by PFIM: Additive and Exponential.

A covariate model equation adjusts the population mean for individual i with covariate value

• Additive: \theta = \mu \cdot (1 + \beta \cdot \mathrm{cov})

• Exponential: \theta = \mu \cdot \exp(\beta \cdot \mathrm{cov})

Concrete subclasses implement computeCovariateValue().

Usage

CovariateModelEquation(beta = 0, combinedEffect = 0, value = 0)

Arguments

Value

An S7 object of class CovariateModelEquation.

Examples

CovariateModelEquation(beta = 1, combinedEffect = 0.2)

CovariateTest Class

Description

CovariateTest stores covariate-test results.

Usage

CovariateTest(
  covariate = data.frame(),
  parameter = data.frame(),
  nonRelevance = data.frame(),
  relevance = data.frame(),
  settings = list()
)

Arguments

Details

covariate

Significance on covariate effects \beta

nonRelevance

TOST non-relevance on \beta

relevance

Clinical relevance on \beta

settings

Run options (tests, thetaL/U, targetPower, alpha, N0)

Value

An S7 object of class CovariateTest.

Examples

source(system.file("examples", "covariate-test-minimal.R", package = "PFIM"))
class(ct)

D-criterion

Description

D-criterion

Value

Numeric D-optimality criterion value.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
PFIM:::Dcriterion(prop(ev, "fim"))

Design

Description

Experimental design: one or more arms, each with dosing and sampling schedules. Filled by evaluateDesign() with per-arm FIM results.

Usage

Design(
  name = character(0),
  size = 0,
  arms = list(),
  evaluationArms = list(),
  numberOfArms = 0,
  fim = NULL
)

Arguments

Value

An S7 object of class Design.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
design = prop(ev, "designs")[[1L]]
prop(prop(design, "arms")[[1L]], "size")

Distribution

Description

Base class for parameter distributions (Normal, LogNormal).

Usage

Distribution(name = character(0), mu = 0, omega = 0)

Arguments

Value

An S7 object of class Distribution.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(Distribution)

Evaluation

Description

Design evaluation: build the model, compute the Fisher information matrix (FIM), and store results per design. Inherits PFIMProject fields directly. Use prop for project fields on both Evaluation and Optimization. After run(), getEvaluationDesign returns per-design results when several designs were evaluated.

Equation strings may use declared ModelParameter names, t, dose_* / Tinf_* for administered outcomes, and other outcome names. Free symbols resolve in knitr::knit_global() (while knitting) or globalenv(). Names that already exist on the search path (beta, gamma, pi) are not reported as missing; declare every model parameter explicitly.

Usage

Evaluation(
  evaluationDesign = list(),
  name = character(0),
  modelClass = character(0),
  modelParameters = list(),
  modelCovariates = list(),
  modelCovariatesEquation = character(0),
  modelEquations = list(),
  modelFromLibrary = list(),
  modelError = list(),
  designs = list(),
  outputs = list(),
  fimType = character(0),
  odeSolverParameters = list(),
  numberOfOccasions = NA_real_,
  fim = NULL
)

Arguments

Value

An Evaluation object with evaluationDesign and fim filled.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))

Exponential

Description

Exponential covariate link: theta(cov) = mu * exp(beta * cov).

Usage

Exponential(beta = 0, combinedEffect = 0, value = 0)

Arguments

Value

An S7 object of class Exponential.

Examples

Exponential(beta = 1, combinedEffect = 0.2)

FedorovWynnAlgorithm

Description

Fedorov-Wynn exchange algorithm for D-optimal sampling-time design (Rcpp kernel). Pass elementaryProtocols, numberOfSubjects, and proportionsOfSubjects via optimizerParameters on Optimization. Optional delta (default 1e-4) is the relative optimality gap \max_i \phi_i \le p(1+\delta), same role as in the multiplicative algorithm. Each elementary protocol may be a flat numeric vector (full grid row) or a list of per-outcome vectors that concatenate to that row (typical PK/PD). A vignette-style list(pk, pd) with a single proportion is accepted as one multi-outcome protocol.

Usage

FedorovWynnAlgorithm(FedorovWynnAlgorithmOutputs = list())

Arguments

Details

FedorovWynnAlgorithm: S7 class

Value

A FedorovWynnAlgorithm specification object for run(Optimization).

Examples

## Not run: 
vignette("Example01")

## End(Not run)

Fedorov-Wynn algorithm in Rcpp.

Description

Fedorov-Wynn algorithm in Rcpp.

Arguments

Value

A list with the results of the Fedorov-Wynn algorithm.

Fim

Description

Base class for Fisher information matrices (PopulationFim, IndividualFim, BayesianFim).

Usage

Fim(
  fisherMatrix = numeric(0),
  fixedEffects = numeric(0),
  varianceEffects = numeric(0),
  SEAndRSE = list(),
  condNumberFixedEffects = 0,
  condNumberVarianceEffects = 0,
  shrinkage = numeric(0),
  singularFim = FALSE
)

Arguments

Value

An S7 object holding FIM matrices, SE/RSE tables, and condition numbers.

Examples

PopulationFim()

IndividualFim

Description

Individual (subject-level) Fisher information matrix.

Across covariate strata (and arms at design level), subject FIMs are combined by averaging covariances: \bar C = \sum_s w_s M_s^{-1}, M_{\mathrm{eff}} = \bar C^{-1}. A positive weight on a non-identifiable protocol yields Inf SE. This mixture is not comparable to summing Fisher matrices (PFIM 6 / PopED). Covariate beta effects are not subject parameters and are omitted. With IOV, each occasion uses V_k = R_k + F_k\,\mathrm{diag}(\gamma^2)\,F_k^\top for the \mu and residual \sigma blocks.

Arm-level matrices are per-subject.

Usage

IndividualFim(
  fisherMatrix = numeric(0),
  fixedEffects = numeric(0),
  varianceEffects = numeric(0),
  SEAndRSE = list(),
  condNumberFixedEffects = 0,
  condNumberVarianceEffects = 0,
  shrinkage = numeric(0),
  singularFim = FALSE
)

Arguments

Details

Block-diagonal structure for a single stratum:

M_I = \mathrm{bdiag}(M_\mu, M_\sigma)

where M_\mu = G^\top V^{-1} G and M_\sigma is the residual variance-effects block (with the same V under IOV).

Value

An IndividualFim object (filled by run()).

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))

LibraryOfModels

Description

Registry of built-in PK and PD model definitions.

Subclasses LibraryOfPKModels and LibraryOfPDModels store named equation lists; defineModelEquationsFromLibraryOfModel() looks them up via the package instances pkModelLibrary / pdModelLibrary.

Usage

LibraryOfModels(models = list())

Arguments

Value

An S7 object of class LibraryOfModels.

Examples

length(prop(pkModelLibrary, "models"))
length(prop(pdModelLibrary, "models"))

LibraryOfPDModels

Description

Built-in pharmacodynamic (PD) model library (Emax, turnover, etc.).

Entries are named lists of equation strings (RespPD for immediate response, Deriv_E for turnover ODEs). Combined with a PK model via definePKPDModel().

Usage

LibraryOfPDModels(models = list())

Arguments

Value

An S7 object of class LibraryOfPDModels.

Examples

names(prop(pdModelLibrary, "models"))[1:5]

LibraryOfPKModels

Description

Built-in pharmacokinetic (PK) model library (bolus, infusion, absorption, one- and two-compartment and Michaelis-Menten structures).

Exported Linear* helpers return equation *strings* (not S7 objects): two-compartment forms expand hybrid rates (alpha/beta) and partial-fraction coefficients (A/B) via string substitution. Prefer looking up names in pkModelLibrary for new code.

Usage

LibraryOfPKModels(models = list())

Arguments

Value

An S7 object of class LibraryOfPKModels.

Examples

names(prop(pkModelLibrary, "models"))[1:5]
nzchar(Linear2BolusSingleDose_ClQV1V2())

Analytic PK equation: Linear2BolusSingleDose_ClQV1V2.

Description

Two-compartment IV bolus (Cl, Q, V1, V2 parameterization).

Usage

Linear2BolusSingleDose_ClQV1V2()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2BolusSingleDose_ClQV1V2())

Analytic PK equation: Linear2BolusSingleDose_kk12k21V (micro-constant form).

Description

Analytic PK equation: Linear2BolusSingleDose_kk12k21V (micro-constant form).

Usage

Linear2BolusSingleDose_kk12k21V()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2BolusSingleDose_kk12k21V())

Analytic PK equation: Linear2BolusSteadyState_ClQV1V2tau.

Description

Analytic PK equation: Linear2BolusSteadyState_ClQV1V2tau.

Usage

Linear2BolusSteadyState_ClQV1V2tau()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2BolusSteadyState_ClQV1V2tau())

Analytic PK equation: Linear2BolusSteadyState_kk12k21Vtau.

Description

Analytic PK equation: Linear2BolusSteadyState_kk12k21Vtau.

Usage

Linear2BolusSteadyState_kk12k21Vtau()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2BolusSteadyState_kk12k21Vtau())

Analytic PK equation: Linear2FirstOrderSingleDose_kaClQV1V2.

Description

Analytic PK equation: Linear2FirstOrderSingleDose_kaClQV1V2.

Usage

Linear2FirstOrderSingleDose_kaClQV1V2()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2FirstOrderSingleDose_kaClQV1V2())

Analytic PK equation: Linear2FirstOrderSingleDose_kakk12k21V.

Description

Analytic PK equation: Linear2FirstOrderSingleDose_kakk12k21V.

Usage

Linear2FirstOrderSingleDose_kakk12k21V()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2FirstOrderSingleDose_kakk12k21V())

Analytic PK equation: Linear2FirstOrderSteadyState_kaClQV1V2tau.

Description

Analytic PK equation: Linear2FirstOrderSteadyState_kaClQV1V2tau.

Usage

Linear2FirstOrderSteadyState_kaClQV1V2tau()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2FirstOrderSteadyState_kaClQV1V2tau())

Analytic PK equation: Linear2FirstOrderSteadyState_kakk12k21Vtau.

Description

Analytic PK equation: Linear2FirstOrderSteadyState_kakk12k21Vtau.

Usage

Linear2FirstOrderSteadyState_kakk12k21Vtau()

Value

Character string: closed-form PK equation.

Examples

nzchar(Linear2FirstOrderSteadyState_kakk12k21Vtau())

Analytic PK equation: Linear2InfusionSingleDose_ClQV1V2.

Description

Analytic PK equation: Linear2InfusionSingleDose_ClQV1V2.

Usage

Linear2InfusionSingleDose_ClQV1V2()

Value

Named list with duringInfusion / afterInfusion equation strings.

Examples

nzchar(Linear2InfusionSingleDose_ClQV1V2()$duringInfusion$RespPK)

Analytic PK equation: Linear2InfusionSingleDose_kk12k21V.

Description

Analytic PK equation: Linear2InfusionSingleDose_kk12k21V.

Usage

Linear2InfusionSingleDose_kk12k21V()

Value

Named list with duringInfusion / afterInfusion equation strings.

Examples

nzchar(Linear2InfusionSingleDose_kk12k21V()$duringInfusion$RespPK)

Analytic PK equation: Linear2InfusionSteadyState_ClQV1V2tau.

Description

Analytic PK equation: Linear2InfusionSteadyState_ClQV1V2tau.

Usage

Linear2InfusionSteadyState_ClQV1V2tau()

Value

Named list with duringInfusion / afterInfusion equation strings.

Examples

nzchar(Linear2InfusionSteadyState_ClQV1V2tau()$duringInfusion$RespPK)

Analytic PK equation: Linear2InfusionSteadyState_kk12k21Vtau.

Description

Analytic PK equation: Linear2InfusionSteadyState_kk12k21Vtau.

Usage

Linear2InfusionSteadyState_kk12k21Vtau()

Value

Named list with duringInfusion / afterInfusion equation strings.

Examples

nzchar(Linear2InfusionSteadyState_kk12k21Vtau()$duringInfusion$RespPK)

LogNormal

Description

Log-normal distribution for positive PK/PD parameters (default in PFIM).

Usage

LogNormal(name = character(0), mu = 0, omega = 0)

Arguments

Value

An S7 object of class LogNormal.

Examples

LogNormal(mu = 1, omega = 0.3)

Model

Description

Internal model object built from a PFIMProject: parameters, covariates, equations, and evaluation hooks (gradients, variance).

Usage

Model(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list()
)

Arguments

Value

An S7 object of class Model.

Examples

Model()

ModelAnalytic

Description

Closed-form (non-ODE) PK/PD model with bolus or explicit dosing.

Usage

ModelAnalytic(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  wrapperModelAnalytic = list(),
  functionArgumentsModelAnalytic = list(),
  functionArgumentsSymbolModelAnalytic = list(),
  solverInputs = list()
)

Arguments

Value

An S7 object of class ModelAnalytic.

Examples

ModelAnalytic()

ModelAnalyticInfusion

Description

Closed-form model with infusion (dose in equations). Equations come as duringInfusion / afterInfusion pairs; evaluation superposes past doses (after formula) with the active infusion (during formula) using half-open windows [t_{\mathrm{dose}},\, t_{\mathrm{dose}}+T_{\mathrm{inf}}).

Usage

ModelAnalyticInfusion(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  wrapperModelAnalyticInfusion = list(),
  functionArgumentsModelAnalyticInfusion = list(),
  functionArgumentsSymbolModelAnalyticInfusion = list(),
  solverInputs = list()
)

Arguments

Value

The requested PFIM result.

Examples

ModelAnalyticInfusion()

ModelAnalyticInfusionSteadyState

Description

Analytic infusion model at steady state.

Usage

ModelAnalyticInfusionSteadyState(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  wrapperModelAnalyticInfusion = list(),
  functionArgumentsModelAnalyticInfusion = list(),
  functionArgumentsSymbolModelAnalyticInfusion = list(),
  solverInputs = list()
)

Arguments

Value

An S7 object of class ModelAnalyticInfusionSteadyState.

Examples

ModelAnalyticInfusionSteadyState()

ModelAnalyticSteadyState

Description

Analytic model at steady state (tau in equations).

Usage

ModelAnalyticSteadyState(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  wrapperModelAnalytic = list(),
  functionArgumentsModelAnalytic = list(),
  functionArgumentsSymbolModelAnalytic = list(),
  solverInputs = list()
)

Arguments

Details

ModelAnalyticSteadyState

Value

An S7 object of class ModelAnalyticSteadyState.

Examples

ModelAnalyticSteadyState()

ModelError

Description

Base class for residual error models (Constant, Combined1, Combined2, Proportional).

Variance is determined by sigmaInter (additive SD), sigmaSlope (proportional SD), cError, and varianceForm:

• "combined1": V=(a + b f^{c})^2

• "combined2": V=a^2 + (b f^{c})^2 (PopED-style)

A sigma is estimable in the FIM iff it is non-zero and not marked fixed (sigmaInterFixed / sigmaSlopeFixed).

Usage

ModelError(
  output = "output",
  sigmaInter = 0,
  sigmaSlope = 0,
  sigmaInterFixed = FALSE,
  sigmaSlopeFixed = FALSE,
  cError = 1,
  varianceForm = "combined1",
  ...
)

Arguments

Value

An S7 object of class ModelError.

Examples

ModelError()

ModelInfusion

Description

Base class for infusion administration models.

Usage

ModelInfusion(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list()
)

Arguments

Value

An S7 object of class ModelInfusion.

Examples

ModelInfusion()

ModelODE

Description

Base class for models integrated with deSolve.

Usage

ModelODE(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list()
)

Arguments

Value

An S7 object of class ModelODE.

Examples

ModelODE()

ModelODEBolus

Description

ODE bolus model with doses in initial conditions.

Usage

ModelODEBolus(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  modelODE = function() NULL,
  doseEvent = list(),
  solverInputs = list()
)

Arguments

Value

An S7 object of class ModelODEBolus.

Examples

ModelODEBolus()

ModelODEDoseInEquations

Description

ODE model with bolus dose terms inside the differential equations.

Usage

ModelODEDoseInEquations(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  modelODEDoseInEquations = function() NULL,
  solverInputs = list()
)

Arguments

Value

An S7 object of class ModelODEDoseInEquations.

Examples

ModelODEDoseInEquations()

ModelODEDoseNotInEquations

Description

ODE model with bolus doses added as compartment events.

Usage

ModelODEDoseNotInEquations(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  modelODE = function() NULL,
  doseEvent = list(),
  solverInputs = list()
)

Arguments

Value

An S7 object of class ModelODEDoseNotInEquations.

Examples

ModelODEDoseNotInEquations()

ModelODEInfusion

Description

ODE model with infusion inputs.

Inherits from ModelODE (numerical nature) rather than ModelInfusion, so S7_inherits(x, ModelODE) is TRUE for infusion ODEs. Use .pfimIsInfusionModel() for the infusion capability.

Usage

ModelODEInfusion(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list()
)

Arguments

Value

An S7 object of class ModelODEInfusion.

Examples

ModelODEInfusion()

ModelODEInfusionDoseInEquation

Description

ODE infusion model with dose terms in the equations.

Usage

ModelODEInfusionDoseInEquation(
  name = character(0),
  modelParameters = list(),
  modelCovariatesEquation = NULL,
  modelCovariates = list(),
  covariatesEffect = list(),
  covariatesCombination = list(),
  modelParametersWithCovariates = list(),
  numberOfOccasions = 1,
  omegaWithIOV = numeric(0),
  samplings = numeric(0),
  modelEquations = list(),
  wrapper = function() NULL,
  outputFormula = list(),
  outputNames = character(0),
  variableNames = character(0),
  outcomesWithAdministration = character(0),
  outcomesWithNoAdministration = character(0),
  modelError = list(),
  odeSolverParameters = list(),
  parametersForComputingGradient = list(),
  initialConditions = numeric(0),
  functionArguments = character(0),
  functionArgumentsSymbol = list(),
  modelODE = function() NULL,
  wrapperModelInfusion = list(),
  solverInputs = list()
)

Arguments

Value

An S7 object of class ModelODEInfusionDoseInEquation.

Examples

ModelODEInfusionDoseInEquation()

ModelParameter

Description

One population model parameter: distribution (mu, omega), optional IOV (gamma), and fix flags.

Usage

ModelParameter(
  name = character(0),
  gamma = 0,
  distribution = NULL,
  fixedMu = FALSE,
  fixedOmega = FALSE,
  value = numeric(0)
)

Arguments

Value

An S7 object of class ModelParameter.

Examples

ModelParameter(name = "Cl", distribution = LogNormal(mu = 1, omega = 0.3))

MultiplicativeAlgorithm

Description

Multiplicative weight algorithm for optimal sampling-time allocation (Rcpp kernel). Pass lambda, delta, numberOfIterations, and weightThreshold via optimizerParameters on Optimization.

Outputs store two D-values: mixtureDcriterion is the D of the continuous mixture over retained candidate cells; realisedDcriterion is the D of the single protocol actually implemented. For joint multi-outcome cells (several arms sharing one protocol in the constraint grid), only the best-weighted cell is kept - mixture weights describe the optimisation simplex, not a multi-protocol subject allocation across joint arms.

Usage

MultiplicativeAlgorithm(multiplicativeAlgorithmOutputs = list())

Arguments

Value

A MultiplicativeAlgorithm specification object.

Examples

## Not run: 
vignette("Example01")

## End(Not run)

MultiplicativeAlgorithm_Rcpp

Description

Calls the compiled Rcpp implementation of the multiplicative weight-update algorithm. Registered via Rcpp::compileAttributes() in R/RcppExports.R.

Arguments

Value

Named list: weights, iterations, converged, singularFim.

Normal

Description

Normal distribution for model parameters (identity link on the mean).

Usage

Normal(name = character(0), mu = 0, omega = 0)

Arguments

Value

An S7 object of class Normal.

Examples

Normal(mu = 0, omega = 1)

Optimization

Description

Design optimization: search over sampling times (or related design variables) using a metaheuristic or exchange algorithm.

Project fields use prop. Several designs: all optimizers (discrete and continuous) optimize each in turn (optimisationAlgorithmOutputs$perDesign).

Usage

Optimization(
  name = character(0),
  modelClass = character(0),
  modelEquations = list(),
  modelCovariatesEquation = character(0),
  modelFromLibrary = list(),
  modelParameters = list(),
  modelCovariates = list(),
  modelError = list(),
  optimizer = character(0),
  optimizerParameters = list(),
  outputs = list(),
  designs = list(),
  fimType = character(0),
  fim = NULL,
  odeSolverParameters = list(),
  numberOfOccasions = NA_real_,
  project = NULL,
  optimisationDesign = list(),
  optimisationAlgorithmOutputs = list()
)

Arguments

Value

An Optimization object; after run(), see optimisationDesign and optimisationAlgorithmOutputs.

Examples

## Not run: 
vignette("Example01")

## End(Not run)

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
class(ev)

PFIMProject

Description

Base S7 class for PFIM design evaluation and optimization projects.

Set numberOfOccasions on Evaluation or Optimization (optional: NA infers from covariates and IOV). When set explicitly, it must match inferNumberOfOccasions. The resolved value is stored on the Model in defineModelType().

All fimType values support covariates and IOV; population adds omega and gamma blocks to the FIM.

Usage

PFIMProject(
  name = character(0),
  modelClass = character(0),
  modelEquations = list(),
  modelCovariatesEquation = character(0),
  modelFromLibrary = list(),
  modelParameters = list(),
  modelCovariates = list(),
  modelError = list(),
  optimizer = character(0),
  optimizerParameters = list(),
  outputs = list(),
  designs = list(),
  fimType = character(0),
  fim = NULL,
  odeSolverParameters = list(),
  numberOfOccasions = NA_real_,
  cacheScope = ""
)

Arguments

Value

An S7 object of class PFIMProject.

Examples

PFIMProject(name = "demo")

PGBOAlgorithm

Description

Population-based global optimization for sampling times (Rcpp kernel). Pass N, muteEffect, maxIteration, purgeIteration, and seed via optimizerParameters on Optimization. muteEffect is an additive mutation scale in the same time unit as the sampling windows (e.g. hours), not a ratio in [0,1]. Search starts from each outcome's initialSamplings; seed controls mutation draws only. Optional fitBase (default 0.03) and cauchyProb (default 0.8, probability of a Cauchy jump vs Gaussian group mutation). Optional tolerance (default 0, stall stop disabled -> converged = NA) and stallIterations (default 5) enable early stopping when tolerance > 0.

Usage

PGBOAlgorithm(optimizerOutputs = list())

Arguments

Value

A PGBOAlgorithm specification object.

Examples

## Not run: 
vignette("Example02")

## End(Not run)

PSOAlgorithm

Description

Particle Swarm Optimization for sampling-time search (Rcpp kernel in src/PSOKernel.cpp). Pass maxIteration, populationSize, seed, and learning coefficients via optimizerParameters on Optimization. Search starts from each outcome's initialSamplings (reported initial design); seed controls swarm exploration after that start. Optional tolerance (default 0, stall stop disabled -> converged = NA) and stallIterations (default 5) enable early stopping when tolerance > 0.

Usage

PSOAlgorithm(optimizerOutputs = list())

Arguments

Value

A PSOAlgorithm specification object.

Examples

## Not run: 
vignette("Example02")

## End(Not run)

PopulationFim

Description

Population Fisher information matrix for nonlinear mixed-effects models.

Usage

PopulationFim(
  fisherMatrix = numeric(0),
  fixedEffects = numeric(0),
  varianceEffects = numeric(0),
  SEAndRSE = list(),
  condNumberFixedEffects = 0,
  condNumberVarianceEffects = 0,
  shrinkage = numeric(0),
  singularFim = FALSE
)

Arguments

Details

The population FIM has fixed-effects (\mu, \beta) and variance-effects (\omega^2, \gamma^2, \sigma) blocks:

M_P = \mathrm{bdiag}(N \cdot M_\mu,\; N \cdot M_\lambda)

where N is the arm size and M_\mu = G_\mu^\top V^{-1} G_\mu.

Value

A PopulationFim object (filled by run()).

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
S7::S7_inherits(prop(ev, "fim"), PopulationFim)

Proportional

Description

Pure proportional residual error: V = (sigmaSlope * f^{cError})^2 (combined1 with sigmaInter locked to 0).

Usage

Proportional(
  output = character(0),
  sigmaInter = 0,
  sigmaSlope = 0,
  sigmaInterFixed = FALSE,
  sigmaSlopeFixed = FALSE,
  cError = 1,
  ...
)

Arguments

Value

An S7 object of class Proportional.

Examples

Proportional(output = "RespPK", sigmaSlope = 0.15)

Generate an HTML evaluation or optimization report

Description

Requires rmarkdown and pandoc (https://pandoc.org).

Rebuilds kable tables and plots for both the initial and optimal evaluations, then hands everything to generateReportOptimization() with the FIM-type R Markdown template.

Assembles model / design / FIM kables and response / SI / SE / RSE plots, then dispatches to the FIM-type R Markdown template via generateReportEvaluation(). Administration / initial-design tables use design 1 only; response and SI plots cover every design in designs.

Usage

Report(pfimproject, ...)

Arguments

Value

Invisibly, the path or result from the report generator.

Examples

## Not run: 
source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
tmp = tempfile(fileext = ".html")
Report(ev, outputPath = tempdir(), outputFile = basename(tmp), plotOptions = list())

## End(Not run)

SamplingTimeConstraints

Description

Constraints on sampling times for design optimization (windows, fixed times, number of points to optimize, minimum spacing).

Metaheuristics (Simplex / PSO / PGBO) draw candidates with generateSamplingsFromSamplingConstraints() and reject infeasible ones via checkSamplingTimeConstraintsForMetaheuristic(). Discrete algorithms instead enumerate combinations with generateSamplingTimesCombination().

Usage

SamplingTimeConstraints(
  outcome = character(0),
  initialSamplings = numeric(0),
  fixedTimes = numeric(0),
  numberOfsamplingsOptimisable = 0,
  numberOfSamplingsOptimisable = NULL,
  samplingsWindows = list(),
  numberOfTimesByWindows = numeric(0),
  minSampling = numeric(0)
)

Arguments

Value

An S7 object of class SamplingTimeConstraints.

Examples

SamplingTimeConstraints(
  outcome = "RespPK",
  initialSamplings = c(0.5, 2, 8),
  numberOfsamplingsOptimisable = 2
)

SamplingTimes

Description

Observation times for one outcome within an arm.

Times are in the model's time unit (often hours). Multiple SamplingTimes objects on an arm cover multi-response designs.

Usage

SamplingTimes(outcome = character(0), samplings = numeric(0))

Arguments

Value

An S7 object of class SamplingTimes.

Examples

SamplingTimes(outcome = "RespPK", samplings = c(1, 4, 8))

SimplexAlgorithm

Description

Nelder-Mead (amoeba) optimization for sampling times (Rcpp kernel). Pass pctInitialSimplexBuilding, tolerance, and maxIteration via optimizerParameters on Optimization. Search starts from each outcome's initialSamplings (same flat layout as PSO/PGBO). Extra vertices move one coordinate toward the far end of its sampling window (not toward 0), so unequal numberOfTimesByWindows stays feasible. Infeasible initialSamplings are replaced by a feasible window start with a warning. tolerance <= 0 disables the relative stop (converged = NA, no warning), matching PSO/PGBO when stall stop is off.

Usage

SimplexAlgorithm(optimizerOutputs = list())

Arguments

Value

A SimplexAlgorithm specification object.

Examples

## Not run: 
vignette("Example02")

## End(Not run)

Scale gradients by the distribution link (identity or log-normal).

Description

Used when mapping \partial f / \partial \theta to \partial f / \partial \eta at the typical value for the population FIM.

Multiplies the gradient by thetaValue (same as LogNormal).

Scales by thetaValue so \partial f / \partial \eta = \theta \cdot \partial f / \partial \theta at the typical value.

For a normal random-effect model, \partial f / \partial \eta = \partial f / \partial \theta.

Usage

adjustGradient(distribution, gradient, thetaValue)

Arguments

Value

Gradient scaled by thetaValue.

Gradient scaled by thetaValue.

Unchanged numeric gradient vector.

Collapse nested combination-by-occasion gradients to one matrix (all outputs stacked).

Description

Plot / label helper only: E[G] = \sum_c \pi_c \mathrm{mean}_k G_{c,k}. Individual / Bayesian FIM must not use this for Fisher blocks - use .evaluateIndBayesMixtureFim() (\sum_c \pi_c \sum_k G^\top R^{-1} G).

Usage

aggregateGradientsWithCovariates(model, arm)

Arguments

Value

Numeric matrix (stacked outputs x parameters).

Expectation of residual variance over combinations / occasions (plots / flat V).

Description

Same averaging contract as aggregateGradientsWithCovariates. FIM assembly for Individual / Bayesian uses .evaluateIndBayesMixtureFim() instead.

Usage

aggregateVarianceWithCovariates(arm)

Arguments

Value

List with errorVariance and sigmaDerivatives.

Tabular administration settings for reports

Description

Tabular administration settings for reports

Default method for Arm.

Usage

armAdministration(arm, designName, ...)

Arguments

Value

List of administration rows formatted for reports.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(armAdministration)

Check that proposed times meet window counts and min spacing.

Description

Returns two logicals: whether each window contains exactly numberOfTimesByWindows points, and whether consecutive points inside each window respect minSampling. Shared endpoints are partitioned by numberOfTimesByWindows (same split as .pfimTimesByDeclaredWindows()).

Usage

checkSamplingTimeConstraintsForMetaheuristic(
  samplingTimesConstraints,
  arm,
  ...
)

Arguments

Value

List with constraintWindowsLength and constraintMinimalSampling.

Examples

## Not run: 
source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(checkSamplingTimeConstraintsForMetaheuristic)

## End(Not run)

Validate generated sampling constraints for feasibility

Description

Same slack test as generateSamplingsFromSamplingConstraints: max - min - (n-1)*delta >= 0. Also requires sum(numberOfTimesByWindows) == length(samplings) per outcome, and that the current sampling times actually occupy the declared windows (counts and minSampling).

Usage

checkValiditySamplingConstraint(design, ...)

Arguments

Value

Logical value indicating whether sampling constraints are valid.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(checkValiditySamplingConstraint)

Apply beta and combinedEffect to produce the adjusted parameter value.

Description

Dispatches to Additive or Exponential methods (see those classes).

Builds a new Additive whose value is beta * (1 + combinedEffect) (elementwise over parameters).

Builds a new Exponential whose value is beta * exp(combinedEffect) (elementwise over parameters).

Arguments

Value

An updated CovariateModelEquation subclass object.

Additive object containing transformed parameter values.

Exponential object containing transformed parameter values.

Examples

PFIM:::computeCovariateValue(Additive(), beta = 2, combinedEffect = 0.1)

Build constraints table used in reports

Description

Build constraints table used in reports

Constraint tables for optimization reports

Constraint tables for optimization reports

Constraint tables for optimization reports

Constraint tables for optimization reports

Constraint tables for optimization reports

Usage

constraintsTableForReport(optimizationAlgorithm, ...)

Arguments

Value

Constraint report tables as a list or data frame.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(constraintsTableForReport)

Convert analytic PK equations to ODE-compatible form

Description

Applies .convertAnalyticPkExprToOde to every equation in the duringInfusion and afterInfusion lists so infusion analytic models can be remapped onto ODE library compartments.

Usage

convertPKModelAnalyticToPKModelODE(pkModel, ...)

Arguments

Value

Character vector of ODE-compatible PK equations.

List with duringInfusion and afterInfusion ODE strings.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(convertPKModelAnalyticToPKModelODE)

covariateTest

Description

Assess significance and clinical relevance from the evaluation FIM.

Pipeline: pull SE/RSE -> classify betas inside/outside the equivalence window on the relative-effect scale -> fill requested tables -> wrap in CovariateTest.

Usage

covariateTest(
  pfimproject,
  thetaL = log(0.8),
  thetaU = log(1.25),
  targetPower = 0.9,
  alpha = 0.05,
  tests = c("significance", "nonRelevance", "relevance")
)

tost(
  pfimproject,
  thetaL = log(0.8),
  thetaU = log(1.25),
  targetPower = 0.9,
  alpha = 0.05,
  tests = c("significance", "nonRelevance", "relevance")
)

Arguments

Details

Covariate effects \beta only. Use tests to select which tables are computed and displayed ("significance", "nonRelevance", "relevance"). Requires a population FIM: individual and Bayesian FIMs omit \beta (subject-level precision conditions on covariates).

Relative-effect display (Ratio, TOST IC) uses e^{\beta} for the exponential covariate link and 1+\beta for the additive link. The clinical window [thetaL, thetaU] remains on the log-ratio scale (default bioequivalence [log(0.80), log(1.25)]).

Sample-size scaling: population FIM recovers unit variance as SE^2 * N0; individual / Bayesian FIM (not multiplied by arm size) use N_scale = 1, so N_Required is the number of independent replications of the subject-level design.

Output column order (PFIM4-compatible): Value, SE, RSE, then (TOST) Ratio and IC bounds, then Power, N_Required. Each table is preceded by the target power for N_Required and, for TOST tables, the equivalence IC bounds.

Value

A CovariateTest object.

Examples

source(system.file("examples", "covariate-test-minimal.R", package = "PFIM"))
nrow(prop(ct, "covariate"))
ct_nr = covariateTest(ev, tests = "nonRelevance")

Build one effect vector for a selected category

Description

The reference category leaves effectVector unchanged; other categories write their named effects entries into matching parameter slots.

Usage

createEffectVector(covariate, ...)

Arguments

Value

A numeric vector of covariate effects.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(createEffectVector)

Prepare all model covariate-derived data structures

Description

Pipeline: effect vectors -> combination grid -> occasion-specific mus -> omega.

Usage

defineCovariatesData(model, ...)

Arguments

Value

Model with covariate effects, combinations, and omega matrix prepared.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(defineCovariatesData)

Build the FIM object from project settings

Description

Instantiates PopulationFim, IndividualFim, or BayesianFim from the project's fimType string via the type registry.

Usage

defineFim(pfimproject, ...)

Arguments

Value

Fim instance built from nested project settings.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
defineFim(ev)

Bind dosing schedules and sampling grids to the model

Description

For tau != 0, expands a single dose into a regular grid 0, tau, 2*tau, ... up to the last sampling time. At each sampling, records relative times since each past dose and how many distinct dose contributions are active (for linear superposition).

Labels each sampling as duringInfusion or afterInfusion on half-open windows [t_{\mathrm{dose}},\, t_{\mathrm{dose}}+T_{\mathrm{inf}}), and records the active dose index plus relative times since each past dose (for superposition in evaluateAnalyticInfusionCore).

For tau != 0, expands a single steady-state dose into a regular grid 0, tau, 2*tau, ... up to the last sampling time. Labels each sampling as duringInfusion or afterInfusion, and records which dose index is active at that time (for superposition of past infusions).

Usage

defineModelAdministration(model, ...)

Arguments

Value

Updated model with samplings and solverInputs.

Updated ModelAnalyticInfusion object with solver inputs.

Updated model with samplings and solverInputs.

Updated model with solver input structures.

Updated model with ODE solver function and inputs.

Updated model with bolus-in-initial-condition administration setup.

Updated model with dose-in-equation administration setup.

Updated model with event-based administration setup.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(defineModelAdministration)

Build model equations from PK/PD model library entries

Description

Looks up modelFromLibrary$PKModel (and optional PDModel), temporarily writes each library equation onto the project to infer model class, then returns the combined PK or PK/PD equation list.

Usage

defineModelEquationsFromLibraryOfModel(pfimproject, ...)

Arguments

Value

List of model equations resolved from the library.

List of model equations resolved from library entries.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
nrow(getFisherMatrix(ev)$fisherMatrix)

Infer and instantiate the concrete model class

Description

Resolves modelClass (explicit or legacy token detection), copies parameters/covariates onto a fresh model instance, then attaches residual error, ODE tolerances, occasions, and the additive/exponential covariate structural equation when requested.

Usage

defineModelType(pfimproject, ...)

Arguments

Value

Concrete Model object inferred from project equations.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(defineModelType)

Compile model equations and output mapping before evaluation

Description

Splits library equations into outcomes that receive dosing versus those that do not (e.g. PD linked to PK), then builds two R functions via .buildAnalyticWrapper. Administered wrappers take dose_* / t_*; passive wrappers take the administered outcome values as inputs.

Splits library equations into administered vs non-administered outcomes, then builds four R functions via .buildAnalyticWrapper. Steady state adds tau to the shared formal argument list.

Does not compile wrappers yet; compilation happens in defineModelAdministration once arm dosing is known.

Usage

defineModelWrapper(model, ...)

Arguments

Value

Updated model with compiled analytic wrappers.

Updated ModelAnalyticInfusion object with compiled wrappers.

Updated model with compiled infusion steady-state wrappers.

Updated model with compiled analytic wrappers.

Updated model with wrapper metadata.

Updated ModelODEBolus wrapper configuration.

Updated ModelODEDoseInEquations wrapper configuration.

Updated ModelODEDoseNotInEquations wrapper configuration.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(defineModelWrapper)

Instantiate optimization algorithm from project configuration.

Description

Looks up optimizer on the nested project and builds the matching algorithm object (Multiplicative, Fedorov-Wynn, Simplex, PSO, PGBO, ...).

Usage

defineOptimizationAlgorithm(optimization, ...)

Arguments

Value

An optimization algorithm object.

Examples

# help(defineOptimizationAlgorithm)

Remap library PK equations onto project compartments

Description

Remap library PK equations onto project compartments

Return PK equations stored on the analytic model (library / user).

Default method for ModelAnalyticInfusion.

Return PK equations stored on the model (library / user analytic infusion SS).

Return PK equations stored on the steady-state analytic model.

Remap library ODE infusion PK equations onto project compartments.

Remap library ODE PK equations onto project compartments (bolus IC).

Return PK equations stored on the dose-in-equation model.

Return PK equations stored on the dose-event model.

Usage

definePKModel(pkModel, pfimproject, ...)

Arguments

Value

List of PK model equations for the project compartments.

List of PK equations from pkModel.

List of PK equations from pkModel.

List of PK equations from pkModel.

List of PK equations from pkModel.

List of remapped PK equations for infusion ODE models.

Named list of remapped PK equations.

List of PK equations from pkModel.

List of PK equations from pkModel.

Examples

## Not run: 
vignette("LibraryOfModels")

## End(Not run)

Combine PK and PD library equations for the project

Description

Combine PK and PD library equations for the project

Concatenate analytic PK and analytic PD equation lists.

Convert analytic PK to ODE, append ODE PD, and remap library compartments.

Default method for ModelAnalyticInfusion.

Default method for ModelAnalyticInfusion.

Concatenate steady-state analytic PK with analytic PD equation lists.

Convert SS analytic PK to ODE, append ODE PD, and remap library compartments.

Combine remapped infusion PK with ODE PD for during and after phases.

Usage

definePKPDModel(pkModel, pdModel, pfimproject, ...)

Arguments

Value

Combined PK/PD equation list for the project.

Concatenated analytic PK and PD equation list.

Named list of remapped PK/PD ODE equations.

List with during/after infusion equation sets.

List with during/after infusion combined ODE equations.

Concatenated analytic PK/PD equation list.

Named list of remapped ODE equations.

List with combined PK/PD equations for during and after infusion.

Examples

## Not run: 
vignette("LibraryOfModels")

## End(Not run)

Ensure outputNames is filled from project outputs when empty.

Description

Ensure outputNames is filled from project outputs when empty.

Usage

ensureModelOutputNames(model, pfimproject)

Evaluate analytic bolus concentrations at all sampling times.

Description

For each observation time and administered outcome, evaluates the closed-form formula over all active doses (superposition via sum), then evaluates passive (non-admin) equations with the administered prediction injected into the shared argument list.

Usage

evaluateAnalyticCore(model, arm)

Arguments

Value

Named list of output data frames at requested sampling times.

Evaluate analytic infusion predictions (superposition of during/after doses).

Description

Unlike the steady-state infusion core, arguments are passed as named lists (vectorised over past doses when several infusions contribute).

Usage

evaluateAnalyticInfusionCore(model, arm)

Arguments

Value

Named list of output data frames at sampling times.

Evaluate analytic infusion steady-state concentrations at all sampling times.

Description

For each observation time and administered outcome:

1. If inside an infusion window: evaluate the during-infusion formula for the current dose; if earlier doses exist, add their after-infusion remnants.

2. If after an infusion: evaluate the after-infusion formula for the current dose, again superposing remnants of previous doses.

Passive (non-admin) equations are evaluated once the administered outcome value is assigned into the shared evaluation environment.

Usage

evaluateAnalyticInfusionSteadyStateCore(model, arm)

Arguments

Value

Named list of output data frames at requested sampling times.

Evaluate analytic steady-state predictions (sum over contributing doses).

Description

Same superposition pattern as evaluateAnalyticCore, but each wrapper call also receives tau (dosing interval) required by the closed forms.

Usage

evaluateAnalyticSteadyStateCore(model, arm)

Arguments

Value

Named list of output data frames at requested sampling times.

Evaluate model, gradients, variance and FIM for one arm

Description

With covariates/IOV, uses the occasion-averaged evaluation core; otherwise runs the flat path. The FIM template is reset by .duplicateFim() before evaluateFim().

Usage

evaluateArm(arm, ...)

Arguments

Details

Flat path reuses the FD grid's nominal column as evaluationModel (one fewer full model solve per arm - same pattern as the covariate path).

Value

Arm populated with model, gradient, variance, and FIM results.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(evaluateArm)

Build covariate effect vectors for model parameters

Description

Build covariate effect vectors for model parameters

Build per-covariate effect vectors aligned with model parameter names.

Usage

evaluateCovariatesEffects(model, ...)

Arguments

Value

Model with grouped covariate effect vectors.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(evaluateCovariatesEffects)

Evaluate a design for a model and FIM type

Description

Runs evaluateArm() on each arm, then .assembleDesignFim().

Usage

evaluateDesign(design, ...)

Arguments

Value

The updated Design object after evaluation.

The same Design with evaluationArms and fim set.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
length(prop(ev, "evaluationDesign"))

Evaluate residual variance and dV/dsigma diagonals

Description

Evaluate residual variance and dV/dsigma diagonals

Usage

evaluateErrorModelDerivatives(modelError, ...)

Arguments

Value

List with errorVariance and sigmaDerivatives.

Examples

err = Combined2(output = "RespPK", sigmaInter = 0.2, sigmaSlope = 0.1)
PFIM:::evaluateErrorModelDerivatives(err, c(1, 2))

Compute the Bayesian FIM for one arm.

Description

FO Bayesian FIM: M^\top M_{\mathrm{data}} M + \Omega^{-1} for every parameter with \omega > 0 (\beta omitted; fix flags do not drop eta). Shrinkage (%) uses M_{\mathrm{BF}}^{-1}\Omega^{-1}.

Fixed-effect block plus residual variance block; not scaled by arm size. Cov/IOV strata use the harmonic-mean subject FIM. No \omega/\gamma block - only \mu and residual \sigma (\beta omitted).

Builds fixed-effect and variance-effect blocks, scales both by arm size N, and returns bdiag(N M_beta, N M_lambda). Fixed-\mu columns are dropped from the FE block; fixedOmega (not fixedMu) drops \omega^2 from the variance block.

Usage

evaluateFim(fim, model, arm, ...)

Details

Scaling: both FE and VE blocks are \times N (iid subjects in the arm). Individual FIM does not scale; Bayesian shrinkage is per-subject then aggregated at the design level.

Value

The updated Fim object after evaluation.

Evaluate ODE initial conditions from the arm

Description

Delegates to .evalInitialConditionsImpl: substitutes typical values into arm initial-condition expressions (numeric values pass through).

Usage

evaluateInitialConditions(model, ...)

Arguments

Value

Named numeric vector of evaluated initial conditions.

Numeric vector of evaluated initial conditions.

Named numeric vector of evaluated initial conditions.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(evaluateInitialConditions)

Predict model responses at arm sampling times

Description

Predict model responses at arm sampling times

Dispatch: covariate/occasion structure -> specialised path; else core evaluator.

Default method for ModelAnalyticInfusion.

Dispatch: covariate/occasion structure -> specialised path; else core evaluator.

Dispatch: covariate/occasion structure -> specialised path; else SS core evaluator.

Dispatch: covariate/occasion structure -> specialised path; else core evaluator.

Dispatch: covariate/occasion structure -> specialised path; else core evaluator.

Dispatch: covariate/occasion structure -> specialised path; else core evaluator.

Dispatch: covariate/occasion structure -> specialised path; else core evaluator.

Usage

evaluateModel(model, ...)

Arguments

Value

Named list of output data frames at requested sampling times.

Named list of output data frames at sampling times.

Named list of output data frames at requested sampling times.

Named list of output data frames at requested sampling times.

Named list of output data frames at requested sampling times.

Model outputs at arm sampling times.

Model outputs at arm sampling times.

Model outputs at arm sampling times.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(evaluateModel)

Gradients of model responses with respect to parameters

Description

Gradients of model responses with respect to parameters

Dispatch gradient evaluation: simple path or covariatexoccasion expansion.

Usage

evaluateModelGradient(model, ...)

Arguments

Value

Gradient structure for the model, with covariate expansion when needed.

Evaluate gradient core without covariate expansion.

Description

Evaluate gradient core without covariate expansion.

Usage

evaluateModelGradientCore(model, arm)

Arguments

Value

Named list of gradient data frames by output.

Evaluate gradients with covariate and occasion structure.

Description

Evaluate gradients with covariate and occasion structure.

Usage

evaluateModelGradientWithCovariates(model, arm, evaluateModelGradientCore)

Arguments

Value

Nested list of gradients by combination and occasion.

Residual variance at sampling times for an arm

Description

Residual variance at sampling times for an arm

Usage

evaluateModelVariance(model, ...)

Arguments

Evaluate model outputs over covariate combinations and occasions

Description

Evaluate model outputs over covariate combinations and occasions

Evaluate model outputs over every covariate combination and occasion.

Usage

evaluateModelWithCovariates(model, ...)

Arguments

Value

Nested list of evaluations keyed by combination and occasion.

Construct omega matrix with IOV structure from covariates

Description

Construct omega matrix with IOV structure from covariates

Cache the IIV variance diagonal (\omega^2) on the model.

Usage

evaluateOmegaMatrixFromCovariates(model, ...)

Arguments

Value

Model with omegaWithIOV variance matrix populated.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(evaluateOmegaMatrixFromCovariates)

Variance / data block of the Bayesian FIM (mu only; no beta, no sigma).

Description

Flat: G^\top V^{-1} G. Nested cov/IOV: harmonic mean of subject FIMs (prior included per stratum).

Flat path: one residual V. Nested cov/IOV path: harmonic mean of per-stratum blocks (see .evaluateIndBayesMixtureFim).

Usage

evaluateVarianceFIM(fim, model, arm, ...)

Value

A variance contribution matrix for the FIM.

Finite-difference perturbations for gradient computation

Description

Relative steps are \varepsilon^{1/3}\max(|\mu|, 10^{-4}). Scale mus to O(1) so the absolute floor does not dominate the truncation error.

Usage

finiteDifferenceHessian(model, ...)

Arguments

Value

Model with finite-difference gradient precomputation fields.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(finiteDifferenceHessian)

Nelder-Mead simplex minimiser (Rcpp).

Description

Compiled implementation in src/SimplexAlgorithm.cpp. The objective funk remains an R callback because FIM evaluation stays in R. Vertices are flat sampling vectors (same layout as PSO); C++ never sees arms.

Arguments

Value

List with p, y, iterations, converged, results.

Generate covariate combination grid and proportions

Description

Proportions multiply across covariates; names encode cov=level pairs.

Usage

generateCovariatesCombination(model, ...)

Arguments

Value

Model with covariate combination grid and proportions.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(generateCovariatesCombination)

Enumerate dose combinations under design constraints

Description

Builds the Cartesian product of dose lists across arms/outcomes, guarded by .pfimMaxCombinationCount. Returns a nested list keyed by arm and outcome, plus numberOfDoses.

Usage

generateDosesCombination(design, ...)

Arguments

Value

A list or matrix of generated dose combinations.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(generateDosesCombination)

Evaluate constraint-generated arm candidates.

Description

Enumerates the Cartesian product of dose and sampling grids under design constraints, evaluates a FIM for each cell (optionally subsampled via constraints.maxTasks), and returns matrices for Fedorov-Wynn and multiplicative algorithms.

Enables eval.batch so nested run(Evaluation) calls share caches. Flat index fimIndex maps to (dose, sampling combo) via integer division; results are reshaped into the lists expected by FW / multiplicative optimizers. Each cell returns both a packed triangle (listFimsAlgoFW) and a dense matrix (listFimsAlgoMult) - do not swap those keys.

Usage

generateFimsFromConstraints(optimization, ...)

Arguments

Value

A list of FIM objects and arm layouts generated from design constraints.

Examples

## Not run: 
source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(generateFimsFromConstraints)

## End(Not run)

Generate an evaluation report from FIM results

Description

Generate an evaluation report from FIM results

Render the evaluation HTML report

Render the evaluation HTML report

Render the evaluation HTML report

Usage

generateReportEvaluation(fim, ...)

Arguments

Value

Invisibly, the generated report path or render result.

Examples

## Not run: 
source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# Report(ev, outputPath = tempdir())

## End(Not run)

Generate an optimization report from FIM results

Description

Generate an optimization report from FIM results

Usage

generateReportOptimization(fim, optimizationAlgorithm, ...)

Arguments

Value

Invisibly, the generated report path or render result.

Examples

## Not run: 
\dontrun{vignette("Example01")}

## End(Not run)

Enumerate sampling-time combinations under constraints

Description

For each arm and outcome: combn of free times plus fixed times, then expand.grid across outcomes (guarded before materialising). Returns a named list of arms -> list of sampling schedules for FIM evaluation.

Usage

generateSamplingTimesCombination(design, ...)

Arguments

Value

A list or matrix of generated sampling-time combinations.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(generateSamplingTimesCombination)

Draw random sampling times inside each window (respecting min spacing).

Description

For each window [min, max] with n points and minimum gap delta, places ordered uniforms so consecutive samples are at least delta apart: remaining slack is max - min - (n-1)*delta.

Usage

generateSamplingsFromSamplingConstraints(samplingTimeConstraints, ...)

Arguments

Value

Numeric vector of generated sampling times (all windows concatenated).

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(generateSamplingsFromSamplingConstraints)

Administration and sampling constraints for an optimizer

Description

Administration and sampling constraints for an optimizer

Usage

getArmConstraints(arm, optimizationAlgorithm, ...)

Arguments

Value

A list of arm-level optimization constraints.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getArmConstraints)

Dose and sampling summary for reports

Description

Dose and sampling summary for reports

Build dose / sampling summary rows for HTML and console reports.

Usage

getArmData(arm, ...)

Arguments

Value

List of arm-level dose and sampling summaries by outcome.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getArmData)

Flat gradient matrix for Individual/Bayesian FIM (aggregates nested evaluations when needed).

Description

Flat gradient matrix for Individual/Bayesian FIM (aggregates nested evaluations when needed).

Usage

getArmEvaluationGradientsMatrix(
  model,
  arm,
  pfimproject = NULL,
  evalModel = NULL
)

Arguments

Value

Numeric matrix (observation rows x parameter columns).

Flat residual variance for Individual/Bayesian FIM.

Description

Flat residual variance for Individual/Bayesian FIM.

Usage

getArmEvaluationVarianceFlat(arm)

Arguments

Value

List with errorVariance and sigmaDerivatives.

Return the reference category for a covariate

Description

Return the reference category for a covariate

Reference category for a covariate (first element of categories).

Usage

getCategoryOfReference(covariate, ...)

Arguments

Value

A character value naming the reference category.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getCategoryOfReference)

Retrieve correlation matrix from results

Description

Retrieve correlation matrix from results

Parameter correlations from the optimal design FIM.

Parameter correlations from the evaluated design FIM.

Usage

getCorrelationMatrix(pfimproject, ...)

Arguments

Value

Correlation matrix of the parameter estimates.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getCorrelationMatrix)

Return covariate effect vectors by category

Description

Returns a named list (one entry per category) built by createEffectVector() from a shared null/base vector.

Each sequence yields a list of occasion-level effect vectors (same length as the sequence), used when averaging the FIM over crossover designs.

Usage

getCovariateEffects(covariate, ...)

Arguments

Value

A numeric vector or list of covariate effects.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getCovariateEffects)

Build HTML tables from a covariate test result

Description

Build HTML tables from a covariate test result

Usage

getCovariateTestTables(covariateTestResult, tests = NULL)

Arguments

Value

Named list of knitr_kable objects (or NULL if empty). Element significance is the covariate slot (report alias).

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getCovariateTestTables)

Retrieve D-criterion from project results

Description

Retrieve D-criterion from project results

D-criterion of the optimal design.

D-criterion of the evaluated design.

Usage

getDcriterion(pfimproject, ...)

Arguments

Value

Numeric D-optimality criterion value.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
getDcriterion(ev)

Retrieve determinant of the Fisher matrix

Description

Retrieve determinant of the Fisher matrix

Determinant of the optimal design FIM.

Determinant of the evaluated design FIM.

Usage

getDeterminant(pfimproject, ...)

Arguments

Value

Numeric determinant of the Fisher information matrix.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
getDeterminant(ev)

Per-design evaluation result from a multi-design run().

Description

Per-design evaluation result from a multi-design run().

Usage

getEvaluationDesign(evaluation, design = 1L)

Arguments

Value

One element of evaluationDesign (evaluated design with fim).

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getEvaluationDesign)

Extract FIM matrix blocks from an evaluation.

Description

Returns the named blocks of the project (or selected design) FIM rather than the S7 object itself - convenient for scripts that only need matrices.

Usage

getFim(evaluation, ...)

Arguments

Value

List with fisherMatrix, fixedEffects, varianceEffects.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
getFim(ev)

Retrieve the Fisher information matrix from results

Description

Runs setEvaluationFim() so dimnames and SE/RSE match the current model metadata, then returns the matrix blocks used by report helpers, plus singularFim.

Usage

getFisherMatrix(pfimproject, ...)

Arguments

Value

A list with fisherMatrix, fixedEffects, varianceEffects, and singularFim.

List with fisherMatrix, fixedEffects, varianceEffects, and singularFim.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
getFisherMatrix(ev)

D-criterion of the continuous mixture over retained Multiplicative cells.

Description

Differs from getDcriterion() (implemented protocol) when joint cells or Hamilton allocation change the realised design. Requires MultiplicativeAlgorithm results.

Usage

getMixtureDcriterion(pfimproject, ...)

Arguments

Value

Numeric D-criterion of the continuous mixture.

Extract residual error settings for reports

Description

Extract residual error settings for reports

Usage

getModelErrorData(modelError, ...)

Arguments

Value

One-row data frame of residual-error settings.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getModelErrorData)

Parameter table for reports (mu, omega2, gamma2, fix flags, distribution)

Description

Parameter table for reports (mu, omega2, gamma2, fix flags, distribution).

Usage

getModelParametersData(modelParameter, ...)

Arguments

Value

A data frame of model parameter values.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getModelParametersData)

Occasion count for a built Model object.

Description

Occasion count for a built Model object.

Usage

getNumberOfOccasionsForModel(model)

Arguments

Value

Integer number of occasions.

Extract the number of occasions from IOV covariate sequences.

Description

Reads sequence lengths from every CategoricalCovariateWithIOV and requires them to match.

Usage

getOccasionsFromIOVCovariates(modelCovariates)

Arguments

Value

Integer occasion count (1 if no IOV covariate is present).

Retrieve relative standard errors from results

Description

Retrieve relative standard errors from results

Relative standard errors from the optimal design FIM (after run()).

Relative standard errors (%) from the evaluated design FIM.

Usage

getRSE(pfimproject, ...)

Arguments

Value

A list or matrix of relative standard errors (percent).

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
getRSE(ev)

D-criterion of the single protocol implemented after Multiplicative allocation.

Description

Matches getDcriterion() on the optimal evaluation. Requires MultiplicativeAlgorithm results.

Usage

getRealisedDcriterion(pfimproject, ...)

Arguments

Value

Numeric D-criterion of the implemented protocol.

Retrieve standard errors from results

Description

Retrieve standard errors from results

Standard errors from the optimal design FIM (after run()).

Standard errors from the evaluated design FIM.

Usage

getSE(pfimproject, ...)

Arguments

Value

A list or matrix of standard errors for the FIM parameters.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
getSE(ev)

Sampling times and grid extent for evaluation plots

Description

Sampling times and grid extent for evaluation plots

Default method for Arm.

Usage

getSamplingData(arm, ...)

Arguments

Value

List containing per-outcome sampling objects and numeric grids.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getSamplingData)

Retrieve shrinkage metrics from results

Description

Retrieve shrinkage metrics from results

Parameter shrinkage from the Bayesian optimal-design FIM.

Parameter shrinkage from a Bayesian evaluation FIM (empty for other types).

Usage

getShrinkage(pfimproject, ...)

Arguments

Value

Numeric vector or list of Bayesian shrinkage values.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(getShrinkage)

Report whether a model includes covariates

Description

Report whether a model includes covariates

Report whether the model defines any covariates.

Usage

hasCovariates(model, ...)

Arguments

Value

Logical scalar indicating whether covariates are configured.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(hasCovariates)

Infer the number of study occasions for a model.

Description

Rules (in order):

1. If any CategoricalCovariateWithIOV is present, use the common sequence length (e.g. 2, 3, or 4 periods).

2. Else if any parameter has gamma > 0 (random IOV), default to 2 occasions; set numberOfOccasions >= 2 on the project for more periods.

3. Else use 1 occasion.

Usage

inferNumberOfOccasions(modelCovariates = list(), modelParameters = list())

Arguments

Value

Integer number of occasions.

Build occasion-specific parameters for each covariate combination

Description

Applies additive or exponential covariate links to mu for each occasion.

Usage

modelParametersWithCovariates(model, ...)

Arguments

Value

Model with occasion-specific parameter sets by combination.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(modelParametersWithCovariates)

Optimize design for a given algorithm.

Description

Dispatches on the algorithm class. Typical pipeline after run(): resolve library equations -> define FIM -> call the algorithm-specific optimizeDesign method, which writes optimisationDesign and optimisationAlgorithmOutputs.

Pipeline: enumerate constraint-grid FIMs -> match each elementaryProtocols seed to a full grid row -> call C++ exchange -> map frequencies to arms -> re-evaluate initial vs optimal designs.

Usage

optimizeDesign(optimizationObject, optimizationAlgorithm, ...)

Arguments

Value

The updated Optimization object after design optimization.

The same Optimization with optimisationDesign and optimisationAlgorithmOutputs filled.

The same Optimization with optimisationDesign and optimisationAlgorithmOutputs filled.

Updated Optimization after optimizing each design in turn.

Updated Optimization after optimizing each design in turn.

Updated Optimization after optimizing each design in turn.

Examples

## Not run: 
source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(optimizeDesign)

## End(Not run)

Parse combination name and fill missing reference values.

Description

Parse combination name and fill missing reference values.

Usage

parseCombinationName(combinationName, modelCovariates)

Arguments

Value

Named list of covariate values including references.

Default built-in PD model library instance.

Description

Default built-in PD model library instance.

Usage

pdModelLibrary

Format

An S7 object of class LibraryOfPDModels.

Value

A LibraryOfPDModels object.

See Also

LibraryOfPDModels for the class constructor.

Examples

length(prop(pdModelLibrary, "models"))

Arm constraints (reports)

Description

Arm constraints for optimization HTML reports.

Details

S7 generic getArmConstraints(arm, optimizationAlgorithm) dispatches on the optimizer class: discrete algorithms (Multiplicative, Fedorov-Wynn) use fixed-time / dose tables; continuous ones (Simplex, PSO, PGBO) use sampling windows. Shared row builders live in .armConstraintsDiscrete here and .armConstraintsContinuous in pfim-utils.R.

Constraint tables for optimization reports.

Description

Builds kableExtra tables of arm-level dose/sampling constraints for discrete (Fedorov-Wynn / Multiplicative) and continuous (PSO / PGBO / Simplex) optimizers. Uses getArmConstraints() from pfim-arm-constraints.R.

Extension listing helpers (model classes, FIM types, optimizers).

Description

Thin wrappers over the registries in pfim-registry.R and pfim-model-registry.R for interactive discovery of registered plugins.

Load-time setOptimalArms and report methods.

Description

Registers S7 methods that map each (FIM type x optimizer) pair to the helper that builds optimal arms after optimizeDesign(), and attaches HTML report templates per FIM type. Continuous optimizers (Simplex / PSO / PGBO) share one path; discrete Multiplicative / Fedorov-Wynn use population-specific helpers that allocate subjects from weights / frequencies.

FIM type and optimizer registries.

Description

Package-private environments map string names to factory functions:

• .pfimFimTypeRegistry - "population", "individual", "bayesian" (and any type registered with pfim_register_fim_type)

• .pfimFimDuplicatorRegistry - how to clone a FIM while clearing computed slots (SE, matrices, ...) for design-level copies

• .pfimOptimizerRegistry - S7 optimizer constructors used by Optimization / run()

Built-ins are registered at load time via .pfimInitBuiltinRegistries().

FIM cache sizes and hit counts

Description

FIM cache sizes and hit counts

Usage

pfim_cache_stats()

Value

A list of cache statistics.

Examples

PFIM:::pfim_cache_stats()

Read a PFIM session option

Description

Read a PFIM session option

Usage

pfim_get_option(name, default = NULL)

Arguments

Value

Option value.

See Also

pfim_set_option, pfim_reset_session

Examples

pfim_get_option("fim.cache.maxEntries")

List registered extensions

Description

List registered extensions

Usage

pfim_list_extensions()

Value

A list of registered extension names.

Examples

pfim_list_extensions()

Register a custom FIM type

Description

Extends PFIM with a new fimType string for Evaluation / Optimization. The factory is called whenever a project needs a fresh FIM of that type. Overwrites silently if name already exists.

Usage

pfim_register_fim_type(name, factory, duplicator = .fimDuplicateReset)

Arguments

Value

Invisibly, NULL.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(pfim_register_fim_type)

Register a model class

Description

Register a model class

Usage

pfim_register_model_class(className, factory, detect = NULL)

Arguments

Value

Invisibly, NULL.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(pfim_register_model_class)

Register a custom optimizer

Description

Makes optimizer = name valid on Optimization. The factory must return an S7 optimizer object with an optimizeDesign method. Overwrites silently if name already exists.

Usage

pfim_register_optimizer(name, factory)

Arguments

Value

Invisibly, NULL.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(pfim_register_optimizer)

Registered model class names

Description

Registered model class names

Usage

pfim_registered_model_classes()

pfim_registered_fim_types()

pfim_registered_optimizers()

Value

A character vector of registered class names.

Examples

pfim_registered_model_classes()
pfim_registered_fim_types()
pfim_registered_optimizers()

Reset PFIM session options and clear all computed-data caches.

Description

Clears .pfimSession options and empties the design FIM cache (.pfimFimDesignCache), covariate/occasion cache, eval-model rebuild cache, and gradient/ODE performance caches (FD scheme, admin, ODE time grids). Call between unrelated runs in a long-lived R session (Shiny, services).

Usage

pfim_reset_session(closeDevices = FALSE)

Arguments

Value

Invisibly NULL.

Examples

pfim_reset_session()

Resolve model class name for a project

Description

Resolve model class name for a project

Usage

pfim_resolve_model_class(pfimproject)

Arguments

Value

Character class name with attribute source ("registry" or "legacy").

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(pfim_resolve_model_class)

Set PFIM session options

Description

Options apply for the current R session until pfim_reset_session.

Usage

pfim_set_option(...)

Arguments

Value

Invisibly NULL.

See Also

pfim_get_option, pfim_reset_session

Examples

pfim_set_option(fim.cache.maxEntries = 2048L)

Population Genetics Based Optimization kernel (Rcpp).

Description

Compiled implementation in src/PGBOAlgorithm.cpp. R=>C++ contract: sorting_groups are 1-based; mutations are per group. check_valid_group(trial, group_1based) is the feasibility gate (no windows_list clamp - unlike PSO). eval_d returns D (not 1/D); the kernel minimises 1/D.

Value

A list of optimization results.

Default built-in PK model library instance.

Description

Default built-in PK model library instance.

Usage

pkModelLibrary

Format

An S7 object of class LibraryOfPKModels.

Value

A LibraryOfPKModels object.

See Also

LibraryOfPKModels for the class constructor.

Examples

length(prop(pkModelLibrary, "models"))

Plot evaluation outputs for a project

Description

Plot evaluation outputs for a project

Predicted responses for the optimal design evaluation.

Predicted responses with sampling markers for all designs/arms.

Usage

plotEvaluation(pfimproject, ...)

Arguments

Value

A nested list of ggplot2 plot objects (by design / arm / outcome).

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
names(plotEvaluation(ev, list()))

ggplot of predicted responses with sampling points

Description

ggplot of predicted responses with sampling points

Default method for Arm.

Usage

plotEvaluationResults(arm, ...)

Arguments

Value

Nested list of ggplot objects for model responses.

ggplot of parameter sensitivities over time

Description

ggplot of parameter sensitivities over time

Default method for Arm.

Usage

plotEvaluationSI(arm, ...)

Arguments

Value

Nested list of ggplot objects for sensitivity indices.

Plot optimized sampling frequencies

Description

Plot optimized sampling frequencies

Fedorov-Wynn optimal frequencies

Usage

plotFrequencies(optimization, ...)

Arguments

Value

A ggplot2 plot object.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(plotFrequencies)

Frequency trajectories of the Fedorov-Wynn algorithm

Description

Frequency trajectories of the Fedorov-Wynn algorithm

Value

A ggplot2 plot object.

Examples

## Not run: 
# help(plotFrequenciesFedorovWynnAlgorithm); vignette("Example01")

## End(Not run)

Plot relative standard errors for project results

Description

Plot relative standard errors for project results

RSE bar chart for the optimal design FIM.

RSE bar chart for the primary evaluation FIM.

Usage

plotRSE(pfimproject, ...)

Arguments

Value

A ggplot2 plot object.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
inherits(plotRSE(ev), "ggplot")

Plot relative standard errors from a FIM

Description

Plot relative standard errors from a FIM

Usage

plotRSEFIM(fim, evaluation, ...)

Arguments

Value

A ggplot2 plot object.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
PFIM:::plotRSEFIM(prop(ev, "fim"), ev)

Plot standard errors for project results

Description

Plot standard errors for project results

SE bar chart for the optimal design FIM.

SE bar chart for the primary evaluation FIM.

Usage

plotSE(pfimproject, ...)

Arguments

Value

A ggplot2 plot object.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
inherits(plotSE(ev), "ggplot")

Plot standard errors from a FIM

Description

Plot standard errors from a FIM

Usage

plotSEFIM(fim, evaluation, ...)

Arguments

Value

A ggplot2 plot object.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
PFIM:::plotSEFIM(prop(ev, "fim"), ev)

Plot sensitivity indices for a project

Description

Plot sensitivity indices for a project

Sensitivity-index plots for the optimal design evaluation.

Sensitivity indices over time for all designs/arms.

Usage

plotSensitivityIndices(pfimproject, ...)

Arguments

Value

A ggplot2 plot object.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
names(plotSensitivityIndices(ev, list()))

Plot Bayesian shrinkage from a FIM

Description

Plot Bayesian shrinkage from a FIM

Default method for BayesianFim.

Usage

plotShrinkage(fim, evaluation, ...)

Arguments

Value

ggplot object showing Bayesian shrinkage by parameter.

Examples

## Not run: 
source(system.file("examples", "covariate-test-minimal.R", package = "PFIM"))
# plotShrinkage(prop(ev, "fim"), ev)  # BayesianFim

## End(Not run)

Plot optimized arm weights

Description

Plot optimized arm weights

Multiplicative algorithm weights by iteration

Usage

plotWeights(optimization, ...)

Arguments

Value

A ggplot2 plot object.

Examples

source(system.file("examples", "evaluation-minimal.R", package = "PFIM"))
# help(plotWeights)

Weight trajectories of the multiplicative algorithm

Description

Weight trajectories of the multiplicative algorithm

Value

A ggplot2 plot object.

Examples

## Not run: 
# help(plotWeightsMultiplicativeAlgorithm)

## End(Not run)

Model response plots for one arm

Description

Re-evaluates the model on a dense time grid and overlays the design sampling times as red markers. The FIM arm is not modified.

Usage

processArmEvaluationResults(arm, model, fim, ...)

Arguments

Value

Nested list of response plots by design and arm.

Sensitivity-index plots for one arm

Description

Re-evaluates gradients on the same dense grid as the response plots. Covariate beta_* columns are omitted from sensitivity plots.

Usage

processArmEvaluationSI(arm, model, fim, ...)

Arguments