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


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. Adding figure numbers and captions
To add captions to the figures you make you need to add the argument `fig.cap="my caption"` to your R chunk that creates the figure. If you have two or more figures created in the R chunk then give the `fig.cap` argument a vector of captions. See the Markdown file to see how this is done for the figures created below. 

If you are knitting to a pdf, you don't need to add "Figure 1", etc. numbering to the figure captions (they will be numbered automatically). For HTML and Word output types, you need to manually number figures. 

## 2. Resizing graphs in Markdown

Suppose we want to create a boxplot  of calories per gram grouped by cereal type and a scatterplot of calories vs. carbs per gram.  Here are the basic commands without any extra formatting that create Figures 1 and 2: 

```{r, fig.cap="Figure 1: Distributions of calories per gram by cereal type"}
boxplot(calgram ~ type, data=Cereals, main="Calories by type", ylab="Calories per gram")
```
```{r, fig.cap="Figure 2: Calories vs. Carbs per gram"}
plot(carbsgram ~ calgram, data=Cereals, main="Carbs vs Calories")
```

We can add `fig.height` and `fig.width` parameters to the Markdown R chunk to resize the output size of the graph. The size inputs used here are a height of 3.5 inches and a width of 6 inches. (See the .Rmd file to see where to place these arguments.) The command below creates Figures 3 and 4. 

```{r, fig.height=3.5, fig.width=5, fig.cap=c("Figure 3: Distributions of calories per gram by cereal type","Figure 4: Calories vs. Carbs per gram")}
boxplot(calgram ~ type, data=Cereals, main="Calories by type", ylab="Calories per gram")
plot(carbsgram ~ calgram, data=Cereals, main="Carbs vs Calories")
```



## 3. Changing graph formatting in R
You can use the `par` command to change R's graphical parameter settings. There are many options that can be changed, but one of the most useful is to change the layout of the graphical output display. The argument `mfrow` (multi-frame row) is given a vector `c(nr, nc)` that draws figures in an `nr` (number of rows) by `nc` (number of columns) array. We can arrange our two graphs in a 1 by 2 display (1 row, 2 columns) with the command:

```{r, fig.height=4, fig.width=7, fig.cap="Figure 5: Distribution of calories per gram  by cereal type and calories vs. carbs per gram."}
par(mfrow=c(1,2))
boxplot(calgram ~ type, data=Cereals, main="Calories by type", ylab="Calories per gram")
plot(carbsgram ~ calgram, data=Cereals, main="Carbs vs Calories")
```


## 4. Hiding R commands
You can omit R commands from your final document by adding `echo=FALSE` to your R chunk argument. Any output produced by your command (graphical or numerical) will still be displayed. For example, the following command (which you can only see in the .Rmd file) creates Figure 6, a boxplot of carbs per gram by cereal type.

```{r, echo=FALSE, fig.cap="Figure 6: Distributions of calories per gram and shelf placement by cereal type", fig.height=3, fig.width=4}
boxplot(carbsgram ~ type, data=Cereals, main="Carbs by type", ylab="Carbs per gram")
```

## 5. Global changes in graph format
The R chunk options that control graph sizes and output features (like `echo`) can be set globally for **all** R chunks either in the header (like with `fig.caption`) or in an `opts_chunk$set()`  command at the start of the .Rmd file. I usually opt for setting global features with the `opts_chunk ` command which you often see at the start of my .Rmd files. Any global settings, like `echo` or `fig.height`, can be overridden locally by changing them in individual chunks. 

## 6. Comments: 

- Markdown is very sensitive to spaces, or lack-there-of. If you get odd formatting issues, try adding a spaces between R chunks, paragrahs, lists, section headers, etc. For example,  you always need a space between an R chunk or text and a section header. 

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