4.1 Colored callouts

The stylesheet includes style code for “callout” sections. These were adapted from the HTML stylesheets in the bootstrap project.

A colored callout must begin as a level-4 markdown heading. The syntax begins with ####, and then after that some syntax that is, actually, HTML style code, is included. The colors for which we have provided are “gray”, “red”, “orange”, “blue”, and “green”.

```
#### Gray Callout {.bs-callout .bs-callout-gray}
```

```
#### Red Callout {.bs-callout .bs-callout-red}
```

```
#### Orange Callout {.bs-callout .bs-callout-orange}
```

```
#### Blue Callout {.bs-callout .bs-callout-blue}
```

```
#### Green Callout {.bs-callout .bs-callout-green}
```

dat <- data.frame(x=rnorm(1000), y=rpois(1000, l=7))
summary(dat)

       x                   y         
 Min.   :-3.128437   Min.   : 0.000  
 1st Qu.:-0.647860   1st Qu.: 5.000  
 Median : 0.054540   Median : 7.000  
 Mean   : 0.005542   Mean   : 6.809  
 3rd Qu.: 0.691346   3rd Qu.: 8.000  
 Max.   : 2.786802   Max.   :17.000  

hist(dat$x, xlab = "Monkey Weight (deviations)", main = "Histogram", prob = TRUE, ylim = c(0, 1))

4.2 Interactive Tabs

This is the only feature that truly differentiates the HTML backend from PDF. The user can “interact” with the tabs. The major benefit is that a section in which there are, say 5, large subsections, can be made to seem shorter by “hiding” the subsections under the tabs.

In our style sheet, tabs are created in two steps. First, a level two markdown header (##) is introduced with the flag {.tabset .tabset-fade}. The tabs within that group are created by level 3 headers (###). To close down the tabbed section, it is necessary to introduce a new level 1 or 2 header.

Please note it is VERY IMPORTANT to include a blank line before a new tabbed section begins. If the line is omitted, then the new section will not be created properly.

4.4 We need to fix up the style a little bit

The “hidden” subsections are labeled, but not vividly, and our CSS is to blame. Or the CSS inherited from others is inadequate. Also we need to more easily color and dramatize these tabs. As discussed next, some raw HTML markup is needed to obtain colors.

## A level-2 heading launches a new tabset, with color via HTML markup {.tabset .tabset-fade}

### <span style="color:orange">An orange tab</span>

4.6 Inserting images: Use HTML code

Pictures or graphics can be inserted into Rmarkdown documents. The usual markdown syntax for image inserts is

![alt text](image/location/file.png "Image Title Text")

That syntax is somewhat limiting, mostly because we cannot resize the images. Another limitation is that some graphics formats are not allowed. The suggested file formats are svg, png, and jpg, so graphics in pdf will not be usable as is.

To resize images, we need to resort to raw HTML code, which seems somewhat disappointing to many authors. HTML allows rescaling. We can specify both the width and the height of the image. In this example code, a png format file named “plot1.png” is inserted in the document.

<img src="ext_img/plot1.png" alt = "Floating .png"
  width  = "308"
  height = "216">

Authors who need to use graphics saved in other formats will need to convert to png, jpg, or svg. The Gold standard of format converters is the convert function of the ImageMagick suite of tools. It is also possible to open a PDF in some editors, such as the GNU Image Manipulation program (GIMP), and save as an image format. There are some websites that might be useful for this purpose, such as https://pdf2png.com.

4.7 International characters

If you can figure out how to insert characters with accents, they will display correctly. For example, Karl Gustav Jöreskog, Dag Sörbom, and Linda Muthén and Bengt Muthén. These are entered at the keyboard using editor-specific tools.

5.1 Chunks that do not generate graphics

1. A chunk that is evaluated, echoed, both input and output. This is a standard chunk, no chunk options are used:

   The user will see both the input code and the output, each in a separate box:

   set.seed(234234)
   x <- rnorm(100)
   mean(x)

   [1] -0.1004232

   Notice the code highlighting is not entirely successful, and is different from results we see in other backends.

2. A chunk with commands that are echoed into the document, but not evaluated (eval=F).

   When the document is compiled, the reader will see the depiction of the code, which is (by default) beautified and reformatted:

   set.seed(234234)
   x <- rnorm(100)
   mean(x)

3. A chunk that is evaluated, with output displayed, but code is not echoed (echo=F). It is not necessary to specify eval=T because that is a default.

   The user will not see any code that runs, but only a result:

   [1] 0.2024592

4. A hidden code chunk. A chunk that is evaluated, but neither is the input nor output displayed (include=F)

   What is the grammatically correct way to say “did you see nothing?” You should not even see an empty box? After that, the object x exists in the on-going R session, it can be put to use.

5.2 Chunks with graphics

5. A chunk that creates a graph, and allows it to be inserted into the document, but the code is not echoed for the reader to see.

   

6. Save a graph in a file and display it at a later point.

   This can be acheived by specifing: fig.show=“hold”, echo=F. Optionally we can specify the height and width of the figure with fig.height and fig.width (which are always in inches). The file will be saved in the current working directory.

   hist(x, main = "Another Histogram")

7. A chunk that shows a series of plotting commands.

   This is a named chunk that is not evaluated, but it is displayed to reader. The same code is then put to use twice in what follows.

   par(mar = c(3,2,0.5,0.5))
   cax <- 0.7 ## cex.axis
   plot(c(0, 1), c(0, 1), xlim = c(0,1), ylim = c(0,1), type = "n", ann = FALSE, axes = FALSE)
   rect(0, 0, 1, 1, col = "light grey", border = "grey")
   axis(1, tck = 0.01, pos = 0, cex.axis = cax, padj = -2.8, lwd = 0.3,
         at = seq(0, 1, by = 0.2), labels = c("", seq(0.2,0.8, by=0.2), ""))
   axis(2, tck = 0.01, pos = 0, cex.axis = cax, padj = 2.8, lwd = 0.3,
        at = seq(0, 1, by = 0.2), labels = c("", seq(0.2,0.8, by=0.2), ""))
   mtext(expression(x), side = 1, line = 0.5, at = .5, cex = cax)
   mtext(expression(y), side = 2, line = 0.5, at = .5, cex = cax)
   mtext(c("Min x", "Max x"), side = 1, line = -0.5, at = c(0.05, 0.95), cex = cax)
   mtext(c("Min y", "Max y"), side = 2, line = -0.5, at = c(0.05, 0.95), cex = cax)
   lines(c(.6, .6, 0), c(0, .6, .6), lty = "dashed")
   text(.6, .6, expression(paste("The location ",
                   group("(",list(x[i] == .6, y[i] == .6),")"))), pos = 3, cex = cax + 0.1)
   points(.6, .6, pch = 16)

   The first re-use of this code simply runs the whole chunk, and keeps the final figure. This figure is a png file that is embedded in the HTML document.

   

   A Special Figure

   A special feature of knitr is the ability to keep the intermediate plots that are produced by each line. An inspection of the tmpout directory shows that this code created several graphs. Observe there are several files:

   list.files("tmpout", pattern="p-chunk76.*png") 

    [1] "p-chunk76-1.png"  "p-chunk76-10.png" "p-chunk76-11.png"
    [4] "p-chunk76-2.png"  "p-chunk76-3.png"  "p-chunk76-4.png" 
    [7] "p-chunk76-5.png"  "p-chunk76-6.png"  "p-chunk76-7.png" 
   [10] "p-chunk76-8.png"  "p-chunk76-9.png" 

   In a way that is rather similar to the PDF backend, we use a backend-specific table structure to display four of the images. The display of the table’s caption is controlled by the style sheet.

<table border="0" cellpadding="0">
<caption>Figure: Table Array of Four Graphics</caption>
<tr><td><img src="tmpout/p-chunk76-4.png" height=350 width=350 alt = "a png"></td>
<td><img src="tmpout/p-chunk76-8.png" height=350 width=350 alt = "b png"></td></tr>
<tr><td><img src="tmpout/p-chunk76-9.png" height=350 width=350 alt = "c png"></td>
<td><img src="tmpout/p-chunk76-11.png" height=350 width=350 alt = "d png"> </td></tr>
</table>

Figure: Table Array of Four Graphics

5.3 Chunks with tables

Markdown includes a rather crude table-making syntax. We used it above in to display the purpose to color relationship of the colored callout boxes. For most serious analysis, that type of table will not be sufficient.

The chunk option results="asis" is used to display HTML markup that can be created by R functions. The cascading style sheet will play an important role in the final display. If we are unhappy with the rendering of the tables, we should concentrate on fixing the CSS, rather than finger-painting borders and such. While working on this project we discovered a flaw in the pandoc processing engine that caused tables to fail. If the HTML generated by the chunk includes spaces, pandoc can be fooled into thinking the text is markdown rather than HTML.

8. Using results=“asis” to display HTML markup: Regression Tables

There are many packages that can create near-publication-quality regression tables. Here is an example of the rockchalk package can create HTML code for a regression table. In this case, we run the code chunk to generate the HTML code, and then we have to manually purge the extra spaces in the output so that pandoc will not corrupt the output.

cat(or1)

9. General purpose HTML output from the pander package

The package pander offers flexability and functionality. It can display an R table, the coefficient object generated by a regression summary

library(pander)    
sum <- summary(m1)
pander(sum$coefficients)

and it can also display a matrix created by the package psyc

library(psych)
pander(describe(dat))

6.1 Equation Numbering

In “display equation” mathematics, we want to insert numbered equations and then refer to them. Unfortunately, Rmarkdown to HTML does not support auto-numbering equations. However, one can number equations manually by adding\tag{} to the end of equations. For example,

\[ + - = \approx \ne \ge \lt \pm\tag{1} \]

\[ \pi \approx 3.1415927\tag{2} \]

\[ a_i \ge 0~~~\forall i\tag{3} \]

\[ x \lt 15\tag{4} \]

Unfortunately, when new equations are inserted, it will be necesssary to manually renumber these. In addition, there is no HTML backend method to then refer to equation (3) without explicitly typing in the equation number.

6.2 Cross references

HTML does offer its own form of cross referencing by hyperlink anchors, however. Suppose we want the reader to be able to click a link that goes to a figure that we have presented previously. We go that that figure and insert HTML code along these lines:

<a name="specialfig"></a>

When we want to write something like click here to see the special figure", the HTML markup is

<a href="#specialfig">click here to see the special figure</a>