3.8 Interface to GNU Octave
GNU Octave is free software designed as a matrix programming language, which is largely compatible with MATLAB. Later versions of GNU Octave feature a simple GUI, but the vast majority of functions can still be accessed only using code. GNU Octave is intended for numerical computations, in general, and graphics, but it can be also used for performing Bayesian inference, especially when using some of its statistics-oriented loadable modules.
BayES’ octave() function provides a convenient interface to GNU Octave, which allows the user to:
- pass BayES matrices and datasets as input to GNU Octave
- request GNU Octave to execute code written in its native language
- retrieve output from GNU Octave and store it in BayES matrix items; all data to be returned from GNU Octave are stored inside a BayES structure item
The general syntax of the octave() function is the following:10
, "data"=<list of matrices/datasets to pass to GNU Octave>
, "return"=<list of matrices to retrieve from GNU Octave>
);
where:
- <structure name> is a BayES id value which will be associated with the BayES structure that the octave() function returns. This structure will contain any GNU Octave matrices that the user requests to be returned to BayES (using the "return" option) after execution of the GNU Octave .m file completes.
- <GNU Octave .m file> is a string pointing to the file which contains the code (written in GNU Octave’s language) that GNU Octave will be requested to execute. If this file is not in the current directory then the file name must be prepended by the path to the file, either in absolute terms (eg. "C:/MyFiles/myFile.m") or relative to the current working directory (eg. "../myFile.m"). This is the only mandatory argument of the octave() function.
- "data" specifies the data that will be passed as input to GNU Octave. These can be either BayES datasets or matrices. <list of matrices/datasets to pass to GNU Octave> is a list of the id values of matrices or datasets (comma-separated names inside curly brackets), as they appear in the GNU Octave .m file. These matrices or datasets must be defined in the current workspace. When either a BayES matrix or dataset is passed as input to GNU Octave then it becomes available as a GNU Octave matrix. That is, BayES datasets are stripped of their additional information (most importantly, variable names and dataset structure) and only the raw data are passed to GNU Octave.
- "return" specifies the GNU Octave matrices that will be returned to BayES when execution of the GNU Octave .m file completes. <list of matrices to retrieve from GNU Octave> is a list of id values (comma-separated id values inside curly brackets) that specify the names of the matrices that should be returned from GNU Octave, as they appear in the GNU Octave .m file. Any GNU Octave matrix that is returned will be stored in BayES as a matrix and all returned matrices are grouped together into a BayES structure. Passing other data types (structures, cells, strings, etc.) between BayES and GNU Octave is not supported.
As the octave() function executes, GNU Octave attempts to print output on the system’s command console. BayES grabs this output and redirects it to the BayES main console in real time. This output is entirely determined by GNU Octave and the commands contained in the GNU Octave .m file provided to octave().
The sample script file in "$BayESHOME/Samples/5Interfaces/octave" contains an example of using the octave() function, along with a simple GNU Octave .m file. The GNU Octave interface is also accessible from the BayES main menu via Interfaces → GNU Octave.
10Arguments inside square brackets are optional. Optional arguments passed to the octave() function can be provided in any order, but always after the mandatory argument (GNU Octave .m file). Optional arguments always come in pairs (eg. "data"={myDataset,myMatrix}).
