=================================
 A Boilerplate for EM algorithms 
=================================

.. r-package:: EMfit
.. r-pkgversion:: 0.2
.. r-name:: EMfit

     EMfit

Description
===========

``EMfit`` provides the boilerplate for EM algorithms and EM-NR accelerated EM algorithms
(also known as the Louis-method of acceleration)

Usage
=====

.. code-block:: r

   EMfit(psi.start, mk_cpl_data, ll_cpl, completeInfo, Jacobian, ...,
     Mstep = Mstep.default, eps = 1e-07, maxiter = 200,
     maxiter.EM = maxiter, maxiter.inner = 25, Information = TRUE,
     verbose = TRUE, verbose.inner = FALSE, show.psi = FALSE)

Arguments
=========

``psi.start``
   A numeric vector with starting values

``mk_cpl_data``
   A function that creates the 'complete data' from the 'observed' data. Its return value
   can be anything that can be used by the other functions given as arguments. The return
   value can also have a component "weights".

``ll_cpl``
   A function that computes the complete-data contributions to the log-likelihood. It should
   at least accept the arguments ``psi``, the parameter vector, and ``cpl_data``, the
   complete-data structure. It should return the complete-data contributions to the
   log-likelihood, with an attributed named "i" that indicates unconditionally independent
   groups of observations.

``completeInfo``
   A function that computes the 'complete-data' information matrix It should at least accept
   the arguments ``psi``, the parameter vector, ``cpl_data``, the complete-data structure,
   and ``weights``, which are weights determined e.g. by posterior probabilities and
   a-priori weights.

``Jacobian``
   A function that computes the Jacobian of the log-likelihood function. It should return a
   matrix with the same number of rows as the length of the result of ``ll_cpl`` and the
   same number of colums as elements of ``psi`` and should have an attribute named "i" that
   indicates unconditionally independent groups of observations.

``Mstep``
   A function that conducts the M-step. It should accept the parameter vector as first
   argument, the complete-data structure as second argument, a vector ``wPPr`` of posterior
   probabilities (weighted if applicable), and should accept anything that is passed via ...

``eps``
   Numeric; a criterion for convergence

``maxiter``
   Maximal number of iterations

``maxiter.EM``
   Maximal number of iterations after which the algorithm should switch to Newton-Raphson
   steps

``maxiter.inner``
   Maximal number of iterations for the M-step

``Information``
   Logical; should the observed-data information matrix be returned?

``verbose``
   Logical; should an interation trace be displayed?

``verbose.inner``
   Logical; should the iteration trace of the M-step be displayed (if applicable)?

``show.psi``
   Logical; should the current parameter value be displayed along with the iteration
   history?

``...``
   Further arguments passed to ``ll_cpl``, ``mk_cpl_data``, etc.

Value
=====

A list with the following components:

psi
     The MLE of the parameter vector

logLik
     The maximized observed-data log-likelihood

gradient
     The gradient of the log-likelihood function

cplInfo
     The complete-data information matrix

missInfo
     The missing-data information matrix

obsInfo
     The observed-data information matrix. Use this to compute standard errors.

converged
     A logical value, indicating whether the algorithm converged.

psi.trace
     A matrix which contains the parameter values for each iteration

logLik.trace
     A vector with the log-likelihood values of each iteration