pymixef.backends.base module

Shared contracts and numerical helpers for reference estimation backends.

Backends accept either a mapping or an object (including the compiler’s DesignMatrices object). If present, to_backend_data() is called first. The common numeric fields are:

response / y

One-dimensional response vector.

fixed / X

Two-dimensional fixed-effect design matrix.

fixed_names

Optional names matching the columns of X.

random_blocks

A sequence of mappings/objects. Each block supplies matrix/Z and may supply row-level groups/group_codes, group_levels, term_names, correlated, and name. A row-level random design is expanded into one block of columns per group. An already-expanded design can be marked with expanded=True.

residual_covariance

Optional explicit positive-definite covariance or correlation matrix. LMM treats it as a correlation template and estimates a common scale unless residual_covariance_fixed=True.

weights / offset / trials

Optional observation vectors used by applicable engines.

MMRM additionally consumes subject/group labels, visit labels, visit times, and a covariance structure; those details are documented in mmrm.py.

Every backend returns the backend-neutral mapping specified in ARCHITECTURE.md: parameters, unconstrained_parameters, parameter_covariance, fitted_values, residuals, random_effects, objective, log_likelihood, method, engine, convergence, diagnostic_data, and extra.

class pymixef.backends.base.Backend(*args, **kwargs)[source]

Bases: Protocol

Protocol implemented by all estimation engines.

name: str
fit(data, **options)[source]

Fit a compiled numeric model and return the shared payload.

Parameters:

  • data (Any)

  • options (Any)

Return type:

dict[str, Any]

exception pymixef.backends.base.BackendError(message, *, code='BACKEND-001', details=None, suggested_engines=())[source]

Bases: PyMixEFError

A stable, machine-readable backend input or numerical error.

Parameters:

  • message (str)

  • code (str)

  • details (Mapping[str, Any] | None)

  • suggested_engines (Sequence[str])

Return type:

None

to_dict()[source]

Return a JSON-compatible diagnostic record.

Return type:

dict[str, Any]

exception pymixef.backends.base.BackendInputError(message, *, details=None)[source]

Bases: BackendError

The compiled numeric input is invalid.

Parameters:

  • message (str)

  • details (Mapping[str, Any] | None)

Return type:

None

exception pymixef.backends.base.BackendNumericalError(message, *, details=None)[source]

Bases: BackendError

A numerical calculation failed before a valid payload could be made.

Parameters:

  • message (str)

  • details (Mapping[str, Any] | None)

Return type:

None

exception pymixef.backends.base.BackendUnsupportedError(message, *, details=None, suggested_engines=())[source]

Bases: EngineCompatibilityError

The requested model is scientifically unsupported by this engine.

Parameters:

  • message (str)

  • details (Mapping[str, Any] | None)

  • suggested_engines (Sequence[str])

Return type:

None

to_dict()[source]

Return a JSON-compatible diagnostic record.

Return type:

dict[str, Any]

class pymixef.backends.base.CompiledData(source, y, X, fixed_names, random_blocks, offset, weights, trials, residual_covariance, residual_covariance_fixed)[source]

Bases: object

Normalized fields shared by LMM and GLMM.

Parameters:

  • source (Any)

  • y (NDArray[float64])

  • X (NDArray[float64])

  • fixed_names (tuple[str, ...])

  • random_blocks (tuple[RandomBlockData, ...])

  • offset (NDArray[float64])

  • weights (NDArray[float64])

  • trials (NDArray[float64] | None)

  • residual_covariance (Any)

  • residual_covariance_fixed (bool)

source: Any
y: NDArray[float64]
X: NDArray[float64]
fixed_names: tuple[str, ...]
random_blocks: tuple[RandomBlockData, ...]
offset: NDArray[float64]
weights: NDArray[float64]
trials: NDArray[float64] | None
residual_covariance: Any
residual_covariance_fixed: bool
property n_obs: int
property n_fixed: int
property random_design: NDArray[float64]
class pymixef.backends.base.CovarianceParameterization(block)[source]

Bases: object

Positive-definite random covariance parameterization.

Parameters:

block (RandomBlockData)

block: RandomBlockData
property size: int
initial(scale)[source]
Parameters:

scale (float)

Return type:

NDArray[float64]

matrix(theta)[source]
Parameters:

theta (ArrayLike)

Return type:

NDArray[float64]

expanded_matrix(theta)[source]
Parameters:

theta (ArrayLike)

Return type:

NDArray[float64]

names_and_values(theta)[source]
Parameters:

theta (ArrayLike)

Return type:

dict[str, float]

unconstrained_names()[source]
Return type:

list[str]

class pymixef.backends.base.RandomBlockData(name, row_design, design, group_codes, group_levels, term_names, correlated, terms_per_group)[source]

Bases: object

One expanded random-effect design block.

Parameters:

  • name (str)

  • row_design (NDArray[float64])

  • design (NDArray[float64])

  • group_codes (NDArray[int64])

  • group_levels (tuple[Any, ...])

  • term_names (tuple[str, ...])

  • correlated (bool)

  • terms_per_group (int)

name: str
row_design: NDArray[float64]
design: NDArray[float64]
group_codes: NDArray[int64]
group_levels: tuple[Any, ...]
term_names: tuple[str, ...]
correlated: bool
terms_per_group: int
property n_groups: int
property coefficient_count: int
coefficient_labels()[source]
Return type:

list[str]

pymixef.backends.base.backend_mapping(data)[source]

Resolve an optional to_backend_data conversion.

Parameters:

data (Any)

Return type:

Any

pymixef.backends.base.cho_solve(cholesky, value)[source]

Solve against a lower Cholesky factor.

Parameters:

  • cholesky (NDArray[float64])

  • value (ArrayLike)

Return type:

NDArray[float64]

pymixef.backends.base.convergence_mapping(*, success, message, iterations, function_evaluations, gradient, hessian_positive_definite, singular, boundary_parameters=(), warnings=(), extra=None)[source]

Create a rich convergence mapping accepted by the public result layer.

Parameters:

  • success (bool)

  • message (str)

  • iterations (int)

  • function_evaluations (int)

  • gradient (ArrayLike | None)

  • hessian_positive_definite (bool | None)

  • singular (bool)

  • boundary_parameters (Sequence[str])

  • warnings (Sequence[Mapping[str, Any]])

  • extra (Mapping[str, Any] | None)

Return type:

dict[str, Any]

pymixef.backends.base.covariance_from_hessian(hessian)[source]

Return a symmetric generalized inverse and definiteness flag.

Parameters:

hessian (ArrayLike)

Return type:

tuple[NDArray[float64], bool]

pymixef.backends.base.covariance_slices(blocks)[source]

Build covariance parameterizations and their theta slices.

Parameters:

blocks (Sequence[RandomBlockData])

Return type:

tuple[tuple[CovarianceParameterization, slice], …]

pymixef.backends.base.factorize(values)[source]

Factorize values in first-observed order without a pandas dependency.

Parameters:

values (ArrayLike)

Return type:

tuple[NDArray[int64], tuple[Any, …]]

pymixef.backends.base.field(source, *names, default=_MISSING)[source]

Retrieve the first matching mapping key or object attribute.

Parameters:

  • source (Any)

  • names (str)

  • default (Any)

Return type:

Any

pymixef.backends.base.finite_gradient(function, point, *, relative_step=1e-6)[source]

Central finite-difference gradient used for termination verification.

Parameters:

  • function (Any)

  • point (ArrayLike)

  • relative_step (float)

Return type:

NDArray[float64]

pymixef.backends.base.finite_hessian(function, point, *, relative_step=2e-4)[source]

Central finite-difference Hessian for small reference problems.

Parameters:

  • function (Any)

  • point (ArrayLike)

  • relative_step (float)

Return type:

NDArray[float64]

pymixef.backends.base.logdet_from_cholesky(cholesky)[source]

Return the log determinant represented by a lower Cholesky factor.

cholesky is assumed to have a positive diagonal; this helper does not validate that the factor came from a positive-definite matrix.

Parameters:

cholesky (NDArray[float64])

Return type:

float

pymixef.backends.base.make_payload(**values)[source]

Validate and order the shared backend payload.

Parameters:

values (Any)

Return type:

dict[str, Any]

pymixef.backends.base.optimizer_covariance(function, point, result, *, compute_hessian, finite_difference_limit)[source]

Return auditable optimizer-scale covariance at the selected optimum.

Parameters:

  • function (Any)

  • point (ArrayLike)

  • result (Any)

  • compute_hessian (bool)

  • finite_difference_limit (int)

Return type:

tuple[NDArray[float64], bool | None, str]

pymixef.backends.base.prepare_data(data, *, require_random=False)[source]

Normalize common compiler output for a numerical backend.

Parameters:

  • data (Any)

  • require_random (bool)

Return type:

CompiledData

pymixef.backends.base.prepare_random_block(raw, n_rows, index)[source]

Validate and expand one compiler random block.

Parameters:

  • raw (Any)

  • n_rows (int)

  • index (int)

Return type:

RandomBlockData

pymixef.backends.base.random_covariance(parameterizations, theta)[source]

Assemble block-diagonal covariance for all expanded coefficients.

Parameters:
Return type:

NDArray[float64]

pymixef.backends.base.safe_cholesky(matrix, *, jitter_scale=1e-10, max_tries=5)[source]

Cholesky factor a symmetric matrix, adding only reported tiny jitter.

Parameters:

  • matrix (ArrayLike)

  • jitter_scale (float)

  • max_tries (int)

Return type:

tuple[NDArray[float64], float]

pymixef.backends.base.select_optimizer_result(refined, rescue, *, objective_tolerance)[source]

Prefer successful finite termination before comparing objective values.

A line-search refinement can improve an objective by floating-point noise while still reporting an abnormal termination. In that case, retaining a successfully terminated derivative-free rescue is more informative than replacing it with the failed refinement.

Parameters:

  • refined (Any)

  • rescue (Any)

  • objective_tolerance (float)

Return type:

Any

pymixef.backends.base.validate_payload(payload)[source]

Validate the backend-neutral result contract and return canonical key order.

The validator is shared by built-in and third-party backends. It checks presence, numeric finiteness, observation alignment, covariance shape, convergence state, and container types without imposing an engine-specific parameterization.

Parameters:

payload (Mapping[str, Any])

Return type:

dict[str, Any]