Using the MATLAB window

Knowledge Base Data Analysis
1

With MWClient’s MATLAB window, you can monitor and analyze the results of your experiment as it runs, using a user-defined MATLAB function. To help you understand and make use of this powerful feature, we’ll first walk through an example and then explain how it works.

Running the example

The MWorks experiment matlab_window_demo.mwel and corresponding MATLAB function (matlab_window_demo.m) demonstrate how to use MWClient’s MATLAB window. To run the demo, follow these steps:

  1. If you haven’t already done so, follow the MATLAB setup instructions.

  2. Open MWClient and connect to MWServer.

  3. Load the experiment (matlab_window_demo.mwel).

  4. Open the MATLAB window: Click on the magnifying glass icon in the lower right of the main MWClient window, then select “MATLAB Interface Window” from the list of options.

  5. In the MATLAB window’s “Synchronization Variable” field, enter “sync”. (Be sure to press Return after typing “sync”; otherwise, the setting won’t take.)

  6. Click “Select .m file” and select the MATLAB file (matlab_window_demo.m).

  7. Make sure that “Process 0 events” and “Collecting Data” are both checked.

  8. Click the “Events” button. In the variable-selection window that pops up, make sure that “rand_var” and “sync” are checked.

  9. Run the experiment. MATLAB should launch and display a histogram containing the values of “rand_var”. The MATLAB function is written to accumulate values from all runs, so if you run the experiment again, the new values will be added to the histogram. The function reports how many values are in the histogram, so if you run the experiment three times, you should see the following under “Matlab output”:

     Drawing histogram (10 values)
 Drawing histogram (20 values)
 Drawing histogram (30 values)

Understanding the example

Now that you’ve seen the MATLAB window in action, here’s how it works:

The basic function of the MATLAB window is to allow you to collect the values of variables of interest and send them to a MATLAB function for processing. You select the variables you want to monitor by clicking the “Events” button and checking the names of the variables. (In the example, we monitor only one variable, “rand_var”, but you can monitor as many variables as you like.)

The synchronization variable allows you to control when variable values are collected. (It’s typically called “sync”, but you can name it whatever you want.) In the experiment, sync is initially set to 0. When you want to start collecting values, you set sync to 1. From that point on, the MATLAB window will record any changes to the variables you’re monitoring. When you’re finished collecting values and want to send the data to your MATLAB function for processing, set sync to 0.

The MATLAB function takes two arguments. The first (called “data” in the example) is a structure that contains both the event codec (which maps variable names to MWorks event codes) and the list of collected events. Every time a variable changes value, an MWorks event is generated, which contains both the time of the change and the new value. The event list passed to your MATLAB function contains all the variable-change events for your monitored variables. The example script demonstrates how to use the codec and event list to extract the values for the variables you’re interested in.

The second argument to your MATLAB function (called “values” in the example) provides a way to pass data from one invocation of the function to the next. The first time your function is invoked, this parameter is omitted. When the function returns, the return value is stored. The next time the function is invoked, the stored return value is passed back to the function as its second argument. The example function uses this mechanism to pass the cumulative histogram data from one invocation to the next.

Don’t worry if this all sounds a bit confusing. Once you’ve tried it a few times, you’ll find that it’s pretty easy to use.

Providing a cleanup function

In addition to your primary MATLAB function, you can also provide a “cleanup” function. While the primary function typically is invoked many times while your experiment runs, the cleanup function is called only once, when the experiment closes. This is useful for finalizing any resources used by the primary function (e.g. closing open files).

Extending the preceding example, if a file named matlab_window_demo_cleanup.m exists in the same directory as matlab_window_demo.m, and the MATLAB window executes function matlab_window_demo at least once, then function matlab_window_demo_cleanup will be executed when the current experiment is unloaded. It will be called with the last value returned by matlab_window_demo as its only argument.