Changeset 632 for library/doc/tutorial

Timestamp:

09/18/09 00:17:38 (15 years ago)

Author:

smidl

Message:

doc + updated tutorial

Location:

library/doc/tutorial

Files:

• 00install.dox (modified) (1 diff)
• 01userguide.dox (modified) (2 diffs)
• 02userguide2.dox (modified) (2 diffs)
• 03devguide.dox (modified) (1 diff)
• 04devguide2.dox (modified) (1 diff)

library/doc/tutorial/00install.dox

@@ -1 +1 @@
 /*!
-\page install How to install BDM
+\page install BDM Use - Installation
 
 BDM is written as a multiplatform library, which was tested on Linux, Windows and Mac OSX.

library/doc/tutorial/01userguide.dox

@@ -1 +1 @@
 /*!
-\page user_guide Howto Use BDM - System, Data, Simulation
+\page user_guide BDM Use - System, Data, Simulation
 
 This section serves as introdustion to the scenario of data simulation. Since it is the simpliest of all scenarios defined in \ref user_guide0 it also serves as introduction to configuration of an experiment (see \ref ui_page) and basic decision making objects (bdm::RV and bdm::DS).
@@ -110 +110 @@
 Mathematical interpretation of RV is straightforward. Consider pdf \f$ f(a)\f$, then \f$ a \f$ is the part represented by RV. Explicit naming of random variables may seem unnecessary for many operations with pdf, e.g. for generation of a uniform sample from <0,1> it is not necessary to specify any random variable. For this reason, RV are often optional information to specify. However, the considered scenanrio \c simulator is build in a way that requires RV to be given.
 
+In software, \c RV has three compulsory properties:
+ - <b>name</b>, unique identifier, two RV with the same name are considered to be identical
+ - <b>size</b>, size of the random variable, if not given it is assumed to be 1,
+ - <b>time</b>, more exactly time shift from \f$ t \f$, defaults to 0.
+ For example, scalar \f$ x_{t-2} \f$ is encoded as (name='x',sizes=1,time=-2).
+ Each RV stores array of these elements, hence RV with:
+ \code
+ names={'a', 'b'};
+ sizes=[ 2 , 3];
+ times=[-1, 1];
+ \endcode 
+ denotes 5-dimensional vector \f$ [a_{t-1}', b_{t+1}] \f$.
+ 
+\subsection ug_rv_alg Algebra on RVs
+Algebra on RVs (adding, searching in, subtraction, intersection, etc.) is implemented, see bdm::RV.
+
+For convenience in Matlab, the following operations are defined:
+ - RV(names,sizes,times) creates configuration structure for RV,
+ - RVjoin(rvs) joins configuration structures for array of RVs rvs=[rv1,rv2,...],
+ - RVtimes(rvs,times) assign times to corresponding rvs.
+
+See examples in bdmtoolbox/tutorial/userguide
+
+\subsection ug_rv_connect
+
 The \c simulator scenario connects the DataSource to second basic class of BDM, bdm:logger. The logger is a class that take care of storing results -- in this case, results of simulation.
 The connection between these blocks is done automatically. The logger stores results of simulations under the names specified in drv.  
 Readers familiar with Simulink environment may look at the RV as being unique identifiers of inputs and outputs of simulation blocks. The inputs are connected automatically with the outputs with matching RV. This view is however, very incomplete, RV have more roles than this.
+
 
 \section loggers Loggers for flexible handling of results

library/doc/tutorial/02userguide2.dox

@@ -24 +24 @@
 object \c Bayesian \c Model (bdm::BM).
 
-\section theory Bayes rule and estimation
+\section ug2_theory Bayes rule and estimation
 The object bdm::BM is basic software image of the Bayes rule:
 \f[ f(x_t|d_1\ldots d_t) \propto f(d_t|x_t,d_1\ldots d_{t-1}) f(x_t| d_1\ldots d_{t-1}) \f]
@@ -42 +42 @@
 Variants of these approaches are implemented as descendats of these level-two classes. This way, each estimation method (represented a class) is fitted in its place in the tree of approximations. This is useful even from software point of view, since related approximations have common methods and data fields.
 
-\section arx Estimation of ARX models
+\section ug2_arx_basic Estimation of ARX models
 
 Autoregressive models has already been introduced in \ref ug_arx_sim where their simulator has been presented.
-We will use the datasource defined there to provide data for estimation.
+We will use results of simulation of the ARX datasource defined there to provide data for estimation using MemDS.
 
-The following code is from bdmtoolbox/tutorial/userguide/arx_basic_example
+The following code is from bdmtoolbox/tutorial/userguide/arx_basic_example.m
 \code
 A1.class = 'ARX';
 A1.rv = y;
-A1.rgr = RVtimes({y,y},[-3,-1]) ;
+A1.rgr = RVtimes([y,y],[-3,-1]) ;
+A1.options = 'logbounds,logll';
 \endcode 
-Using the same logic as before, 
+This is the minimal configuration of an ARX estimator. Optional elements of bdm::ARX::from_setting() were set using their default values:
+
+The first three fileds are self explanatory, they identify which data are predicted (field \c rv) and which are in regressor (field \c rgr).
+The field \c options is a string of options passed to the object. In particular, class \c BM understand only options related to storing results:
+ - logbounds - store also lower and upper bounds on estimates (obtained by calling BM::posterior().qbounds()),
+ - logll - store also loglikelihood of each step of the Bayes rule.
+These values are stored in given logger (\ref ug_loggers). By default, only mean values of the estimate are stored.
+
+Storing of the log-likelihood is useful, e.g. in model selection task when too models are compared.
+
+The bounds are useful e.g. for visualization of the results. Run of the example should provide result like the following:
+\image html arx_basic_example_small.png 
+\image latex arx_basic_example.png "Typical run of tutorial/userguide/arx_basic_example.m" width=\linewidth
+
+\section ug2_model_sel Model selection
+
+In Bayesian framework, model selection is done via comparison of marginal likelihood of the recorded data. See [some theory].
+
+A trivial exammple how this can be done is presented in file bdmtoolbox/tutorial/userguide/arx_selection_example.m. The code extends the basic A1 object as follows:
+\code
+A2=A1;
+A2.constant = 0;
+
+A3=A2;
+A3.frg = 0.95;
+\endcode
+That is, two other ARX estimators are created, 
+ - A2 which is the same as A1 except it does not model constant term in the linear regression. Note that if the constant was set to zero, then this is the correct model.
+ - A3 which is the same as A2, but assumes time-variant parameters with forgetting factor 0.95.
+ 
+Since all estimator were configured to store values of marginal log-likelihood, we can easily compare them by computint total log-likelihood for each of them and converting them to probabilities. Typically, the results should look like:
+\code
+Model_probabilities =
+
+    0.0002    0.7318    0.2680
+\endcode
+Hence, the true model A2 was correctly identified as the most likely to produce this data. 
+
+For this task, additional technical adjustments were needed:
+\code
+A1.name='A1';
+A2.name='A2';
+A2.rv_param = RV({'a2th', 'r'},[2,1],[0,0]);
+A3.name='A3';
+A3.rv_param = RV({'a3th', 'r'},[2,1],[0,0]);
+\endcode
+First, in order to distinguish the estimators from each other, the estimators were given names. Hence, the results will be logged with prefix given by the name, such as M.A1ll for field \c ll.
+
+Second, if the parameters of a ARX model are not specified, they are automatically named \c theta and \c r. Howver, in this case, \c A1 and \c A2 differ in size, hence their random variables differ and can not use the same name. Therefore, we have explicitly used another names (RVs) of the parameters.
+
+\section ug2_bm_composition Composition of estimators
+
+Similarly to mpdfs which could be composed via \c mprod, the Bayesian models can be composed. However, justification of this step is less clear than in the case of epdfs.
+
+One possible theoretical base of composition is the Marginalized particle filter, which splits the prior and the posterior in two parts:
+\f[ f(x_t|d_1\ldots d_t)=f(x_{1,t}|x_{2,t},d_1\ldots d_t)f(x_{2,t}|d_1\ldots d_t) \f]
+each of these parts is estimated using different approach. The first part is assumed to be analytically tractable, while the second is approximated using empirical approximation.
+
+The whole algorithm runs by parallel evaluation of many \c BMs for estimation of \f$ x_{1,t}\f$, each of them conditioned on value of a sample of \f$x_{2,t}\f$.
+
+For example, the forgetting factor, \f$ \phi \f$ of an ARX model can be considered to be unknown. Then, the whole parameter space is \f$ [\theta_t, r_t, \phi_t]\f$ decomposed as follows:
+\f[ f(\theta_t, r_t, \phi_t) = f(\theta_t, r_t| \phi_t) f(\phi_t) \f]
+Note that for known trajectory of \f$ \phi_t \f$ the standard ARX estimator can be used if we find a way how to feed the changing \f$ \phi_t \f$ into it.
+This is achieved by a trivial extension using inheritance method bdm::BM::condition().
+
+
 
 */

library/doc/tutorial/03devguide.dox

@@ -1 +1 @@
 /*!
-\page dev_guide Howto Use BDM in C++ for your needs
-\addindex Howto Use BDM in C++ for your needs
-
+\page dev_guide  BDM Use - in C++ 
 
 \section Intro Logic of BDM

library/doc/tutorial/04devguide2.dox

@@ -1 +1 @@
 /*!
-\page dev_guide2 Howto Contribute to BDM - Advanced development
+\page dev_guide2 BDM Development - Contribution guide
 \addindex Howto Contribute to BDM - Advanced development