Haghish, E. F. (2014). Applied Statistics Using Stata.

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

Updated on 1 March 2016 Star Watch Fork

Weaver Package

| Introduction |     | Weaver commands |     | Features |     | Examples |     | Weaver markup |     | Installation |     | Math |    

The article discusses what is wrong with the way statisticians use literate programming, as compared to the original idea of literate programming used by software developers. The article also completely documents the features of the software package and provide basic examples.

Rethinking Literate Programming in Statistics

Introduction

The Weaver package supports HTML and LaTeX for creating dynamic analysis reports, without requiring any knowledge of these markup languages. Particularly if the log file is created in HTML because Weaver includes a simplified JavaScript-based markup language called "Weaver Markup" that allows writing text headings and paragraphs, styling text, changing text color, highlighting text, and adding a hypertext link in the HTML log. Moreover, Weaver also comes with a built-in JavaScript syntax highlighter for Stata code which makes the code more distinguished from the text. For writing dynamic text, adding figures, and creating dynamic tables both in the HTML and LaTeX log files, Weaver includes three specialized commands that make these tasks convenient. Additionally,Weaver supports rendering mathematical notations in both the HTML and LaTeX log files. Finally, both the HTML or LaTeX log and the rendered PDF document can be previewed in real-time in the process of developing the dynamic report.

  • It runs in parallel to Stata smcl log file
  • Creates dynamic documents interactively in HTML, PDF, and LaTeX
  • Includes a simplified markup language for writing HTML document and keeping the code readable
  • Includes a syntax highlighter for Stata code, in both HTML and LaTeX documents
  • Is interactive and creates the PDF in read-time
  • Renders mathematical notations in both HTML, PDF, and LaTeX
  • Can automatically import figures from Stata to the dynamic document
  • Supports dynamic text and dynamic tables in both formats

Summary of Weaver Commands

Weaver includes two sets of commands. The commands that begin with weave are related to handling the log such as opening a new log file, merging existing HTML or LaTeX documents into the current log, exporting a live-preview PDF document, closing the log, or temporarily turning it on or off. The other commands are used for annotating the document, i.e. inserting a figure, creating a dynamic table, echoing Stata commands and outputs, and writing and styling text in the log file. These commands are introduced separately as weave commands and annotating commands.

Summary of the weave commands

weave using filename Creating a new HTML or LaTeX log file
weave close closes the Weaver log and prints the final PDF document
weave query Reporting the status of the Weaver log
weave on   |  off Temporarily deactivating or reactivating the Weaver log
weave pdf Render a PDF document from the Weaver log anytime
weave merge using filename Render a PDF document from the Weaver log anytime
weave preserve   |  restore preserves and restores the status of the Weaver log
weave setup Opens weaversetup.ado to setup paths to printer and MathJax permanently

Summary of the annotating commands

div [code] | [result] command displaying Stata commands and outputs in the Weaver log
txt [code] display_directive Display dynamic text in the Weaver log
img [filename] Importing a figure from Stata, hard disk, or internet the HTML or LaTeX log
tbl (*[,*...] [\ *[,*...] [\ [...]]]) Creating a dynamic table

Examples

Weaver Markup

The Weaver markup codes are primarily written for the txt command, which provides the possibility of dynamic text writing. When the Weaver log is written in HTML, these markup codes can greatly imprive the readability of the source code, compared to HTML LaTeX. The example below demonstrate how to display the content of a macro in a heading 1 format.

local title "this is heading 1"
txt *- `title' -*

Phrase Emphasis

#_italic_# /* make the text italic */
#__bold__# /* make the text bold */
#___bold & italic ___# /* make the text italic & bold */

Headers and subtitles

txt *- this is heading 1 -* /* create heading 1 */
txt *-- this is heading 2 --* /* create heading 2 */
txt *--- this is heading 1 ---* /* create heading 3 */
txt *---- this is heading 4 ----* /* create heading 4 */

Paragraph

txt this is a text paragraph and it does not require any markup syntax.

Alignment

The Markdown codes do not allow you to align the text to the center or right side of the document. The additional markup codes provide syntax for aligning text to the center and the right. Pay attention to the [#] sign that closes the [center] and [right] signs.

[center] align the text to the center [#]
[right] align the text to the right[#]

Font color

The Markdown codes do not allow you to change the font color. The additional markup codes provide 6 different colors which each of them begin with a bracket containing the color name and end with [#] sign.

[blue] change the text color to blue [#]
[green] change the text color to green[#]
[red] change the text color to red[#]
[purple] change the text color to purple[#]
[pink] change the text color to pink[#]
[orange] change the text color to orange[#]

Text highlighter

The syntax for highlighting text using additional markup codes is similar to the font color. Although the color tag begins with a hyphen in the brackets.

[-yellow] highlight the text yellow [#]
[-blue] highlight the text blue[#]
[-green] highlight the text green[#]
[-pink] highlight the text pink[#]
[-purple] highlight the text purple[#]
[-gray] highlight the text gray[#]

Page and line break

When the output document is PDF, you have the option of breaking the line or page. Breaking the line means leaving a line empty and starting a new paragraph. On the other hand, page break will begin a new page.

line-break /* breaks the paragraph and leaves one line empty */
page-break /* breaks the page and begins a new page (in PDF only) */

Link

[-- "MyLink" --][- http://haghish.com/stata -] /* create a link named MyLink */

In the example above, the "MyLink" is the hyperlinked text, i.e. the text that appears in the document.

Note that there should be no space between the --][- characters.

Installation

The Weaver package is hosted on SSC server. It also requires the Statax Package which appends a JavaScript syntax highlighter to the HTML log. Both packages can be installed by typing:

ssc install weaver          // install Weaver
ssc install statax          // install Statax JavaScript Syntax Highlighter

In addition, Weaver requires two third-party software which are wkhtmltopdf and MathJax. The wkhtmltopdf freeware provides command line tools for converting HTML to PDF and accurately renders CSS and JavaScript to PDF. MathJax is a JavaScript engine for rendering mathematical notations in the HTML log file. Both MathJax and wkhtmltopdf are open-source freeware, available for Microsoft Windows, Macintosh, and Unix operating systems. Naturally, for typesetting a PDF document from the LaTeX log file a LaTeX distribution should be installed on the machine. In order to use Weaver without any third-party software installation, the noprint option should be used. This option will avoid errors regarding MathJax, wkhtmltopdf, and pdfLaTeX.

The SSC server only hosts the ado and help files and the required third-party software should be installed manually. Nonetheless, to make the installation process more convenient, Weaver provides an optional automatic installation for MathJax and wkhtmltopdf. Both manual and automatic installation of the required software are described below.


Manual installation

Manual installation of wkhtmltopdf is straightforward. The software can be downloaded from wkhtmltopdf.org and installed in any location on the machine. However, the path to the executable wkhtmltopdf on the machine should be given to Weaver using the printer(str) option. Similarly, in order to typeset the LaTeX log to PDF, the proper LaTeX distribution based on the operating system should be downloaded from https://latex-project.org/ and the path to executable pdfLaTeX should be provided using the printer(str) option. The manual installation of MathJax is rather easier. The "MathJax-master.zip" file can be downloaded from http://mathjax.org/ and unzipped in the \ado\plus\Weaver\ directory.

Alternatively, users can also setup the default file paths to avoid specifying the printer(str) option for PDF drivers or installing MathJax in the Weaver directory permanently. The weave setup command opens the weaversetup.ado file which includes global macros for memorizing the full path to executable wkhtmltopdf, pdfLaTeX, and MathJax-master directory for future use. The third-party software are only needed for rendering PDF and mathematical notations. Therefore, users who only wish to avoid creating a PDF or rendering mathematical notations, the noprint option can be used to suppress any error regarding the required software.

The Weaver Directory is located in the Plus directory of Stata. To find the path to Plus directory on your system type sysdir command in your Stata. The "likely" paths to Weaver directory are shown below.

Microsoft Windows : C:\ado\plus\Weaver Macintosh : ~/Library/Application Support/Stata/ado/plus/Weaver Unix : /home/username/ado/plus/Weaver

Automatic installation

The install option downloads wkhtmltopdf and MathJax automatically and installs them in Weaver directory. The automatic installation of the required software was successfully tested on Macintosh (OSX 9.5 and 10.10) and 32bit and 64bit versions of Microsoft Windows (XP, 7, and 8), sand Linux (Ubuntu 14, Mint 17, CentOS 7). However, manual installation is generally recommended because it assures the installation of the latest version of the software. The example below shows how to install the required software while opening a new dynamic report log.

weave using example.html, install replace   // for automatic installation

Mathematical Notations

Weaver log files, both HTML and LaTeX support rendering mathematical notations, which makes Weaver a useful tool for taking notes.

Writing mathematical notations requires separating the notations from the rest of the text. Users whom are familiar with writing notations in LaTeX already know that they can use single $ sign or double $$ sing for rendering mathematical notations within a text paragraph, or centered on a separate line. For example the following formula would be rendered as:

$$ \widehat{\mu} (x) = \beta{_0} + \beta{_1} x  $$

\[ \widehat{\mu} (x) = \beta{_0} + \beta{_1} x \]

While dollar sign is popular for notation in LaTeX, it also can be very troublesome in HTML. In addition, writing notation with dollar sign in Stata also requires further care because a tiny mistake may cause Stata to interpret the string as a global macro. To avoid that, Weaver provides alternative syntax for rendering mathematical notation, which is summarized below for both HTML and LaTeX log files.

Summary of the mathematical notations

\(  Mathematical Notation  \) rendering LaTeX inline with text
\[  Mathematical Notation  \] rendering LaTeX on separate line
$$  Mathematical Notation  $$ rendering LaTeX on separate line

This syntax is supported in both HTML and LaTeX log files. However, single dollar sign $ can only be used with LaTeX log file and is not supported in HTML log, for the reason explained above.

The mathematical notations can be used anywhere in HTML or LaTeX logs. Forexample, whether you use them in the summary(str) of the document, or title(str) option of a figure, within text paragraph, or even inside a dynamic table. However, when used in tbl command for creating a dynamic table, you should be extra careful. The reason is that the tbl command uses backslash for parsing the given text. Therefore, the \( ... \) and also, \[ ... \] should not be used in the tbl command, because they also include backslash sign.

When you use the dollar sign, especially if you use the single dollar sign in LaTeX log, be extra careful and always apply a white space before and after the sign, to ensure Stata does not interpret it as global macro.

You may use these signs interchangably. All of them are recognized in both the LaTeX and HTML logs (apart from single dollar sign). The same rules also apply for writing mathematical notation in MarkDoc package.