Changeset 944 for library/doc

Show
Ignore:
Timestamp:
05/16/10 23:13:21 (14 years ago)
Author:
smidl
Message:

Doc + new examples

Location:
library/doc/tutorial
Files:
1 added
3 modified
2 moved

Legend:

Unmodified
Added
Removed

  • library/doc/tutorial/000install.dox

    r837 r944  
    1414Installation: 
    1515\li svn checkout http://mys.utia.cas.cz:1800/svn/mixpp/applications/bdmtoolbox/ into your local directory of your choice (this will be denoted \<toolbox_dir\>) 
    16 \li open matlab and type: \>\> addpath \<toolbox_dir\>/mex; addpath \<toolbox_dir\>/mexw32 
    17 \li the toolbox is ready to be used, test it e.g. by: \>\> cd tutorial/userguide; pdfds_example 
     16\li or download a prepared zip file from http://staff.utia.cas.cz/smidl/Public/bdmtoolbox_win32.zip and extract it to any directory (will be denoted \<toolbox_dir\>) 
     17\li open matlab and type:  
     18\code  
     19>> addpath <toolbox_dir>/mex;  
     20>> addpath <toolbox_dir>/mexw32 
     21>> addpath <toolbox_dir>/mex_classes 
     22\endcode 
     23\li the toolbox is ready to be used, test it e.g. by:  
     24\code >> cd tutorial/userguide;  
     25>> pdfds_example \endcode 
    1826\li if no error is given, the toolbox is installed correctly 
    19 \li proceed to http://mys.utia.cas.cz:1800/trac/bdm/doxygen/pages.html to learn how to use it 
     27\li proceed to tutorial at http://mys.utia.cas.cz:1800/trac/bdm/doxygen/pages.html to learn how to use it 
    2028 
    2129\section src Source code 

  • library/doc/tutorial/005userguide0.dox

    r853 r944  
    44BDM 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: 
    55 
    6  - <b> Experimentators </b> who run prepared scripts with different parameterizations and analyze their results, 
    7  - <b> Algorithms designers </b> who are able to understand the logic of BDM and extend its functionality to new applications. 
     6 - <b> Experimenters </b> who run prepared scripts with different parameterizations and analyze their results, 
     7 - <b> Advanced users</b> who are able to extend functionality by filling prepared Matlab classes,  
     8 - <b> Porgrammers </b> who are able to implement algorithms withing C++ backend of BDM. 
    89 
    9 The primary design aim of BDM was to ease development of complex algorithms, hence the target user is the latter.  
    10 However, running experiments is the first task to learn for both types of users. 
     10This tutorial is intended for the first two classes of users. Programmers should read it for introduction and then follow to the Doxygen maunal. 
    1111 
     12The logic of bdmtoolbox is that the experiment is run in C++ via mex-file. Parameterization of the task is done via Matlab structures.  
     13A range of selected "callback" functions to Matlab is available. This range can be extended by a Programmer, please contact authors if available extension point are not satisfactory for you. 
    1214 
    1315\section param Experiment is fully parameterized before execution 
    1416 
    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. 
    16  
    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). 
     17The main logic behind the experiment is that all necessary information about it are gathered in advance in a configuration structure. 
    1818This approach was designed especially for time consuming  experiments and Monte-Carlo studies for which it suits the most.  
    1919 
    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. 
     20For smaller decision making tasks, interactive use of the experiment can be achieved by showing the full configuration structure (or its selected parts),  
     21running the experiment on demand and showing the results. 
    2122 
    2223Semi-interactive experiments can be designed by sequential run of different algorithms. This topic will be covered in advanced documentation. 
    … …  
    3132 - <b>Closed loop</b>: sequantial estimation from previous step is complemneted by adaptive controller (or decision maker) that designs control strategy for the next step. 
    3233 
     34Mex files for some atomic operations with internal objects are provided for comfortable definition of an experiment and analysis. 
     35These functions are not efficient for use in repettitive way. 
     36 
    3337These scenarios may serve as a starting point for advanced users who can design specific algorithms tailored for given application domain. 
    3438 
    3539A tutorial how to run the scenarios are: 
    3640 
    37  - \ref userguide 
    38  - \ref userguide2 
     41 - \ref userguide_pdf 
     42 - \ref userguide_sim 
     43- \ref userguide_estim 
    3944 
    4045*/ 

  • library/doc/tutorial/007userguide_pdf.dox

    r778 r944  
    44This section serves as an introduction to basic elements of the BDM: probability density functions, pdfs. 
    55 
    6 The tutorial is written in for the BDM toolbox, if you are interested in use of C++ classes see class reference pages. 
     6The tutorial is written for the BDM toolbox, if you are interested in use of C++ classes see class reference pages. 
    77 
    8 \section ugpdf_create Creation of pdfs 
     8\section ug_pdf_create Using built-in pdfs 
    99 
    1010In BDM toolbox, a pdf is specified by matlab structure, e.g. 
    … …  
    1616\endcode 
    1717Which encodes information \f$ f(a,b) = \mathcal{N}(mu=[3;2],R=eye(2))\f$. 
    18 \li the keyword "enorm\<ldmat\>" means "Unconditional Normal distribution with covariance matrix in L'DL form", othe rpossibilities are:  
     18\li the keyword "enorm\<ldmat\>" means "Unconditional Normal distribution with covariance matrix in L'DL form", other possibilities are:  
    1919"enorm\<chmat\>" for Choleski decomposition, and "enorm\<fsqmat\>" for full (non-decomposed) matrices. 
    2020\li mu denotes mean value 
    … …  
    5858\endcode 
    5959 
    60 \section ugpdf_cond Conditioned densities 
     60\section ug_pdf_cond Conditioned densities 
    6161Note that the result of conditioning is of type "mlnorm\<ldmat\>" which is a special case of pdf with variables in condition, specifically  
    6262\f[ f(a|b) = \mathcal{N}(A*b+const, R)\f]  
    … …  
    7575Thus it is differently encoded as: 
    7676\code 
    77 fab.class = 'eprod'; 
     77fab.class = 'eprod';         % result is unconditioned pdf 
    7878fab.pdfs  = {fa_b, fb}; 
    7979 
    80 fab_c.class = 'mprod'; 
     80fab_c.class = 'mprod';       % result is conditioned pdf 
    8181fab_c.pdfs  = {fa_b, fb_c}; 
    8282\endcode 
    8383 
     84\section ug_pdf_fnc Pdfs with functional transformation 
     85 
     86In more general type of pdfs, variables in condition may be transformed by a function.  
     87For example Gaussian density with nonlinear transformation of mean value, \f$ f(x|y) = \mathcal{N}(g(y), R)\f$, is represented by class \c mgnorm 
     88 
     89\code 
     90fx.class  = 'mgnorm<ldmat>';              
     91fx.g      = 'mexFunction';              % function is evaluated in matlab 
     92fx.g.function = 'test_function';         % name of the matlab function to evaluate 
     93fx.g.dim  = 2;                          % expected dimension of output 
     94fx.g.dimc = 2;                          % expected dimension of input 
     95fx.R      = eye(2);                     % variance R 
     96\endcode 
     97 
     98This example is using generic function specified by name of Matlab .m file.  
     99Compulsory fields \c g.dim and \c g.dimc are used to check correct dimension of inputs and outputs of the function.  
    84100 
    85101 
     102\section ug_pdf_mex Creating user-defined pdfs in Matlab 
     103 
     104Definition of new pdf classes in matlab is done by extending (inheriting from) class mexPdf which is defined in file: bdmtoolbox/mex/mex_classes/mexEpdf.m 
     105 
     106The file lists all necessary functions that must be filled in order to plug the new class into other bdm algorithms. 
     107 
     108Please read Matlab manual for details on its implementation of object oriented programming.  
     109 
     110For easier start, an example class, mexLaplace, is defined in \<toolbox_dir\>/mex/mex_classes/mexLaplace.m  
     111 
     112Using matlab-extended classes is done via a structure with only two required fields: 
     113\code  
     114fL.class = 'mexEpdf';         % declaration of derivative from mexEpdf 
     115fL.object = mexLaplace;       % any particular instance of mexEpdf 
     116 
     117fL.object.mu = 1;             % set values of attributes of the chosen class, in this case mexLaplace 
     118fL.object.b = 1;               
     119\endcode 
     120 
     121See example bdmtoolbox/tutorial/userguide/mexpdf_example.m 
    86122 
    87123 
    88  
    89  
     124For list of all available pdf objects, see \ref app_base 
    90125*/ 

  • library/doc/tutorial/01userguide_sim.dox

    r897 r944  
    11/*! 
    2 \page userguide BDM Use - System, Data, Simulation 
     2\page userguide_sim BDM Use - System, Data, Simulation 
    33 
    44This section serves as introduction to the scenario of data simulation. Since it is the simpliest of all scenarios defined in \ref userguide0 it also serves as introduction to configuration of an experiment (see \ref ui) and basic decision making objects (bdm::RV and bdm::DS). 
    55 
    6 All experiments are demonstarted on scenario simulator which can be either standalone application or mex file (simulator.mex**). 
    7  
    8  
    9 \section ug_config Configuration of an experiment 
     6All experiments are demonstarted on mex file \c simulator, which is also available as a standalone application. 
     7 
     8 
     9\section ug_sim_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. 
    1212 
    13 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. 
    14  
    15 The configuration has two possible options: 
    16  - configuration file using syntax of libconfig (see \ref ui), 
    17  - matlab structure. 
    18 For 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) 
     13Specific 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. This information is stored in Matlab structures (or objects, see section on Matlab extensions). 
     14 
     15Advacnded users can find more information in (\ref ui). 
    2016 
    2117\subsection ug_first First experiment 
    … …  
    2925 
    3026The code above is the minimum necessary information to run scenario \c simulator in matlab.  
    31 To actually do so, make sure that matlab can find the simulator.mex file, e.g. by running: 
    32 \code  
    33 >> addpath _path_to_/bmtoolbox/mex/ 
    34 \endcode 
     27To actually do so, make sure that matlab paths are correctly set, as described in \ref install. 
    3528 
    3629The expected result for Matlab is: 
    … …  
    4336\endcode 
    4437 
    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 install.  
    4638All that the simulator did was actually copying \c DS.Data to \c M.ch0. Explanation of the experiment and the logic used there follows. 
    4739 
    … …  
    6456One of the definition of a system is that system is a "set of variables observed on a part of the world". Under this definition system is understood as generator of data. This definition may be a considered too simplistic, but it serves well as a description of what software object \c DataSource is. 
    6557 
    66 DataSource is an object that is essentially: 
    67  -# able to return data observed at time \f$ t \f$, (bdm::DS::getdata()), 
    68  -# able to perform one a time step, (bdm::DS::step()). 
    69  -# able to describe what these data are, (bdm::DS::_drv()), 
     58DataSource is an object that is essentially able to: 
     59 -# return data observed at time \f$ t \f$,  
     60 -# perform one a time step. 
     61 -# describe what these data are, via class RV, introduced in ref \ug_pdf_marg, 
     62 -# store log of its activity into dedicated logger. 
    7063 
    7164No fruther specification, e.g. if the data are pre-recorded or computed on-the-fly, are given. 
    72 Specific behaviour of various DataSources is implemented as specialization of the root class bdm::DS. 
     65For a list of available DataSources, see ... 
    7366 
    7467 
    … …  
    8275 -# each row is named as "ch0","ch1",... 
    8376 
    84 This is the default bahavior. It can be customized using the UI mechanism. 
    85 When the object of class MemDS is created it calls method  bdm::MemDS::from_setting() and the input structure is parsed for settings. All available settings are documented in the method, see bdm::MemDS::from_setting(). The options are: 
     77This is the default bahavior. It can be customized using the UI mechanism. Full list of options is: 
    8678\code 
    8779DS.class = 'MemDS'; 
    … …  
    9082DS.drv = RV({"ch0",...} ); // Identification how rows of the matrix Data will be known to others 
    9183DS.time = 0;               // Index of the first column to user_info, 
    92 DS.rowid = [1,2,3...];     // ids of rows to be used 
    9384\endcode 
    9485The compulsory fields are listed at the beginning; the optional fields are separated by string "--- optional ---". 
    9586 
    96 Fields \c time and \c rowid are self-explanatory. Field \c drv is a the one that specifies identification of the data elements, (point 3. of the general requirements of a DataSource).  
     87Fields \c time denotes the first record to start counting from. Field \c drv is a the one that specifies identification of the data elements, (point 3. of the general requirements of a DataSource).  
    9788 
    9889All optionals fields will be filled by default values, it this case: 
    … …  
    10091DS.drv  = RV({'ch0'},1,0); 
    10192DS.time = 0; 
    102 DS.rowid = [1]; 
    10393\endcode 
    10494Where the first line specifies a universal identification structure: random variable (bdm::RV). 
    … …  
    10696\section ug_rvs What is RV and how to use it 
    10797 
    108 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).  
    109  
    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. 
    111  
    112 In software, \c RV has three compulsory properties: 
    113  - <b>name</b>, unique identifier, two RV with the same name are considered to be identical 
    114  - <b>size</b>, size of the random variable, if not given it is assumed to be 1, 
    115  - <b>time</b>, more exactly time shift from \f$ t \f$, defaults to 0. 
    116  For example, scalar \f$ x_{t-2} \f$ is encoded as (name='x',sizes=1,time=-2). 
    117  Each RV stores array of these elements, hence RV with: 
    118  \code 
    119  names={'a', 'b'}; 
    120  sizes=[ 2 , 3]; 
    121  times=[-1, 1]; 
    122  \endcode  
    123  denotes 5-dimensional vector \f$ [a_{t-1}, b_{t+1}] \f$. 
    124   
    125 \subsection ug_rv_alg Algebra on RVs 
    126 Algebra on RVs (adding, searching in, subtraction, intersection, etc.) is implemented, see bdm::RV. 
    127  
    128 For convenience in Matlab, the following operations are defined: 
    129  - RV(names,sizes,times) creates configuration structure for RV, 
    130  - RVjoin(rvs) joins configuration structures for array of RVs rvs=[rv1,rv2,...], 
    131  - RVtimes(rvs,times) assign times to corresponding rvs. 
    132  
    133 See examples in bdmtoolbox/tutorial/userguide 
    134  
    135 \subsection ug_rv_connect 
    136  
    137 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. 
    138 The connection between these blocks is done automatically. The logger stores results of simulations under the names specified in drv.   
     98RV stands for \c random \c variable which is a description of random variable or its realization. However, this object serves as general descriptor of fields in vectors of data.  
     99 
     100It is used for: 
     101 - desription of RV in pdfs, ways how to define marginalization and conditioning, 
     102 - connection between source of data and computational objects that use them, 
     103 - connection <b>time</b>, more exactly time shift from \f$ t \f$, defaults to 0. 
     104 
     105\subsection ug_rv_connect Storing results 
     106 
     107results of an experiment can be stored in many ways. This functionality was abstracted into a class called logger. Exact form of the stored resuls is chosen by choosing appropriate class. 
     108For example, \c stdlog writes all output in the console, \c dirfilelog writes all data in the dirfilelog format for high-speed data processing, \c mexlog writes data into matlab structure.  
     109The \c mexlog is the default option in bdmtoolbox. 
     110 
     111Connection between computational blocks and loggers is controlled by structure called \c log_level which governes the level of details to be logged. 
     112A standard Data source has two levels, \c logdt and \c logut which means "log all outputs, dt" and "log all inputs, ut". 
    139113Readers 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. 
    140114 
    141  
    142 \section ug_loggers Loggers for flexible handling of results 
    143 Loggers are universal objects for storing and manipulating the results of an experiment. Similar to DataSource, every logger has to provide basic functionality: 
    144  -# initialize its storage (bdm::logger.init()), 
    145  -# assign a connection point to each interested object (bdm::logger.logadd()), 
    146  -# accept data to be logged to given connection (bdm::logger.logit()), 
    147  -# finalize the storage when experiment is finished. 
    148  
    149 These abstarct operations can be specialized in many ways. For example, storing all results in memory and writing them to disc when finished (bdm::memlog), storing data in a matlab structure (bdm::mexlog), writing them out in ascii (bdm::stdlog) or more sophisticated buffered output to harddrive (bdm::dirfilelog). 
    150  
    151 Since 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. 
    152  
    153 \section ug_datasource Class inheritance and DataSources 
    154  
    155 As 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. 
    156  
    157 At the time of writing this tutorial, available datasources are 
    158 bdm::DS 
    159  - bdm::EpdfDS 
    160  - bdm::MemDS 
    161    - bdm::FileDS 
    162      - bdm::CsvFileDS 
    163      - bdm::ITppFileDS 
    164  - bdm::PdfDS 
    165  - bdm::stateDS 
    166  
    167 The MemDS has already been introduced in the example in \ref ug_memds. 
    168 However, any of the classes listed above can be used to replace it in the example. 
    169 This will be demonstrated on the \c EpdfDS class. 
    170  
    171 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. 
    172  
    173 For example, we wish to simulate realizations of a Uniform pdf on interval <-1,1>.  
    174 This is achieved by plugging an object representing uniform pdf into general simulator of independent random samples, EpdfDS. Uniform density is implemented as class bdm::euni. 
    175 An instance of \c euni can be again created method \c from_setting, in this case bdm::euni.from_setting(). Using documentation we define it with the following code: 
     115\section ug_pdfds How to create a simulator from pdfs  
     116For example, we would like to simulate a random Uniform distributed noise on interval <-1,1>.  
     117This is achieved by plugging an object representing uniform pdf into general simulator of independent random samples, pdfDS. Uniform density is implemented as class bdm::euni, which is created from the following structure: 
    176118\code 
    177119U.class='euni'; 
    … …  
    186128The datasource itself, i.e. the instanc of \c EpdfDS can be then configured via: 
    187129\code 
    188 DS.class = 'EpdfDS'; 
    189 DS.epdf  = U; 
     130DS.class = 'pdfDS'; 
     131DS.pdf  = U; 
    190132\endcode 
    191133where \c U is the structure defined above. 
    … …  
    197139\endcode 
    198140 
    199 The result is as expected in field \c M.a the name of which corresponds to name of \c U.rv . 
     141The result is as expected in field \c M.DS_dt_a the name of which corresponds to results form "datasouce" / "output_dt" / "name given in U.rv". 
    200142 
    201143If 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. 
    … …  
    209151where \f$ a,b \f$ are known constants, and \f$ r \f$ is known variance. 
    210152 
    211 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$. 
    212153We need to handle two issues: 
    213154 -# extra unsimulated variable \f$ u \f$, 
    … …  
    224165and 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. 
    225166 
    226 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. 
     167That is done in automatic way (via bdm::datalink_buffered). The only issue a user may need to take care about is the missing initial conditions for simulation. 
    227168By default these are set to zeros. Using the default values, the full configuration of this system is: 
    228169\code 
    … …  
    252193 - 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.  
    253194 - 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. 
    254  - class 'mprod' represents the chain rule of probability. Attribute \c pdfs of its configuration structure is a list of conditional densities. Conditional density \f$ f(a|b)\f$ is represented by class \c pdf and its offsprings. Class \c RV is used to describe both variables before conditioning (field \c rv ) and after conditioning sign (field \c rvc). 
    255   
     195 - class 'mprod' represents the chain rule of probability, see \ref ug_pdf_cond. 
    256196  
    257197The code above can be immediatelly run, usin the same execution sequence of \c estimator as above.  
    … …  
    259199\subsection ug_ini Initializing simulation 
    260200 
    261 When zeros are not appropriate initial conditions, the correct conditions can be set using additional commands (see bdm::pdfDS.from_setting() ): 
     201When zeros are not appropriate initial conditions, the correct conditions can be set using additional commands: 
    262202\code 
    263203DS.init_rv = RV({'y','y','y'}, [1,1,1], [-1,-2,-3]); 
    … …  
    267207The values of \c init_values will be copied to places in history identified by corresponding values of \c init_rv. 
    268208Initial 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. 
    269  
    270209 
    271210\section ug_store Storing results of simulation 
    … …  
    289228\endcode 
    290229 
     230For list of all DataSources and loggers, see \ref app_base 
    291231*/ 

  • library/doc/tutorial/02userguide_estim.dox

    r870 r944  
    11/*! 
    2 \page userguide2 BDM Use - Estimation and Bayes Rule 
     2\page userguide_estim BDM Use - Estimation and Bayes Rule 
    33 
    44Baysian theory is predominantly used in system identification, or estimation problems.  
    … …  
    3030Since this operation can not be defined universally, the object is defined as abstract class with methods for: 
    3131 - <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). 
     32 - <b> evidence </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, and can be swithed off. 
    3434 - <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(). 
    36 These are only basic operations, see full documentation for full range of defined operations. 
    3735         
    38 These operation are abstract, i.e. not implemented for the general class.  
    3936Implementation 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.  
    4037These approaches are first level of descendants of class \c BM, classes bdm::BMEF and bdm::PF, repectively. 
    41  
    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. 
    4338 
    4439\section ug2_arx_basic Estimation of ARX models 
    … …  
    5449A1.log_level = 'logbounds,logevidence'; 
    5550\endcode  
    56 This is the minimal configuration of an ARX estimator. Optional elements of bdm::ARX::from_setting() were set using their default values: 
     51This is the minimal configuration of an ARX estimator.  
    5752 
    5853The first three fileds are self explanatory, they identify which data are predicted (field \c rv) and which are in regressor (field \c rgr). 
    5954The field \c log_level is a string of options passed to the object. In particular, class \c BM understand only options related to storing results: 
    6055 - logbounds - store also lower and upper bounds on estimates (obtained by calling BM::posterior().qbounds()), 
    61  - logevidence - store also loglikelihood of each step of the Bayes rule. 
     56 - logevidence - store also evidence of each step of the Bayes rule. 
    6257These values are stored in given logger (\ref ug_loggers). By default, only mean values of the estimate are stored. 
    6358 
    64 Storing of the log-likelihood is useful, e.g. in model selection task when two models are compared. 
     59Storing of the evidence is useful, e.g. in model selection task when two models are compared. 
    6560 
    6661The bounds are useful e.g. for visualization of the results. Run of the example should provide result like the following: 
    67 \image html arx_basic_example_small.png  
    6862\image latex arx_basic_example.png "Typical run of tutorial/userguide/arx_basic_example.m" width=\linewidth 
    6963 
    7064\section ug2_model_sel Model selection 
    7165 
    72 In Bayesian framework, model selection is done via comparison of marginal likelihood of the recorded data. See [some theory]. 
     66In Bayesian framework, model selection is done via comparison of evidence (marginal likelihood) of the recorded data. See [some theory]. 
    7367 
    7468A 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: 
    … …  
    10094A3.rv_param = RV({'a3th', 'r'},[2,1],[0,0]); 
    10195\endcode 
    102 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. 
     96First, 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.A1_evidence. 
    10397 
    10498Second, if the parameters of a ARX model are not specified, they are automatically named \c theta and \c r. However, 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. 
    … …  
    106100\section ug2_bm_composition Composition of estimators 
    107101 
    108 Similarly to pdfs 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. 
     102Similarly to pdfs which could be composed via \c mprod, the Bayesian models can be composed togetrer. However, justification of this step is less clear than in the case of epdfs. 
    109103 
    110104One possible theoretical base of composition is the Marginalized particle filter, which splits the prior and the posterior in two parts: 
    … …  
    119113This is achieved by a trivial extension using inheritance method bdm::BM::condition(). 
    120114 
    121 Extension of standard ARX estimator to conditional estimator is implemented as class bdm::ARXfrg. The only difference from standard ARX is that this object will change its forgetting factor via method ARXfrg::condition(). Existence of this function is assumed by the MPF estimator. 
     115Extension of standard ARX estimator to conditional estimator is implemented as class bdm::ARXfrg. The only difference from standard ARX is that this object will obtain its forgetting factor externally as a conditioning variable.  
    122116Informally, the name 'ARXfrg' means: "if anybody calls your condition(0.9), it tells you new value of forgetting factor". 
    123117 
    124 The MPF estimator is implemented by class bdm::MPF. In the toolbox, it can be constructed as follows: 
     118The MPF estimator for this case is specified as follows: 
    125119\code 
    126120%%%%%% ARX estimator conditioned on frg 
    … …  
    139133phi_pdf.betac = [0.01 0.01];       % stabilizing elememnt of random walk 
    140134 
     135%%%%%% Particle 
     136p.class = 'MarginalizedParticle'; 
     137p.parameter_pdf = phi_pdf;         % Random walk is the parameter evolution model 
     138p.bm    = A1; 
     139 
     140% prior on ARX 
    141141%%%%%% Combining estimators in Marginalized particle filter 
    142 E.class = 'MPF'; 
    143 E.BM = A1;                         % ARX is the analytical part 
    144 E.parameter_pdf = phi_pdf;         % Random walk is the parameter evolution model 
    145 E.n = 20;                          % number of particles 
     142E.class = 'PF'; 
     143E.particle = p;                    % ARX is the analytical part 
     144E.res_threshold = 1.0;             % resampling parameter 
     145E.n = 100;                         % number of particles 
    146146E.prior.class = 'eDirich';         % prior on non-linear part 
    147 E.prior.beta  = [1 1]; %  
    148 E.log_level ='logbounds,logevidence'; 
     147E.prior.beta  = [2 1]; %  
     148E.log_level = 'logbounds'; 
    149149E.name = 'MPF'; 
    150150 
    … …  
    168168Note: error bars in this case are not directly comparable with those of previous examples. The MPF class implements the qbounds function as minimum and maximum of bounds in the condidered set (even if its weight is extreemly small). Hence, the bounds of the MPF are probably larger than it should be. Nevertheless, they provide great help when designing and tuning algorithms. 
    169169 
     170\section ug_est_ext Matlab extensions of the Bayesian estimators 
     171 
     172Similarly to the extension of pdf, the estimators (or filters) can be extended via prepared class \c mexBM in directory bdmtoolbox/mex/mex_classes. 
     173 
     174An example of such class is mexLaplaceBM in \<toolbox_dir\>\tutorial\userguide\laplace_example.m 
     175 
     176Note that matlab-extended classes of mexEpdf, specifically, mexDirac and mexLaplace are used as outputs of methods posterior and epredictor, respectively. 
     177 
     178In order to create a new extension of an estimator, copy file with class mexLaplaceBM.m and redefine the methods therein. If needed create new classes for pdfs by inheriting from mexEpdf, it the same way as in the mexLaplace.m example class. 
     179 
     180Foro list of all estimators, see \ref app_base. 
    170181*/