root/applications/bdmtoolbox/doc/local/001wrappers.dox @ 1375

/*!
\page bdt_wrappers Use Case #2: Matlab wrappers for BDM functions

A wrapper is a mex file that does the following:
 -# reads its arguments from Matlab structures and translates them into C++ structures
 -# calls the corresponding function in C++,
 -# converts the results into Matlab structures and passes them to the output
 
The use of these functions is inefficient, however, it is very usefull for:
 - operations on parts of the experiment configurations for scenarios, see ...
 - insight into the results, e.g. mean values of non-standard densities 
 - algorithms written in Matlab using these functions can be trivially re-written into C++
 
General notation of wrappers is: <b> \<class\>_\<function\>.m </b>

For example, function \b epdf_mean.m  represents function \b mean  of class \b epdf  and any it its offsprings.

For full list of available wrappers see content of directory /bdmtoolbox/mex

\section bdt_wr_conv Convenience wrappers

A useful wrapper is called \b class_defaults which takes the input matlab structure tries to copy it into BDM class and returns a structure how BDM interprets it.

This is useful for:
 - checking if the fields are correctly named: fields of input structure that are not in the output are not understood
 - seeing what defaults the BDM assigns to fields that are optional
 
Example:
\code
>> CLS.class='RV'

CLS = 

    class: 'RV'

>> CLSout=class_defaults(CLS)

CLSout = 

    class: 'RV'
    names: {1x0 cell}
    sizes: [1x0 double]
    times: [1x0 double]
\endcode

The fields that are understood and accepted were filled.

\code
>> CLS.class='egauss'

CLS = 

    class: 'egauss'

>> CLSout=class_defaults(CLS)
??? Unexpected Standard exception from MEX file.
What() is:UIException: the compulsory Setting named
"mu" is missing. Check path "".
\endcode

In this case, empty class of type 'egauss' is not allowed, the fields named "mu" is compulsory. The next step would be to add define CLS.mu.


\section bdt_wrp_epdf Wrappers for pdfs

The follwing wrappers are provided:
 - \b epdf_mean returning mean value of any epdf function in <a href="annotated_bdm_epdf.html"> list </a>.
 \code 
 >> G.class='egamma';
 >> G.alpha = 3;
 >> G.beta = 4;
 >> epdf_mean(G) 

 ans =

    0.7500 
 \endcode
 - \b epdf_variance returning variance of any epdf function in <a href="annotated_bdm_epdf.html"> list </a>..
 \code
 >> epdf_variance(G)

 ans =

    0.1875
 \endcode
 - \b epdf_evallog_mat returns logarithm of the values in argument,
 - \b epdf_sample_mat sample given number of independent samples for this density,
 - \b epdf_marginal sample given number of independent samples for this density,
 - \b epdf_condition sample given number of independent samples for this density,
 - \b epdf_sample_mat sample given number of independent samples for this density,

List of arguments of each function can be obtained by running the function with no argument:
\code
>> epdf_mean
??? Error using ==> epdf_mean
Usage:
vec=pdf_mean(pdf_struct)
  pdf_struct = struct('class','pdf_offspring',...);  %
  description of pdf
output:
  vec mean value of given pdf.
\endcode

For up-to-date list of wrappers see files in <a href="files.html"> files.html</a>
 
 \section bdt_wrp_off Wrappers of offsprings
 
 When a new class defines its private function, its wrapper starts with the name of the class that defines it.
 An example is function \b enorm_bhattacharyya.m  which id defined only for normal distributed densities (enorm\<sqmat\>)

\section bdt_wrp_bm Wrappers for Bayesian Models (BMs)

Wrappers for BM correspond to the main functions of BM, that is:
 - \b bayes recursive update of posterior statistics by currently observed data and data in conditions, function \b bm_bayes
 - \b bayesweighted recursive update of posterior statistics by currently observed data and data in conditions, when data are generated from this class only with probability w, function \b bm_bayesweighted
 - \b epredictor returns unconditional predictor of the next data observation (if such density is available) \b bm_epredictor

Example:
\code
>> CLS.class='multiBM'                % Estimator of multinomial density
>> CLS.prior.beta = [1,2];            % Prior is Dirichlet with statistics beta

>> CLSapost=bm_bayes(CLS, [0.5 0.5])  % update posterior, using data [0.5, 0.5]
>> CLSapost.prior.beta

ans =

    1.5000    2.5000
\endcode 
 */