Maintain Interactive MATLAB Report

This example shows how a basic report was created using the Report Explorer. This report explains and illustrates magic squares – matrices whose columns, rows, and diagonals each add up to the same number (see the magic function reference in the MATLAB^® documentation).

To create this report, you perform these main tasks:

• Create a Report Setup File

• Add Report Content Using Components

Note

You do not need to know the MATLAB software to use this example. However, knowledge of MATLAB is helpful for understanding the MATLAB code that executes during report generation.

This example includes separate sections for different kinds of report creation and generation tasks. Each section builds on the previous sections. However, if you want to work through a later section without having done the previous sections, you can view the completed report setup file: Magic Squares Report.

Create a Report Setup File

To set up the magic squares report, first create a setup file to store the setup. Then add MATLAB objects, called components, to the setup to specify the report content.

To create the report setup file:

1. Start a MATLAB software session.

2. Open the Report Explorer. From the MATLAB Toolstrip, in the Apps tab, in the Database Connectivity and Reporting section, click Report Generator.

3. Select File > New to create a report setup file. The new report setup has the default name Unnamed.rpt.

4. In the Properties pane on the right:

   1. To save the report in the current working folder, select Present working directory from the Directory list.

   2. Set File format to HTML (from template) to generate the report output as HTML. Using the (from template) option creates the report table of contents in a format that you can expand and collapse.

   3. In the Report description text box, replace the existing text with the following text.

      This report creates a series of magic squares
      and displays them as images.
      
      A magic square is a matrix in which the 
      columns, rows, and diagonal all add up to the 
      same number.

   Note

   When you change a Properties pane field, its background color changes. This indicates that there are unapplied changes to that field. As soon as you perform any action with another component, MATLAB Report Generator™ applies the changes, and the background color becomes white again.

5. Save your report. Select File > Save As and name your report setup file magic_squares.rpt.

   The new file name appears in the Outline pane.

   

To create the content for the report, see Add Report Content Using Components.

Add Report Content Using Components

• Report Components

• Specify Report Variables

• Create a Title Page

• Add a Chapter

• Add Introductory Text to the First Chapter

• Add an Image

• Create the Magic Squares and Their Images

• Create a For Loop

• Add a Chapter for Each Square

• Determine the Matrix Size

• Insert the Magic Square Size into the Report

• Create the Magic Square

• Add Display Logic

• Display the Magic Square

Report Components

Report components specify the information to include in the report. The following figure shows a sample page from the report that you create in this example, highlighting components that you use to produce the report.

Specify Report Variables

The magic squares report uses variables defined in the MATLAB workspace to specify the number and sizes of squares to display and whether to display the variables as tables of numbers or images of color-coded squares:

• The magicSizeVector variable specifies an array of magic square sizes

• largestDisplayedArray variable specifies the size of the largest magic square to be displayed as an array of numbers

You could require that a user create these variables in the MATLAB workspace before running the report. However, a better solution is to let the report create the variables, using the Evaluate MATLAB Expression component.

To use the Evaluate MATLAB Expression component to define the report variables:

1. In the Outline pane on the left, select the root component of the report setup.

   

2. In the Library pane in the middle, under MATLAB, select Evaluate MATLAB Expression.

   

3. In the Properties pane on the right, click the icon next to Add component to current report to insert the Evaluate MATLAB Expression component into the report.

   You can edit the component information in the Properties pane only after you add the component to the report.

   In the Outline pane, the Eval component appears under the magic_squares report.

   

   The icon in the upper left corner of the Eval component indicates that this component cannot have child components. By default, any components you add with the Eval component selected are siblings to this component.

   The options for the Evaluate MATLAB Expression component appear in the Properties pane.

   

4. To exclude the MATLAB code details and its output in this report, clear the Insert MATLAB expression in report and Display command window output in report check boxes.

5. In the Expression to evaluate in the base workspace text box, replace the existing text with the following MATLAB code.

   Tip

   Copy and paste this text from the HTML documentation into the Report Explorer.

   %This MATLAB code sets up two variables
   %that define how the report runs.
   %magicSizeVector is a list of MxM
   %Magic Square sizes to insert into
   %the report. Note that magic
   %squares cannot be 2x2.
   
   magicSizeVector=[4 8 16 32];
   
   %largestDisplayedArray sets the
   %limit of array size that will be
   %inserted into the report with the
   %Insert Variable component.
   
   largestDisplayedArray=15;

6. In the Evaluate this expression if there is an error text box, replace the existing text with the following text.

   disp(['Error during eval: ', evalException.message])

   This causes an error to display if the MATLAB code fails.

   Tip

   To execute these commands immediately, in the top right corner of the Report Explorer, click the Eval Now button. This confirms that your commands are correct, to reduce the chances of report generation problems.

7. Save the report.

Create a Title Page

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

To create a title page for the report, use the Title Page component.

1. In the Outline pane on the left, select the Eval component.

   

2. In the Options pane in the middle, under Formatting, add the Title Page component to the report.

   Because the Eval component icon indicates that this component cannot have children, the Title Page component is a sibling of the Eval component. Likewise, the Title Page component cannot have child components.

   

   Note

   To use a Title Page component, your report needs a Chapter component. You have not yet added a Chapter component, so the Properties pane displays a message indicating that a chapter is required for the Title Page component to appear correctly. Because later in this example you add Chapter components to this report, you can ignore that message.

3. In the Properties pane on the right, use the Main tab to enter the title page information.

   1. In the Title text box, enter Magic Squares.

   2. In the Subtitle text box, enter Columns, Rows, Diagonals: Everyone is Equal.

   3. Under Options, choose Custom author from the list.

      

   4. In the field to the right of the Custom author field, enter Albrecht Durer.

      Albrecht Dürer created an etching that contains a magic square. Your final report includes an image of that etching.

   5. Select the Include copyright holder and year check box.

   6. In the next text box, enter The MathWorks.

   7. In the second text box, enter 1988.

      

4. In the Properties pane, in the Abstract tab, enter:

   An introduction to Magic Squares and their meaning.

   

5. Save the report.

Add a Chapter

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

Add a chapter to the report by using the Chapter/Subsection component.

1. In the Outline pane on the left, select the Title Page component.

   

2. In the Library pane in the middle, under Formatting, add a Chapter/Subsection component.

   

   The Eval, Title Page, and Chapter components are all child components of the report's top level and are siblings of one another.

3. For the custom chapter title, in the Properties pane on the right, enter Magic Squares Explained.

   The Outline pane displays the chapter title.

   

4. Save the report.

Add Introductory Text to the First Chapter

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

Include introductory text in the first chapter by adding the Paragraph and Text components.

1. In the Outline pane on the left, select the Chapter component.

2. In the Library pane in the middle, under Formatting , add a Paragraph component.

   In the Outline pane, the new component appears as a child of the Chapter component.

   

3. By default, the Paragraph component inherits its text from its child components. Add two Text components.

   Note

   The Text component must have a Paragraph component as its parent.

4. In the Library pane, under the Formatting category, add two Text components to the outline.

   

5. In the Outline pane, select the first Text component.

6. In the Text to include in report text box, enter %<help('magic')>.

   The % sign and angle brackets <> indicate to the MATLAB Report Generator software that this is MATLAB code to evaluate. The command help('magic') displays information about the MATLAB magic function.

7. In the Outline pane, select the second Text component.

8. In the Text to include in report text box, enter this text.

   The German artist Albrecht Durer (1471-1528) 
   created many woodcuts and prints with religious
   and scientific symbolism.  One of his most famous
   works, Melancholia I, explores the depressed state 
   of mind that opposes inspiration and expression.
   Renaissance astrologers believed that the Jupiter magic
   square (shown in the upper right portion of the image)
   could aid in the cure of melancholy. The engraving's 
   date (1514) can be found in the lower row of numbers
   in the square.  

9. Save the report.

The contents of the first chapter are now complete.

Add an Image

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

Create an image of Albrecht Dürer and include it in the report.

1. In the Outline pane on the left, select the Chapter component.

2. In the Library pane in the middle, under MATLAB, add an Evaluate MATLAB Expression component.

   

3. Move the Eval component under the Paragraph component so that the image follows the introductory text. To move it, on the toolbar, click the down arrow.

   

4. With the Eval component selected, set these properties:

   1. Clear the Insert MATLAB expression in report and Display command window output in report check boxes. You do not want to include the code or its output in the report.

   2. In the Expression to evaluate in the base workspace text box, replace the existing text with this MATLAB code.

      %This loads a self-portrait of Albrecht
      %Durer, a German artist. There is a
      %magic square in the upper right corner
      %of the image.
      
      durerData=load('durer.mat','-mat');
      figure('Units','Pixels',...
      'Position',[200 200 size(durerData.X,2)*.5 size(durerData.X,1)*.5 ]);
      
      image(durerData.X);
      colormap(durerData.map);
      axis('image');
      set(gca,...
          'Xtick',[],...
          'Ytick',[],...
          'Units','normal',...
          'Position',[0 0 1 1]);
      
      clear durerData

      This MATLAB code displays the Dürer etching in a MATLAB figure window.

   3. In the Evaluate this expression if there is an error text box, replace the existing text with the following text:

      disp(['Error during eval: ', evalException.message])

      This code executes if an error occurs while loading the Dürer etching.

      

5. In the Outline pane on the left, select the Eval component.

6. In the Library pane in the middle, under Handle Graphics, add a Figure Snapshot component to the report.

   To inline an image component (such as Image or Figure Snapshot), include it in a Paragraph component.

7. In the Properties pane:

   1. In the Paper orientation list, select Portrait.

   2. In the Invert hardcopy list, select Don't invert.

      Selecting this option specifies not to change the image's onscreen colors for printing.

   The next three steps set up the report to delete the image from the MATLAB workspace after the image has been added to the report.

8. In the Outline pane, select the Figure Snapshot component.

9. In the Library pane, under MATLAB, add an Evaluate MATLAB Expression component to the report.

10. In the Properties pane:

    1. Clear the Insert MATLAB expression in report and Display command window output in report check boxes. You do not want to include the code or its output in the report.

    2. In the Expression to evaluate in the base workspace text box, replace the existing text with:

       %This command deletes the Durer image
       delete(gcf);

       The delete(gcf) command deletes the current image in the MATLAB workspace, in this case, the Dürer etching.

    3. In the Evaluate this expression if there is an error text box, replace the existing text with the following text:

       disp(['Error during eval: ', evalException.message])

       This code executes if an error occurs while deleting the Dürer etching.

11. Save the report.

Create the Magic Squares and Their Images

Add a chapter to the report for each magic square specified by the magicSizeVector report variable. You use a For Loop component to perform this repetitive task. To create the magic squares and their images, you perform these tasks:

• Create a For Loop

• Add a Chapter for Each Square

• Determine the Matrix Size

• Insert the Magic Square Size into the Report

• Create the Magic Square

• Add Display Logic

• Display the Magic Square

Create a For Loop

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

1. In the Outline pane on the left, select the Chapter component.

2. In the Library pane in the middle, under Logical and Flow Control, add a For Loop component to the report.

   

   This For Loop component appears inside the Chapter component. However, the magic squares should be processed after the first chapter, so make the for component a sibling of the Chapter component, not a child.

3. In the Outline pane, select the for component.

4. Click the left arrow to make the for component a sibling of the Chapter component.

   

5. In the Properties pane on the right:

   1. In the End text box, replace the existing text with this text:

      length(magicSizeVector)

      This is the length of the vector that contains the various sizes for the magic square matrices.

   2. In the Variable name text box, replace the existing text with the following text:

      MAGIC_SQUARE_INDEX

      This variable acts as a loop index.

   

6. Save the report.

Add a Chapter for Each Square

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

Create a chapter for each square by adding a Chapter component to the report as a child of the For Loop component. This causes the Report Generator to create a chapter on each iteration of the for loop during report generation.

1. In the Outline pane on the left, select the for component.

2. In the Library pane in the middle, under Formatting, add a Chapter/Subsection component to the report setup.

   It becomes a child of the for component.

3. In the Properties pane on the right, select Custom from the Title list and enter this for the chapter title:

   Magic Square # %<MAGIC_SQUARE_INDEX>

4. Save the report.

Determine the Matrix Size

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

Extract the size of each magic square matrix from magicSizeVector using an Evaluate MATLAB Expression component.

1. In the Outline pane on the left, select the bottom Chapter component.

2. In the Library pane in the middle, under MATLAB category, add an Evaluate MATLAB Expression component to the report setup.

3. In the Properties pane:

   1. Clear the Insert MATLAB expression in report and Display command window output in report check boxes.

   2. In the Expression to evaluate in the base workspace text box, replace the existing text with:

      magic_Square_Size=magicSizeVector(MAGIC_SQUARE_INDEX);

      This command extracts the next size for the magic square from the vector of sizes initialized in the first Eval component of the report. The variable magic_Square_Size represents the size of the current magic square being processed.

   3. In the Evaluate this expression if there is an error text box, replace the existing text with this text:

      disp(['Error during eval: ', evalException.message])

      This code executes if an error occurs while attempting to extract a value from magicSizeVector.

   

4. Save the report.

Insert the Magic Square Size into the Report

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

Insert the size of the magic square into the report using the Paragraph and Insert Variable components.

1. In the Outline pane on the left, select the bottom Eval component.

2. In the Library pane in the middle, under Formatting, add a Paragraph component to the report setup.

   Do not change the properties. The variable that contains the size of the magic square goes in this paragraph.

3. In the Outline pane, select the Paragraph component (below the for component).

4. In the Library pane, under MATLAB, add an Insert Variable component into the report setup.

5. In the Properties pane on the right:

   1. In the Variable name text box, enter magic_Square_Size.

   2. From the Display as list, select Inline text.

   

6. Save the report.

Create the Magic Square

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

To create the magic square and display the associated matrix or image, use the Evaluate MATLAB Expression component.

1. In the Outline pane on the left, select the bottom Paragraph component.

2. In the Library pane in the middle, under MATLAB, add an Evaluate MATLAB Expression component to the report setup.

3. Make this Evaluate MATLAB Expression component a sibling of the Paragraph component. In the Outline pane, select the Eval component. Click the left arrow on the toolbar.

4. In the Properties pane on the right:

   1. Clear the Insert MATLAB expression in report and Display command window output in report check boxes.

   2. In the Expression to evaluate in the base workspace text box, replace the existing text with this MATLAB code.

      % This MATLAB script produces a magic
      % square of size magic_Square_Size
      % and creates an image of that square.
      
      mySquare=magic(magic_Square_Size);
      clf
      imagesc(mySquare);
      title(sprintf('Magic Square N=%i',magic_Square_Size))
      set(gca,'Ydir','normal');
      axis equal;
      axis tight;
      

      This code creates a magic square matrix mySquare of size magic_Square_Size, and opens an image of that matrix in the MATLAB figure window.

   3. In the Evaluate this expression if there is an error text box, replace the existing text with this text:

      disp(['Error during eval: ', evalException.message])

      This code executes if an error occurs while creating and displaying the magic square.

5. Save the report.

Add Display Logic

Note

This section builds on the previous tasks described in the step-by-step example summarized in Maintain Interactive MATLAB Report.

If you have not completed the previous sections of this example, open the completed report setup file: Magic Squares Report.

Use Logical If, Logical Then, and Logical Else components to determine whether to display the magic square as an array of numbers or as an image.

1. In the Outline pane on the left, select the Eval component.

   

2. On the Library pane in the middle, under Logical and Flow Control, double-click Logical If.

3. On the Properties pane on the right, in the Test Expression text box, replace the existing text with this text:

   magic_Square_Size<=largestDisplayedArray

   This command tests whether the current matrix size (magic_Square_Size) is less than or equal to the value assigned in the first Eval component of the report (largestDisplayedArray=15).

   To process the result of this Logical If component, create two child components—Logical Then and Logical Else. If magic_Square_Size is less than or equal to 15, the matrix variable appears in the report. If magic_Square_Size is greater than 15, the matrix image appears in the report.

4. On the Outline pane, select the if component.

   

5. On the Library pane, under Logical and Flow Control, double-click Logical Else.

6. On the Outline pane, select the if component again.

7. On the Library pane, under Logical and Flow Control, double-click Logical Then.

   The then component appears above the else component.

   

8. Save the report.

Display the Magic Square

Note

This section builds on the step-by-step example presented in Maintain Interactive MATLAB Report.

To see the completed report setup file, open Magic Squares Report.

1. In the Outline pane on the left, select the then component.

2. In the Library pane in the middle, under MATLAB, double-click Insert Variable.

3. In the Properties pane on the right:

   1. In the Variable name text box, enter mySquare, which is the variable that contains the magic square of the specified size.

   2. From the Title list, select None.

   3. In the Array size limit text box, enter 0.

      This Variable component displays the magic square matrix, stored in the mySquare variable.

4. In the Outline pane, select the else component.

5. In the Library pane, under Handle Graphics, double-click Figure Loop.

   Do not change its properties.

6. In the Outline pane, select the Figure Loop component.

7. In the Library pane, under Handle Graphics, double-click Figure Snapshot.

8. In the Properties pane:

   1. In the Paper orientation list, select Portrait.

   2. In the Image size list, select Custom.

   3. Under the Image size list, enter [5 4] for the custom image size.

   4. In the Invert hardcopy list, select Invert.

      This option changes dark axes colors to light axes colors, and vice versa.

   The Outline pane looks like this.

   

9. Save the report.

Error Handling for MATLAB Code

You can add MATLAB code to a report, by using the Evaluate MATLAB Expression component (also called the Eval component).

The Evaluate MATLAB Expression component dialog box includes an Evaluate this expression if there is an error check box. The dialog box includes default error handling code that you can use, or you can create your own error handling code.

If you do not change the default error handling code, then when you generate the report, and there is an error in the MATLAB code that you added:

• If you clear Evaluate this expression if there is an error check box, then the complete report is generated, without displaying an error message at the MATLAB command line.

• If you select Evaluate this expression if there is an error check box, then the complete report is generated and an error message appears at the MATLAB command line.

To stop report generation when an error occurs in the MATLAB code that you added, change the second and third lines of the following default error handling code, as described below:

warningMessageLevel = 2;
displayWarningMessage = true;
failGenerationWithException = false;
failGenerationWithoutException = false;

To stop report generation and display an exception, change the default code to:

displayWarningMessage = false;
failGenerationWithException = true;

To stop report generation without displaying an exception, change the default code to:

displayWarningMessage = false;
failGenerationWithoutException = true;

If you want to replace the default error handling code, use the evalException.message variable in your code to return information for the exception.

Generate a Report

Note

This section builds on the step-by-step example presented in Maintain Interactive MATLAB Report.

To see the completed report setup file, open Magic Squares Report.

At the beginning of this example, you specified HTML (from template) as the output format of the report. If you did not, or if you opened the completed report setup file later in the tutorial, set it that way now.

1. On the toolbar, click the Report button to generate the report.

2. While the report generates, in the Message List window, specify the level of detail you want the Message List window to display.

   

   In the Report Explorer Outline pane, each component of the report setup file highlights as it executes.

When processing finishes, the MATLAB Web browser opens and displays the HTML file.

When you choose HTML (from template) as the output type, the table of contents appears collapsed in the report. Expand or collapse each node by clicking the plus or minus sign on the node. Press Ctrl+click to expand or collapse the entire structure (CMD+click on Macintosh platforms).