---
title: "Formatting Numerical output in Markdown"
author: "Katie St. Clair"
output: html_document
---
```{r, include=FALSE}
knitr::opts_chunk$set(collapse=TRUE, prompt=TRUE, comment=NULL)
```

This handout gives some basic ways to format numerical output produced in your R chunks.  Some of the methods mentioned below might only work when knitting to a PDF.  Additional info about formatting text in R Markdown can be found online:

- <http://rmarkdown.rstudio.com/authoring_basics.html>
- <http://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>
- <http://rmarkdown.rstudio.com/pdf_document_format.html>

In homework or R appendices, I expect to see both the commands and output produced by those commands as your "work" for a problem. But in reports, as in any formal research paper, you should not include R commands or output (except for graphs). This handout is designed, primarily, to help you format numerical results to present into your written *reports*.

The data set Cereals contains information on cereals sold at a local grocery store. 
```{r}
# load the data set from Collab 
Cereals <- read.csv("http://math.carleton.edu/Stats215/RLabManual/Cereals.csv")
```

## 1. Hiding R commands and R output
As mentioned in the graph formatting handout, adding the chunk option `echo=FALSE`  will display output (like graphs) produced by a chunk but not show the commands used in the chunk.  You can stop **both** R commands and output from being displayed in a document by adding the chunk option `include=FALSE`. 

As you work through a report analysis, you may initially want to see all of your R results as you are writing your report. But after you've summarized results in paragraphs or in tables, you can then use the `include=FALSE` argument to hid your R commands and output in your final document. If you ever need to rerun or reevaluate your R work for a report, you can easily recreate and edit your analysis since the R chunks used in your original report are still in your R Markdown .Rmd file.


## 2. Markdown tables

The Markdown language allows you to construct simple tables using vertical lines `|` to separate columns and horizontal lines `-` to create a header. Make sure to include at least one space before and after your Markdown table or it will not format correctly. I can't find an easy way to attached an automatic table number and caption to this type of table, so I've simply written (and centered) the table number and caption by hand for the table below. 

Suppose we want to present the 5-number summary of calories per gram by cereal type. The  `tapply` command can be used to obtain these numbers.  
```{r}
tapply(Cereals$calgram, Cereals$type, summary)
```
See the Markdown .Rmd file for this handout to see how to construct Table 1 below. 

Table 1: Five-number summary of calories per gram by cereal type.

Type | Min | Q1 | Median | Q3 | Max 
---- | --- | --- | --- | --- | ---
Adult | 2.0 | 3.2 | 3.5 | 3.7 | 4.6 
Children | 3.6 | 3.9 | 4.0 | 4.1 | 4.5

## 3. Markdown tables via `kable`
The R package `knitr` contains a simple table making function called `kable`. You can use this function to, say, show the first few rows of a data frame:
```{r}
library(knitr)
kable(head(Cereals), caption="Table 2: Cereals data (first 6 cases)")
```

Or you can use `kable` on a two-way table of counts or proportions:
```{r}
kable(table(Cereals$brand, Cereals$type), caption="Table 3: Cereal brand and type")
```

This function doesn't work well with other types of output, like summary output, but we can use other more sophisticated packages for more complicated output. 


## 4. Using R packages to generate tables: the `pander` package
The R package `pander` creates simple tables in R that do not need any additional formatting in Markdown. If `pander` is not in your RStudio package list, then you will need to install the package or run the command `install.packages("pander")` before compiling your Markdown document. 

The `pander()` function takes in an R object, like a summary table or t-test output, and outputs a Markdown table. You can add a `caption` argument to include a table number and title. Here is a table for the summary of calories per gram (Table 4):
```{r}
library(pander)
pander(summary(Cereals$calgram), caption="Table 4: Summary statistics for calories per gram.")
```

Pander can format tables and proportion tables. Here is the table for cereal type and shelf placement (Table 5), along with the distribution of shelf placement by cereal type (Table 6). 
```{r}
my.table <- table(Cereals$type,Cereals$shelf)
pander(my.table,round=3, caption="Table 5: Cereal type and shelf placement")
pander(prop.table(my.table,1),round=3, caption="Table 6: Distribution of shelf placement by cereal type")
```


Here are t-test results for comparing mean calories for adult and children cereals (Table 7):
```{r}
pander(t.test(calgram ~ type, data=Cereals), caption="Table 7: Comparing calories for adult and children cereals")
```

Here are chi-square test results for testing for an association between shelf placement and cereal type (Table 8). Note that the `simulate.p.value` option was used to give a randomization p-value since the sample size criteria for the chi-square approximation was not met. 
```{r}
pander(chisq.test(my.table, simulate.p.value = TRUE),caption="Table 8: Chi-square test for placement and type")
```

Here are the basic results for the regression of carbs on calories (Table 9).
```{r}
pander(lm(carbsgram ~ calgram, data=Cereals), caption="Table 9: Regression of carbs on calories")
```



## 5. Using R packages to generate tables: the `stargazer` package
The `stargazer` package, like `pander`, automatically generates Markdown tables from R objects. The `stargazer` function has more formatting options than `pander` and can generate summary stats from a data frame table. It can also provide nicely formatted comparisons between 2 or more regression models. See the help file `?stargazer` for more options. 

To use the `stargazer` package you may have to first install it `install.packages("stargazer")` before compiling your Markdown document. You will need to add the R chunk option `results='asis'` to get the table formatted correctly. I also include the `message=FALSE` option in the chunk below that runs the library command to suppress the automatic message created when running the `library` command with `stargazer`. When you give `stargazer` a data frame, it gives you summary stats for all numeric variables in the data frame (Table 10):
```{r,  results='asis', message=FALSE}
library(stargazer)
stargazer(Cereals, type="html", title="Table 10: Default summary stats using stargazer")
```

The default table `type` is `"latex"` which is the format you want when knitting to a pdf document. When knitting to an html document we need to change `type` to `"html"`. Unfortunately, there is no `type` that works nicely with Word documents so you would be better off using `pander` if you want a Word document. 

Note: When using the `latex` type and knitting to a pdf, you will get an annoying stargazer message about the creation of your latex table. Include the argument `header=FALSE` in the `stargazer` command to suppress this message when knitting to a pdf.

You can subset the Cereals data frame to only include the variables (columns) that you want displayed. In Table 11 we only see calories and carbs. You can also edit the summary stats displayed by specifying them in the `summary.stat` argument. See the `stargazer` help file for more stat options. 
```{r, results='asis'}
stargazer(Cereals[,c("calgram","carbsgram")], type="html", title="Table 11: Five number summary stats", 
          summary.stat=c("max","p25","median","p75","max"))
```

The `stargazer` package was created to display results of statistical models. Here is the basic display for the regression of carbs on calories (Table 12). The argument `single.row` puts estimates and standard errors (in parentheses) in one row. There are many options that can be tweaked, like including p-values or confidence intervals.  
```{r, results='asis'}
my.lm <- lm(carbsgram ~ calgram, data=Cereals)
stargazer(my.lm, type="html", title="Table 12: Regression of carbs on calories", single.row=TRUE)
```

Table 13 adds the argument `keep.stat` to specify that only sample size and $R^2$ should be included in the table. See the help file for more options to this argument. 
```{r, results='asis'}
stargazer(my.lm, type="html", title="Table 13: Regression of carbs on calories", single.row=TRUE, 
          keep.stat=c("n","rsq"))
```


------
*(St. Clair, Sept 2017)*
