Data Loading Application Programming Interface
Data Loading API Specification
You can use the data loading API (application programming interface) to write
your own data loading function, plug these functions into the toolbox, and
subsequently use data loaded by these functions within the toolbox. To allow
this, there are several stages that need to be followed as described below.
For an example, see xregReadConcerto.m (in the
mbctools directory).
Data Function Prototype
A function to successfully load data has the following prototype:
[OK, msg, out] = dataLoadingFcn(filename, protoOut)
Input Arguments
filename is the full path to the file to be loaded.
protoOut is an empty structure with the fields expected in
the return argument out. This allows the data loading API
to be easily extended without the need for data loading functions to change
when the toolbox changes.
Output Arguments
The first return argument, OK, allows the function to
signal that it has successfully loaded the data file. A value of 1 signals
success, and 0 failure. If the function fails, it can return a message,
msg, to indicate the reason for the failure. This
message is displayed in a warning dialog box if the function fails. If the
function is successful, the return argument out contains
the data necessary for the toolbox.
out.varNames is a cell array of strings that hold the names
of the variables in the data (1 x n or n x
1).
out.varUnits is a cell array of strings that hold the units
associated with the variables in varNames (1 x
n or n x 1). This array can be empty,
in which case no units are defined.
out.data is an array that holds the values of the variables
(m x n).
out.comment is an optional string holding comment
information about the data.
Data Function Check In
Once you have written the function, you need to check it into the toolbox,
using the mbccheckindataloadingfcn function. This
function has the following prototype:
OK= mbccheckindataloadingfcn(fun, filterSpec, fileType, filename)
fun is a string that is the function to call to load the
data. This function must be on the MATLAB® path.
filterSpec is a 1 x 2 element cell array
that contains the extensions that this function loads and the descriptions
of those files. This cell array is used in the uigetfile
function, for example, {'*.m;*.fig;*.mat;', 'All MATLAB
Files'} or {'*.m', 'M-files (*.m)'}.
MBC attempts to decide automatically which sort of file is loaded, based on
the extension. In the case of duplicate extensions, the first in the list is
selected; however, it is always possible to override the automatic selection
with a user selection. You will see a warning message if there is any
ambiguity.
fileType is a string that describes the file type, for
example, 'MATLAB file' or 'Excel
file'.
