Changeset 630 for library/doc

Show
Ignore:
Timestamp:
09/18/09 00:17:14 (15 years ago)
Author:
smidl
Message:

Tutorial update + new .m files

Location:
library/doc/tutorial
Files:
2 modified

Legend:

Unmodified
Added
Removed

  • library/doc/tutorial/01userguide.dox

    r617 r630  
    22\page user_guide Howto Use BDM - System, Data, Simulation 
    33 
    4 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) and basic decision making objects (bdm::RV and bdm::DS). 
     4This 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). 
    55 
    66All experiments are demonstarted on scenario simulator which can be either standalone application of mex file (simulator.mex**). 
    77 
    88 
    9 \section config Configuration of an experiment 
     9\section ug_config Configuration of an experiment 
    1010 
    1111Configuration file (or config structure) is organized as a tree of information. High levels represent complex structures, leafs of the tree are basic data elements such as strings, numbers or vectors. 
    … …  
    1414 
    1515The configuration has two possible options: 
    16  - configuration file using syntax of libconfig (see \ref ui), 
     16 - configuration file using syntax of libconfig (see \ref ui_page), 
    1717 - matlab structure. 
    1818For the purpose of tutorial, we will use the matlab notation.  
    19 These two options can be mutually converted from one to another using prepared mex files: config2mxstruct.mex and mxstruct2config.mex. Naturally, these scripts require matlab to run. If it is not available, manual conversion is relatively trivial, the major difference is in using different types of brackets (\ref ui) 
    20  
    21 \subsection first First experiment 
     19These two options can be mutually converted from one to another using prepared mex files: config2mxstruct.mex and mxstruct2config.mex. Naturally, these scripts require matlab to run. If it is not available, manual conversion is relatively trivial, the major difference is in using different types of brackets (\ref ui_page) 
     20 
     21\subsection ug_first First experiment 
    2222 
    2323The first experiment that can be performed is: 
    … …  
    4343\endcode 
    4444 
    45 If you see this result, you have configured BDM correctly and you have sucessfully run you first experiment. In other cases, please check your installation, \ref installation.  
     45If you see this result, you have configured BDM correctly and you have sucessfully run you first experiment. In other cases, please check your installation, \ref install.  
    4646All that the simulator did was actually copying \c DS.Data to \c M.ch0. Explanation of the experiment and the logic used there follows. 
    4747 
    48 \section sim Systems and DataSources 
     48\section ug_sim Systems and DataSources 
    4949 
    5050In standard system theory, the system is typically illustrated graphically as: 
    … …  
    7373 
    7474 
    75 \section memds DataSource of pre-recorded data -- MemDS 
     75\section ug_memds DataSource of pre-recorded data -- MemDS 
    7676 
    7777The first experiment run in \ref first was actually an instance of DataSource of pre-recorded data that were stored in memory, i.e. the bdm::MemDS class. 
    … …  
    104104Where the first line specifies a universal identification structure: random variable (bdm::RV). 
    105105 
    106 \section rvs What is RV and how to use it 
     106\section ug_rvs What is RV and how to use it 
    107107 
    108108RV stands for \c random \c variable which is a description of random variable or its realization. This object playes role of identifier of elements of vectors of data (in datasources), expected inputs to functions (in pdfs), or required results (operations conditioning).  
    … …  
    125125Since all experiments are performed in matlab, the default mexlog class will be used. However, the way how the results are to be stored can be configured using configuration structure filled by fields from \c from_setting of the chosen logger, and passing it as third argument to \c simulator. 
    126126 
    127 \section datasource Class inheritance and DataSources 
     127\section ug_datasource Class inheritance and DataSources 
    128128 
    129129As mentioned above, the scenario \c simulator is written to accept any datasource (i.e. any offspring of bdm::DS). For full list of offsprings, click see Classes > Class Hierarchy. 
    … …  
    175175If the task was only to generate random realizations, this would indeed be a very clumsy way of doing it. However, the power of the proposed approach will be revelead in more demanding examples, one of which follows next. 
    176176 
    177 \section arx Simulating autoregressive model 
     177\section ug_arx_sim Simulating autoregressive model 
    178178 
    179179Consider the following autoregressive model:  
    … …  
    232232The code above can be immediatelly run, usin the same execution sequence of \c estimator as above.  
    233233 
    234 \subsection ini Initializing simulation 
     234\subsection ug_ini Initializing simulation 
    235235 
    236236When zeros are not appropriate initial conditions, the correct conditions can be set using additional commands (see bdm::MpdfDS.from_setting() ): 
    … …  
    244244 
    245245 
     246\section ug_store Storing results of simulation 
     247 
     248If the simulated data are to be analyzed off-line it may be advantageous to store them and use for later use.  
     249This operation is straightforward if the class of logger used in the \c simulator is compatible with some datasource class. 
     250 
     251For example, the output of \c MemDS can be stored as an .it file (filename is specified in configuration structure) which can be later read by bdm::ITppFileDS. 
     252 
     253In matlab, the output of mexlog is a structure of vectors or matrices. The results can be saved in a matlab file using: 
     254\code 
     255Data=[M.y; M.u]; 
     256drv = RVjoin({y,u}); 
     257save mpdfds_results Data drv 
     258\endcode 
     259Such data can be later provided e.g. by MemDS 
     260\code 
     261mxDS.class   = 'MemDS'; 
     262mxDS.Data    = 'Data'; 
     263mxDS.drv     = drv; 
     264\endcode 
     265 
    246266*/ 

  • library/doc/tutorial/02userguide2.dox

    r616 r630  
    11/*! 
    2 \page user_guide Howto Use BDM - Introduction 
    3 \addindex Howto Use BDM - Introduction 
     2\page user_guide2 BDM Use - Estimation and Bayes Rule 
    43 
    5 BDM is a library of basic components for Bayesian decision making, hence its direct use is not possible. In order to use BDM the components must be pulled together in order to achieve desired functionality. We expect two kinds of users: 
     4Baysian theory is predominantly used in system identification, or estimation problems.  
     5This section is concerned with recursive estimation, as implemneted in prepared scenario \c estimator. 
    66 
    7  - <b> Basic users </b> who run prepared scripts with different parameterizations and analyze their results, 
    8  - <b> Advanced users </b> who are able to understand the logic of BDM and extend its functionality to new applications. 
     7The function of the \c estimator is graphically illustrated: 
     8\dot 
     9digraph estimation{ 
     10        node [shape=box]; 
     11        {rank="same"; "Data Source"; "Bayesian Model"} 
     12        "Data Source" -> "Bayesian Model" [label="data"]; 
     13        "Bayesian Model" -> "Result Logger" [label="estimation\n result"]; 
     14        "Data Source" -> "Result Logger" [label="Simulated\n data"]; 
     15} 
     16\enddot 
    917 
    10 The primary design aim of BDM was to ease development of complex algorithms, hence the target user is the advanced one.  
    11 However, running experiments is the first task to learn for both types of users. 
     18Here, 
     19\li Data Source is an object (class DS) providing sequential data, \f$ [d_1, d_2, \ldots d_t] \f$. 
     20\li Bayesian Model is an object (class BM) performing Bayesian filtering, 
     21\li Result Logger is an object (class logger) dedicated to storing important data from the experiment. 
    1222 
    13 \section param Experiment is fully parameterized before execution 
     23Since objects  datasource and the logger has already been introduced in section \ref user_guide, it remains to introduce  
     24object \c Bayesian \c Model (bdm::BM). 
    1425 
    15 Experiments in BDM can be performed using either standalone applications or function bindings in high-level environment. A typical example of the latter being mex file in Matlab environment. 
     26\section theory Bayes rule and estimation 
     27The object bdm::BM is basic software image of the Bayes rule: 
     28\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] 
    1629 
    17 The main logic behind the experiment is that all necessary information about it are gathered in advance in a configuration file (for standalone applications) or in configuration structure (Matlab). 
    18 This approach was designed especially for time consuming  experiments and Monte-Carlo studies for which it suits the most.  
     30Since this operation can not be defined universally, the object is defined as abstract class with methods for: 
     31 - <b> Bayes rule </b> as defined above, operation bdm::BM::bayes() which expects to get the current data record \c dt, \f$ d_t \f$ 
     32 - <b> log-likelihood </b> i.e. numerical value of \f$ f(d_t|d_1\ldots d_{t-1})\f$ as a typical side-product, since it is required in denominator of the above formula. 
     33   For some models, computation of this value may require extra effort, hence it computation can be suppressed by setting BM::set_evalll(false). 
     34 - <b> prediction </b> the object has enough information to create the one-step ahead predictor, i.e. \f[ f(d_{t+1}| d_1 \ldots d_{t}), \f]  
     35        this object can be either created bdm::BM::predictor(), sometimes it is enought only a few values of prediction hence construction of the full predictor would be too expensive operation. For this situation were designed cheaper operations bdm::BM::logpred() or bdm::BM::epredictor(). 
     36These are only basic operations, see full documentation for full range of defined operations. 
     37         
     38These operation are abstract, i.e. not implemented for the general class.  
     39Implementation of these operations is heavily dependent on the specific class of prior pdf, or its approximations. We can identify only a few principal approaches to this problem. For example, analytical estimation which is possible within sufficient the Exponential Family, or estimation when both prior and posterior are approximated by empirical densities.  
     40These approaches are first level of descendants of class \c BM, classes bdm::BMEF and bdm::PF, repectively. 
    1941 
    20 For smaller decision making tasks, interactive use of the experiment can be achieved by showing the full configuration structure (or its selected parts), running the experiment on demand and showing the results. 
     42Variants 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. 
    2143 
    22 Semi-interactive experiments can be designed by sequential run of different algorithms. This topic will be covered in advanced documentation. 
     44\section arx Estimation of ARX models 
    2345 
    24 \section config Configuration of an experiment 
     46Autoregressive models has already been introduced in \ref ug_arx_sim where their simulator has been presented. 
     47We will use the datasource defined there to provide data for estimation. 
    2548 
    26 Configuration file (or config structure) is organized as a tree of information. High levels represent bigger structures, leafs of the structures are basic data elements such as strings, numbers or vectors. 
    27  
    28 Specific treatment was developed for objects. Since BDM is designed as object oriented library, the configuration was designed to honor the rule of inheritance. That is, offspring of a class can be used in place of its predecessor. Hence, objects (instances of classes) are configured by a structure  with compulsory field \c class. This is a string variable corresponding to the name of the class to be used. 
    29  
    30 Consider the following example: 
     49The following code is from bdmtoolbox/tutorial/userguide/arx_basic_example 
    3150\code 
    32 DS = {class="MemDS"; 
    33    data = [1, 2, 3, 4, 5, 6, 7]; 
    34 } 
    35 \endcode 
    36 or written equivalently in Matlab as 
    37 \code 
    38 DS.class='MemDS'; 
    39 DS.Data =[1 2 3 4 5 6]; 
    40 \endcode 
    41  
    42 The code above is the minimum necessary information to run a pre-made algorithm implemented as executable \c estimator or Matlab mex file \c estimator. The expected result for Matlab is: 
    43 \code 
    44 >> M=estimator(DS,{}) 
    45  
    46 M =  
    47  
    48     ch0: [6x1 double] 
    49 \endcode 
    50  
    51 The structure \c M has one field called \c ch0 to which the data from \c DS.Data were copied. This was configured to be the default behavior which can be easily changed by adding more information to the configuration structure. 
    52  
    53 First, we will have a look at all options of MemDS. 
    54  
    55 \section memds How to understand configuration of classes 
    56  
    57 As a first step, the estimator algorithm has created an object of class MemDS and called its method  bdm::MemDS::from_setting(). 
    58 This is a universal method called when creating an instance of class from configuration. Object that does not implement this method can not be created automatically from configuration. 
    59  
    60 The documentation contains the full structure which can be loaded. e.g.: 
    61 \code 
    62 { class = 'MemDS'; 
    63         Data = (...);            // Data matrix or data vector 
    64         --- optional --- 
    65         drv = {class='RV'; ...} // Identification how rows of the matrix Data will be known to others 
    66         time = 0;               // Index of the first column to user_info, 
    67         rowid = [1,2,3...];     // ids of rows to be used 
    68 } 
    69 \endcode 
    70 for MemDS. The compulsory fields are listed at the beginning; the optional fields are separated by string "--- optional ---". 
    71  
    72 For the example given above, the missing fields were filled as follows: 
    73 \code 
    74   drv  = {class="RV"; names="{ch0 }"; sizes=[1];}; 
    75   time = 0; 
    76   rowid = [1]; 
    77 \endcode 
    78 Meaning that the data will be read from the first column (time=0), all rows of data are to be read (rowid=[1]), and this row will be called "ch0".  
    79  
    80 \note <b>Mixtools reference</b> This object replaces global variables DATA and TIME. In BDM, data can be read and written to a range of \c datasources, objects derived from bdm::DS. 
    81  
    82 \section rvs What is RV and how to use it 
    83  
    84 RV stands for \c random \c variable which is a description of random variable or its realization. This object playes role of identifier of elements of vectors of data (in datasources), expected inputs to functions (in pdfs), or required results (operations conditioning).  
    85  
    86 \note <b>Mixtools reference </b> RV is generalization of "structures" \c str in Mixtools. It replaces channel numbers by string names, and adds extra field size for each record. 
    87  
    88 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 algorithm \c estimator is build in a way that requires RV to be given. 
    89  
    90 The \c estimator use-case expects to join the data source with an array of estimators, each of which declaring its input vector of data. The connection will be made automatically using the mechanism of datalinks (bdm::datalink). 
    91 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 are much more powerful than this.  
    92  
    93 \section datasource Class inheritance and DataSources 
    94  
    95 As mentioned above, the algorithm \c estimator is written to accept any datasource (i.e. any offspring of bdm::DS). For full list of offsprings, click Classes > Class Hierarchy. 
    96  
    97 At the time of writing this tutorial, available datasources are 
    98 bdm::DS 
    99  - bdm::EpdfDS 
    100  - bdm::MemDS 
    101    - bdm::FileDS 
    102      - bdm::CsvFileDS 
    103      - bdm::ITppFileDS 
    104  - bdm::MpdfDS 
    105  - bdm::stateDS 
    106  
    107 The MemDS has already been introduced in the example in \ref memds. 
    108 However, any of the classes listed above can be used to replace it in the example. 
    109 This will be demonstrated on the \c EpdfDS class. 
    110  
    111 Brief decription of the class states that EpdfDS "Simulate data from a static pdf (epdf)". The static pdf means unconditional pdf in the sense that the random variable is conditioned by numerical values only. In mathematical notation it could be both \f$ f(a) \f$ and \f$ f(x_t |d_1 \ldots d_t)\f$. The latter case is true only when all \f$ d \f$ denotes observed values. 
    112  
    113 For example, we wish to simulate realizations of a Uniform density on interval <-1,1>. Uniform density is represented by class bdm::euni. 
    114 From bdm::euni.from_setting() we can find that the code is: 
    115 \code  
    116 U={class="euni"; high=1.0; low = -1.0;} 
    117 \endcode 
    118 for configuration file, and  
    119 \code 
    120 U.class='euni'; 
    121 U.high = 1.0; 
    122 U.low  = -1.0; 
    123 U.rv.class = 'RV'; 
    124 U.rv.names = {'a'}; 
    125 \endcode 
    126 for Matlab. 
    127    
    128 The datasource itself, can be then configured via 
    129 \code 
    130 DS = {class='EpdfDS'; epdf=@U;}; 
    131 \endcode 
    132 in config file, or  
    133 \code 
    134 DS.class = 'EpdfDS'; 
    135 DS.epdf  = U; 
    136 \endcode 
    137 in Matlab. 
    138  
    139 Contrary to the previous example, we need to tell to algorithm \c estimator how many samples from the data source we need. This is configured by variable \c experiment.ndat. The configuration has to be finalized by: 
    140 \code  
    141 experiment.ndat = 10; 
    142 M=estimator(DS,{},experiment); 
    143 \endcode 
    144  
    145 The result is as expected in field \c M.a the name of which corresponds to name of \c U.rv . 
    146  
    147 If the task was only to generate random realizations, this would indeed be a very clumsy way of doing it. However, the power of the proposed approach will be revelead in more demanding examples, one of which follows next. 
    148  
    149 \section arx Simulating autoregressive model 
    150  
    151 Consider the following autoregressive model:  
    152 \f[ 
    153 y_t \sim \mathcal{N}( a y_{t-3} + b u_{t-1}, r) 
    154 \f] 
    155 where \f$ a,b \f$ are known constants, and \f$ r \f$ is known variance. 
    156  
    157 Direct application of \c EpdfDS is not possible, since the pdf above is conditioned on values of \f$ y_{t-3}\f$ and \f$ u_{t-1}\f$. 
    158 We need to handle two issues: 
    159  -# extra unsimulated variable \f$ u \f$, 
    160  -# time delayes of the values. 
    161  
    162 The first issue can be handled in two ways. First, \f$ u \f$ can be considered as input and as such it could be externally given to the datasource. This solution is used in algorithm use-case \c closedloop. 
    163 However, for the \c estimator scenario we will apply the second option, that is we complement \f$ f(y_{t}|y_{t-3},u_{t-1})\f$ by extra pdf:\f[ 
    164 u_t \sim \mathcal{N}(0, r_u) 
    165 \f] 
    166 Thus, the joint density is now:\f[ 
    167 f(y_{t},u_{t}|y_{t-3},u_{t-1}) = f(y_{t}|y_{t-3},u_{t-1})f(u_{t}) 
    168 \f] 
    169 and we have no need for input since the datasource have all necessary information inside. All that is required is to store them and copy their values to appropriate places. 
    170  
    171 That is done in automatic way using dedicated class bdm::datalink_buffered. The only issue a user may need to take care about is the missing initial conditions for simulation. 
    172 By default these are set to zeros. Using the default values, the full configuration of this system is: 
    173 \code 
    174 y = RV({'y'}); 
    175 u = RV({'u'}); 
    176  
    177 fy.class = 'mlnorm<ldmat>'; 
    178 fy.rv    = y; 
    179 fy.rvc   = RV({'y','u'}, [1 1], [-3, -1]); 
    180 fy.A     = [0.5, -0.9]; 
    181 fy.const = 0; 
    182 fy.R     = 0.1; 
    183  
    184  
    185 fu.class = 'enorm<ldmat>'; 
    186 fu.rv    = u; 
    187 fu.mu    = 0; 
    188 fu.R     = 0.2; 
    189  
    190 DS.class = 'MpdfDS'; 
    191 DS.mpdf.class  = 'mprod'; 
    192 DS.mpdf.mpdfs  = {fy, epdf2mpdf(fu)}; 
    193 \endcode 
    194  
    195 Explanation of this example will require few remarks: 
    196  - class of the \c fy object is 'mlnorm<ldmat>' which is Normal pdf with mean value given by linear function, and covariance matrix stored in LD decomposition, see bdm::mlnorm for details. 
    197  - naming convention 'mlnorm<ldmat>' relates to the concept of templates in C++. For those unfamiliar with this concept, it is basicaly a way how to share code for different flavours of the same object. Note that mlnorm exist in three versions: mlnorm<ldmat>, mlnorm<chmat>, mlnorm<fsqmat>. Those classes act identically the only difference is that the internal data are stored either in LD decomposition, choleski decomposition or full matrices, respectively.  
    198  - the same concept is used for enorm, where enorm<chmat> and enorm<fsqmat> are also possible. In this particular use, these objects are equivalent. In specific situation, e.g. Kalman filter implemented on Choleski decomposition (bdm::KalmanCh), only enorm<chmat> is approprate. 
    199  - class 'mprod' represents the chain rule of probability. Attribute \c mpdfs of its configuration structure is a list of conditional densities. Conditional density \f$ f(a|b)\f$ is represented by class \c mpdf and its offsprings. Class \c RV is used to describe both variables before conditioning (field \c rv ) and after conditioning sign (field \c rvc). 
    200  - due to simplicity of implementation, mprod accept only conditional densities in the field \c mpdfs. Hence, the pdf \f$ f(u_t)\f$ must be converted to conditional density with empty conditioning, \f$ f(u_t| \{\})\f$. This is achieved by calling function epdf2mpdf which is only a trivial wrapper creating class bdm::mepdf. 
    201   
    202   
    203 The code above can be immediatelly run, usin the same execution sequence of \c estimator as above.  
    204  
    205 \subsection ini Initializing simulation 
    206  
    207 When zeros are not appropriate initial conditions, the correct conditions can be set using additional commands: 
    208 \code 
    209 DS.init_rv = RV({'y','y','y'}, [1,1,1], [-1,-2,-3]); 
    210 DS.init_values = [0.1, 0.2, 0.3]; 
    211 \endcode 
    212  
    213 The values of \c init_values will be copied to places in history identified by corresponding values of \c init_rv. 
    214 Initial data is not checked for completeness, i.e. values of random variables missing from \c init_rv (in this case all occurences of \f$ u \f$) are still initialized to 0. 
    215  
    216 \section conc What was demonstrated in this tutorial 
    217 The purpose of this page was to introduce software image of basic elements of decision making as implemented in BDM. 
    218  
    219  - random values as identification mechanism (bdm::RV) 
    220  - unconditional pdfs (bdm::epdf), 
    221  - conditional pdfs (bdm::mpdf), 
    222   
    223 And the use of these in simulation of data and function of datasources. In the next tutorial, Bayesian models (bdm::BM) and loggers (bdm::logger) will be introduced. 
    224  
    225  
    226  
     51A1.class = 'ARX'; 
     52A1.rv = y; 
     53A1.rgr = RVtimes({y,y},[-3,-1]) ; 
     54\endcode  
     55Using the same logic as before,  
    22756 
    22857*/