root/applications/bdmtoolbox/doc/local/01userguide_pdf.dox @ 1044

/*!
\page userguide_pdf BDM Use - Probability density functions

This section serves as an introduction to basic elements of the BDM: probability density functions, pdfs.

Table of content:
 - \ref ug_pdf_create 
 - \ref ug_pdf_marg 
 - \ref ug_pdf_cond 
 - \ref ug_pdf_fnc 
 - \ref ug_pdf_mex 

\section ug_pdf_create Using built-in pdfs

In BDM toolbox, a pdf is specified by matlab structure, e.g.
\code
Nab.class= 'enorm<ldmat>';
Nab.mu   = [3,2];
Nab.R    = eye(2);
Nab.rv   = RV({'a','b'});
\endcode
Which encodes information \f$ f(a,b) = \mathcal{N}(mu=[3;2],R=eye(2))\f$.
\li the keyword "enorm\<ldmat\>" means "Unconditional Normal distribution with covariance matrix in L'DL form", other possibilities are: 
"enorm\<chmat\>" for Choleski decomposition, and "enorm\<fsqmat\>" for full (non-decomposed) matrices.
\li mu denotes mean value
\li R denotes variance (written in full matrix regardles of the used decomposition),
\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)
\li rv denotes names assigned to the variables. RV is more complicated structure, but here it is sufficient to use default values.
\li rv is an optional parameter, some operations do not need it, such as sampling or evaluation of moments

For generating samples try:
\code
>> M=epdf_sample_mat(Nab,4);
\endcode
which should return 4 samples of the Nab distribution.

For evaluation of mean and variance:
\code
>> Nab_m=epdf_mean(Nab);
>> Nab_v=epdf_variance(Nab);
\endcode

Other distributions are created analogously, see \ref bdm_doc/annotated_epdf.html

\section ug_pdf_marg Marginalization and conditioning

Basic operations on pdfs are marginalization and conditioning, which are provided by mex functions edpf_marginal and epdf_condition, respectively.

This operation does require the rv parametetr to be fully specified. If it isn't, it will fail with the following message
\code
--- fill in the message ----
\endcode

If rv is correctly specified, marginal pdf of Nab on variable "a" is obtained by:
\code
Na = epdf_marginal(Nab,RV('a'));
\endcode

Similarly for conditional:
\code
Na_b = epdf_condition(Nab,RV('a'));
Nb_a = epdf_condition(Nab,RV('b'));
\endcode

\section ug_pdf_cond Conditioned densities
Note that the result of conditioning is of type "mlnorm\<ldmat\>" which is a special case of pdf with variables in condition, specifically 
\f[ f(a|b) = \mathcal{N}(A*b+const, R)\f] 
i.e. "Normal distributed pdf with mean value as linear function of variable b".

This 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, 
it is necessary to specify what is the value of variable in condition. 

That is why a different function is used:
\code
Smp=pdf_samplecond_mat(Na_b, 10)
\endcode

The 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.:
\f[ f(a,b)=f(a|b)f(b), OR, f(a,b|c)=f(a|b)f(b|c)\f]
Thus it is differently encoded as:
\code
fab.class = 'eprod';         % result is unconditioned pdf
fab.pdfs  = {fa_b, fb};

fab_c.class = 'mprod';       % result is conditioned pdf
fab_c.pdfs  = {fa_b, fb_c};
\endcode

\section ug_pdf_fnc Pdfs with functional transformation

In more general type of pdfs, variables in condition may be transformed by a function. 
For 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

\code
fx.class  = 'mgnorm<ldmat>';             
fx.g      = 'mexFunction';              % function is evaluated in matlab
fx.g.function = 'test_function';         % name of the matlab function to evaluate
fx.g.dim  = 2;                          % expected dimension of output
fx.g.dimc = 2;                          % expected dimension of input
fx.R      = eye(2);                     % variance R
\endcode

This example is using generic function specified by name of Matlab .m file. 
Compulsory fields \c g.dim and \c g.dimc are used to check correct dimension of inputs and outputs of the function. 

List of functions is in \ref bdm_doc/annotated_fnc

\section ug_pdf_mex Using Matlab classes of pdfs

Access to Matlab defined classe of pdfs is provided via structure:
\code 
class = 'mexEpdf';
object = any_object_of_mexEpdf;
\endcode
where object can be created by any offspring of mexEpdf.

See \ref mex_bdm, and files: mex/mex_classes/mexEpdf.m

If you wish to write your own Matlab classes see \ref ug_dev_mat.

For list of all available pdf objects, see \ref annotated_epdf.html , \ref annotated_pdf.html and \ref annotated.html
*/