API reference¶
Acceleration¶
- pydaarem.daarem(par, fixptfn, objfn=None, *args, control=None, **kwargs)¶
Accelerate a fixed-point iteration with DAAREM.
DAAREM is a damped Anderson acceleration scheme with periodic restarts and monotonicity control. It is intended as an off-the-shelf accelerator for smooth, monotone, slowly converging fixed-point iterations, including expectation-maximization (EM), minorization-maximization (MM), and related algorithms.
- Parameters:
- par
array, shape (n_parameters,) Starting values for the parameter vector.
parcan be an array of any library that supports the Python array API standard, for example NumPy, PyTorch or CuPy. A list or a scalar is converted to a NumPy array. The computation uses the namespace and the device ofpar, with the float64 data type.- fixptfncallable
Fixed-point mapping
G. The callable must accept the current parameter vector as its first argument and return a vector with the same length. It defines the iterationx[k + 1] = G(x[k]). For an EM algorithm, this function performs one E/M update.- objfncallable or
None, optional Scalar merit function
Lthat is maximized at the fixed point ofG. The callable must accept the parameter vector as its first argument and return a scalar. For an EM algorithm, this is typically the observed-data log-likelihood. Supplyingobjfnis optional but preferable because it enables monotonicity control. IfNoneis passed, DAAREM uses the residual-norm acceptance rule from the R implementation’s no-objective path;value_objfn,objfevals, andobjfn_trackare returned asNone, andresidualscontains the recorded residual norms.- *args
Additional positional arguments passed to both
fixptfnandobjfn.- control
dict, optional Algorithm controls. The accepted keys are the R control names with each dot replaced by an underscore. No other keys are allowed.
maxiterint, default=2000Maximum number of iterations or fixed-point evaluations, following the R implementation’s accounting for the selected algorithm path.
orderint, default=5Order of the DAAREM acceleration scheme. Internally this is capped at
ceil(len(par) / 2).tolfloat, default=1e-8Convergence tolerance. With
convtype="param", iteration stops when||G(x[k]) - x[k]|| < tol. Withconvtype="objfn", iteration stops whenabs(L(x[k + 1]) - L(x[k])) < tol.mon_tolfloat, default=0.01Nonnegative tolerance for objective monotonicity. With an objective function, an accelerated proposal is rejected when
L(x[k + 1]) < L(x[k]) - mon_tol.cycl_mon_tolfloat, default=0.0Nonnegative tolerance for the cycle-level monotonicity check at restart boundaries.
kappafloat, default=25Half-life parameter controlling how quickly the relative damping factor approaches one.
alphafloat, default=1.2Parameter greater than one controlling the initial relative damping factor and its rate of relaxation.
resid_tolfloat, default=0.95Residual-change tolerance used when
objfnis not supplied. A proposed accelerated step is accepted when its residual norm is at most the previous residual norm times1 + resid_tol**k.convtype{“param”, “objfn”}, default=”param”Convergence criterion used when
objfnis supplied.intermedbool, default=FalseIf true, return intermediate iterates in
p_intermed. With an objective function, the first column is the objective value and the remaining columns are parameters.
- **kwargs
Additional keyword arguments passed to both
fixptfnandobjfn.
- par
- Returns:
dictDictionary with the keys of the R result, with each dot replaced by an underscore.
pararrayFinal parameter vector.
fpevalsintNumber of fixed-point function evaluations or iterations, following the R implementation’s accounting.
value_objfnfloat or NoneObjective function value at termination, or
Nonewhen no objective function is supplied.objfevalsint or NoneNumber of objective function evaluations, or
Nonewhen no objective function is supplied.convergenceboolTrue if the algorithm converged before reaching
maxiter.objfn_trackarray or NoneObjective values recorded during iteration, or
Nonewhen no objective function is supplied.residualsarray, optionalResidual norms recorded during iteration. Returned only when
objfnis not supplied.p_intermedarray or NoneIntermediate iterates when
intermedis true, otherwiseNone.
The arrays have the namespace and the device of
par, and the float64 data type.
- Warns:
RuntimeWarningIf the algorithm reaches the iteration limit without convergence.
Notes
The public API and control names follow the R package
daarem. Unknown control names and aconvtypeother than"param"or"objfn"raiseValueError. The R package also stops with an error in these cases.fixptfnreceives and must return an array of the namespace ofpar. pydaarem converts its output to float64 on the device ofpar.objfnmust return a value thatfloat()accepts, for example a Python float or a 0-dimensional array.DAAREM decides each step from the values of the residual norm and the objective. These values are converted to Python floats, so each iteration copies a small number of scalars from the device to the host. For the same reason, pydaarem does not support tracing transformations such as
jax.jitortorch.compile.References
Henderson, N. C. and Varadhan, R. (2019). Damped Anderson acceleration with restarts and monotonicity control for accelerating EM and EM-like algorithms. Journal of Computational and Graphical Statistics, 28(4), 834-846. https://doi.org/10.1080/10618600.2019.1594835
Examples
>>> import numpy as np >>> from pydaarem import daarem >>> def fixpt(x): ... return np.cos(x) >>> out = daarem(np.array([1.0]), fixpt, control={"maxiter": 100}) >>> out["par"].shape (1,)
Data sets¶
- pydaarem.datasets.fetch_mixdata()¶
Download and load the mixture proportions example data.
The data comes from the
mixemanalysis in the stephenslab/daarem repository. The first call downloads the file and verifies its SHA-256 hash. Later calls use the local copy.- Returns:
Examples
>>> from pydaarem.datasets import fetch_mixdata >>> L, x = fetch_mixdata() >>> L.shape (100000, 10)