The webdoc graph command

To include a graph in the output document, simply type webdoc graph after the graph has been created. webdoc graph will store the graph on disk and place an appropriate <img> tag in the output document to display the graph. By default, a PNG image with a width of 500 pixels is produced. There are various options to change how the graph is exported and how it is integrated into the output document; see the graph options in the help file.

The following example sets the physical width of the graph to 1000 pixels, sets the display width to 100%, provides a caption for the graph, and also sets a tooltip title.

webdoc init, header(width(700px)) logall

/***
<p>Open the 1978 Automobile Data and draw a scatter plot of price against
milage using the <code>twoway</code> command and include a linear fit.</p>
***/

sysuse auto
twoway (scatter price mpg) (lfit price mpg)
webdoc graph, caption(Figure 1: Twoway plot of price by milage) cabove ///
          width(1000) title(price by mpg) attributes(width="100%")
Code
1.png

Moving the pointer across the graph displays a tooltip "price by mpg". Furthermore, clicking the graph opens the graph file (to see these effects, open the HTML document by clicking the above picture).

[top]

SVG format (Stata 14)

By default, webdoc graph creates a bitmap graph using the PNG (Portable Network Graphics) format. To use the SVG (Scalable Vector Graphics) format (available since Stata 14), specify option as(svg):

webdoc init, header(width(700px)) logall

/***
<p>Open the 1978 Automobile Data and draw a scatter plot of price against
milage using the <code>twoway</code> command and include a linear fit.</p>
***/

sysuse auto
twoway (scatter price mpg) (lfit price mpg)
webdoc graph, caption(Figure 1: Twoway plot of price by milage) cabove ///
          title(price by mpg) attributes(width="100%") as(svg)
Code
2.png

Advantages of an SVG over a PNG are that the SVG is relatively small (unless the graph contains a large amount of data points) and can be scaled without loss of precision. For further available output formats, see help graph export.

[top]

Graph name

webdoc graph automatically creates a name for the graph (based on the name of the relevant Stata output section). If you want your graph to have a specific name, you can type webdoc graph name, where name is the name to be used for the graph.

[top]

Placement of graphs

If, as in the example above, the logall option is specified, webdoc will stop the Stata output section at the position of the webdoc graph command, insert the graph, and then continue with a new output section. If you want to display a graph that has been produced within an explicit webdoc stlog section, it is usually better to call webdoc graph after the section has been closed, so that the graph is placed after the output section. That is, type

webdoc stlog
    ...
    graph command
    ...
webdoc stlog close
webdoc graph

instead of

webdoc stlog
    ...
    graph command
    webdoc graph
    ...
webdoc stlog close

Typing webdoc graph within a webdoc stlog section is allowed (and will be suppressed in the resulting output), but it will cause the graph to be included in the HTML document before the output box.

[top]

Hiding the graph commands

If you just want to include the graph in the output document without showing the commands generating the graph, place the commands in a webdoc stlog section and apply the nolog option. Placing the commands in a webdoc stlog section makes it possible to rerun the do-file later on without having to recreate the graph (i.e. applying the nodo option).

webdoc init, header(width(700px))

/***
<p>The following graph displays a scatter plot including a linear fit of 
price against milage using the 1978 Automobile Data.</p>
***/

webdoc stlog, nolog
    sysuse auto
    twoway (scatter price mpg) (lfit price mpg)
webdoc stlog close
webdoc graph, title(price by mpg) attributes(width="100%")
Code
3.png
[top]

The hardcode option

The default for webdoc graph is to provide the image source in form of a link to the external graph file. However, you can also specify the hardcode option to directly embed the image in the HTML document using Base64 encoding (this only works if the requested graph format is PNG). The hardcode option is useful, for example, if you want to share your HTML file without having to copy around multiple files. Another use might be if you want to embed a low resolution graph in the HTML document and, at the same time, provide a link to an external high resolution graph file. This could be achieved as follows.

webdoc init, header(width(700px)) logall

sysuse auto
twoway (scatter price mpg) (lfit price mpg)
webdoc graph, hardcode width(100) link
webdoc graph, custom width(1000)
Code
4.png

The first webdoc graph command embeds a low-resolution graph (100 pixels wide) in the HTML document and also includes a link to the external graph file. The second webdoc graph command overwrites the external graph file with a high-resolution variant (1000 pixels wide), but does not include any code in the HTML document (due to option custom). If the user clicks the image in the browser, the high-resolution graph will be opened.

[top]

Cross-referencing

webdoc graph adds an ID to the figure environment of the image. You can use this ID to cross-reference the figure in the text. The default ID is constructed as fig-name, where name is the base name of the graph. For example, you could type:

webdoc init, header(width(700px)) logall

/***
<p>The following <a href="#fig-price-by-mpg">figure</a> displays the 
relation between price and milage.</p>
***/

sysuse auto
twoway (scatter price mpg) (lfit price mpg)
webdoc graph price-by-mpg
Code
5.png

You may also provide a custom ID typing figure(id):

webdoc init, header(width(700px)) logall

/***
<p>The following <a href="#price-by-mpg">figure</a> displays the 
relation between price and milage.</p>
***/

sysuse auto
twoway (scatter price mpg) (lfit price mpg)
webdoc graph, figure(price-by-mpg)
Code
6.png

To automate cross-referencing in larger documents it may be convenient to maintain a counter for your graph IDs. An example is as follows:

webdoc init, header(width(700px))
local gr 0

webdoc put <p><a href="#gr-`++gr'">Figure `gr'</a>
/*** displays a scatter plot of price by milage. </p> ***/

webdoc stlog
    sysuse auto
    twoway (scatter price mpg)
webdoc stlog close
webdoc graph, figure(gr-`gr') caption(Figure `gr') cabove

/*** <p> To further analyze the relation between price by milage, we can 
add a linear fit to the plot ***/
webdoc put (<a href="#gr-`++gr'">figure `gr'</a>).</p>

webdoc stlog
    sysuse auto
    twoway (scatter price mpg) (lfit price mpg)
webdoc stlog close
webdoc graph, figure(gr-`gr') caption(Figure `gr') cabove
Code
7.png