Parameters

class openpkpd.model.parameters.ThetaSpec(init, lower=-inf, upper=inf, fixed=False, label=None)[source]

Bases: object

Specification for a single THETA parameter.

Parameters:
init: float
lower: float = -inf
upper: float = inf
fixed: bool = False
label: str | None = None
__init__(init, lower=-inf, upper=inf, fixed=False, label=None)
Parameters:
Return type:

None

class openpkpd.model.parameters.OmegaSpec(block_size, values, fixed=False, same=False, label=None)[source]

Bases: object

Specification for an OMEGA block.

Parameters:
block_size: int
values: list[float]
fixed: bool = False
same: bool = False
label: str | None = None
to_matrix()[source]

Expand lower-triangle values to full symmetric matrix.

Values are stored in row-major lower-triangle order (NONMEM convention): v11; v21 v22; v31 v32 v33; …

Return type:

ndarray

__init__(block_size, values, fixed=False, same=False, label=None)
Parameters:
Return type:

None

class openpkpd.model.parameters.SigmaSpec(block_size, values, fixed=False, label=None)[source]

Bases: object

Specification for a SIGMA block (residual error variance).

Parameters:
block_size: int
values: list[float]
fixed: bool = False
label: str | None = None
to_matrix()[source]

Expand lower-triangle values to full symmetric matrix.

Values are stored in row-major lower-triangle order (NONMEM convention): v11; v21 v22; v31 v32 v33; …

Return type:

ndarray

__init__(block_size, values, fixed=False, label=None)
Parameters:
Return type:

None

class openpkpd.model.parameters.ParameterSet(theta, omega, sigma, theta_specs=<factory>, omega_specs=<factory>, sigma_specs=<factory>)[source]

Bases: object

A concrete parameter point in (THETA, OMEGA, SIGMA) space.

THETA: 1-D array of population fixed effects. OMEGA: full n_eta × n_eta positive-definite matrix. SIGMA: full n_eps × n_eps positive-definite matrix.

Parameters:
theta: ndarray
omega: ndarray
sigma: ndarray
theta_specs: list[ThetaSpec]
omega_specs: list[OmegaSpec]
sigma_specs: list[SigmaSpec]
to_vector()[source]

Pack free parameters into a 1-D vector for the optimizer.

Return type:

ndarray

Convention:

  • Free THETA values (log-transformed if lower=0)

  • Free OMEGA lower-Cholesky elements (diagonal log-transformed)

  • Free SIGMA lower-Cholesky elements (diagonal log-transformed)

classmethod from_vector(vec, template)[source]

Unpack optimizer vector back to structured ParameterSet.

Return type:

ParameterSet

Parameters:
apply_bounds()[source]

Clamp THETA to bounds; ensure OMEGA/SIGMA are positive-definite.

Return type:

ParameterSet

classmethod from_specs(theta_specs, omega_specs, sigma_specs)[source]

Build a ParameterSet from specs using initial values.

Return type:

ParameterSet

Parameters:
n_theta()[source]
Return type:

int

n_eta()[source]
Return type:

int

n_eps()[source]
Return type:

int

n_iov_occasions()[source]

Number of occasions for IOV (count OMEGA SAME specs).

An OmegaSpec with same=True means this OMEGA block is a copy of the preceding block (NONMEM OMEGA SAME syntax). Each such repetition represents an additional occasion.

Return type:

int

Returns:

Number of occasions. Returns 1 when no IOV is present (every individual has exactly one occasion).

has_iov()[source]

Return True if any OMEGA spec has same=True.

An OmegaSpec with same=True signals that this block is an IOV (Inter-Occasion Variability) repetition of the preceding block.

Return type:

bool

expand_omega_iov(n_occasions)[source]

Expand OMEGA to handle IOV by creating per-occasion ETA blocks.

For each OmegaSpec that is not marked same=True, the block is repeated n_occasions times to form a block-diagonal OMEGA. The resulting OMEGA has n_eta_base * n_occasions random effects.

This mirrors the NONMEM pattern:

$OMEGA BLOCK(1) 0.04
$OMEGA BLOCK(1) SAME   ; occasion 2
$OMEGA BLOCK(1) SAME   ; occasion 3

which openpkpd stores as one BLOCK + two SAME entries.

Parameters:

n_occasions (int) – Number of occasions to expand to. Must be >= 1.

Return type:

ParameterSet

Returns:

A new ParameterSet with expanded OMEGA (block-diagonal over occasions) and OMEGA specs updated accordingly. THETA and SIGMA are copied unchanged.

Raises:

ValueError – If n_occasions < 1.

n_free()[source]

Number of free (non-fixed) parameters in the optimization vector.

Return type:

int

get_optimizer_bounds()[source]

Return L-BFGS-B bounds for every element of to_vector().

  • Free THETA: (None, None) — the logit/log transform already enforces spec.lower/upper in from_vector/apply_bounds.

  • OMEGA/SIGMA log-Cholesky diagonal: (None, _MAX_COVA_LOG_DIAG_BOUND) so omega_ii ≤ _MAX_OMEGA_DIAG. Prevents the outer loop from driving IIV to infinity (a degenerate but numerically cheap solution). No lower bound is set: if the optimizer drives omega toward zero, the objective() closure detects the resulting 1e10 penalty and retries with a cold η-hat reset (see foce.py) to recover clean OFV.

  • OMEGA/SIGMA off-diagonal Cholesky elements: (None, None).

Return type:

list[tuple[float | None, float | None]]

__init__(theta, omega, sigma, theta_specs=<factory>, omega_specs=<factory>, sigma_specs=<factory>)
Parameters:
Return type:

None