bdmtoolbox: Use Case #2: Matlab wrappers for BDM functions

Use Case #2: Matlab wrappers for BDM functions

A wrapper is a mex file that does the following:

  1. reads its arguments from Matlab structures and translates them into C++ structures
  2. calls the corresponding function in C++,
  3. 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: <class>_<function>.m

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

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

Convenience wrappers

A useful wrapper is called 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:

>> CLS.class='RV'
CLS =
    class: 'RV'
>> CLSout=class_defaults(CLS)
CLSout =
    class: 'RV'
    names: {1x0 cell}
    sizes: [1x0 double]
    times: [1x0 double]

The fields that are understood and accepted were filled.

>> 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 "".

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.

Wrappers for pdfs

The follwing wrappers are provided:

  • epdf_mean returning mean value of any epdf function in list .
     >> G.class='egamma';
     >> G.alpha = 3;
     >> G.beta = 4;
     >> epdf_mean(G)
     ans =
        0.7500
    
  • epdf_variance returning variance of any epdf function in list ..
     >> epdf_variance(G)
     ans =
        0.1875
    
  • epdf_evallog_mat returns logarithm of the values in argument,
  • epdf_sample_mat sample given number of independent samples for this density,
  • epdf_marginal sample given number of independent samples for this density,
  • epdf_condition sample given number of independent samples for this density,
  • 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:

>> 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.

For up-to-date list of wrappers see files in files.html

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 enorm_bhattacharyya.m which id defined only for normal distributed densities (enorm<sqmat>)

Wrappers for Bayesian Models (BMs)

Wrappers for BM correspond to the main functions of BM, that is:

  • bayes recursive update of posterior statistics by currently observed data and data in conditions, function bm_bayes
  • 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 bm_bayesweighted
  • epredictor returns unconditional predictor of the next data observation (if such density is available) bm_epredictor

Example:

>> 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

Generated on Fri Aug 27 16:55:20 2010 for bdmtoolbox by  doxygen 1.6.0