

    \filetitle{estimate}{Estimate model parameters by optimising selected objective function}{model/estimate}

	\paragraph{Syntax}
 
 \begin{verbatim}
 [P,POS,COV,HESS,M,V,~,~,DELTA,PDELTA] = estimate(M,D,RANGE,E,...)
 \end{verbatim}
 \paragraph{Input arguments}
 
 \begin{itemize}
 \item
   \texttt{M} {[} struct {]} - Model object.
 \item
   \texttt{D} {[} struct \textbar{} cell {]} - Input database or datapack
   from which the measurement variables will be taken.
 \item
   \texttt{RANGE} {[} struct {]} - Date range.
 \item
   \texttt{E} {[} struct {]} - Database with the list of paremeters that
   will be estimated, and the estimation specifications for each of them.
 \end{itemize}
 \paragraph{Output arguments}
 
 \begin{itemize}
 \item
   \texttt{P} {[} struct {]} - Database with point estimates of requested
   parameters.
 \item
   \texttt{POS} {[} poster {]} - Posterior,
   \href{poster/Contents}{\texttt{poster}}, object; this object also
   gives you access to the value of the objective function at optimum or
   at any point in the parameter space, see the \url{poster/eval}
   function.
 \item
   \texttt{COV} {[} numeric {]} - Approximate covariance matrix for the
   estimates of parameters with slack bounds based on the asymptotic
   Fisher information matrix (not on the Hessian returned from the
   optimisation routine).
 \item
   \texttt{HESS} {[} cell {]} - \texttt{HESS\{1\}} is the total hessian
   of the objective function; \texttt{HESS\{2\}} is the contributions of
   the priors to the hessian.
 \item
   \texttt{M} {[} model {]} - Model object solved with the estimated
   parameters (including out-of-likelihood parameters and common variance
   factor).
 \end{itemize}
 The remaining five output arguments, \texttt{V}, \texttt{F},
 \texttt{PE}, \texttt{DELTA}, \texttt{PDELTA}, are the same as the
 \url{model/loglik} output arguments of the same names.
 
 A tilda, \ensuremath{\sim}, denotes a void (unused) output argument that
 is included for backward compatibility.
 
 \paragraph{Options}
 
 \begin{itemize}
 \item
   \texttt{'exclude='} {[} cellstr \textbar{} \emph{empty} {]} - List of
   measurement variables that are to be excluded from the likelihood
   function (treated as deterministic).
 \item
   \texttt{'filter='} {[} cell \textbar{} \emph{empty} {]} - Cell array
   of options that will be passed on to the Kalman filter; see help on
   \url{model/filter} for the options available.
 \item
   \texttt{'maxIter='} {[} numeric \textbar{} \emph{\texttt{500}} {]} -
   Maximum number of iterations allowed.
 \item
   \texttt{'maxFunEvals='} {[} numeric \textbar{} \emph{\texttt{2000}}
   {]} - Maximum number of objective function calls allowed.
 \item
   \texttt{'noSolution='} {[} \emph{\texttt{'error'}} \textbar{}
   \texttt{'penalty'} {]} - Specifies what happens if solution or steady
   state fails to solve in an iteration: \texttt{'error='} stops the
   execution with an error message, \texttt{'penalty='} returns an
   extremely low value of the likelihood.
 \item
   \texttt{'objective='} {[} \emph{\texttt{'-loglik'}} \textbar{}
   \texttt{'prederr'} {]} - Objective function optimised; it can be minus
   the log likelihood function or weighted sum of prediction errors,
   either adjusted for prior distributions.
 \item
   \texttt{'objectiveSample='} {[} numeric \textbar{} \emph{\texttt{Inf}}
   {]} - The objective function will be computed on this subrange only;
   \texttt{Inf} means the entire range will be used.
 \item
   \texttt{'optimSet='} {[} cell \textbar{} \emph{empty} {]} - Cell array
   used to create the Optimization Toolbox options structure; work only
   with \texttt{'solver='} \texttt{'default'}.
 \item
   \texttt{'refresh='} {[} \emph{\texttt{true}} \textbar{} \texttt{false}
   {]} - Refresh dynamic links in each iteration.
 \item
   \texttt{'solve='} {[} \emph{\texttt{true}} \textbar{} \texttt{false}
   {]} - Re-compute solution in each iteration.
 \item
   \texttt{'solver='} {[} \emph{`default'} \textbar{} cell \textbar{}
   function\_handle {]} - Minimisation procedure; \texttt{'default'}
   means the Optimization Toolbox \texttt{fminunc} or \texttt{fmincon}
   functions. You can enter a function handle to your own optimisation
   procedure, or a cell array with a function handle and additional input
   arguments --- see below.
 \item
   \texttt{'sstate='} {[} \texttt{true} \textbar{} \emph{\texttt{false}}
   \textbar{} cell \textbar{} function\_handle {]} - Re-compute steady
   state in each iteration. You can specify a cell array with options for
   the \texttt{sstate} function, or a function handle whose behaviour is
   described below.
 \item
   \texttt{'tolFun='} {[} numeric \textbar{} \emph{\texttt{1e-6}} {]} -
   Termination tolerance on the objective function.
 \item
   \texttt{'tolX='} {[} numeric \textbar{} \emph{\texttt{1e-6}} {]} -
   Termination tolerance on the estimated parameters.
 \end{itemize}
 \paragraph{Description}
 
 In the input parameter database, \texttt{E}, you can provide the
 following four specifications for each parameter:
 
 \begin{verbatim}
 E.parameter_name = {start,lower,upper,logprior}
 \end{verbatim}
 where \texttt{start} is the value from which the numerical optimisation
 will start, \texttt{lower} is the lower bound, \texttt{upper} is the
 upper bound, and \texttt{logprior} is a function handle expected to
 return the log of the prior density. You can use the
 \href{logdist/Contents}{\texttt{logdist}} package to create function
 handles for some of the basic prior distributions.
 
 You can use \texttt{NaN} for \texttt{start} if you wish to use the value
 currently assigned in the model object. You can use \texttt{-Inf} and
 \texttt{Inf} for the bounds, or leave the bounds empty or not specify
 them at all. You can leave the prior distribution empty or not specify
 it at all.
 
 ---User-supplied optimisation (minimisation) routine
 
 You can supply a function handle to your own minimisation routine
 through the option \texttt{'solver='}. This routine will be used instead
 of the Optim Tbx's \texttt{fminunc} or \texttt{fmincon} functions. The
 user-supplied function is expected to take at least five input arguments
 and return three output arguments:
 
 \begin{verbatim}
 [POPT,OBJOPT,HESS] = yourminfunc(F,P0,PLOW,PHIGH,OPT)
 \end{verbatim}
 with the following input arguments:
 
 \begin{itemize}
 \item
   \texttt{F} is a function handle to the function minimised;
 \item
   \texttt{P0} is a 1-by-N vector of initial parameter values;
 \item
   \texttt{PLOW} is a 1-by-N vector of lower bounds (with \texttt{-Inf}
   indicating no lower bound);
 \item
   \texttt{PHIGH} is a 1-by-N vector of upper bounds (with \texttt{Inf}
   indicating no upper bounds);
 \item
   \texttt{OPT} is an Optim Tbx style struct with the optimisation
   settings (tolerance, number of iterations, etc); of course you may
   simply ignore this information and leave the input argument unused.
 \end{itemize}
 and the following output arguments:
 
 \begin{itemize}
 \item
   \texttt{POPT} is a 1-by-N vector of estimated parameters;
 \item
   \texttt{OBJOPT} is the value of the objective function at optimum;
 \item
   \texttt{HESS} is a N-by-N approximate hessian matrix at optimum.
 \end{itemize}
 If you need to use extra input arguments in your minimisation function,
 enter a cell array instead of a plain function handle:
 
 \begin{verbatim}
 {@yourminfunc,ARG1,ARG2,...}
 \end{verbatim}
 In that case, the solver will be called the following way:
 
 \begin{verbatim}
 [POPT,OBJOPT,HESS] = yourminfunc(F,P0,PLOW,PHIGH,OPT,ARG1,ARG2,...)
 \end{verbatim}
 ---User-supplied steady-state solver
 
 You can supply a function handle to your own steady state solver (i.e.~a
 function that finds the steady state for given parameters) through the
 \texttt{'sstate='} option.
 
 The function is expected to take one input argument, the model object
 with newly assigned parameters, and return at least two output
 arguments, the model object with a new steady state (or balanced-growth
 path) and a success flag. The flag is \texttt{true} if the steady state
 has been successfully computed, and \texttt{false} if not:
 
 \begin{verbatim}
 [M,SUCCESS] = yoursstatesolver(M)
 \end{verbatim}
 It is your responsibility to add the growth characteristics if some of
 the model variables drift over time. In other words, you need to take
 care of the imaginary parts of the steady state values in the model
 object returned by the solver.
 
 \paragraph{Example}


