Stata-Blog

Applied Statistics Using Stata^{®}

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

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

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

Weaver includes two sets of commands. The commands that begin with

filename |
Creating a new HTML or LaTeX log file |

closes the Weaver log and prints the final PDF document | |

Reporting the status of the Weaver log | |

Temporarily deactivating or reactivating the Weaver log | |

Render a PDF document from the Weaver log anytime | |

filename |
Render a PDF document from the Weaver log anytime |

preserves and restores the status of the Weaver log | |

Opens weaversetup.ado to setup paths to printer and MathJax permanently |

command |
displaying Stata commands and outputs in the Weaver log |

display_directive |
Display dynamic text in the Weaver log |

filename] |
Importing a figure from Stata, hard disk, or internet the HTML or LaTeX log |

(*[,*...] [\ *[,*...] [\ [...]]]) |
Creating a dynamic table |

The Weaver markup codes are primarily written for the

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

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

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.

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.

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

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

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 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

Alternatively, users can also setup the default file paths to avoid specifying the

The Weaver Directory is located in the Plus directory of Stata. To find the path to Plus directory on your system type

The

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

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

$$ \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

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

● The mathematical notations can be used anywhere in HTML or LaTeX logs. Forexample, whether you use them in the *str**str**...* *...*

● 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.