Applied Statistics Using Stata

Free Online Stata Tips & Tutorials. Data Management; Stata Graphs and Graphics; Data Analysis; Stata Programming; Advanced Statistics

Stata Weaver Package

| Quick Tips |    
| Introduction |    
| Weaving a document |    
| Text |    
| Graph |    
| Examples |    

Quick Tips

Weaver package provides a handful of commands for creating dynamic reports in Stata. Weaver was developed to meet the need of Lecturers and Statisticians that need to write and share a lot of reports, especially with other academic people which are not very interested in the details of the analysis and Stata codes. Weaver help to produce a clean HTML or PDF document that presents the important results and graphs, avoiding other technical and coding details that may not be of interst of other researchers with less background in statistics.

Introduction

Imagin you have worked on a data analysis and have written a long dofile. Let’s say that you wish to create a dynamic report that includes the important results and graphs and some text that explain the procedure and discuss the findings. Do you prepare a separate dofile for creating the document? This might not be a bad idea because in the process of analysis you may have tried several commands that you do not wish to include in your document. For example, maybe you just wanted to check for something that was not very necessary or perhaps, you wanted to check the distribution of your variables using several histograms but you think that it is better to just write a few lines in your document that the distribution of the variable seems reasonable and avoid puting them in your document. In these ocassions, it make sense to start another dofile which is intended to be used for generating a dynamic document. That would be the case if you were intending to share a SMCL logfile or translate a logfile to HTML, PDF, or Docx using Ketchup or MarkDoc.

Since Weaver is a very selective dynamic document producer, it can offer a better solution which is writing a document as you begin the analysis. By selective, I mean that when using Weaver, you have the option to include a particular code or output in the report or alternatively, include them in the dofile and execute them without including them in the report. In other word, Weaver runs in parralel to Stata and only writes the commands and output that you wish to include in the document. This feature gives Stata users a big advantage over other packages for developing dynamic report.

So how does Weaver provide the option to the user to select the codes that they wish to include in the document? Weaver creates a special logfile, which is a HTML logfile. The logfile is created by using the weave command and is closed with the weavend command. Next, Weavend automatically prints the HTML document into PDF.

In contrast to SMCL logfile which automatically registers everything which is written by the user, the HTML logfile requires an additional command to write the code, Stata outputs, or both in the report. In other words, Weaver even gives the option of only including a command or only including the results to the user which can help to produce cleaner reports for people who are not very interested in the codes or the statistical details.

Weaver includes a number of commands which all cooperate with one another to produce a decent HTML and PDF documents. The commands can be categorized in 4 groups. The first group includes commands that are related to creating the HTML logfile and the PDF documents. The second group of commands includes commands that are used for adding text and graphs to the document. The third group of commands includes the commands that provide the options about what commands and results to include in the document and what to exclude from the document. And finally, the fourth group is consist of commands that are used for refining the document. Below, these groups are explained and the commands relating to each group are named. In this article I introduce the Weaver commands and provide examples for each of them.

1) commands that relate to creating the HTML logfile and PDF document : weave, weavend, report, html

2) commands related to adding text and graphs to the document : img, knit, markup, markdown, quote

3) commands that select what should be included in the document : div, codes, results

4) commands that refine the document : linebreak, pagebreak

Weaving HTML and PDF documents

To begin a document, use the weave command to create a HTML logfile. When a new HTML logfile is opened, the weave command show the link to the new HTML logfile on the results window of Stata. For example, let’s open a new logfile called example and see the Stata output:

● If you click on the example.html, the HTML file will open in your default web browser. moreimportantly, whenever you add a new command/output/text/graph to the weaving document, you can preview it by refreshing the HTML logfile. This can give you a live preview of how your document looks like. This feature is a big advantage to other packages such as Ketchup or MarkDoc which cannot provide a live preview of the document.

Perhaps it’s time to discuss a tiny limit casued by HTML (or any other web-based document). In contrast to other common document formats such as Docx, Doc, Odt, and PDF, HTML and other web-based documents do not appear in separate pages. Imagin browsing in a website and instead on scrolling down, you have to flip pages. Although such a feature can be programed for a website (i.e. the content appear in fixed sized pages) but probably many users will not find it very appealing.

However, HTML file can include codes that tell the regular printer or a PDF printer how to put the HTML codes into pages. For example, this website use specific CSS codes that makes it very printer friendly. In fact, by clicking on the printer icon (top-left side of this page) or pressing CMD + P keys in Mac or Ctrl + P keys in Windows, you can obtain a good document out of this website. However, codes that tell the printer to separate pages from one another do not appear in the HTML file, simply because there is no “pages” in HTML, it is only one infinitely long page.

● Therefore, although the HTML file shows the content to appear one after another, in the PDF document they may appear in separate pages. By default, the weave command presents the “title page” as well as the “contents page” (if the contents ption is selected) in separate pages.

The report command is the safety belt of the Weaver paclage. At allows you to print a PDF file from the current HTML logfile at anytime. By doing so, you can make sure that you are happy with the appearence of your document and everything is going as you wish. This command can save a lot of trouble if you use it while you’re developing the analysis and writing the report. To do so, simply type report in the Stata console. Weaver will print a PDF from the HTML file and automatically opens the PDF document.

The report command has another useful function which can be used outsede Weaver. type help weaver in your Stata console to bring the Weaver help file and search for “report” in the help file. The helpfile describes the report command as follows:

Every experienced Stata users have figured out by now that the report command “can” have an additional function. It “can” take a HTML file and print a PDF out of it. This HTML file can be literally any HTML file on your system. If you wish, you can rename the PDF output using the export(name) option. You can also decide which printer to use by using the printer(name) option. Similar to weave command, the prin
ter name can be prince or wkhtmltopdf (for more information regarding these two printers see this article). Finally, you can also define the path to the printer with the setpath(name) option if the printer is not installed on the default path, recognized by Weaver. These paths are as follows:

There is another command that may be useful for some of the advanced users or users that are familiar with web languages. The html command inserts scripts to the HTML logfile. This command can be used to add, for example, HTML codes, JavaScript, CSS, or any other language/code/object that can be interpreted by web browser.

In the example below, I write the following html code using the html command:

Give the html command a try..:

I used the html code to insert a yellow box that include text, only to demonstrate that you can write html codes and insert them in the document. Many of you may not know HTML and other web languages. That’s Ok! There are plenty of software that you have been using on daily basis which allow you to export your document in HTML. For example, Microsoft Word, Excel, OpenOffice allow you to export a table in HTML format. You can simply copy the HTML code and insert it in the document if you wish to have a well-designed table in your document. I have written a separate article about this idea which you can read here.

● Remember that the [blue] text [#] is one of the Additional Markup Codes that can change the text color.

Text

There are two main ways for writing text in Weaver. The first one is using Markdown, which is the simple way and the second one is using the knit command which can be used for writing dynamic text i.e. text that includes Macros. Before I begin discussing methods of writing text in Weaver, I should reveal one of the tricky differences between Weaver and his other siblings, Ketchup and MarkDoc. If you have used these packages, you probably remember that for writing in Ketchup and MarkDoc all you needed to do was using Markdown syntax within comment signs. For example, you could write:

However, in Weaver, if you write the text similar to Ketchup and MarkDoc, the text will not appear in the HTML logfile. Can you think of a reason why? If you have read the introduction of this article carefully you should probably remember the reason. Because Weaver needs to be told to include a command or results and by default ignores everything. To tell Weaver that you are about to start writing text in Markdown format, you should use the markup or its abbreviation mp . When you are done with the text writing, you should tell Weaver that the text is over and it should ignore what comes next. To do so, use the markdown command or its abbreviation, md . Therefore, the correct way of writing text using Markdown syntax is as follows:

Or alternatively, you can write:

So you may wonder that what these two commands actually do. The markup command opens a temporary SMCL file and begins registering everything. The markdown command closes the SMCL logfile, translate it to Markdown textfile and then translate the markdown text to a temporary HTML document and then again, it appends the temporary HTML file to the HTML logfile or in other words, the document that you are weaving.

The markdown or md commands “can” do 2 an additional tasks which may be useful from time to time. These additional functions are independent from the markup command. Markdown command can be used to :

markdown command can insert a smcl file to the document you are weaving. This is a feature that probably will not be used often but can be helpful. If you have done an analysis before and saved it in SMCL logfile, you can append that file using the markdown command. The markdown command translate the smcl to HTML and appends it to the report.

If you wish to insert a separate HTML document instead, you can also use the markdown or md commands and add the html option. For example, say that you have saved a HTML document from Wikipedia and you wish to include that document in the current document that you are weaving. If the document you wish to insert is in the same working directory, you only have to write its complete name and suffix. For example, assuming the name of the HTML file I wish to insert is wikipedia.html, I would write:

If you do not specify the html option, markdown will consider that as a SMCL file. Below the markdown command and its options are shown. The erase option removes the SMCL or HTML document after it appends it to the report.

● I fear that the markdown or its abbreviation, md command cause confusion to some of the users. The rule is that markdown only obtains the additional functions if you give it a SMCL or HTML file. Then it recognizes that you wish to insert another document into the current document in Weaver. You can think of these features as features that can be very useful for creating appendix based on the other analyses that you did not intend to weave in the main body of the report.

Graphs and images

Weaver offers several ways for inserting a graph or image to the document. The easiest and the best way is the img command which can resize and style the graph. The img command takes the source (path) to the graph and inserts it to the document. The width(int) and height(int) options can be used to resize the image. By default, the image is inserted at the left side of the document but the center and right options can be applied to place the image at the center or the right side of the document.

For example, imagin that I want to insert a graph named grp1.png which is in the working directory. I want to insert this graph to the center of the document and in a small size of 300 x 200 pixels:

Alternatively, you could import the same graph using the html command which is mich more complicated than the img command:

I think I have a good reason to believe most of you would prefer the the img command over the html command and exactly for the same reason, I wrote the img command!

There is another possibility for importing a graph to the document which is using Markdown syntax. Although I have explained it in details in the Using Markdown with Stata article, I brifly explain the Markdown syntax for importing a graph below:

The description is optional and prints the description under the graph. if you do not wish to describe the graph leave the brackets empty i.e.  but there should be no space between ] and ( . In the example below, I import the grp1.png graph which is in the working. Note that the markdown command should be written in as a comment.

To Be Continued…

Download example templates

Download the following do-files templates to see examples of how to use the Ketchup package properly. Right click and select “Save Link As” to download the files. These example templates show you how to write text with Markdown, how to insert a graph using Markdown, HTML, and img command.

weaver_example1.do

additional_markup.do

back to top