octave_packages/optim-1.2.0/residmin_stat.m

   1 ## Copyright (C) 2011 Olaf Till <olaf.till@uni-jena.de>
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## -*- texinfo -*-
  17 ## @deftypefn {Function File} {@var{info} =} residmin_stat (@var{f}, @var{p}, @var{settings})
  18 ## Frontend for computation of statistics for a residual-based
  19 ## minimization.
  20 ##
  21 ## @var{settings} is a structure whose fields can be set by
  22 ## @code{optimset} with Octave versions 3.3.55 or greater; with older
  23 ## Octave versions, the fields must be set directly and in the correct
  24 ## case. With @var{settings} the computation of certain statistics is
  25 ## requested by setting the fields @code{ret_<name_of_statistic>} to
  26 ## @code{true}. The respective statistics will be returned in a
  27 ## structure as fields with name @code{<name_of_statistic>}. Depending
  28 ## on the requested statistic and on the additional information provided
  29 ## in @var{settings}, @var{f} and @var{p} may be empty. Otherwise,
  30 ## @var{f} is the model function of an optimization (the interface of
  31 ## @var{f} is described e.g. in @code{nonlin_residmin}, please see
  32 ## there), and @var{p} is a real column vector with parameters resulting
  33 ## from the same optimization.
  34 ##
  35 ## Currently, the following statistics (or general information) can be
  36 ## requested:
  37 ##
  38 ## @code{dfdp}: Jacobian of model function with respect to parameters.
  39 ##
  40 ## @code{covd}: Covariance matrix of data (typically guessed by applying
  41 ## a factor to the covariance matrix of the residuals).
  42 ##
  43 ## @code{covp}: Covariance matrix of final parameters.
  44 ##
  45 ## @code{corp}: Correlation matrix of final parameters.
  46 ##
  47 ## Further @var{settings}
  48 ##
  49 ## The functionality of the interface is similar to
  50 ## @code{nonlin_residmin}. In particular, structure-based, possibly
  51 ## non-scalar, parameters and flagging parameters as fixed are possible.
  52 ## The following settings have the same meaning as in
  53 ## @code{nonlin_residmin} (please refer to there): @code{param_order},
  54 ## @code{param_dims}, @code{f_pstruct}, @code{dfdp_pstruct},
  55 ## @code{diffp}, @code{diff_onesided}, @code{complex_step_derivative},
  56 ## @code{cstep}, @code{fixed}, and @code{weights}. Similarly,
  57 ## @code{param_config} can be used, but only with fields corresponding
  58 ## to the settings @code{fixed}, @code{diffp}, and @code{diff_onesided}.
  59 ##
  60 ## @code{dfdp} can be set in the same way as in @code{nonlin_residmin},
  61 ## but alternatively may already contain the computed Jacobian of the
  62 ## model function at the final parameters in matrix- or structure-form.
  63 ## Users may pass information on the result of the optimization in
  64 ## @code{residuals} (self-explaining) and @code{covd} (covariance matrix
  65 ## of data). In many cases the type of objective function of the
  66 ## optimization must be specified in @code{objf}; currently, there is
  67 ## only a backend for the type "wls" (weighted least squares).
  68 ##
  69 ## Backend-specific information
  70 ##
  71 ## The backend for @code{objf == "wls"} (currently the only backend)
  72 ## computes @code{cord} (due to user request or as a prerequisite for
  73 ## @code{covp} and @code{corp}) as a diagonal matrix by assuming that
  74 ## the variances of data points are proportional to the reciprocal of
  75 ## the squared @code{weights} and guessing the factor of proportionality
  76 ## from the residuals. If @code{covp} is not defined (e.g. because the
  77 ## Jacobian has no full rank), it makes an attempt to still compute its
  78 ## uniquely defined elements, if any, and to find the additional defined
  79 ## elements (being @code{1} or @code{-1}), if any, in @code{corp}.
  80 ##
  81 ## @seealso {curvefit_stat}
  82 ## @end deftypefn
  83
  84 function ret = residmin_stat (varargin)
  85
  86   if (nargin == 1)
  87     ret = __residmin_stat__ (varargin{1});
  88     return;
  89   endif
  90
  91   if (nargin != 3)
  92     print_usage ();
  93   endif
  94
  95   varargin{4} = struct ();
  96
  97   ret = __residmin_stat__ (varargin{:});
  98
  99 endfunction