Watch videos with subtitles in your language, upload your videos, create your own subtitles! Click here to learn more on "how to Dotsub"

12 Generating Documents and Reports

0 (0 Likes / 0 Dislikes)
This section of Introduction to Wolfram Notebooks is about using programs and templates to generate notebook documents programmatically. Computer-generated notebooks are useful in applications involving documents that are somehow repetitive, like the series of reports shown here, or for documents with repetitive content, like this notebook, or in a variety of more specialized applications, like generating reports on a schedule, generating computational contracts or just to record results from long-running programs. One basic process for generating reports, which will be described in more detail in a moment, is to start by creating a template notebook like this one and then fill in information within that template to generate the document. This input uses the GenerateDocument function with values for named slots in the template, which has been saved in a file. Another lower-level way of generating documents is to write a program like this one, with functions like CreateDocument and NotebookWrite to create a notebook document and insert content into that notebook. Any approach for generating notebooks is ultimately made possible by the fact that Wolfram Notebooks are represented as Wolfram Language expressions and so can be created and modified by Wolfram Language programs. Describing a notebook as a list of cells means literally that the content of the notebook is a Wolfram Language list with cell expressions as the elements of that list. Here, for example, is a notebook expression for a notebook with three cells and with options specifying the title of the top of the notebook window and the size of the window. This expression can be displayed as a notebook using the NotebookPut function. Direct entry of a notebook expression is not how notebooks are typically constructed, but notebook generation ultimately works through operations on notebook expressions. One of those operations is the CreateNotebook function, which is used here to create a new notebook expression and display it on the computer screen. That input also assigns the resulting notebook object as the value of a variable. One way of getting content into that notebook is to use the NotebookWrite function to insert cell expressions into that notebook. All of the general programming features of the Wolfram Language can also be used in generating notebooks. For example, starting with some data to form the basis for a report, here is a program that creates a new notebook, writes a title cell into that notebook and then uses NotebookWrite commands in a loop to generate a notebook with a section for each element in the data list. Beyond CreateNotebook and NotebookWrite, there are many other functions for manipulating notebooks. You can find more information about those functions in the Wolfram documentation, such as in this page on manipulating notebooks from the kernel. There are functions here for moving around and searching within a notebook, for inserting and deleting content, for opening and closing notebooks, and so on. Basically almost anything that can be done by interactively editing this notebook can also be done from a program. A more graphical way of generating notebooks is the method mentioned earlier of starting with a template notebook like this one and inserting content within that template. A template notebook can be created by choosing New ► Programmatic Notebook ► Template Notebook from the File menu, which opens a new notebook with a toolbar in a docked cell at the top of the notebook. Except for the toolbar, this notebook can be edited much like any other notebook. The report is completed either by inserting expressions at locations called slots within this notebook or by doing evaluations within the template when the report is generated. You can add a slot by clicking the Slot button, which opens a dialog box for entering the name of the slot, and you can optionally enter default values for each slot. After finishing the template, you can click the Generate button to generate a report with the slots filled in by the default values, which is useful for checking that the template is giving the expected result. The template notebook can also be saved for later use like any other notebook by choosing Save under the File menu. After creating the template, there are several tools for filling in the slots in the template. One of those tools is the GenerateDocument function, shown here with the name of the saved template notebook as the first argument and a list of rules giving values for the named template slots as the second argument. The result is a report with the template slots filled in with the specified values. Rather than evaluating expressions and inserting the results into slots in the template, it is also possible, and often makes the document-generation process somewhat easier, to do those evaluations right within the template. For example, the DateString expression in that GenerateDocument input, which is evaluated to get a result that is inserted into a slot in the template, could alternatively be included right in the template using the Expression button in the template toolbar. Clicking the Expression button gives a box where you can enter an expression to be evaluated when the document generated. After saving the revised template, we can return to the GenerateDocument input, where the DateString expression is no longer needed. When the document is generated, the output from evaluating the DateString expression in the template is inserted and the document looks just as it did before, but that GenerateDocument input is a bit less complicated. Reports can be much more elaborate than this one and can include tables and graphs and anything else that can be included in any notebook. For example, here is a plot using data from a dataset that is loaded from an external file. This plot can be added to the report by including another slot in the template, as shown here; saving the revised template; then moving over to the GenerateDocument input to enter a value for the new named slot and evaluating that input to generate the report. As was used earlier for the DateString expression, the programming to load the data and generate the plot in that example can also be put in the template. A direct way of doing that is to simply edit the template to add the inputs to load the data and generate the plot. If we click the Generate button for this template, the inputs and outputs are all included in the report. If the report only needs to show the plot, the inputs can be omitted with the help of items under the Cell Behavior menu in the report template toolbar. To evaluate and then delete the cell with the input for loading the data, select that cell and choose Evaluate and Delete from the Cell Behavior menu. For the cell with the input that generates the plot, we could again choose Evaluate and Delete, which would show the plot and delete the input, or we can choose Evaluate and Hide. Clicking the Generate button shows the effect of those settings. The cell for loading the data, which was set to Evaluate and Delete, was evaluated and deleted, and the cell for generating the plot, which was set to Evaluate and Hide, gives the plot shown in a closed cell group. Double-clicking on the closed cell group bracket opens that cell group to show the input, which can be useful if users of the report might want to see that input. Other choices for cell behavior are Leave Unevaluated, which copies the chosen cell over to the report without doing any evaluation, and Exclude Cell, which omits the cell from the report, also without evaluating it, which is useful for saving notes and comments that are not part of the report. The programming in that example brings up a technical detail that can sometimes be important to know about, which is that the notebooks for the report template and for the generated report have an option setting that causes new variables to be assigned a context that is unique to each notebook. The new variable in question in this example is the data variable. By default, the context of new variables is global in all notebooks, so a new variable in one notebook is the same as a variable with that same name in another notebook. In this generated notebook, however, the context is unique to this notebook, so values assigned to this variable in this notebook have no effect on variables with the same name in another notebook. Normally this is desirable behavior, but if report generation is for some reason set up to depend on global names for variables, then it is necessary to specify the context explicitly or to otherwise arrange for those variables to use the same context. The most common reason for creating a template is for creating more than one report, which in part means being careful to program into the template only the content and formatting that is common to all of the reports. As an example, consider generating a separate report for each record in the dataset that was loaded earlier. That dataset consists of a list of records and the example template is programmed to show only the first record. This data happens to be in the form of a Wolfram Language dataset, from which it is easy to extract an expression called an association for the elements in each record. This association can be used in the GenerateDocument function, just like the list of rules that was used earlier for named slots in a template. To make the template work with this dataset, we can modify the template so that the names of the named slots in the template match the names of the named items in each record in the dataset. After saving the revised template, the GenerateDocument function can be used with the association extracted from the dataset to generate a report. Applying the Normal function to the entire dataset gives a list of associations for each record, and each association has the names and values to use in the GenerateDocument function to generate the document. All that remains now is to write a short program to apply the GenerateDocument function to each element in that list, which results in a separate report being generated for each record in the dataset. Rather than creating separate reports, a report based on this dataset could alternatively be a single document with a separate section for each record in the dataset. One way of generating such a report uses the Repeating Block feature in the template toolbar. To demonstrate how repeating block works in a simple example, here is a template with two cells. To repeat these two cells, select the cell bracket and click the Repeating Block button, which opens a dialog box with several choices. Here we will demonstrate only the second choice, which specifies that this template will use a variable named data and that the value of that variable will be a list for filling in the slots in each block. A GenerateDocument input to use this template can look like this, where the value of the data variable is a list of associations and each association gives a list of named values for filling in the slots in each block. In this example, the value of the data variable has three elements, so the block will be repeated three times in the report. Returning to the previous dataset, rather than applying GenerateDocument separately to each record in the dataset, this time the entire list of associations from that dataset will be passed to the GenerateDocument function as the value of the variable named data. Now modify the earlier template to use a repeating block with named slots that match the names of the elements in each record. After that modification, the GenerateDocument program to create the report is just a single line of input. All of the formatting and interactive features of notebooks that have come up in earlier sections can also be used in automatically generated reports. For example, here is a template that uses the Grid function to show data in a table and a TabView input so that users of the report can choose between different plots. The report generated from that template is an interactive report with a summary table and an interactive feature for selecting different information to display. That's the end of the examples for this section. There are many variations on the basic report-generation process. In the Wolfram documentation, you can find more information by searching for report generation. For example, this guide page gives links to the functions that came up in the section and also functions for doing document generation in the cloud and for such things as generating reports automatically on a schedule. There are also workflow guides with step-by-step instructions for the basic process of generating a report from a template and for generating a report on schedule or as a PDF file.

Video Details

Duration: 11 minutes and 26 seconds
Language: English
License: Dotsub - Standard License
Genre: None
Views: 19
Posted by: wolfram on Feb 25, 2020

12 Generating Documents and Reports

Caption and Translate

    Sign In/Register for Dotsub to translate this video.