Changeset 988

Timestamp:

05/26/10 18:42:06 (15 years ago)

Author:

smidl

Message:

doc

Files:

• applications/bdmtoolbox/mex/mex_classes/mexLaplaceBM.m (modified) (2 diffs)
• library/doc/tutorial/040devguide_matlab.dox (modified) (6 diffs)

applications/bdmtoolbox/mex/mex_classes/mexLaplaceBM.m

@@ -11 +11 @@
             obj.apost_pdf.point = [0;0];
             obj.log_evidence = 0;                             % evidence is not computed!
-            disp('val');
         end
 
@@ -34 +33 @@
             p.mu = obj.apost_pdf.point(1);
             p.b  = obj.apost_pdf.point(2);
+                                % do not forget to validate
             p=p.validate;
+                                % assign descriptions
+                                p.rv = yrv;
+                                % rvc is empty be default
         end
     end

library/doc/tutorial/040devguide_matlab.dox

@@ -7 +7 @@
 See \ref ug_pdf_fnc example.
 
-This tutorial assumes you are familiar with basic classes of BDM: random variables \ref userguide_pdf and estimators \ref userguide_estim.
-
-If no premade class is suitable for your mneeds, you can create your own class in Matlab via predefined interfaces to class epdf (mexEpdf) and BM (mexBM).
-These classes are treated as regular C++ classes in prepared mex files. Creation of a new estimator (offspring of mexBM) can be achieved by inheriting from class mexBM.
+This tutorial assumes you are familiar with basic classes of BDM: pdfs, random variables (\ref userguide_pdf) and estimators (\ref userguide_estim).
+
+Previous part of the tutorial introduced ways how to use existing classes. If no premade class is suitable for your mneeds, you can create your own class in Matlab via predefined interfaces to class epdf (mexEpdf) and BM (mexBM).
+These classes are treated as regular C++ classes in prepared mex files. Creation of a new estimator (offspring of class BM) can be achieved by inheriting from class mexBM.
 
 In practice this means creation of a new file, e.g. my_bm.m, with header:
@@ -32 +32 @@
 Epdf is a class representing probability density function of a multivariate (vector) variable.
 
-The easiest example of a density is dirac Delta function:
+The easiest example of a density is dirac Delta function 
+\f[
+f(x_t) = \delta( x_t - \bar{x}_t )
+\f]
+with properties:
+ - \f$ \bar{x}_t \f$ is the statistics of this density.
+ - dimension of the density is dimension of the vector \f$ \bar{x}_t \f$
+ - the mean value of the density is \f$ E(x_t) = \bar{x}_t \f$
+ - the variance value of the density is \f$ var(x_t) = zeros() \f$
+ - all samples from this density are equal to \f$ \bar{x}_t \f$
+ 
+ These properties are encoded in software as follows:
+ 
 \code
 classdef mexDirac < mexEpdf
     % Dirac delta probability distribution
     properties                                                 % DATA structures
-        point                                                  % point of the support
+        point                                                  % point of the support, \bar{x}_t
     end
     methods
@@ -73 +85 @@
 \endcode
 
-Once you define these functions, this object can be plugged into (almost) an arbitrary algoritm, such as simulator, etc.
-
-For seamless use with other objects, you nedd to define its random variables - via attribute rv, \ref ug_pdf_create.
+An additional compulsory function is called \c validate which is called always before use of the class in an algorithm. The task of this function is to detect any inconsistency in the object and give the user an appropriate warning. 
+For example, in this case, the function checks if the property point is indeed a vector and not a matrix or other structure.
+
+Once you define the methdos above, this object can be plugged into (almost) an arbitrary algoritm, such as simulator, etc.
+
+For seamless use with other objects, you need to define its random variables - via attribute rv, \ref ug_pdf_create.
 
 For inspiration see example class mexLaplace.m and its use in simulation in tutorial/userguide/epdfds_example.m
 
-\section dev_mat_bm Creating your own Bayesian Model (BM)
-
+\section dev_mat_bm Defining your own Bayesian Estimator (BM)
 If you look into the mexBM.m file you see the basic attributes and default functions. mexBM as such will not work as a valid estimator.
 In order to make it work, you need to re-define at least functions <b>dimensions</b> and <b>bayes</b>, and attribute <b>apost_pdf</b>:
-  \code
-  function dims=dimensions(p)
-      %please fill
-      %dims = [size_of_posterior size_of_data size_of_condition]
-      dims = [0,0,0] %
-  end
-  \endcode
+  
 This function announces sizes of random variables to other objects. 
 
@@ -115 +123 @@
 Note, that statistics of the posterior are stored in attribute apost_pdf. So, the task of this function is to update fileds in apost_pdf. 
 
-Any additional sttributes needed for this task shoul be added to properties of the object.
-
-An example calss of BM for Laplace pdf is implemented in class mexLaplaceBM.m. This class represents maximum likelihood estimator of two parameters of the density. 
-One parameter is a median of data on a sliding window.  
-This can be interpreted as a coarse approximation of Bayesian filtering with posterior reduced to Dirac delta.
-
-Hence, we need:
- - apost_pdf to be of type mexDirac,
- - store information about window length in the properties
- - store the windown of data in properties
- - the method bayes adds new data to the window and copies median of the window to the point in apost_pdf.
+Any additional attributes needed for this task shoul be added to properties of the object.
+
+
+\section dev_exa Example task: Laplace estimation
+
+Consider a systems, where data are generated by a Laplace model 
+\f[
+f(y_t|a,b) = \frac{1}{2b} \exp \left( -\frac{x-a}{b} \right)
+\f]
+with unknown time-varying parameters \f$ a \f$ and \f$ b \f$. 
+
+We decided to estimate parameters of the system using ML estimates of parameters on a sliding window. The estimates are then:
+\f{eqnarray}
+\hat{a}& =& \mathrm{median}([y_{t},y_{t-1},\ldots , y_{t-d}),\\
+\hat{b}& = & \frac{1}{d} \sum_{\tau=t-d}^{t} | y_\tau - \hat{a} |
+\f}
+
+Implementing this system in BDM requires the following steps:
+ - realize that ML estimation is an extreme approximation of Bayes rule with posterior in the form of Dirac delat pdf, this pdf is ready from the previous step.
+ - under this choice, the posterior is a 2-dimensional dirac, which is encoded as:
+ \code
+ apost_pdf = mexDirac;
+ apost_pdf.point = [0;0];
+ \endcode 
+ - the class mexDirac as introduced has only one attribute: point, which is a vector of the support. If we wish to distinguish the meaning of these values, we use attribute rv. For example, 
+ \code
+ apost_pdf.rv = RV({'a','b'});
+ \endcode
+ - the class representing an estimator of this type, needs to remember internal statistics in the form window of data, which will be stored in properties of the class
+
+ - dimensionality of the estimator is then: 2-dimensional parameters, 1-dimensional observation, 0-dimensional conditioning variables. It is encoded as:
+ \code
+  function dims=dimensions(p)
+      %please fill
+      %dims = [size_of_posterior size_of_data size_of_condition]
+      dims = [2,1,0] %
+  end
+  \endcode
+ - the method \c bayes then copies the obtained data into the window and updates estimates \f$ \hat{a}, \hat{b}\f$
+
+This estimator has been implemented as class mexLaplaceBM as follows:
  
 This is implemented as follows:
@@ -141 +179 @@
             obj.apost_pdf.point = [0;0];
             obj.log_evidence = 0;                             % evidence is not computed!
-            disp('val');
         end
 
@@ -159 +196 @@
             obj.apost_pdf.point = [m_hat; b_hat];             % store result in psoterior pdf
         end
-        function p=epredictor(obj,cond)                       % when predictive density is needed approximate it by Laplace with point estimates
-            % return predictive density (max likelihood)
-            p = mexLaplace;
-            p.mu = obj.apost_pdf.point(1);
-            p.b  = obj.apost_pdf.point(2);
-            p=p.validate;
-        end
-    end
-
+    end
+
+end
+\endcode
+
+\section dev_mat_alt Alternative representations of this estimator
+
+Note, that the estimator above is rather coarse approximation of the Bayes rule. Indeed, in this case, the sliding window represnts a statistics on the posterior parameters, 
+and thus it should be part of the posterior, which can thus evaluate more moments that the current Dirac density.
+
+Such a design is certainly possible, however, it would result in much more complex calculations and more complex coding. If that is the aim, a new class can be designed.
+
+\section dev_mat_pred Predictors and simulation
+
+Note, that the Laplacian likelihood model of the example is not needed for its estimation. The very basic estimator introduced above does not need to know about existence of the likelihood function.
+
+However, existence of this distribution is required by related tasks of data simulation and data prediction.
+Therefore, a class mexLaplace was designed, which implements all operations of pdf in the same manner as the in \ref dev_mat_pdf.
+
+This pdf is then used in the mexLaplaceBM in function that creates predictors:
+\code 
+function p=epredictor(obj,cond)                       % when predictive density is needed approximate it by Laplace with point estimates
+   % return predictive density (max likelihood)
+   p = mexLaplace;
+   p.mu = obj.apost_pdf.point(1);
+   p.b  = obj.apost_pdf.point(2);
+        % do not forget to validate
+   p=p.validate;
+        % assign descriptions
+        p.rv = yrv;
+        % rvc is empty be default
 end
 \endcode
   
+Also, the class mexLaplace can be used to generate data, see bdmtoolbox/mex/epdfds_example.m
+
+Since it provides all required methods, it can be combined with other pdfs in chain rules, as in pdfds_example.m
+
 Similar extensions to mexEpdf and mexBM can be made to other classes. See library/mex/mex_Epdf.h and library/mex/mex_BM.h how it is done.
 As always, feel free to contact the maintainer for help.