[1044] | 1 | /*! |
---|
| 2 | \page bdt_wrappers Elementary functions operating on descriptive matlab structures |
---|
| 3 | |
---|
| 4 | A wrapper is a mex file that does the following: |
---|
| 5 | -# reads its arguments from Matlab structures and translates them into C++ structures |
---|
| 6 | -# calls the corresponding function in C++, |
---|
| 7 | -# converts the results into Matlab structures and passes them to the output |
---|
| 8 | |
---|
| 9 | The use of these functions is inefficient, however, it is very usefull for: |
---|
| 10 | - operations on parts of the experiment configurations for scenarios, see example in \ref some_ref |
---|
| 11 | - insight into the results, e.g. mean values of non-standard densities |
---|
| 12 | - algorithms written in Matlab using these functions can be trivially re-written into C++ |
---|
| 13 | |
---|
| 14 | |
---|
| 15 | General notation of wrappers is: <b> \<class\>_\<function\>.m </b> |
---|
| 16 | |
---|
| 17 | For example, function \b epdf_mean.m represents function \b mean of class \b epdf and any it its offsprings. |
---|
| 18 | |
---|
| 19 | For full list of available wrappers see content of directory /bdmtoolbox/mex |
---|
| 20 | |
---|
| 21 | \section bdt_wr_conv Convenience wrappers |
---|
| 22 | |
---|
| 23 | 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. |
---|
| 24 | |
---|
| 25 | This is useful for: |
---|
| 26 | - checking if the fields are correctly named: fields of input structure that are not in the output are not understood |
---|
| 27 | - seeing what defaults the BDM assigns to fields that are optional |
---|
| 28 | |
---|
| 29 | Example: |
---|
| 30 | \code |
---|
| 31 | >> CLS.class='RV' |
---|
| 32 | |
---|
| 33 | CLS = |
---|
| 34 | |
---|
| 35 | class: 'RV' |
---|
| 36 | |
---|
| 37 | >> CLSout=class_defaults(CLS) |
---|
| 38 | |
---|
| 39 | CLSout = |
---|
| 40 | |
---|
| 41 | class: 'RV' |
---|
| 42 | names: {1x0 cell} |
---|
| 43 | sizes: [1x0 double] |
---|
| 44 | times: [1x0 double] |
---|
| 45 | \endcode |
---|
| 46 | |
---|
| 47 | The fields that are understood and accepted were filled. |
---|
| 48 | |
---|
| 49 | \code |
---|
| 50 | >> CLS.class='egauss' |
---|
| 51 | |
---|
| 52 | CLS = |
---|
| 53 | |
---|
| 54 | class: 'egauss' |
---|
| 55 | |
---|
| 56 | >> CLSout=class_defaults(CLS) |
---|
| 57 | ??? Unexpected Standard exception from MEX file. |
---|
| 58 | What() is:UIException: the compulsory Setting named |
---|
| 59 | "mu" is missing. Check path "". |
---|
| 60 | \endcode |
---|
| 61 | |
---|
| 62 | 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. |
---|
| 63 | |
---|
| 64 | |
---|
| 65 | \section bdt_wrp_epdf Wrappers for pdfs |
---|
| 66 | |
---|
| 67 | The follwing wrappers are provided: |
---|
| 68 | - \b epdf_mean returning mean value of any epdf function in \ref annotated_epdf. |
---|
| 69 | \code |
---|
| 70 | >> G.class='egamma'; |
---|
| 71 | >> G.alpha = 3; |
---|
| 72 | >> G.beta = 4; |
---|
| 73 | >> epdf_mean(G) |
---|
| 74 | |
---|
| 75 | ans = |
---|
| 76 | |
---|
| 77 | 0.7500 |
---|
| 78 | \endcode |
---|
| 79 | - \b epdf_variance returning variance of any epdf function in \ref annotated_epdf. |
---|
| 80 | \code |
---|
| 81 | >> epdf_variance(G) |
---|
| 82 | |
---|
| 83 | ans = |
---|
| 84 | |
---|
| 85 | 0.1875 |
---|
| 86 | \endcode |
---|
| 87 | - \b epdf_evallog_mat returns logarithm of the values in argument, |
---|
| 88 | - \b epdf_sample_mat sample given number of independent samples for this density, |
---|
| 89 | - \b epdf_marginal sample given number of independent samples for this density, |
---|
| 90 | - \b epdf_condition sample given number of independent samples for this density, |
---|
| 91 | - \b epdf_sample_mat sample given number of independent samples for this density, |
---|
| 92 | |
---|
| 93 | List of arguments of each function can be obtained by running the function with no argument: |
---|
| 94 | \code |
---|
| 95 | >> epdf_mean |
---|
| 96 | ??? Error using ==> epdf_mean |
---|
| 97 | Usage: |
---|
| 98 | vec=pdf_mean(pdf_struct) |
---|
| 99 | pdf_struct = struct('class','pdf_offspring',...); % |
---|
| 100 | description of pdf |
---|
| 101 | output: |
---|
| 102 | vec mean value of given pdf. |
---|
| 103 | \endcode |
---|
| 104 | |
---|
| 105 | For up-to-date list of wrappers see files in \ref files.html |
---|
| 106 | |
---|
| 107 | \section bdt_wrp_off Wrappers of offsprings |
---|
| 108 | |
---|
| 109 | When a new class defines its private function, its wrapper starts with the name of the class that defines it. |
---|
| 110 | An example is function \b enorm_bhattacharyya.m which id defined only for normal distributed densities (enorm\<sqmat\>) |
---|
| 111 | |
---|
| 112 | \section bdt_wrp_bm Wrappers for Bayesian Models (BMs) |
---|
| 113 | |
---|
| 114 | Wrappers for BM correspond to the main functions of BM, that is: |
---|
| 115 | - \b bayes recursive update of posterior statistics by currently observed data and data in conditions, function \b bm_bayes |
---|
| 116 | - \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 |
---|
| 117 | - \b epredictor returns unconditional predictor of the next data observation (if such density is available) \b bm_epredictor |
---|
| 118 | |
---|
| 119 | Example: |
---|
| 120 | \code |
---|
| 121 | >> CLS.class='multiBM' % Estimator of multinomial density |
---|
| 122 | >> CLS.prior.beta = [1,2]; % Prior is Dirichlet with statistics beta |
---|
| 123 | |
---|
| 124 | >> CLSapost=bm_bayes(CLS, [0.5 0.5]) % update posterior, using data [0.5, 0.5] |
---|
| 125 | >> CLSapost.prior.beta |
---|
| 126 | |
---|
| 127 | ans = |
---|
| 128 | |
---|
| 129 | 1.5000 2.5000 |
---|
| 130 | \endcode |
---|
| 131 | */ |
---|