root/library/doc/tutorial/007userguide_pdf.dox @ 1274

Revision 948, 5.5 kB (checked in by smidl, 14 years ago)

doc

Line 
1/*!
2\page userguide_pdf BDM Use - Probability density functions
3
4This section serves as an introduction to basic elements of the BDM: probability density functions, pdfs.
5
6The tutorial is written for the BDM toolbox, if you are interested in use of C++ classes see class reference pages.
7
8Table of content:
9 - \ref ug_pdf_create
10 - \ref ug_pdf_marg
11 - \ref ug_pdf_cond
12 - \ref ug_pdf_fnc
13 - \ref ug_pdf_mex
14
15\section ug_pdf_create Using built-in pdfs
16
17In BDM toolbox, a pdf is specified by matlab structure, e.g.
18\code
19Nab.class= 'enorm<ldmat>';
20Nab.mu   = [3,2];
21Nab.R    = eye(2);
22Nab.rv   = RV({'a','b'});
23\endcode
24Which encodes information \f$ f(a,b) = \mathcal{N}(mu=[3;2],R=eye(2))\f$.
25\li the keyword "enorm\<ldmat\>" means "Unconditional Normal distribution with covariance matrix in L'DL form", other possibilities are:
26"enorm\<chmat\>" for Choleski decomposition, and "enorm\<fsqmat\>" for full (non-decomposed) matrices.
27\li mu denotes mean value
28\li R denotes variance (written in full matrix regardles of the used decomposition),
29\li parameters mu and R are vector and matrix, respectively. They can be given directly (as in Nab.mu) or as a result of arbitrary matlab function, (as in Nab.R)
30\li rv denotes names assigned to the variables. RV is more complicated structure, but here it is sufficient to use default values.
31\li rv is an optional parameter, some operations do not need it, such as sampling or evaluation of moments
32
33For generating samples try:
34\code
35>> M=epdf_sample_mat(Nab,4);
36\endcode
37which should return 4 samples of the Nab distribution.
38
39For evaluation of mean and variance:
40\code
41>> Nab_m=epdf_mean(Nab);
42>> Nab_v=epdf_variance(Nab);
43\endcode
44
45Other distributions are created analogously, see ??? for their list and parameters???
46Sampling and evaluation of moments are done by exactly the same functions as for the normal density.
47
48\section ug_pdf_marg Marginalization and conditioning
49
50Basic operations on pdfs are marginalization and conditioning, which are provided by mex functions edpf_marginal and epdf_condition, respectively.
51
52This operation does require the rv parametetr to be fully specified. If it isn't, it will fail with the following message
53\code
54--- fill in the message ----
55\endcode
56
57If rv is correctly specified, marginal pdf of Nab on variable "a" is obtained by:
58\code
59Na = epdf_marginal(Nab,RV('a'));
60\endcode
61
62Similarly for conditional:
63\code
64Na_b = epdf_condition(Nab,RV('a'));
65Nb_a = epdf_condition(Nab,RV('b'));
66\endcode
67
68\section ug_pdf_cond Conditioned densities
69Note that the result of conditioning is of type "mlnorm\<ldmat\>" which is a special case of pdf with variables in condition, specifically
70\f[ f(a|b) = \mathcal{N}(A*b+const, R)\f]
71i.e. "Normal distributed pdf with mean value as linear function of variable b".
72
73This type of pdfs differ from previously used type is the way of use. For example, it is not possible to sample directly form such density,
74it is necessary to specify what is the value of variable in condition.
75
76That is why a different function is used:
77\code
78Smp=pdf_samplecond_mat(Na_b, 10)
79\endcode
80
81The conditioned and Unconditioned pdf may be combined together in the chain rule. The chain rule can be of two different types: conditioned or unconditioned, i.e.:
82\f[ f(a,b)=f(a|b)f(b), OR, f(a,b|c)=f(a|b)f(b|c)\f]
83Thus it is differently encoded as:
84\code
85fab.class = 'eprod';         % result is unconditioned pdf
86fab.pdfs  = {fa_b, fb};
87
88fab_c.class = 'mprod';       % result is conditioned pdf
89fab_c.pdfs  = {fa_b, fb_c};
90\endcode
91
92\section ug_pdf_fnc Pdfs with functional transformation
93
94In more general type of pdfs, variables in condition may be transformed by a function.
95For 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
96
97\code
98fx.class  = 'mgnorm<ldmat>';             
99fx.g      = 'mexFunction';              % function is evaluated in matlab
100fx.g.function = 'test_function';         % name of the matlab function to evaluate
101fx.g.dim  = 2;                          % expected dimension of output
102fx.g.dimc = 2;                          % expected dimension of input
103fx.R      = eye(2);                     % variance R
104\endcode
105
106This example is using generic function specified by name of Matlab .m file.
107Compulsory fields \c g.dim and \c g.dimc are used to check correct dimension of inputs and outputs of the function.
108
109
110\section ug_pdf_mex Creating user-defined pdfs in Matlab
111
112Definition 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
113
114The file lists all necessary functions that must be filled in order to plug the new class into other bdm algorithms.
115
116Please read Matlab manual for details on its implementation of object oriented programming.
117
118For easier start, an example class, mexLaplace, is defined in \<toolbox_dir\>/mex/mex_classes/mexLaplace.m
119
120Using matlab-extended classes is done via a structure with only two required fields:
121\code
122fL.class = 'mexEpdf';         % declaration of derivative from mexEpdf
123fL.object = mexLaplace;       % any particular instance of mexEpdf
124
125fL.object.mu = 1;             % set values of attributes of the chosen class, in this case mexLaplace
126fL.object.b = 1;             
127\endcode
128
129See example bdmtoolbox/tutorial/userguide/mexpdf_example.m
130
131
132For list of all available pdf objects, see \ref app_base
133*/
Note: See TracBrowser for help on using the browser.