3.7 Interface to MATLAB®
MATLAB is a proprietary software platform designed for solving engineering and scientific problems. Although it provides some toolboxes that facilitate statistical analysis, in general, and econometric modeling, in particular (mostly time-series models), MATLAB is primarily known for its extensive and easy to use language. This is largely a matrix-based language, specifically designed for solving computational problems.
BayES’ matlab() function provides a convenient interface to MATLAB, which allows the user to:
- pass BayES matrices and datasets as input to MATLAB
- request MATLAB to execute code written in its native language
- retrieve output from MATLAB and store it in BayES matrix items; all data to be returned from MATLAB are stored inside a BayES structure item
The general syntax of the matlab() function is the following:9
, "data"=<list of matrices/datasets to pass to MATLAB>
, "return"=<list of matrices to retrieve from MATLAB>
, "options"=<string of options when starting MATLAB>
);
where:
- <structure name> is a BayES id value which will be associated with the BayES structure that the matlab() function returns. This structure will contain any MATLAB matrices that the user requests to be returned to BayES (using the "return" option) after execution of the MATLAB .m file completes.
- <MATLAB .m file> is a string pointing to the file which contains the code (written in MATLAB’s language) that MATLAB 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 matlab() function.
- "data" specifies the data that will be passed as input to MATLAB. These can be either BayES datasets or matrices. <list of matrices/datasets to pass to MATLAB> is a list of the id values of matrices or datasets (comma-separated names inside curly brackets), as they appear in the MATLAB .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 MATLAB then it becomes available in MATLAB as a MATLAB 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 MATLAB.
- "return" specifies the MATLAB matrices that will be returned to BayES when execution of the MATLAB .m file completes. <list of matrices to retrieve from MATLAB> 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 MATLAB, as they appear in the MATLAB .m file. Any MATLAB 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 MATLAB is not supported.
- "options" specifies the MATLAB options to be passed to the command-line argument when calling
MATLAB. All these options should be provided as a single string. The default value
is:
"nojvm nodesktop nodisplay nosplash minimize wait r"
and has the following effects:- nojvm: starts MATLAB without the JVM software. Features that require Java software (such as the desktop tools and graphics) are not supported.
- nodesktop: runs the JVM software without opening the MATLAB desktop
- nodisplay: starts the JVM software without starting the MATLAB desktop
- nosplash: does not display the splash screen during startup
- minimize: minimizes the MATLAB window
- wait: blocks the script from continuing until the results from MATLAB are generated.
- r: executes the MATLAB statement, specified as a string or as the name of a MATLAB script or function. This should always be used as the last option because BayES appends to this option the location of the provided MATLAB .m file.
As the matlab() function executes with the above options, MATLAB 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 MATLAB and the commands contained in the MATLAB .m file provided to matlab().
The sample script file in "$BayESHOME/Samples/5Interfaces/matlab" contains an example of using the matlab() function, along with a simple MATLAB .m file. The MATLAB interface is also accessible from the BayES main menu via Interfaces → MATLAB®.
9Arguments inside square brackets are optional. Optional arguments passed to the matlab() function can be provided in any order, but always after the mandatory argument (MATLAB .m file). Optional arguments always come in pairs (eg. "data"={myDataset,myMatrix}).
