---
title: "Annotation: Text in Stata Graphs"
author: "Doug Hemken"
date: "October 2015"
output: 
  html_document:
    includes:
      after_body: ../Rmd/bottomRmdKB.html
      before_body: ../Rmd/topRmdKB.html
      in_header: ../Rmd/headRmdKB.html
    self_contained: no
    theme: null
    toc: yes
---
```{r setup, echo=FALSE, message=FALSE}
require(knitr)
# Figure out which version of Stata is available
if (file.exists("C:/Program Files (x86)/Stata14/StataMP-64.exe")) {
  statapath <- "C:/Program Files (x86)/Stata14/StataMP-64.exe"
  } else if (file.exists("C:/Program Files (x86)/Stata14/StataSE-64.exe")) {
    statapath <- "C:/Program Files (x86)/Stata14/StataSE-64.exe"
    }

# Set universal chunk options
opts_chunk$set(engine="stata", engine.path=statapath, comment="", results="hide")

# Define a "codecollect" chunk option
knit_hooks$set(collectcode = function(before, options, envir) {
  if (!before) {
    profile <- file("profile.do", open="at")
    writeLines(options$code, profile)
    close(profile)
  }
})

# Always hide some Stata commands in the echoed source,
#   e.g. "graph export"
source_hook <- knit_hooks$get("source")
knit_hooks$set(source = function(x, options) {
    y <- strsplit(x, "\n")[[1]]
    # Find and remove graph export in Stata source
    graphexport <- grep("^graph export.*", y)
    if (length(graphexport)>0) {y <- y[-(graphexport)]}
    graphcombine <- grep("^graph combine.*", y)
    if (length(graphcombine)>0) {y <- y[-(graphcombine)]}
    # Now treat the result as regular source code
    source_hook(y, options)
})
# Always clean Stata commands from the output
hook_output <- knit_hooks$get("output")
knit_hooks$set(output = function(x, options) {
    y <- strsplit(x, "\n")[[1]]
    # Find output lines that are commands
    commandlines <- grep("^\\.", y)
    if (length(commandlines)>0) {y <- y[-(grep("^\\.", y))]}
    # Some commands have a leading space?
    if (length(grep("^[[:space:]*]\\.", y))>0) {
      y <- y[-(grep("^[[:space:]*]\\.", y))]
    }
    # Ensure a trailing blank line
    if (length(y)>0 && y[length(y)] != "") { y <- c(y, "") }
    # Remove blank lines at the top of the Stata log
    firsttext <- min(grep("[[:alnum:]]", y))
    if (firsttext != Inf) {y <- y[-(1:(firsttext-1))]}
    # Now treat the result as regular output
    hook_output(y, options)
})
```

# Introduction

Without text, a statistical graph has no meaning.  We typically
want to provide the reader with guides to interpreting the
position and types of graphical objects used - scale and
legend annotation.  It is also good practice to include
titles, captions, and/or notes.

We may also want to add text directly to the plot area.

Almost all the control over the text in a graph lies outside the
primary part of the graphics commands.  Text generally comes from
variable labels, value labels, statistical transformations provided
by the graphics routine, or the distribution of data values.  Within
a graphics command, control over annotation lies mainly in *options*.

There are scores if not hundreds of options that can be applied to
any graph, so it is useful to become familiar with the Stata
documentation - you **will** be using it!

We'll start with familar data, and add a categorical variable
with many categories.

```{r, collectcode=TRUE}
sysuse auto
generate maker = substr(make, 1, strpos(make, " ")-1)
replace maker = make if strpos(make, " ")==0
label variable maker "Manufacturer"
```

## Annotation Outside the Plot Region

### Titles, Subtitles, Notes, Captions

```{r}
scatter mpg weight, title("Gas Mileage") subtitle("Decreases with Weight") ///
    note("1978 data") caption("Figure 1: adding text in the margins")
graph export "StataGraphAnnotation_files/titles.png"
```

See `help title_options`.

There are numerous options here that can be used to style the text
itself. These include using extended character sets (including
math symbols), specifying font face and size, repositioning text, color, etc..

![titles](StataGraphAnnotation_files/titles.png)

## Axis Titles

Notice the axis labels are just the variable labels.  We can relabel
our data (`help variable label`), or we can have arbitrary
axis labels (`help axis_title_options`) that only affect our plot.

```{r}
scatter mpg weight, xtitle("Weight in pounds") ytitle("Miles per gallon")
graph export "StataGraphAnnotation_files/xtitle.png"
```

![xtitles](StataGraphAnnotation_files/xtitle.png)

In plots with categorical axes we do not have a categorical title
by default, and we are not allowed to use `xtitle()`, but we can use
`b1title()` instead.

```{r}
graph bar weight, over(maker) name(g1)
* graph bar weight, over(maker) xtitle("Manufacturer") // error
graph bar weight, over(maker) b1title("Manufacturer") name(g2)
graph combine g1 g2
graph export "StataGraphAnnotation_files/catxtitle.png"
```

![Categorical xtitles](StataGraphAnnotation_files/catxtitle.png)

```{r, engine='R', echo=FALSE, message=FALSE}
  unlink("profile.do")
```