Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Create a MATLAB Notebook with Microsoft Word

Getting Started with MATLAB Notebooks

You can use the notebook function to open Microsoft® Word and record MATLAB® sessions to supplement class notes, textbooks, or technical reports. After executing the notebook function, you run MATLAB commands directly from Word itself. This Word document is known as a MATLAB Notebook. As an alternative, consider using the MATLAB publish function.

Using the notebook command, you create a Microsoft Word document. You then can type text, input cells (MATLAB commands), and output cells (results of MATLAB commands) directly into this document. You can format the input in the same manner as any Microsoft Word document. You can think of this document as a record of an interactive MATLAB session annotated with text, or as a document embedded with live MATLAB commands and output.

    Note   The notebook command is available only on Windows® systems that have Microsoft Word installed.

Creating or Opening a MATLAB Notebook

If you are running the notebook command for the first time since you installed a new version of MATLAB, follow the instructions in Configuring the MATLAB Notebook Software. Otherwise, you can create a new or open an existing notebook:

  • To open a new notebook, execute the notebook function in the MATLAB Command Window.

    The notebook command starts Microsoft Word on your system and creates a MATLAB Notebook, called Document1. If a dialog box appears asking you to enable or disable macros, choose to enable macros.

    Word adds the Notebook menu to the Word Add-Ins tab, as shown in the following figure.

    Microsoft product screen shot reprinted with permission from Microsoft Corporation.

  • To open an existing notebook, execute notebook file_name in the MATLAB Command Window, where file_name is the name of an existing MATLAB notebook.

Converting a Word Document to a MATLAB Notebook.  To convert a Microsoft Word document to a MATLAB Notebook, insert the document into a notebook file:

  1. Create a MATLAB Notebook.

  2. From the Insert tab, in the Text group, click the arrow next to Object.

  3. Select Text from File. The Insert File dialog box opens.

  4. Navigate and select the Word file that you want to convert in the Insert File dialog box.

Running Commands in a MATLAB Notebook

You enter MATLAB commands in a notebook the same way you enter text in any other Word document. For example, you can enter the following text in a Word document. The example uses text in Courier Font, but you can use any font:

Here is a sample MATLAB Notebook.

a = magic(3)

Execute a single command by pressing Crtl+Enter on the line containing the MATLAB command. Execute a series of MATLAB commands using these steps:

  1. Highlight the commands you want to execute.

  2. Click the Notebook drop-down list on the Add-Ins tab.

  3. Select Evaluate Cell.

MATLAB displays the results in the Word document below the original command or series of commands.

    Note   A good way to experiment with MATLAB Notebook is to open a sample notebook, Readme.doc. You can find this file in the matlabroot/notebook/pc folder.

Creating and Evaluating Cells in a MATLAB Notebook

Creating Input Cells

Input cells allow you to break up your code into manageable pieces and execute them independently. To define a MATLAB command in a Word document as an input cell:

  1. Type the command into the MATLAB Notebook as text. For example,

    This is a sample MATLAB Notebook.
    
    a = magic(3)
    
  2. Position the cursor anywhere in the command, and then select Define Input Cell from the Notebook drop-down list. If the command is embedded in a line of text, use the mouse to select it. The characters appear within cell markers ([ ]). Cell markers are bold, gray brackets. They differ from the brackets used to enclose matrices by their size and weight.

    [a = magic(3)]
    

Creating Autoinit Input Cells.  Autoinit cells are identical to input cells with additional characteristics:

  • Autoinit cells evaluate when MATLAB Notebook opens.

  • Commands in autoinit cells display in dark blue characters.

To create an autoinit cell, highlight the text, and then select Define AutoInit Cell from the Notebook drop-down list.

Creating Cell Groups.  You can collect several input cells into a single input cell, called a cell group. All the output from a cell group appears in a single output cell immediately after the group. Cell groups are useful when you need several MATLAB commands to execute in sequence. For instance, defining labels and tick marks in a plot requires multiple commands:

x = -pi:0.1:pi;
plot(x,cos(x))
title('Sample Plot')
xlabel('x')
ylabel('cos(x)')
set(gca,'XTick',-pi:pi:pi)
set(gca,'XTickLabel',{'-pi','0','pi'})

To create a cell group:

  1. Use the mouse to select the input cells that are to make up the group.

  2. Select Group Cells from the Notebook drop-down list.

A single pair of cell markers now surrounds the new cell group.

[x = -pi:0.1:pi;
plot(x,cos(x))
title('Sample Plot')
xlabel('x')
ylabel('cos(x)')
set(gca,'XTick',-pi:pi:pi)
set(gca,'XTickLabel',{'-pi','0','pi'})]

When working with cell groups, you should note several behaviors:

  • A cell group cannot contain output cells. If the selection includes output cells, they are deleted.

  • A cell group cannot contain text. If the selection includes text, the text appears after the cell group, unless it precedes the first input cell in the selection.

  • If you select part or all of an output cell, the cell group includes the respective input cell.

  • If the first line of a cell group is an autoinit cell, then the entire group is an autoinit cell.

Evaluating Input Cells

After you define a MATLAB command as an input cell, you can evaluate it in your MATLAB Notebook using these steps:

  1. Highlight or place your cursor in the input cell you want to evaluate.

  2. Select Evaluate Cell in the Notebook drop-down list, or press Ctrl+Enter.

    The notebook evaluates and displays the results in an output cell immediately following the input cell. If there is already an output cell, its contents update wherever the output cell appears in the notebook. For example:

    This is a sample MATLAB Notebook.
    
    [a = magic(3) ]
    
    [a =
         8     1     6
         3     5     7
         4     9     2  ]
    

To evaluate more than one MATLAB command contained in different, but contiguous input cells:

  1. Select a range of cells that includes the input cells you want to evaluate. You can include text that surrounds input cells in your selection.

  2. Select Evaluate Cell in the Notebook drop-down list or press Ctrl+Enter.

    Note   Text or numeric output always displays first, regardless of the order of the commands in the group.

When each input cell evaluates, new output cells appear or existing ones are replaced. Any error messages appear in red, by default.

Evaluating Cell Groups.  Evaluate a cell group the same way you evaluate an input cell (because a cell group is an input cell):

  1. Position the cursor anywhere in the cell or in its output cell.

  2. Select Evaluate Cell in the Notebook drop-down list or press Ctrl+Enter.

When MATLAB evaluates a cell group, the output for all commands in the group appears in a single output cell. By default, the output cell appears immediately after the cell group the first time the cell group is evaluated. If you evaluate a cell group that has an existing output cell, the results appear in that output cell, wherever it is located in the MATLAB Notebook.

Using a Loop to Evaluate Input Cells Repeatedly.  MATLAB allows you to evaluate a sequence of MATLAB commands repeatedly, using these steps:

  1. Highlight the input cells, including any text or output cells located between them.

  2. Select Evaluate Loop in the Notebook drop-down list. The Evaluate Loop dialog box appears.

    Microsoft product screen shot reprinted with permission from Microsoft Corporation.

  3. Enter the number of times you want to evaluate the selected commands in the Stop After field, then click Start. The button changes to Stop. Command evaluation begins, and the number of completed iterations appears in the Loop Count field.

You can increase or decrease the delay at the end of each iteration by clicking Slower or Faster.

Evaluating an Entire MATLAB Notebook.  To evaluate an entire MATLAB Notebook, select Evaluate MATLAB Notebook in the Notebook drop-down list. Evaluation begins at the top of the notebook, regardless of the cursor position and includes each input cell in the file. As it evaluates the file, Word inserts new output cells or replaces existing output cells.

If you want to stop evaluation if an error occurs, set the Stop evaluating on error check box on the Notebook Options dialog box.

Undefining Cells

You can always convert cells back to normal text. To convert a cell (input, output, or a cell group) to text:

  1. Highlight the input cell or position the cursor in the input cell.

  2. Select Undefine Cells from the Notebook drop-down list.

When the cell converts to text, the cell contents reformat according to the Microsoft Word Normal style.

    Note  

    • Converting input cells to text also converts their output cells.

    • If the output cell is graphical, the cell markers disappear and the graphic dissociates from its input cell, but the contents of the graphic remain.

Defining Calc Zones

You can partition a MATLAB Notebook into self-contained sections, called calc zones. A calc zone is a contiguous block of text, input cells, and output cells. Section breaks appear before and after the section, defining the calc zone. The section break indicators include bold, gray brackets to distinguish them from standard Word section breaks.

You can use calc zones to prepare problem sets, making each problem a calc zone that you can test separately. A notebook can contain any number of calc zones.

    Note   Calc zones do not affect the scope of the variables in a notebook. Variables defined in one calc zone are accessible to all calc zones.

Creating a Calc Zone.  

  1. Select the input cells and text you want to include in the calc zone.

  2. Select Define Calc Zone under the Notebook drop-down list.

A calc zone cannot begin or end in a cell.

Evaluating a Calc Zone.  

  1. Position the cursor anywhere in the calc zone.

  2. Select Evaluate Calc Zone from the Notebook drop-down list or press Alt+Enter.

By default, the output cell appears immediately after the calc zone the first time you evaluate the calc zone. If you evaluate a calc zone with an existing output cell, the results appear in the output cell wherever it is located in the MATLAB Notebook.

Formatting a MATLAB Notebook

Modifying Styles in the MATLAB Notebook Template

You can control the appearance of the text in your MATLAB Notebook by modifying the predefined styles in the notebook template, m-book.dot. These styles control the appearance of text and cells.

This table describes MATLAB Notebook default styles. For general information about using styles in Microsoft Word documents, see the Microsoft Word documentation.

Style

Font

Size

Weight

Color

Normal

Times New Roman®

10 points

N/A

Black

AutoInit

Courier New

10 points

Bold

Dark blue

Error

Courier New

10 points

Bold

Red

Input

Courier New

10 points

Bold

Dark green

Output

Courier New

10 points

N/A

Blue

When you change a style, Word applies the change to all characters in the notebook that use that style and gives you the option to change the template. Be cautious about changing the template. If you choose to apply the changes to the template, you affect all new notebooks that you create using the template. See the Word documentation for more information.

Controlling the Format of Numeric Output

To change how numeric output displays, select Notebook Options from the Notebook drop-down list. The Notebook Options dialog box opens, containing the Numeric format pane.

Microsoft product screen shot reprinted with permission from Microsoft Corporation.

You can select a format from the Format list. Format choices correspond to the same options available with the MATLAB format command

The Loose and Compact settings control whether a blank line appears between the input and output cells. To suppress this blank line select Compact.

Controlling Graphic Output

MATLAB allows you to embed graphics, suppress graphic output and adjust the graphic size.

By default, MATLAB embeds graphic output in a Notebook. To display graphic output in a separate figure window, click Notebook Options from the Notebook drop-down list. The Notebook Options dialog box opens, containing the Figure options pane.

Microsoft product screen shot reprinted with permission from Microsoft Corporation.

From this pane, you can choose whether to embed figures in the MATLAB Notebook. You can adjust the height and width of the figure in inches, centimeters, or points.

    Note   Embedded figures do not include Handle Graphics® objects generated by the uicontrol and uimenu functions.

To prevent an input cell from producing a figure, select Toggle Graph Output for Cell from the Notebook drop-down list. The string (no graph) appears after the input cell and the input cell does not produce a graph if evaluated. To undo the figure suppression, select Toggle Graph Output for Cell again or delete the text (no graph).

    Note   Toggle Graph Output for Cell overrides the Embed figures in MATLAB Notebook option, if that option is set.

Tips for Using MATLAB Notebooks

Protecting the Integrity of Your Workspace in MATLAB Notebooks

If you work on more than one MATLAB Notebook in a single word-processing session, notice that

  • Each notebook uses the same MATLAB executable.

  • All notebooks share the same workspace. If you use the same variable names in more than one notebook, data used in one notebook can be affected by another notebook.

    Note:   You can protect the integrity of your workspace by specifying the clear command as the first autoinit cell in the notebook.

Ensuring Data Consistency in MATLAB Notebooks

You can think of a MATLAB Notebook as a sequential record of a MATLAB session. When executed in sequential order, the notebook accurately reflects the relationships among the commands.

If, however, you edit input cells or output cells as you refine your notebook, it can contain inconsistent data. Input cells that depend on the contents or the results of other cells do not automatically recalculate when you make a change.

When working in a notebook, consider selecting Evaluate MATLAB Notebook periodically to ensure that your notebook data is consistent. You can also use calc zones to isolate related commands in a section of the notebook, and then use Evaluate Calc Zone to execute only those input cells contained in the calc zone.

Debugging and MATLAB Notebooks

Do not use debugging functions or the Editor while evaluating cells within a MATLAB Notebook. Instead, use this procedure:

  1. Complete debugging files from within MATLAB.

  2. Clear all the breakpoints.

  3. Access the file using notebook.

If you debug while evaluating a notebook, you can experience problems with MATLAB.

Configuring the MATLAB Notebook Software

After you install MATLAB Notebook software, but before you begin using it, specify that Word can use macros, and then configure the notebook command. The notebook function installs as part of the MATLAB installation process on Microsoft Windows platforms. For more information, see the MATLAB installation documentation.

    Note:   Word explicitly asks whether you want to enable macros. If it does not, refer to the Word help. You can search topics relating to macros, such as "enable or disable macros".

To configure MATLAB Notebook software, type the following in the MATLAB Command Window:

notebook -setup

MATLAB configures the Notebook software and issues these messages in the Command Window:

Welcome to the utility for setting up the MATLAB Notebook
for interfacing MATLAB to Microsoft Word

Setup complete

When MATLAB configures the software, it:

  1. Accesses the Microsoft Windows system registry to locate Microsoft Word and the Word templates folder. It also identifies the version of Word.

  2. Copies the m-book.dot template to the Word templates folder.

The MATLAB Notebook software supports Word versions 2002, 2003, 2007, and 2010.

After you configure the software, typing notebook in the MATLAB Command Window starts Microsoft Word and creates a new MATLAB Notebook.

If you suspect a problem with the current configuration, you can explicitly reconfigure the software by typing:

notebook -setup

More About

Was this topic helpful?