Images

View the underlying source code to understand how this page was composed at: https://github.com/HandsOnDataViz/book/blob/master/17-bookdown.Rmd

Create high-resolution color screenshots and other static images in .png or .jpg format, with tight cropping on a high-resolution Retina monitor, typically at 144 ppi. Save items into the images subfolder by chapter. Make sure that color images include high contrast and/or shading, because they will be converted to grayscale by the publisher for the print book. Write file names in lowercase with dashes (not spaces) and begin with keyword of relevant section to keep related images grouped together. Despite being in separate folders, avoid duplicate image file names across the book. Avoid numbering images since they may not match the final sequence.

If a screenshot requires additional artwork or text for the HTML edition, make a copy of the original and add -ann to note that this version is annotated, save into the same folder with the same root file name, and use in the code-chunk image pathnames. The publisher will use the original image and add their own artwork for their editions.

If an image is larger than approximately 300px on either side, one more option is to reduce the image size in the PDF version. Use Photoshop (not Preview) to reduce the image size, and save a copy with the same file name with the .pdf extension into the folder.

In some cases (such as images inside Markdown tables, or static screenshots to accompany iframes), it may make sense to save a full-size version, with -original in the file name, for the publisher to use when creating the print book.

Overall, sometimes the folder will contain only one version of a simple image, but in other cases it may contain up to 3-4 versions of an image:

images/05-chart/design-setup.png
images/05-chart/design-setup-ann.png
images/05-chart/design-setup-ann.pdf
images/05-chart/design-setup-original.png

If creating images to appear as the same size in sequence, add a code-comment with the image width, height, and resolution as a reminder to make others match up, like this:

<!-- Images below are 200x200 at 300 resolution -->

In this book, use Markdown formatting only for images that appear inside tables or do not require captions or figure numbering, and leave the caption field blank, like this example:

Co-Authors About Us
About Jack Dougherty
About Ilya Ilyankou

Although Markdown formatting offers a simple syntax that easily converts into other formats with Bookdown/Pandoc, there is no auto-numbering in the HTML edition, while auto-numbering appears in the PDF edition, and numbered figures are required by the publisher. Furthermore, Markdown formatting does not allow conditional output.

Images using R code-chunks

For these reasons, this book primarily uses R code-chunk formatting for images. The syntax is more complex but supports auto-numbering in HTML and PDF, and conditional output for interactive and static images. Note that static R code-chunk images convert to Markdown, but interactive images do NOT convert and need to be manually edited in the modified file, described further below.

Auto-numbering appears in Figure x.x format in HTML and PDF, but Figure x format in MS Word and Markdown. Note that Word formatting can be changed with reference.docx.

Note that images in PDF output will “float” by design and may appear before or after the desired page, so always add a cross-reference call-out.

Write R code-chunk labels that follow the image file name, and avoid duplicate labels across the book:

ref:design-setup

images/05-chart/design-setup.png

Do not insert spaces inside the ref:chunk-label for the caption, but add a blank line to separate it from the code-chunk. After the code-chunk, add another blank line to avoid “undefined reference” Bookdown errors.

Inside the R code-chunk ref caption, do NOT use mischievous characters (such as < or > or ") that will throw HTML errors into the Markdown output images. Instead, use safe characters such as (* and -) to designate computer instructions, such as File - Make a Copy.

For each figure, manually add a cross-reference call-out and insert fig.pos='h' to place the image “here” on the page in the PDF output, to attempt to avoid PDF floating. Ignore the Bookdown LaTeX warning message “h float specifier changed to ht.” See more at https://bookdown.org/yihui/bookdown/figures.html and https://bookdown.org/yihui/rmarkdown-cookbook/figure-placement.html

This Bookdown index.Rmd file includes two global R code-chunk settings immediately after the first header. One setting displays each code-chunk image without a code echo. The other setting automatically inserts the PDF version of an PNG/JPG image, whenever it exists, in the PDF output, which allows us to manually reduce the image sizes for the PDF book. Read more about these options in this Bookdown chapter: https://bookdown.org/yihui/bookdown/figures.html.

{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)
options(knitr.graphics.auto_pdf = TRUE)

Demo: R code-chunk for small static image for HTML and PDF editions

Small is defined as each side less than 300px, as shown in Figure D.1.

Caption here. Markdown embedded links are acceptable.

Figure D.1: Caption here. Markdown embedded links are acceptable.

R code-chunk for larger static image using out.width and PDF img

For larger images, where one side is greater than 300px, set the out.width to a pixel number for ideal display in the HTML edition. Also optional to reduce float in PDF: fig.pos='h',. If necessary, copy the image, use Photoshop to create a smaller image size, and save with same file name and a .pdf extension for auto-substitution in the PDF output …as shown in Figure D.2.

Using out.width=200 and smaller PDF image size.

Figure D.2: Using out.width=200 and smaller PDF image size.

R code-chunks allow more complex conditional formatting, where an interactive map or animated GIF or YouTube video clip appears in the web version, and a static image with an embedded link appears in the PDF and MS Word outputs. To change the height of the default 400px iframe, add the new height to include_url as shown in the examples. However, to change the width of the default 675px iframe to less than 100 percent, add a line in a custom-scripts.html file.

Demo: R code-chunk for iframe in HTML and static image in PDF

…as shown in Figure D.3.

Figure D.3: Caption here, and add embedded link to explore the full-screen interactive map.

Demo: R code-chunk for animated GIF in HTML and static image in PDF

When appropriate, create animated GIF files using Camtasia, and add fade-to-black to mark the end-point in the looped version. Add …as shown in Figure D.4.

Figure D.4: Caption here, with embedded link to the animated GIF.

Demo: R code-chunk for Youtube video in HTML and static image in PDF

Be sure to use the embed link from the YouTube share button.

…as shown in the video D.5.

Figure D.5: Caption here, with embedded link to the YouTube video.

Demo: R code-chunk for YouTube video in HTML, with NO static image in PDF

This option may be relevant when you wish to display a video only in the HMTL edition, with no screenshot of it in the PDF edition. Note that this will alter figure-numbering between the HTML and PDF editions.

Figure D.6: Caption only for HTML version, with embedded link to the YouTube video.