Alison Hill, PhD

The Theseus Benchmarks Report

Wed, 01 May 2024 00:00:00 +0000

The Benchmarks Report is a deep dive into how and why Voltron Data does benchmarking differently, and presents data comparing compute performance of our engine, Theseus, to Spark.

I led the development of the report, which involved industry/market research, subject matter expert interviews with engineers, and cross-functional strategic storytelling alignment with founders. I also drove the development of the interactive data visualizations, which were created by the talented Tanya Shapiro. This report defined our first feature launch for the Theseus engine in spring 2024, announced at Nvidia’s GTC conference.

The Composable Codex

Wed, 01 May 2024 00:00:00 +0000

The Composable Codex is a 5-part guide to building composable data systems layer by layer with open standards like Apache Arrow. I researched, wrote, and designed the Codex as part of my role on Voltron Data’s Go-To-Market Strategy team. This initiative was the onramp to our first product launch for the Theseus engine in fall 2023.

The happiest notebooks on Earth

Thu, 10 Nov 2022 13:00:00 +0000

Notebooks hold a special place in every data scientist’s heart. They may treasure every moment creating their own, or commenting on others’ notebooks. Or they may sincerely and truly hate notebooks. But notebooks are useful. How could we “imagineer” better notebooks? I’ve made and read hundreds of notebooks in the past decade. In this talk, I share key principles for developing happier notebooks – ones that are more fun to write, more fun to read, and more fun as an onramp to the next ride.

The happiest notebooks on Earth

Thu, 27 Oct 2022 18:50:00 +0000

The untold story of palmerpenguins

Tue, 21 Jun 2022 08:45:00 +0000

The palmerpenguins R package provides a modern, approachable dataset containing body size measurements for three penguin species that nest on islands throughout the Palmer Archipelago, Western Antarctic Peninsula. Since palmerpenguins was released on the Comprehensive R Archive Network (CRAN) in July 2020, the package has been downloaded over 340,000 times, was quickly adapted for use in other languages including Python’s seaborn package and Google’s TensorFlow datasets, and has become a go-to option for data science and statistics educators worldwide. In this talk, we share the untold story of the palmerpenguins package. From original data collection on rocky Antarctic shores to CRAN submission and beyond, we describe the penguins’ journey from polar research project to global teaching product. What started out as a simple methods paper for a dissertation project turned into a widely used data science product mainly because of initial efforts to make the data publicly available and easily accessible by others. The success of the palmerpenguins R package underscores the importance of proper data archiving for unknown future applications.

We don't talk about Quarto

Mon, 04 Apr 2022 00:00:00 +0000

Thumbnail image from the Official Disney Fan Club website

Background

Early last year, I was busily checking Quarto, and totally terrified of checking Twitter. Seriously, I held my breath every time. It. Was. Not. Ready. It was changing fast and breaking fast. Everyday I was seeing the GitHub stars slowly creeping up, and I was nervous. And we had all agreed on our team that “We don’t talk about Quarto” on the outside (this was pre- Encanto). That means not a single one of us were tweeting or blogging about it, or even at that point trying to teach it to anyone — yet.

But, things started easing up. By the time summer internship positions at RStudio were announced, I was excited to have reserved a slot for our first Quarto intern, who would be tasked with working with myself, JJ Allaire, and Charles Teague to help get the Quarto docs off the ground. We brought Paul Villanueva on in one of the best hiring decisions I’ve made, and he ended up doing so much more than just docs! By August 2021, I had convinced Paul to join me as a TA to teach the first public Quarto workshop for the R/Medicine. And I honestly felt comfortable teaching Quarto then — it felt like it was time. Luckily, the Quarto team had stabilized releases of Quarto in August before the workshop, and we were able to spin up a custom RStudio Cloud environment to use a preview release of the RStudio IDE, and we were off!

Fast forward to now, and it looks like we are talking about Quarto. I am >6 months from my time at RStudio and I am writing a book with the amazing Rich Iannone about doing data science with R and Quarto, in a Quarto book, and I’ve built an internal knowledge repository for my IBM team with Quarto (these are not R or RStudio users!). So in this post, I thought I’d finally share my notes to myself after testing and teaching Quarto, and now as a user and enabler.

Mirabel sliding down the stairs in Encanto

What actually is Quarto?

So thanks for the blog post Alison, but what actually is Quarto?

That is a great question. Four things:

It is a way to render plain text source files that contain code written in Python, R, or Observable.
- If you want to use Python, you don’t need to install R or RStudio.
- If you want to use R, you don’t have to install Python.
- If you want to use Observable, you just can in a Quarto document or project.
In any language, when you render, you execute the code and include plots, tables, and other results in your output woven together with narrative text. So it is still “literate programming.”
When you render, you can export to over 40 different output formats, all enabled by Pandoc.
Quarto adds functionality on top of Pandoc’s markdown language, and the rest of this post will give you some pointers to these features.

Obviously, if you are already an R Markdown user, this will sound pretty familiar but maybe a shade different — yet the software itself is a completely new incantation designed from the bottom up.

What you’ll need to know

Quarto is actually a separate installation.
- What to do? Follow Step 1 to download Quarto for your OS. I do this now regularly about once a week to make sure I’m getting the latest goodies.
- There is also an R package, which will allow you to render at the command line if you aren’t an RStudio IDE/button clicking person, but you could also use the terminal, which is what I do.
Quarto works within the RStudio IDE.
- What to do? Download the latest RStudio IDE release from this link: https://quarto.org/docs/get-started/hello/rstudio.html
- It has actually worked inside the RStudio IDE for almost a year. It was previously supported only in the dailies (which are honestly low-risk to download and use!). But nowadays it works with the latest official released version of the RStudio IDE. I still update my RStudio version to the latest daily whenever I remember to update Quarto.
- It also works in VSCode; see Step 2 here.
The RStudio IDE’s Visual R Markdown Editor was in actuality the first “shots fired” from Quarto. The announcement about the Editor was published 2020/09/30, and the first Quarto commit was only 5 days before on 2020/09/25.
- Fun fact: I forgot to tell our first Quarto intern, Paul, about the visual editor until about 4 weeks into his internship— and it totally changed his outlook, even as an experienced Markdown user. So don’t sleep on the visual editor when teaching and using Quarto. In particular, don’t miss:
  - Easy editing/formatting of Markdown tables
  - Copy/paste from Google docs (did you know this? Literally just copy any formatted text from Google docs and paste it into the visual editor)
  - Citations
  - The “insert anything” keyboard shortcut
  - Emojis 🥰

What you’ll like

Across all formats:

Two column (and more) flexible content layouts for displaying images, code, text, tables, plots, anything. This to me was the “one killer feature” when JJ first started showing me regular demos — I was floored. While patchwork can get you pretty far, this allows for literally anything (including just blank space) to be in any position, making it a layout swiss army knife.
Global chunk options set in your YAML using the execute key (no more knitr setup chunk!). See all supported chunk options (that go beyond knitr ones) here.
```
---
title: "We don't talk about Quarto"
subtitle: "Until now!"
execute:
  echo: false
---
```
Instead of:

```{r}
#| label: setup
#| include: false
knitr::opts_chunk$set(echo = FALSE)
```

Easier verbatim chunks using echo: fenced as a code chunk option when you want to show and execute and double curly braces like {r} for show and don’t execute (this was also improved in knitr too recently).

For example, in the first chunk, I am using this chunk option here (invisibly) to show a chunk where I am suppressing the results printing:

```{r}
#| results: hide
1 + 1
```

```{r}
#| results: show
1 + 1
```

In the chunk just above, I would allow the results to be shown, but because I used {r} as the chunk engine it isn’t evaluated.

Chunk options as YAML with the special hashpipe #| (great for longish alt text) (note that Quarto also added a way to add alt text for Markdown inserted images, thanks to Silvia Canelon)

```{r}
#| label: penguin-plot
#| fig-alt: "Scatterplot of flipper length by bill length of 3 penguin species, where we show penguins with bigger flippers have bigger bills."
#| warning: false
library(palmerpenguins)
library(ggplot2)
ggplot(data = penguins, aes(x = flipper_length_mm,
                            y = bill_length_mm,
                            color = species)) +
  geom_point(aes(shape = species), alpha = 0.8) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) 
```

Universal cross-referencing ( no more bookdown::html_document2(), etc.)
Parameters (side note: here is the first rmarkdown issue from 2014 that Tom Mock and I found where the idea for parameters was “born” 👶)

And, if you are anything like me and your heart belongs to HTML output…

SUBFOLDERS for projects (praise be). Yes you can have a website or book or any other multi-file Quarto project and render content in even deeply nested subdirectories. Rejoice!

To put in your final product, let your heart decide- you can either list as chapters or as parts (similar to bookdown) or use listing pages (like with distill).
Built-in site search (enabled by default for books and websites). Can also be tweaked.
“Batteries included” HTML features across single documents and projects (like HTML books, websites, etc). This may be a RIP to the wonderful “Pimp my Rmd”.
- Here are just a few features that were available in some but not all R packages with .Rmd ▶️ HTML output formats: code folding, copy/paste chunks, callout blocks, TOC on the side, code linking via downlit (previously only available in pkgdown), tabsets, anchored headings
Show source to anyone viewing your HTML output (this was previously only possible with rmarkdown::html_document() - my tweet from when I first discovered this output option!)
Compatibility with Hugo/ blogdown. This post is a .qmd file with format: hugo rendered with Quarto.
```
---
title: "We don't talk about Quarto"
subtitle: "Until now!"
format: hugo
---
```
There is nothing stopping you from using Quarto to render individual posts, then blogdown to use Hugo, or just use Hugo from command line. The Hugo-specific flavor of Markdown ( goldmark) is also supported by the visual editor.

What you’ll stumble on

Chunk options as YAML
```
#| fig-alt: "Scatterplot of flipper length by bill length of 3 penguin species, where we show penguins with bigger flippers have bigger bills."
#| echo: false
#| warning: false
```
- I always forgot the symbol, which is #| (read: the hashpipe). If you also cannot remember this, channel your 90s kid and enjoy this Weezer flashback:
```
    
        
        
          
        
```
- No equal sign, use a colon instead (i.e., comment: '')
- If the value is true/false, use lower case! (no more screaming booleans!) 😱 So echo: false.

To render to a specific format, use the format YAML key (instead of output)¹

---
title: "We don't talk about Quarto"
subtitle: "Until now!"
format: html
---

Use kebab-case 🍡 for all YAML keys and to delimit figure/layout/code chunk options instead of … what we had before.

This will be confusing at first because your knitr chunk options won’t match the package documentation. See here for the change (Quarto will auto-convert fig.alt for example to fig-alt, but still, you or someone you teach might be confused by this).
You’ll be rendering as your verb, not knitting 🧶 but you’ll still be using the knitr package as your engine if you want to use R instead of Python code chunks.
- This also means to watch knitr for news! Follow releases carefully— they will still matter.
For projects like books, websites, blogs, quarto render vs quarto preview. See docs here. Not sure I have advice at this point, but do read this bit:

Note that development server updates do not cause an update to the final site output. Consequently, you should always quarto render your site before deploying it, even if you have already previewed the changes with the development server [with quarto preview].

What you’ll miss (for now)

Defining your own format.
Making and bundling templates that are easily shareable.
Xaringan and remark.js for slides. This particular package and flavor of markdown was never supported in the visual editor because it is not a Pandoc-defined output format (the visual editor is specific to Pandoc-flavored markdown). So for HTML slides in Quarto, reveal.js is where it is at. I had a post about doing that research too (actually all my testing at that time was in Quarto!).

What you (probably) won’t miss

All the packages, each one working slightly different than the ones you had already used. Essentially your experience trying to figure out to work the shower everytime you go to a new hotel, but for each package in the R Markdown ecosystem:

Every dang hotel I've stayed in. pic.twitter.com/xPb7PdwG2f
— Keith Humphreys (@KeithNHumphreys) November 13, 2021

If you are on my blog, you are probably an R Markdown lover. As well you should be. As am I. But who among us has not chased their own tail for hours trying to figure out why one YAML key works over here but not over there. Or perhaps you simply lacked the wherewithall to branch out into the various extension packages because you sensed a rabbit hole ahead. Or maybe you were a person who filed or upvoted GitHub issues begging RStudio folks to just give you tabsets for every single html-based output format. You probably will not miss this.

This one screwed me up so bad, I actually tried to go back to rmarkdown at one point and couldn’t figure out why I couldn’t knit to output_format: html_document 🤦🏻 ↩︎

Empowering women in data (science)

Mon, 21 Feb 2022 10:00:00 +0000

R-Ladies Cologne is kicking off with a roundtable on “Empowering Women in Data (Science)” on February 21, 2022, at 7 pm CET. We are excited to have four fantastic speakers from across the globe working in different fields to share their experiences, tips, tricks, and challenges with us! 🚀

Our four amazing panelists are:

✨ Alison Hill (Ph.D., Senior Data Scientist, AI Strategy & Innovation @IBM)

✨ Ana Carolina Leote (PhD Candidate @ Cologne Graduate School of Ageing Research)

✨ Angélica Becerra (Data Scientist @ cynkra GmbH)

✨ Nina Hauser (Head of Data Literacy @ CorrelAid e.V.)

Tidy your mental models

Tue, 25 Jan 2022 09:00:00 +0000

In this talk, I shared some lessons learned from teaching and learning tidymodels over the past two years.

R Markdown Notebooks for Scientific Communication

Wed, 15 Dec 2021 10:45:00 +0000

Speakers

Alison Hill, RStudio
Fernando Pérez, University of California, Berkeley
Simon Goring, University of Wisconsin / Leah Wasser, Earth Lab at CU Boulder / Laura DeCicco, USGS
Loren Shure, MathWorks
Hugh Shanahan, University of London / RDA
Chris Erdmann, American Geophysical Union
Kenton McHenry or Dan Katz (moderator), University of Illinois

Panel abstract

As science becomes more and more dependent on data and software, capturing these elements of the modern scientific procedure has become critical in achieving reproducibility. Computational notebooks have emerged as an increasingly valued way of capturing not only the traditional elements of a scientific paper but also the software steps in an executable and reproducible manner. As part of the 2020 EarthCube Annual Meeting, the EarthCube office, Leadership Council, and Technical Architecture Committee experimented by issuing a call focused on notebook submissions as peer reviewed publications. The call was well received by the community: 21 Jupyter notebooks were submitted, and 12 of these were accepted for publication. As part of the 2021 call for notebooks, the idea of expanding this call to more types of “notebooks” is being discussed, with the goal of eliciting submissions from a wider group of researchers, who may be more comfortable with other notebook technologies.

The proposed session will bring together representatives from the major “notebook” efforts, efforts such as Jupyter, RStudio, and commercial efforts such as MATLAB live scripts. Presenters will discuss the latest developments in each of their technologies, emphasizing elements that support the notions of ease of use, long-term executability, interoperability, and software publication. Lessons learned from building a geoscience-focused notebook directory, notebook template, and long-term preservation in AGU’s ESSOaR will be discussed as well as how this relates to international efforts to elevate notebooks and make them FAIR.

Talk abstract

In this talk, I’ll describe the R Markdown ecosystem for computational notebooks that support the full lifecycle of scientific communication, including basic reports, presentations, peer-reviewed journal article submissions, and long-form books. The ecosystem has roots in the Pandoc open source project, and includes a family of R packages scientists can use for research.

Introduction to Machine Learning with Tidymodels

Wed, 15 Sep 2021 03:00:00 +0000

Due to COVID-19, the conference was held remotely instead of in Bari, Italy.

This six-hour workshop will provide a gentle introduction to machine learning with R using the modern suite of predictive modeling packages called tidymodels. We will build, evaluate, compare, and tune predictive models. Along the way, we’ll learn about key concepts in machine learning including overfitting, the holdout method, the bias-variance trade-off, ensembling, cross-validation, and feature engineering. Learners will gain knowledge about good predictive modeling practices, as well as hands-on experience using tidymodels packages like parsnip, rsample, recipes, yardstick, tune, and workflows.

Up and running with officedown

Tue, 27 Jul 2021 00:00:00 +0000

Lately, I’ve been exploring the world of R Markdown through the lens of knitting to Microsoft output formats like Word and PowerPoint. I wanted to write down what I’ve learned so far about the officedown package for making PowerPoint (PPT) slides with R Markdown. It is extremely powerful, and I’ve now referred a lot of folks to it, but it was pretty hard for me to grasp at first. These notes are a rough account of my own personal friction log for the next time I use officedown.

Why use officedown?

Why use it? To knit to Microsoft PowerPoint (and Word). Naturally, you might ask, but Alison- there is an rmarkdown::powerpoint_presentation output format already. Yes there is.

Here is a great use case for not using that format though, from Shannon Pileggi:

“I don’t knit directly to ppt b/c editable graphics are key for finishing touches in our deliverables. If we could knit to powerpoint with an editable graphics option like in officer that would be a great feature.”

Issue thread

So officedown is definitely the answer for many users who wish to go beyond what the rmarkdown package can offer. For more on editable graphic workflows with R, Shannon has a great blog post.

What is officedown?

It is a package whose goal is to allows users to write Word and Powerpoint documents using R Markdown. Install from CRAN:

install.packages("officedown")

(It will also download the officer package for you).

Note that the GitHub page for this package does not include an Issues tab: https://github.com/davidgohel/officedown This means there is no way for users to file bug reports, feature requests, etc. This is definitely a developer’s choice, but I’m not sure how to find a community of users for officedown questions or to get help if you suspect a bug. RStudio Community has a tag but only two posts as of today, one of which was asked by an RStudio employee and never answered 😭 : https://community.rstudio.com/tag/officedown

Officedown works with editable graphics by default. This is huge plus for some workflows (like Shannon’s), but also a huge gotcha because it depends on another package that I didn’t know about and that officedown did not import for me: the rvg package. You must install it separately:

install.packages("rvg")

I suspect but cannot confirm that the name of the package is r + vg (vector graphics). Then there is a function in that package that you must use: rvg::dml(), which I can with certainty tell you stands for DrawingML.

What is DrawingML? Oh I’m so glad you asked, here is a link about it: http://officeopenxml.com/drwOverview.php

“DrawingML is the language for defining graphical objects such as pictures, shapes, charts, and diagrams within ooxml documents.”

What is ooxml?

“Office Open XML, also known as OpenXML or OOXML, is an XML-based format for office documents, including word processing documents, spreadsheets, presentations, as well as charts, diagrams, shapes, and other graphical material.”

Want more weird acronyms?

“It is important to keep in mind that OOXML is not the same as Open Office XML or the Open Document Format (ODF) that underlies the OpenOffice.org and other open source office software. Office Open XML and Open Office XML or ODF are in some sense competing XML standards for office documents.”

What is XML?

Learn here: https://learnxinyminutes.com/docs/xml/

Still want more? A brief history here:

https://en.wikipedia.org/wiki/Office_Open_XML_file_formats

Do you need to know much of these acronyms? No, not really, but you’ll want rvg::dml() burned into your brain as you’ll be typing it often.

Where are the docs at?

The creator of the officeverse collection of packages, which officedown is a part of, is named David Gohel. He has a bookdown book with a chapter on officedown, but it is only about Word rather than PPT output:

https://ardata-fr.github.io/officeverse/officedown-for-word.html

For this reason alone, you may not realize you can use officedown to knit to PPT! I certainly didn’t until my colleague Christophe Dervieux gave me enough support to try it on my own.

Here is the documentation for the PPT output format, although I found it minimally helpful: https://davidgohel.github.io/officedown/reference/rpptx_document.html

I also found this video from a recent meetup by the package author helpful to watch:

So how do I use it?

The new output format officedown gives you is:

---
output: officedown::rpptx_document
---

Christophe shared this link with me, and it helped lot: https://github.com/davidgohel/officedown/blob/master/inst/examples/minimal_powerpoint.Rmd

I didn’t realize at first that the package contains built-in R Markdown templates, which is now where I wish I had started. Use RStudio to access: File > New File > R Markdown > From Template then find:

Once you are inside, go ahead and knit freely. I also recommend loading up a reference template sooner rather than later so you aren’t looking at that default deck for long. Here is how you add a reference template:

---
output: 
  officedown::rpptx_document: 
    reference_doc: alison-template.pptx
---

You can download my simple one here: https://github.com/apreshill/rmd2ppt/tree/main/templates

A brief walk through the template

First, you have the packages loaded. Both officedown and rvg are critical here.

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, fig.cap = TRUE)
library(officedown)
library(ggplot2)
library(rvg)
```

If you try to knit the same deck without the officedown package loaded, you will see slides like this:

Figure 1: Two bad slides.

With officedown loaded, you should instead see:

Next up, you’ll see slide number 1 (not to be confused with your title slide, which is populated from the YAML):

## Table

```{r layout='Two Content', ph=officer::ph_location_left()}
head(cars)
```

```{r layout='Two Content', ph=officer::ph_location_right()}
head(iris)
```

The above creates two columns of R-based content. You won’t be able to add normal text to this slide. If you want normal text in one column opposite a plot, scroll down to this text in the template to see how:

## ggplot in right column


- Some
- Bullets

```{r ph=officer::ph_location_right()}
mygg <- ggplot(pressure, aes(x = temperature, y = pressure)) +
  geom_point()
dml(ggobj = mygg)
```

Which produces:

If you only wanted to use Markdown in each column, you’ll need to fall back on Pandoc’s two column syntax:

## Pandoc columns

:::: {.columns}
::: {.column}
over here
:::
::: {.column}
over there
:::
::::

Before you get any further, let’s explain these ph things.

Placeholders

These ph knitr code chunk options are part of the officedown package, so in order to use them you must load the package! ph stands for placeholder, and this is a specific way that Microsoft pours your slide content into a PowerPoint template.

It is essentially a bunch of rectangles on a slide, each called a placeholder. Placeholders typically can hold either text or an image, but not both. For example, in a typical PowerPoint slide like the one above, you can insert either text (often with bullets) or an image – but that is it! The title is text, and is a separate placeholder.

Placeholder values are themselves functions from the officer package with optional function arguments. Now I personally feel that officer::ph_location_left() and officer::ph_location_right() are a little long to type over and over again, which you will. Obviously you could load the officer package at the top, but still that function name is lengthy. I don’t have an answer for simplifying because there is no code completion for knitr chunk options. Maybe snippets?

Technically you can do left vs right with rmarkdown::powerpoint_presentation too, but you have more options here:

ph_location_type(type="body")
ph_location_fullsize()
ph_location(width = 2, height = 2, left = 2, top = 2) (for example)
More documented here: https://davidgohel.github.io/officer/reference/index.html#section-slide-content

Layouts

The layout chunk option is harder. I think this name comes from the template you are using. To see your actual options, I recommend now using the officer package directly to read_pptx() of your template file, and the using layout_summary():

## Seeing my layout options

This is handy, `officer::layout_summary()`

```{r echo=FALSE}
library(officer)
my_template <- read_pptx("alison-template.pptx") 
layout_summary(my_template) %>% knitr::kable()
```

Here was my output:

layout	master
Title Slide	Office Theme
Title and Vertical Text	Office Theme
Vertical Title and Text	Office Theme
Title and Content	Office Theme
Section Header	Office Theme
Two Content	Office Theme
Comparison	Office Theme
Title Only	Office Theme
Blank	Office Theme
Content with Caption	Office Theme
Picture with Caption	Office Theme

You can use any of these as valid layouts. This is another difference between rmarkdown::powerpoint_presentation which only supports four layouts:

Title Slide
Title and Content
Section Header
Two Content

New slides

You might be wondering at this point is “how do I make new slides?” and “how does it know where a new slide starts?” This format derives from rmarkdown::powerpoint_presentation, which derives from Pandoc. Pandoc documents slide separators as follows:

By default, the slide level is the highest heading level in the hierarchy that is followed immediately by content, and not another heading, somewhere in the document. In the example above, level-1 headings are always followed by level-2 headings, which are followed by content, so the slide level is 2. This default can be overridden using the –slide-level option.

The document is carved up into slides according to the following rules:

A horizontal rule always starts a new slide.

A heading at the slide level always starts a new slide.

Headings below the slide level in the hierarchy create headings within a slide.

Headings above the slide level in the hierarchy create “title slides,” which just contain the section title and help to break the slide show into sections. Non-slide content under these headings will be included on the title slide (for HTML slide shows) or in a subsequent slide with the same title (for beamer).

A title page is constructed automatically from the document’s title block, if present. (In the case of beamer, this can be disabled by commenting out some lines in the default template.)

Clear? Right, yea it confuses me too every time.

The default slide_level is 2, which means that you should expect to start new slides with ## My slide title. Starting a slide with # A level 1 header will create a section title slide, using your section header layout (see layouts above), and none of your body text will be displayed. You could change this in your YAML, but I recommend keeping the default:

---
output: 
  officedown::rpptx_document: 
    reference_doc: alison-template.pptx
    slide_level: 2 # default + recommended
---

With that default, if you added:

# Let's goooo

## Tables

You would see:

You cannot have normal body text on a section slide, so don’t add anything between those two slides or Pandoc will helpfully split off a new slide:

# Let's goooo

anybody home?  <- don't do this

## Table

With slide_level: 2, here is how a deck gets chopped up:

# I'm a new slide- a section header

## I'm slide number 2, with content

### I'm also slide number 2, text is slightly bold

I'm content on slide number 2

## I'm slide number 3

# I'm slide number 4- another section header

You can force a slide break using ---, but headers will still work the same way.

# I'm a new slide- a section header

## I'm slide number 2, with content

### I'm also slide number 2, text is slightly bold

---

I'm slide number 3

---

## I'm slide number 4

# I'm slide number 5- another section header

Plots

Including plots for me was sadly a long drawn-out affair. I didn’t understand:

I had to use the rvg::dml() wrapper for plots, even if I didn’t care if they were editable or not. This is required if you don’t want TRUE printed after each plot. In a two-column slide layout, non-dml() wrapped plots will also appear on a slide by themselves, without an error.
If you further want to use ggplot2, you also cannot just print your plot object, you must use dml(ggobj = my_plot). This one really got me. Again, in the template, but less well-documented elsewhere. If you try to wrap a ggplot2 object in dml() only, you might see this error:
You cannot combine text and code or plots inside the same placeholder. They cannot co-exist. If you do, the text is either overlaid or covered up by your code/output. This is how rmarkdown::powerpoint_presentation works as well. A way around it is to use figure and table captions.
I use ref.label all the time to reuse code chunks, especially for plots. Because of the above, you’ll need to always create and save a plot object, then wrap it is rvg::dml(ggobj=mygg) in the origin chunk. I get an error if I try to use the magrittr pipe here (%>% , so this gets a bit laborious to change your plotting ways. For example:

## Testing officedown

```{r flipper-hist, include=FALSE}
library(palmerpenguins)
library(dplyr)
library(ggplot2)
# Histogram example: flipper length by species
flipper-hist <- ggplot(data = penguins, 
       aes(x = flipper_length_mm)) +
  geom_histogram(
    aes(fill = species),
    alpha = 0.5, 
    position = "identity") + 
  scale_fill_manual(values = c("darkorange","darkorchid","cyan4")) 

rvg::dml(ggobj = flipper-hist) # you must do this!
```

```{r layout='Two Content', width=2, ph=officer::ph_location_left(), warning=FALSE, message=FALSE, echo=FALSE}
penguins %>% 
  count(species)
```

```{r ref.label='flipper-hist', width=2, layout='Two Content', ph=officer::ph_location_right(), echo=FALSE, warning=FALSE, message=FALSE}
```

Wrapping up

This is as far as I got with officedown. I can see it being very useful to users who need more control over their Microsoft outputs than base rmarkdown and Pandoc can provide. However, there are definitely some places where a typical R Markdown user will accumulate pretty serious papercuts.

I’d love to hear about happy officedown use cases and the problems it solves for teams! I know a lot of organizations run on Microsoft Office products, so I appreciate the hard work that has gone into this suite of tools.

Revealing research

Thu, 22 Jul 2021 00:00:00 +0000

Background

Lately, one of the most exciting things you can say to me (at work) is

“Why aren’t people using X? What are the problems with X, and how can we fix them?”.

Sometimes, I know these answers already by heart, because I have lived and breathed X. This is how blogdown was for me - I felt very tuned in to the usability problems there, and had good ideas for how to resolve them.

Other times, I have not used X (yet!). This happened to me recently when I was asked:

“Why aren’t people using reveal.js for slides with R Markdown? What are the problems with reveal.js, and how can we fix them?”.

What is reveal.js? Here is a demo deck:

It’s possible you’ve heard or seen reveal.js before - and it didn’t look this good! It may have looked more like this:

Figure 1: Two sample slides created from the revealjs package.

This…never quite worked for me. If you know my work, you know I’m a pretty big fan of the xaringan package by Yihui Xie for making HTML-based slides with R Markdown. That package wraps a third-party JavaScript library called remark.js and lets you use that to knit R code and its output into your remark.js slides. I’ve used xaringan for years, and have taught it quite a lot too. It helps me make slides like this:

I love it, but also recognize that it is hard, and that it is not intended for beginners (hence the “ninja” references in the package name and supporting documentation).

Which is too bad, because I think HTML-based slides are a great way for beginners to get started using R Markdown.

So here we are! Why aren’t people using reveal.js? I set out to find out, and thought this was a great example of one of the things I love most about being a Product Manager. Since I am not a current user, but would conceivably be a target user, I get to play the part of the “wide-eyed doe in the woods” - eager to learn but also a little cautious - will reveal.js cause me pain? It is likely

Plus, since it has been almost 6 months since my last blog post, I thought I would turn this early research project into a blog post to give a glimpse of some of the daily work I do as the Product Manager for Data Science Communication at RStudio.

Goal

Understand how users experience using reveal.js to make slides, and identify areas for improvement.

The competition

The landscape of HTML slide-making is unfortunately pretty big, but it’s important to sketch it out. There are lots of frameworks, largely based off of different JavaScript tools. I see almost a new one a month! If you just look at Pandoc alone, it supports five different frameworks:

Remark.js is another popular one, as I mentioned earlier. There is also Webslides. And Slidev. And Shower. And Marp. And more I’m sure! (In fact, here is a gist with more.)

The rmarkdown package also supports ioslides as an output format.

Why reveal.js?

So starting simple: why do we think R Markdown users could benefit from using reveal.js?

Pandoc slide syntax
Visual editor support
Powered by slides.com for publishing/sharing- so well supported (that is paid though)
Good docs: https://revealjs.com/
Extensive plug-ins are available to extend: https://revealjs.com/plugins/
We have an existing package ( https://github.com/rstudio/revealjs) (albeit a little out-of-date)
Built in themes: https://revealjs.com/themes/
It is also a supported slideshow framework for Jupyter/IPython via RISE
Custom themes are possible (but perhaps not easy) using SASS layers: https://github.com/hakimel/reveal.js/blob/master/css/theme/README.md

Research questions

Given all these pluses, and the competition, what do we want to know/

[Functionality] How, if at all, do users expect to use reveal.js? What problems does it solve for them, and what are unaddressed problems?
[Ease of use] Where, if at all, do users express uncertainty, frustration, or confusion? What API problems arise?
[Task success] What kinds of messages, warnings, or errors do users encounter when using reveal.js? Where, if at all, do they get stuck or confused? What, if any, strategies or resources do they find for troubleshooting?

Method

With these goals in mind, I wanted to start with just a few days of work, because I couldn’t tell how big of a project this was. So I didn’t want to do user interviews.

Instead, I relied on combing through community forums, blog posts, existing documentation, and GitHub issues to trace the outline of the problem space first. I actually got a lot of mileage from this exercise, even without direct user input.

Here were some of my primary research resources (GitHub issues I tracked inline with my notes below):

This kind of research is sort of akin to bushwhacking. There is no clear trail, and you are traveling in sort of wild country. There may be lots of noise in all these channels that actually isn’t accurate, so you have to trust your own intuition some and do your own testing even more.

I’ll note here that a red flag right off the bat for me is that we don’t even have revealjs tagged on RStudio Community, so we aren’t exactly advertising usage. Nevertheless, there are questions about it on there, which seem to largely go unanswered. I also didn’t find a lot of blog posts or meetup presentations on the topic. If you know the #rstats community, you know that sharing knowledge is basically baked in, so this tells you something is up (but it could be messaging - the tool may still be great!).

What works?

Before reading through many of the blog posts and community forum threads, I also actually just used the tool.

Here was my minimal demo deck:

I tried to follow the docs myself, and maintain a friction log of what worked well and what didn’t. If I stumbled, I tried to make a mental note to actually figure out why at some point. It could be an actual bug, or it could be that my mental model is wrong, or it could be that I trusted a doc or a user’s guide and that led me astray. Whatever it is, it’s important that I track what went wrong. Here is my scratchpad of what I tried that did work.

Multi-column layout (but, a bit clunky? Have to create container first. In xaringan, this is just .pull-left[contents...] and .pull-right[contents...])
```
:::: {.columns} 
::: {.column width="40%"} 
contents… 
::: 
::: {.column width="60%"} 
contents… 
::: 
::::
```
Tile view: escape kbd shortcut - very cool!
- Although why does tile view show all top aligned slides instead of centered?
Vertical slides: Aha you invoke vertical slides by using level 1 headers! (essentially, by adding sections). The “default” horizontal slide layout depends on using ## for all slide headers - a bit of a gotcha to folks so we’ll need to really document and teach this well
- Pandoc’s docs on this: Note: in reveal.js slide shows, if slide level is 2, a two-dimensional layout will be produced, with level-1 headings building horizontally and level-2 headings building vertically. It is not recommended that you use deeper nesting of section levels with reveal.js.
- The option for vertical is actually nice- several customers have mentioned to me that they like it for making flexible presentations (i.e., if you have 5 min, you do just the horizontal, if you have 20 you know you can go down and use the vertical)

Speaker notes + s kbd shortcut for speaker view- nice, awesome

::: notes 
This is my note.

-   It can contain Markdown

-   like this list 
:::

Hidden slides- nice, awesome
```
## {visibility="hidden"}
```
Cool layout options: https://revealjs.com/layout/

Backgrounds for individual slides- images, transitions, all per slide, all work great (but! see the oof below regarding relative vs absolute image paths on GH pages)

## CSS color bg {background=#ff0000}

## Full size image bg {background="background.jpeg"}

## Video bg {background-video="background.mp4"}

## A bg html page {background-iframe="https://example.com"}

What might work but I don’t know for sure?

This syntax should work to change a slide background using the three dashes as the slide separator instead of the level 2 markdown header, but does not:
```
--- {background-color="#FBD989"}
```
- [TODO]: test with updated Pandoc, file bug if still doesn't work
How do I change syntax highlighting themes using the built-in highlight.js? https://revealjs.com/code/#theming
- See: http://arm.rbind.io/slides/xaringan.html
- NOTE: the R package we have has a YAML key for this
These are all very nice code chunk effects- how would I use with knitr chunks? https://revealjs.com/code/
Two column incremental?
- [TODO:] test this
Want to see slide numbers out of total, but this does not work: slideNumber: 'c/t'
- See: https://revealjs.com/slide-numbers/
- [TODO:] test with latest Pandoc and file issue there if can confirm bug with reprex

What needs to change?

Difficult to style out of the box (i.e., you are in CSS inspect element world).
- “Creating themes seems to require you to fork reveal’s github repo for full generality, which feels a bit weird…Either way, in practice theming can be a rabbit hole of flex-box and responsive media queries.” - blog post
- “Note - if you are an artist (or very focused on small visual details), then you might want to reconsider using reveal.js.” - blog post
Build in SASS/SCSS support
- I made my own: https://github.com/apreshill/revealing-slides/blob/main/assets/my-style.scss
- Then used the sass package to compile to css: https://github.com/apreshill/revealing-slides/blob/main/assets/compile-sass.R
- Then used the css key in the YAML
The visual editor view is disorienting (hard to see where slides start/end):
Accessibility: slide tones on advance?
- See: https://pkg.garrickadenbuie.com/xaringanExtra/#/slide-tone
- https://stackoverflow.com/questions/32956342/with-reveal-js-how-can-i-make-slides-change-upon-completion-of-embedded-media
- [TODO:] test out this plugin: <https://github.com/rajgoel/reveal.js-plugins/tree/master/audio-slideshow>
Adding a logo is hard, needs to be easier. See also:
- https://arm.rbind.io/slides/xaringan.html#121
- https://pkg.garrickadenbuie.com/xaringanExtra/#/logo
- Closed issue → solution is CSS: https://github.com/hakimel/reveal.js/issues/1122
Changing the overall alignment is hard, needs to be easier (all centered by default):
- https://github.com/hakimel/reveal.js/issues/1897
- https://stackoverflow.com/questions/41024596/r-markdown-slides-with-reveal-js-how-to-left-align-list-items-bullets-and-numb/41047550#41047550
- You can use center: false in the YAML, but this is only for vertical alignment

The default transitions look a bit dated…changing all to “none” looks more modern

[TODO:] change defaults?

// Transition style 
transition: 'slide' --> 'none', 
// none/fade/slide/convex/concave/zoom // 
// Transition style for full page slide backgrounds 
backgroundTransition: 'fade' --> 'none', 
// none/fade/slide/convex/concave/zoom

Good + modern built-in themes- I have zero love for any of the existing themes
- A good start for a style template: https://github.com/hakimel/reveal.js/blob/master/css/theme/template/settings.scss
- [TODO:] Provide a set of built-in themes that data scientists would want to use
Customizing title slide- looks like it is YAML only? It would be nice to be able to opt for using straight up HTML in the first slide as the title slide. This is a Pandoc principle though across slide formats.
- See: http://arm.rbind.io/slides/xaringan.html#117
- https://stackoverflow.com/questions/40345094/reveal-js-title-slide-override
Build in shortcode for panelsets? I’m totally sold on panelsets for slide decks:
- https://pkg.garrickadenbuie.com/xaringanExtra/#/panelset
Easily use google fonts- maybe using YAML for fonts like bslib/sass package does (and does the dirty work for you to be able to work offline)
- See: https://rstudio.github.io/sass/reference/font_face.html
- [TODO:] get bslib support for SASS/SCSS files in R package
Can we make PDF exporting easier, perhaps with pagedown? https://revealjs.com/pdf-export/
Can we have emoji support?
- Official answer is no: https://github.com/hakimel/reveal.js/issues/2517
A Pandoc bug? The data- prefix is not required for other attributes, but in the YAML for the title slide they are required:
```
title-slide-attributes: 
  data-background-image: /img/pink-paint.jpg
  data-background-size: cover
```

Follow-up in the future

Live revealjs theme editor (v v v old): https://github.com/byteclubfr/uncloak
The menu plugin looks interesting: https://stackoverflow.com/a/61075371/9437012
As does the spotlight plugin: https://github.com/denniskniep/reveal.js-plugin-spotlight
Oof it looks like publishing ghpages from the project root misses files in subdirectories, note that none of my background images show up!
- Note to self: use relative urls to images rather than absolute (so don’t start with a slash if in subdirectory as the Pandoc docs led you to believe- that will generate absolute urls that GH Pages will trip on- Netlify did not)

My final answer

So the question I started with was:

“Why aren’t people using reveal.js for slides with R Markdown? What are the problems with reveal.js, and how can we fix them?”.

My answer? I think there are a few factors working against reveal.js. The most obvious is that there is a noticeable lack of community engagement around the format - so there is an enthusiasm gap there between reveal.js and R packages like xaringan. The sheer number of options for HTML-based slide output formats leads folks toward using the one they see and hear about in the wild. That often starts with brave sharers on social media like Twitter, which then trickles down into user blog posts, folks who can answer questions on community, and ultimately contributors who improve the open-source software themselves. There have been amazing community contributions around the xaringan ecosystem. Have you heard of: https://xaringan.club/ (brought to you by Garrick)?

“The first rule of xaringan club is…we talk about xaringan.”

Will there be a reveal.js club? I hope so! In my research, I found a lot of things to like working with reveal.js, and some things that I do think would serve R Markdown users and especially beginners well, perhaps even better than xaringan/remark.js. But, is there room for improvement? Always 😉

Honestly, with slide making tools, my own experience is that I’m less enthusiastic when I feel less empowered. I feel empowered as a user when a tool lets me customize the look and layout of my slides, with some guardrails to make sure I don’t enter the deep-dark CSS labyrinth. What I want is to fall into the “pit of beauty” more quickly, instead of the “pit of ugly” after hours of trying. See this interview with Hadley Wickham about the “pit of success” if you don’t get this reference! In my experience, this is what will drive some brave adopters to dip their toe into reveal.js, and ultimately what might help teams take the plunge together.

So what happens next? This was just the beginning, but it is where I’m at after a few days of research and testing. I know I’ll be using it for my next slide deck so stay tuned!

R Markdown

Tue, 15 Jun 2021 12:00:00 +0000

Speakers

Kenton McHenry (University of Illinois) and Dan Katz (University of Illinois) will moderate a discussion with presenters:

Alison Hill (RStudio),
Chris Holdgraf (2i2c - Jupyter),
Chris Erdmann (American Geophysical Union), and
Loren Shure (MathWorks - Matlab).

The talks will focus on the latest developments in each of the presenters’ technologies, emphasizing elements that support the notions of ease of use, long-term executability, interoperability, and software publication. Lessons learned from building a geoscience-focused notebook directory, notebook template, and long-term preservation in AGU’s ESSOaR will also be discussed - as well as how this all relates to international efforts to elevate notebooks and make them FAIR. This session has been designed for attendees that are already developing notebooks, those interested in doing so, and organizers who want to support these technologies in their events and proceedings.

Introduce yourself online with blogdown & Hugo Apéro

Wed, 26 May 2021 11:00:00 +0000

“You should have a website!” You may have heard this one before, or even said it yourself. In this workshop, you’ll learn how to build and customize a website from the comfort of the RStudio IDE with R Markdown. We’ll use the blogdown package and the Hugo Apéro theme to build and deploy a personal website. We’ll cover basic website care and feeding like using R Markdown to create content, how to use GitHub for version control and Netlify for publishing, and how to use the latest upgrades to the blogdown R package to keep your site up and running.

The goal of this workshop is to equip participants with tools that amplify their own contributions, build a more visible presence in the R/data community, and share their knowledge and insights with others.

Hugo Apéro

Sun, 23 May 2021 00:00:00 +0000

Apéro (a-pay-ROH) is a Hugo theme for personal websites. It is more than a blog, with flexible custom layouts that help you introduce yourself online.

Why apéro?

Apéro is a unique kind of casual get-together in French culture, when you gather with friends and get to know each other better over some apéritifs, snacks, and anything in between. A good apéro is one where you’d happily spend a few hours just hanging out.

I hope this theme helps you create your own virtual apéro. A place where you and your site’s visitors enjoy spending time, and one that helps folks get to know you better.

Free & Open Source Software

Tue, 18 May 2021 10:00:00 +0000

Crafting Kind Tools

Mon, 12 Apr 2021 18:00:00 +0000

Abstract:

We are all tool-makers. If you are an educator, your lessons are tools. You make them to be used by students. Students use your lessons to build mental models piece-by-piece, and learn processes step-by-step. If you are a researcher, you design experiments as tools to be used by participants. As a scientist, your analyses are tools used by other researchers to replicate and extend what you did. And finally, if you use software for making any of these tools, you are also using a tool that was crafted by someone else. Is it kind? What makes a tool kind? In this talk, I’ll share ideas and insights I’ve gained while working to make tools for everyday data science communication kinder for users. I’ll discuss some case studies from my work on free and open-source software at RStudio over the past 2.5 years.

Making R Markdown work better for you

Wed, 24 Mar 2021 18:00:00 +0000

Take a Sad Plot & Make It Better

Thu, 25 Feb 2021 12:00:00 +0000

Alison Hill (I think her unofficial nickname is RMarkdown Whisperer) is going to talk to us on another of her strengths. Making things beautiful, and informative. She’s going to do her “Take a Sad Plot & Make it Better” talk, for us. In this talk, Alison will discuss one plot’s life cycle, from a sad Powerpoint slide to the finished product made with the ggplot2 package in R, and what she learnt from it.

Alison doesn’t need much introduction, she’ll be the main search result if you’re looking for RMarkdown info, xaringan inspiration, blogging and teaching online using R, among many other topics! Read about her here: https://alison.rbind.io/about/. If you’re on Twitter, you’d learn a lot by following https://twitter.com/apreshill.

Aside: Also have a look at Hugo Apéro, for some inspiration on building a presence online ( https://hugo-apero.netlify.app/).

Introduce yourself online

Mon, 25 Jan 2021 13:00:00 +0000

“You should have a website!” You may have heard this one before, or even said it yourself. In this workshop, you’ll learn how to build and customize a website from the comfort of the RStudio IDE using the blogdown package. We’ll also cover basic website care and feeding like using R Markdown to create content, and how to use GitHub and Netlify to improve your workflow. Pre-work will be shared with participants ahead of time, but to get the most out of this workshop, you’ll want to have a GitHub account and be able to push and pull files from a GitHub repository using your local RStudio IDE.

Up & running with blogdown in 2021

Thu, 31 Dec 2020 00:00:00 +0000

Welcome

Hi! Hello! Welcome. Bienvenidos.

About 3.5 years ago, I wrote my first blog post and published it on my first website. Since then, that single post has been viewed over 27,557 times. That may not seem like a lot to some folks, but it is to me! Even more meaningful to me, though, has been watching the launches of so many people’s personal websites.

However, the process of creating and maintaining a Hugo website using blogdown was not always pain-free. Sometimes we have Hugo “improvements” to thank, other times your Hugo theme is at fault, and sometimes we could blame blogdown. Regardless of where the pain came from, there was definitely room for improvement.

Here are some great blog posts that document pretty common user experiences and frustrations:

All of this, combined with my own experiences teaching and using blogdown for over 3.5 years led me to…my giant blogdown wishlist. I had a lot of ideas to help beginners get started, but just as important, to improve the quality of life for existing users. You can see my mega-wishlist that Yihui Xie (the blogdown conceptor and author) asked me to share with him: https://github.com/rstudio/blogdown/issues/476

I’m very happy to report that our team has been working very hard to address these issues, and many others raised by users, to make blogdown easier to learn and use. Just in time for the new year, we have a new and improved release of the blogdown package for you to test. I know a lot of folks are itching to introduce themselves into online communities and conversations, so I thought it would be fun to take my original blogdown post, and trace the same process of building a Hugo website with the same theme (now named “Wowchemy” instead of Hugo Academic- don’t get me started).

So if you are feeling fearless and want to live on the bleeding edge, read on to give the development version of blogdown a spin along with me.

tl;dr

If you already know what you are doing, this entire post can be condensed into just a few lines of code:

remotes::install_github("rstudio/blogdown")
usethis::create_project()
blogdown::new_site(theme = "wowchemy/starter-academic")
blogdown::serve_site()
blogdown::new_post(title = "Hi Hugo", 
                     ext = '.Rmarkdown', 
                     subdir = "post")
usethis::use_git()
usethis::use_github() # requires a GitHub PAT

The above sequence is a slightly more advanced workflow than the steps I follow below, but is fairly magical- attempt at your own risk! For everyone else, read on…

Pre-requisites

Getting any website up and running with all the moving parts (RStudio, GitHub, Hugo, Netlify) can take a few tries. In this post, I’m passing along what works for me, and the workflow that I use when I teach Hugo website development. Everyone’s mileage may vary, though, depending on your operating system and your approach.

For this blog post, I’m assuming you have basic familiarity with:

R,
the RStudio IDE, and
GitHub.

If that is not you, you will need to work through Happy Git with R by Jenny Bryan et al. first, then come back here when you are ready.

Since the development version of blogdown is currently only available on GitHub, you may need to setup a GitHub Personal Access Token to install it.

In my original 2017 post, I mentioned that at that time, I was a new mom, and just in the process of writing all that up, I filled up my tea mug twice with ice cold water, and filled my water bottle with scalding hot water. This time around isn’t too different! Fast forward to 2020: there is a global pandemic, I’ve been under stay-at-home orders with a child under 5 years of age at home for months. So buckle up :cowboy:

I’ve included code chunks below using the rstudioapi package to help you navigate to the right file at the right time. Hugo sites have a dizzying and heavily nested directory structure! You’ll need to run install.packages("rstudioapi") to use those code chunks, but you can also navigate on your own to the file you need too.

Step 0: Set your intentions

During workshops, I try to set aside some time at the start for folks to set their website intentions. This might feel a bit like navel-gazing, but trust me here. I know you just want to jump in and get started!

Hear me out though, and don’t skim or skip this step. The process of actually building and deploying a personal site can be complicated, and it is easy to get lost in the weeds.

It is very easy to run out of steam when it is time to do the most fun and important piece: dreaming about the kind of site you want to make!

Do this right now! Take 10 minutes to set your website intentions—grab a pen and notepad and a cup of 🍵 and read on…

1. Content

Hugo is made for blogs. But, in addition to a blog, the starter-academic theme provides a unique system of widgets. You can have one or many widgets on pages in your site. I like to think of widgets like Mr. Potato Head where:

Each page is a potato head, and
Each widget is a piece you could place on the potato head.

Take the homepage for example, seen on the Academic demo site. Each band or section you see is a widget. Widgets can be stand-alone pages, or can be combined on a single page.

Examples:

Multiple widget page: my resume and about pages
Single widget page: my projects

Look at the Academic demo site and write down some widgets you see that you like, and the ones you definitely don’t.

Now that you have a sense of the content you want, how do you want a visitor to be able to explore your content? I typically recommend limiting the top navbar to 5 links max (excluding the search icon).

Use some of my favorite personal sites (that do not use our theme) as inspiration too:

Think about how the menu “prewires” you to know what to expect as you dig deeper into their site. How do you want people to get to know you online?

Write down up to 5 items to appear in your upper navbar.

3. Homepage

This is the first page a visitor lands on when they find your site. Think of it like a welcome mat. Do you like a single page site where you scroll and see everything on one page? Or do you prefer a short and sweet homepage? Do you want a photo and a bio to be the first thing visitors see? What else?

Here are some examples of personal websites built with the Hugo Academic theme to inspire you:

Write down the widgets you want to see on your homepage. It can be one, or many.

OK, keep these notes handy! We are ready to make something.

Step 1: Create repo

Go online to your GitHub account, and create a new repository (check to initialize with a README but don’t add .gitignore- this will be taken care of later). For naming your repo, consider your future deployment plan:
- Netlify. I recommend using Netlify to both build and host your site. In this case, you can name the repository anything you want!
- GitHub Pages. I recommend Netlify over GitHub Pages for blogdown/Hugo sites. But, if you want to host your site with GitHub Pages, you should name your repository yourgithubusername.github.io (so mine would have been apreshill.github.io). This post won’t be able to help you with publishing.

You can see some of the repo names used by members of the rbind organization here.

Go to the main page of your new repository, and under the repository name, click the green Clone or download button.
Choose either SSH or HTTPS (if you don’t know which, choose HTTPS). Choose by clicking on the clipboard icon to copy the remote URL for your new repository. You’ll paste this text into RStudio in the next section.

Step 2: Create project

We just created the remote repository on GitHub. To make a local copy on our computer that we can actually work in, we’ll clone that repository into a new RStudio project. This will allow us to sync between the two locations: your remote (the one you see on github.com) and your local desktop.

Open up RStudio to create a new project where your website’s files will live.

Click File > New Project > Version Control > Git.
Paste the copied URL from the previous step.
Be intentional about where you tell RStudio to create this new Project on your workstation.
Click Create Project.

Step 3: Create site

The latest version of blogdown will not be available on CRAN until January 2021, but you can install the development version from GitHub with:

> if (!requireNamespace("remotes")) install.packages("remotes")
> remotes::install_github("rstudio/blogdown")
Using github PAT from envvar GITHUB_PAT
Downloading GitHub repo rstudio/blogdown@master

Let’s use our first blogdown function to create a website with the Hugo Wowchemy “starter-academic” project:
```
> library(blogdown)
> new_site(theme = "wowchemy/starter-academic")
```
You should now see something like this. Take a moment to read through these messages - importantly, it tells you how to start and stop the server so you can preview your site. Importantly, when you come back to your project, note that you can use blogdown::serve_site() or the “Serve Site” addin to preview it locally.

Let’s select y to let blogdown start a server for us.

Exciting, isn’t it? Now, don’t trap your site in the RStudio Viewer pane. Let it out! Click to “Show in new window” (to the right of the 🧹 icon) to preview it in a normal browser window. When you do that, you’ll be re-directed to the site’s main homepage. Let’s find our way back to the R Markdown post. Click on Posts > Hello R Markdown to read it:

This is what blogdown gives you- everything else in the site is given to you by Hugo and your Wowchemy Hugo theme. But this post, and your ability to see output and plots rendered with is what blogdown adds!

Step 4: Create content

Let’s use more R Markdown 🎉

Blogdown allows you to create new two kinds of R Markdown posts that are knittable:

.Rmd 🧶 to .html or
.Rmarkdown 🧶 to .markdown

Once knitted, both are then previewable in your Hugo site.

I used to agonize over which file extension to use. But now I am squarely in .Rmarkdown camp with Maëlle- I like knitting to .markdown and wish this was easier in blogdown; see: https://github.com/rstudio/blogdown/issues/530

Use the console to author a new .Rmarkdown post; I’ll name my post “Hi Hugo”:

> blogdown::new_post(title = "Hi Hugo", 
                     ext = '.Rmarkdown', 
                     subdir = "post")

This takes the path to where you want your post to live, relative to the content/ folder (so that piece of the path is assumed, rightly so!). In the Academic theme, the example site organizes blog posts into the content/post/ folder, but the name of this folder varies across Hugo themes.

A rule that is true 90% of the time: folders in content/ are singular, not plural— ✔️ post; ❌ posts

You can add an option to your .Rprofile to save these settings so you don’t have to remember them:

# if exists, opens; if not, creates new
blogdown::config_Rprofile()

Then add the blogdown options to that file, save, and RESTART YOUR R SESSION for changes to take effect:

options(
  # to automatically serve the site on RStudio startup, set this option to TRUE
  blogdown.serve_site.startup = FALSE,
  # to disable knitting Rmd files on save, set this option to FALSE
  blogdown.knit.on_save = FALSE     <- change
  blogdown.author = "Alison Hill",  <- add
  blogdown.ext = ".Rmarkdown",      <- add
  blogdown.subdir = "post"          <- add
)

Always restart your R session after editing your .Rprofile for changes to take effect. Don’t forget to run serve_site() after a restart.

If you look in your Files pane, you can see that this creates a folder with the date and the “slug” name of my post ("hi-hugo"). The actual R Markdown file is named index.Rmarkdown.

This is a Hugo page bundle. Each post gets its own bundle, or folder. Inside the post bundle is where all your static images, static data files like .csv files should go.

content/
├── posts
│   ├── 2021-01-01-hi-hugo
│   │   ├── bakers.csv
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── index.Rmarkdown

In the post itself, use the relative file path like:

![my-first-image](image1.jpg)

Let’s look at the index.Rmarkdown. We’ll knit this .Rmarkdown to a .markdown file. You may 🧶 knit 🧶 freely now in blogdown!

To knit an .Rmarkdown post, you can either:

Use the Knit button to knit to the correct output format, or
Use the keyboard shortcut Cmd+Shift+K (Mac) or Ctrl+Shift+K (Windows/Linux).

After knitting, you should now see:

content/
├── posts
│   ├── hi-hugo
│   │   ├── bakers.csv
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   ├── index.Rmarkdown
│   │   └── index.markdown   <- 🆕

Go ahead and add an R code chunk like:

```{r}
summary(Orange)
```

After you edit your .Rmarkdown post, knit. Note that knitting automatically saves the file for you. You also can just save the file without knitting- this is good for when your code still needs work and won’t run as is.

The most important thing here is to realize that the act of knitting creates an index.markdown file in the same post bundle as index.Rmarkdown. Because Hugo doesn’t know R or R Markdown, The index.markdown version is what then feeds into the Hugo static site generator.

Try it again! Add another R code chunk like:

```{r echo=FALSE}
library(ggplot2)
oplot <- ggplot(Orange, aes(x = age, 
                   y = circumference, 
                   colour = Tree)) +
  geom_point() +
  geom_line() +
  guides(colour = FALSE) +
  theme_bw()
oplot
```

Knit, and you should see something like:

Many R Markdown output options for HTML documents are not going to be possible here, like tabbed sections, floating table of contents, the code_download button, etc. Also, HTML widgets are a little dicey currently.

This is a single page. It is made with R Markdown, and happens to be a blog post, although you can use R Markdown to create content for any other content section too.

If you want a featured image to accompany your post and show up on your listing page (the clickable list of all your posts), you’ll want to add an image with the word featured in the filename:

content/
├── posts
│   ├── hi-hugo
│   │   ├── bakers.csv
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   ├── index.Rmarkdown
│   │   ├── index.markdown   
│   │   └── featured-bakers.jpg   <- ➕

Workflow

My workflow in RStudio at this point (again, just viewing locally because we haven’t deployed yet) works best like this:

Open the RStudio project for the site.
Start the Hugo server using blogdown::serve_site() (only once due to the magic of LiveReload).
View site in the RStudio viewer pane, and open in a new browser window while I work.
Select existing files to edit using the file pane in RStudio.
After making changes, save if a plain .md file, or if working with an .Rmd or an .Rmarkdown document, knit to preview! You can now use the Knit button to knit to the correct output format. You can also use the keyboard shortcut Cmd+Shift+K (Mac) or Ctrl+Shift+K (Windows/Linux).
The console will detect the change (it will print Change detected, rebuilding site.), the viewer pane will update, and (in a few seconds) your local view in your browser will also refresh. Try to avoid hitting the refresh button in your browser.
When happy with changes, add/commit/push changes to GitHub.

Having blogdown::serve_site running locally with LiveReload is especially useful as you can immediately see if you have totally screwed up. For example, in editing my about.md file, this error popped up in my console after making a change and I was able to fix the error right away:

Started building sites ...
ERROR 2017/06/08 16:22:34 failed to parse page metadata for home/about.md: (18, 6): missing comma
Error: Error building site: Errors reading pages: Error: failed to parse page metadata for home/about.md: (18, 6): missing comma for about.md

Using GitHub

Let’s go ahead and push our changes to GitHub. First, let’s make a .gitignore file:

file.edit(".gitignore")

Add this content:

.Rproj.user
.Rhistory
.RData
.Ruserdata
.DS_Store
Thumbs.db

Check yourself before you wreck yourself

Let’s use blogdown to check this file before we do our first commit:

blogdown::check_gitignore()

You should see something like:

> check_gitignore()
― Checking .gitignore
| Checking for items to remove...
○ Nothing to see here - found no items to remove.
| Checking for items you can safely ignore...
○ Found! You have safely ignored: .DS_Store, Thumbs.db
| Checking for items to ignore if you build the site on Netlify...
● [TODO] When Netlify builds your site, you can safely add to .gitignore: public, resources
― Check complete: .gitignore

You have a [TODO] item- go ahead and add public and resources on their own lines in your .gitignore file. We’ll be configuring Netlify to build our site shortly, so go right ahead while the file is open.

While we are at it, let’s check out our content too:

blogdown::check_content()

You may notice a few pieces of content are flagged as draft. This is good to know! Read up on drafts in Hugo here.

Our checks are pretty clean, so you can freely add/commit your project files to GitHub. You now should have the basic mechanics of your site working.

Step 5: Publish site

Thus far, we’ve only been previewing our site locally, then pushing the source files (but not the built site) to GitHub. This workflow works, but I assume you want to ride this bike. Let’s skip the training wheels — we are going one step more advanced by using GitHub with Netlify now.

Note that you could use blogdown::build_site(), then publish the public/ folder using Netlify drag & drop. Watch this webinar called “Sharing on Short Notice” to learn more - but this is a less advanced workflow.

To get started using Netlify for real (which has a free plan that should largely cover recreational blogging use!):

Go online to Netlify.
Click on the Sign Up button and sign up using your existing GitHub account (no need to create another account).
Log in, and select: New site from Git > Continuous Deployment: GitHub.
From there, Netlify will allow you to select from your existing GitHub repositories. You’ll pick the repo you’ve been working from with blogdown. Leave all settings as they are and select Deploy Site.

You should see something like this:

When it is done, you can click on the link to your new site! And the most magical thing of all, every time you push any changes to your site to GitHub, Netlify will detect the push, re-build, then update your published site. It’s a good thing. It’s called continuous deployment, and it is the main reason to use Netlify for a blogdown site.

With a new site, Netlify will deploy your site and assign you a random subdomain name of the form random-word-12345.netlify.app. Mine was particularly unfortunate, with the random word garbage-collector-janice. You should know that you can change this; I changed mine to apreshill.netlify.app. Do this by navigating to your site on Netlify, then click on Settings. Under Site information, click on the Change site name button.

Whether you change your Netlify site name or use the random one, go back to your configuration file and cchange the baseurl there to match where Netlify is publishing your site:

rstudioapi::navigateToFile("config.yaml", line = 3)

You actually have most of the necessary wiring laid out for you already in your repo, which is why this worked. Our site has a netlify.toml file, which sets us the necessary settings for letting Netlify build our site for us and then publish it. You can read more about this file here, and check it out using:

# if exists, opens; if not, creates new
blogdown::config_netlify()

Now, back in your local blogdown project, let’s check this file with blogdown:

> blogdown::check_netlify()
― Checking netlify.toml...
○ Found HUGO_VERSION = 0.79.1 in [build] context of netlify.toml.
| Checking that Netlify & local Hugo versions match...
| Mismatch found:
  blogdown is using Hugo version (0.79.0) to build site locally.
  Netlify is using Hugo version (0.79.1) to build site.
● [TODO] Option 1: Change HUGO_VERSION = "0.79.0" in netlify.toml to match local version.
● [TODO] Option 2: Use blogdown::install_hugo("0.79.1") to match Netlify version, and set options(blogdown.hugo.version = "0.79.1") in .Rprofile to pin this Hugo version.
| Checking that Netlify & local Hugo publish directories match...
○ Good to go - blogdown and Netlify are using the same publish directory: public
― Check complete: netlify.toml

I recommend going with Option 1 here, so follow that [TODO] and then run the function again to get a clean check.

When you are ready to deploy, commit your changes and push to GitHub! Watch as your site rebuilds 🎉

To get an *.rbind.io URL, follow these instructions.

Anytime you change your subdomain name, you need to update the baseurl in your config.toml file (so I changed mine to baseurl = “ https://apreshill.netlify.com/").

Step 6: Sculpt site

Now, we’ll leave blogdown and R Markdown behind. We’ll just be using Hugo and Wowchemy (I think it is said like alchemy? Why??) to build your personal website.

Let’s start by running another blogdown check to check_hugo():

> blogdown::check_hugo()
― Checking Hugo
| Checking Hugo version...
○ Found 4 versions of Hugo. You are using Hugo 0.79.0.
| Checking .Rprofile for Hugo version used by blogdown...
○ blogdown is using Hugo 0.79.0 to build site locally.
● [TODO] Also run blogdown::check_netlify() to check for possible problems with Hugo and Netlify.
― Check complete: Hugo

All set! We’ve already checked out our Netlify set-up ✔️ If you wish to clean up your local Hugo installations, check out:

blogdown::remove_hugo()

Configure your site

Let’s start with the last thing you typically do to your home- decorate.

Open up the file config/_default/params.toml. Play with any of these configurations, but especially fonts/themes.

rstudioapi::navigateToFile("config/_default/params.toml")

If you want deeper customization of the styling, you can create a new CSS file assets/scss/custom.scss and use it to override any existing styles. You can see mine here; heavily borrowing from my former intern Desirée De Leon!

While you are at it, edit the other configuration files:

You can also view my config.toml file

Remember our menu intentions? Go ahead and edit those too:

rstudioapi::navigateToFile("config/_default/menus.toml")

Let’s run a blogdown check on the configuration file before we leave:

> blogdown::check_config()
― Checking config.yaml
| Checking "baseURL" setting for Hugo...
○ Found baseURL = "https://silly-dubinsky-de5482.netlify.app"; nothing to do here!
| Checking "ignoreFiles" setting for Hugo...
● [TODO] Add these items to the "ignoreFiles" setting: "\\.Rmd$", "\\.Rmarkdown$", "\\.knit\\.md$", "\\.utf8\\.md$"
| Checking setting for Hugo's Markdown renderer...
○ All set! Found the "unsafe" setting for goldmark.
― Check complete: config.yaml

Looks like we have a few [TODO] items to add to our config.yaml file:

rstudioapi::navigateToFile("config.yaml", line = 15)

Goodbye Nelson B.

Let’s say goodbye to Nelson Bighetti. Everything in this single markdown file populates what is called the about widget; a customized one looks like this:

Find and open the file content/authors/admin/_index.md:

rstudioapi::navigateToFile("content/authors/admin/_index.md")

Edit the YAML metadata to change:

The icons and where they link to
Your current role and organization
Your interests
Your education

The text under the YAML is your bio; you can use markdown here. Add an avatar.jpg file too (it must be named this) to the same folder.

Prune widgets

Remember how we started with thinking about your content? We are ready to prune out some of our unwanted widgets.

Recall that on the Academic demo site, the entire home page is filled with widgets! The default example site is the exact same as the demo. It sets almost every available widget to active to show you the range of what you could do.

Deactivating the widgets you don’t need and only activating the ones you want will help you avoid having your home page feel like the 💀 “scroll of death,” as my friend Jackie Wirz called it.

Remember my Mr. Potato Head analogy? The home page is your most prominent potato, and the widgets are all the pieces you could use.

Each widget you see is a *.md file in the content/home/ folder. The metadata at the top helps you configure each widget; namely whether it is active (true or false) and the widgets weight (ordering, actual numbers doesn’t matter- only relative to the other weights).

For example, to turn off the hero widget, use this code in your console and set active = false:

rstudioapi::navigateToFile("content/home/hero.md", line = 5, column = 10)

Take about 10 minutes about try out turning widgets off and on, and changing their order to see what you like!

You can also delete a widget file. You can always recover *.md widget files by going into your themes/hugo-academic/exampleSite/content/home/ folder.

For my own site, I use 4 main home page widgets:

about (photo / icons / bio / interests / education)
slider (used to showcase some feedback from my workshops)
posts (set to show only the most recent)
talks (set to show only the most recent)

Transplant widgets

If you opted for a more streamlined home page with fewer widgets, you may experience widget pruning regret. Many are very useful, and you may wish to use widgets on other pages that are not the home page. In this theme, this is possible! Even if you turn off a widget on the home page, you can create what is called a widget page and add or even combine widgets there. I make heavy use of widget pages in my own site. Here are the steps (following the docs):

Create a new folder in content/; let’s call it resume
Inside content/resume/, add a file named index.md

Populate content/resume/index.md with a YAML, like this:

---
summary: More about my work experience
title: "Resume"
type: widget_page
---

The very critical line here is the type: widget_page—this sets you up to now copy over widgets from content/home/ in this new folder.

Copy the widget *.md files you’d like to use into this content/resume/ folder. Edit their metadata (weights, other info), and be sure to set active = true. For my own resume, I copied the experience and accomplishments widgets over.
If you want to access this new widget page from your top navbar, open up your config/_default/menus.toml and add it there, like:
```
[[main]]
  name = "Resume"
  url = "/resume"
  weight = 50
```

You can link to any specific widget by taking your baseurl and appending /#{name-of-widget}, so /#slider links to my homepage slider. And /resume/#accomplishments links to my honors & awards

Let’s run one final check, which wraps all 5 checking functions we’ve used so far into a single final checklist:

> blogdown::check_site()

This is immensely comforting to me; read more about these new checking functions here.

We made it!

At this point, you should be up and running with blogdown, GitHub, and Netlify. You now have the scaffold up and ready for your ideas, your style, and your voice. If you made it this far, please share your site- I’d love to see it!

Unbreak your blogdown site

Sun, 27 Dec 2020 00:00:00 +0000

This holiday season, the R Markdown elves at RStudio have been busy at work wrapping up the next release of the blogdown package. Blogdown is a package close to my own heart, as it was the subject of my very first blog post, and that led to co-authoring the book on blogdown.

Fast-forward more than three years later, and I have built, borked, and torched more blogdown/Hugo sites than I care to admit.

But, I’ve also learned a lot about how to use and learn blogdown/Hugo, and how to help other people troubleshoot their sites too.

For anyone thinking about dipping their toes into blogdown and making their first Hugo site, the vocabulary alone can be wildly intimidating. I remember being skeptical about Netlify, and also not fully understanding how exactly I had entered into a relationship with Hugo and what our boundaries were. There are so many moving pieces, and many possible missteps for new and even “more senior” users like myself. I’ve seen it all- users trying to serve a site from within an empty repo, having a missing theme folder, ignoring all rendered files, accidentally knitting an R Markdown file ( but now you can!). The list goes on and on and on.

I admit- I originally thought education could solve these issues at first. We just needed to improve the documentation, I thought. Maybe the book could be better. But, in truth, we needed to think inside the package box, because that is the only failsafe way to reach users. So, the package itself needed to do more. The blogdown package had already implemented several printed warnings and error messages intended to help guide users toward the happy path. However, we got feedback that many users were unsure how to act on the messages and sometimes just ignored them (myself included!). Then I asked my colleague Jenny Bryan about her approach to package warnings and error messages, and she said something very simple (paraphrased from my notes!):

When possible, it is much better to offer users control over when and how they can solve their own problems.

When you force users to wait for an error to occur, you are putting the user in a reactive stance. This is typically not a great mental space to be in to learn. Learning is highly unlikely in a reactive stance too, because messages focus on informing the user what the error is, but often fail to say how to make it go away. On the other hand, giving users targeted functions can help them feel proactive and empowered. Well-designed functions can give you as the package developer an opportunity to offer opinionated advice, and at the same time, help the user gain a mental model of a complicated situation. This idea is the driver behind the usethis::git_sitrep() and usethis::proj_sitrep() functions.

After this conversation with Jenny, I sketched out an idea for a series of “checking” functions for blogdown. I wasn’t sure all of these were actually possible, but with the amazing help of Yihui Xie and Christophe Dervieux, we came up with five functions to help ensure user success:

check_config()
check_gitignore()
check_hugo()
check_content()
check_netlify()

Each of these functions is meant to be used interactively as you build and edit your blogdown site. A clean pre-flight checklist still unfortunately cannot ensure website success, but it will help users sidestep the most common and avoidable pitfalls.

A sixth function, check_site(), wraps all five up in a single function, which I suspect will be most useful for existing blogdown users who are already familiar with GitHub, Netlify, and Hugo.

We ended up doing a lot of massaging of the output formatting ( see my PR), and finally settled on the following:

----------------------------------------------------------
○ A successful check looks like this.
● [TODO] A check that needs your attention looks like this.
| Let's check out your blogdown site!
----------------------------------------------------------

I’m really happy with the end result, and I hope users are as well. I not-so-secretly hope these functions help educators feel braver about teaching blogdown too. So, without further ado…

| Let's check out your blogdown site!

To do this on your own, you’ll want to use the remotes package to install the development version of blogdown:

remotes::install_github("rstudio/blogdown")

Check your site’s configuration

Your Hugo site’s main configuration file is located in the project root of your website, called config.toml or config.yaml. This file is your most direct line of communication with Hugo itself, and settings in this file are usually the first I check when trying to help users troubleshoot their build.

blogdown::check_config()

― Checking config.toml
| Checking "baseURL" setting for Hugo...
○ Found baseURL = "https://alison.rbind.io"; nothing to do here!
| Checking "ignoreFiles" setting for Hugo...
● [TODO] Add these items to the "ignoreFiles" setting: "\\.Rmd$", "\\.Rmarkdown$", "\\.knit\\.md$", "\\.utf8\\.md$"
| Checking setting for Hugo's Markdown renderer...
○ All set! Found the "unsafe" setting for goldmark.
― Check complete: config.toml

You can see I have one [TODO] item. Below, I’ll bork up my own config.toml file a bit more:

― Checking config.toml
| Checking "baseURL" setting for Hugo...
● [TODO] Update "baseURL" to your actual URL when ready to publish.
| Checking "ignoreFiles" setting for Hugo...
● [TODO] Add these items to the "ignoreFiles" setting: "\\.Rmd$", "\\.Rmarkdown$", "\\.knit\\.md$", "\\.utf8\\.md$"
| Checking setting for Hugo's Markdown renderer...
| You are using the Markdown renderer 'goldmark'.
● [TODO] Allow goldmark to render raw HTML by adding this setting to config.toml (see https://github.com/rstudio/blogdown/issues/447 for more info):

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

==> Do you want blogdown to set this for you? (y/n) n
― Check complete: config.toml

A few more [TODO] items here, but all are actionable, and originate from a single file (config.toml) which the function also opens for you interactively. 🎉

Check your `.gitignore` file

If you are using blogdown, you’ll likely need a version control system like Git. Files named in a .gitignore file will always be ignored whenever you add and commit files to your remote repository, but having the wrong files listed here can easily sink you a few hours (I’ve had this happen several times with collaborators!). Now, we can run a tidy little check:

blogdown::check_gitignore()

― Checking .gitignore
| Checking for items to remove...
○ Nothing to see here - found no items to remove.
| Checking for items you can safely ignore...
○ Found! You have safely ignored: .DS_Store
● [TODO] You can safely add to .gitignore: Thumbs.db
| Checking for items to ignore if you build the site on Netlify...
○ Found! You have safely ignored: public, resources
― Check complete: .gitignore

This function screens for items you should remove, and for items you can safely add. It also checks if you are using Netlify, which we assume based on the presence of a netlify.toml file in your project.

Check your Hugo versions

Hugo versions were by far my biggest pain point. Earlier this year, I had added some kind of Hugo versioning system built into blogdown to my giant feature wishlist. I am so relieved that this latest release of blogdown includes this, but that meant we also needed to provide users with ways to inspect and maintain their Hugo versions.

blogdown::check_hugo()

― Checking Hugo
| Checking Hugo version...
○ Found 4 versions of Hugo. You are using Hugo 0.79.0.
| Checking .Rprofile for Hugo version used by blogdown...
| Hugo version not set in .Rprofile.
● [TODO] Set options(blogdown.hugo.version = "0.79.0") in .Rprofile.
● [TODO] Also run blogdown::check_netlify() to check for possible problems with Hugo and Netlify.
― Check complete: Hugo

Note that the new blogdown Hugo versioning system now relies on a .Rprofile file that you probably want to keep in the project root. These files are a bit annoying, because anytime you need to edit them, you’ll want to restart your R session for changes to take effect. If you don’t have a project-level .Rprofile file, try the newly added blogdown::config_Rprofile() function to create one (see ?config_Rprofile for help).

Check your Hugo content

Your Hugo site’s content predictably lives inside the content/ folder of your project. But there are lots of unpredictable things Hugo can do (or not do) with your content. For example, I think every blogdown user at some point has stumbled into the draft: TRUE minefield, or the future dated content abyss. As well, many users accidentally end up with duplicate rendered output files (Hugo will prefer the .html if present). This function checks these things for you:

blogdown::check_content()

― Checking content files
| Checking for previewed content that will not be published...
● [TODO] Found 1 file with a future publish date:

  content/talk/2021-rstudio-global/index.md

  If you want to publish today, change a file's YAML key to 'date: 2020-12-27'
○ Found 0 files marked as drafts.
| Checking your R Markdown content...
○ All R Markdown files have been knitted.
○ All R Markdown output files are up to date with their source files.
| Checking for .html/.md files to clean up...
○ Found 0 duplicate .html output files.
○ Found 0 incompatible .html files to clean up.
― Check complete: Content

Note that this also checks that all R Markdown files have some kind of knitted rendered output present. This is 🆕, and we believe is a better default. Think: save-on-knit. You now only need to knit R Markdown files (the previous behavior was knit-on-save, which sometimes led to an error-filled render vortex if your code did not run).

Check your Netlify setup

Almost done with your pre-flight checklist! The last one helps set you up for deployment success:

blogdown::check_netlify()

― Checking netlify.toml...
○ Found HUGO_VERSION = 0.79.0 in [build] context of netlify.toml.
| Checking that Netlify & local Hugo versions match...
○ It's a match! Blogdown and Netlify are using the same Hugo version (0.79.0).
| Checking that Netlify & local Hugo publish directories match...
○ Good to go - blogdown and Netlify are using the same publish directory: public
― Check complete: netlify.toml

No [TODO]s! Now let’s bork things up:

― Checking netlify.toml...
○ Found HUGO_VERSION = 0.69.0 in [build] context of netlify.toml.
| Checking that Netlify & local Hugo versions match...
| Mismatch found:
  blogdown is using Hugo version (0.79.0) to build site locally.
  Netlify is using Hugo version (0.69.0) to build site.
● [TODO] Option 1: Change HUGO_VERSION = "0.79.0" in netlify.toml to match local version.
● [TODO] Option 2: Use blogdown::install_hugo("0.69.0") to match Netlify version, and set options(blogdown.hugo.version = "0.69.0") in .Rprofile to pin this Hugo version.
| Checking that Netlify & local Hugo publish directories match...
○ Good to go - blogdown and Netlify are using the same publish directory: public
― Check complete: netlify.toml

Whoops! You can see that a mismatch was found: I’m using a newer version of Hugo on Netlify than I am using to build locally. You want these to match, so that you can be reasonably sure that what you see on your public site will not be a surprise 😱

Check your site

If you don’t want to go file-by-file and step-by-step, and you’re into more of a “kitchen sink” approach, give check_site() a try. It will wrap all these checks up for you in a single function call.

Please give the development version of the blogdown package a try, and help us make it better by filing issues on GitHub. And I hope these new functions help you have more fun actually working with your site!

You can watch my recent talk at the LA R User Group meetup on YouTube to see learn more about the new features you can look forward to with this latest blogdown release here.

M-F-E-O: postcards + distill

Tue, 22 Dec 2020 00:00:00 +0000

This is a very brief “postcard to myself” about how to use the new postcards package by Sean Kross. What problem does postcards solve?

“Create simple, beautiful personal websites and landing pages using only R Markdown.”

— postcards README.md

Postcards includes four templates:

You can see postcards::trestles in action here: http://jtleek.com/

And here (this is where we are headed!):

Distill is a package that also helps you make simple, beautiful websites and blogs using only R Markdown. They are M-F-E-O (‘made for each other’: this is a “Sleepless in Seattle” reference with sadly, a complete lack of video to support). But if you’ve seen the movie this scene may sound familiar:

Becky: So I mailed your letter.

Annie: “Dear Annie, thanks for your letter. It was great. You sound neat. We’re very excited about meeting you in New York on Valentine’s Day and seeing if we are M-F-E-O. See you soon. Sleepless in Seattle.”

Becky: M-F-E-O?

Annie: “Made for each other.”

Becky: It’s cute. It’s like a little clue. So he can’t write. Big deal. Verbal ability is a highly over-rated thing in a guy and our pathetic need for it is what gets us into so much trouble.

— Sleepless in Seattle, script from https://plantyourstory.com/mfeo-its-like-a-little-clue/

Consider this post like a little clue (I’m using it as a sandbox before updating our distill documentation for this new feature). Here is our existing signpost in the distill docs. With the CRAN versions of all three packages now, you can embed a postcards page within your distill site. This means the page will come with all your distill goodies like site navigation, theme, and google-analytics support.

You can see the demo site I made alongside this post here: https://apreshill.github.io/mfeo/ (source: https://github.com/apreshill/mfeo).

Pre-requisites

You’ll need the CRAN versions of three packages:

distill (v >= 1.2) (see: https://pkgs.rstudio.com/distill/news/index.html#distill-v1-2-cran-)
rmarkdown (v >= 2.7)
postcards (v >= 0.2.0)

install.packages(c("distill", "rmarkdown", "postcards"))

You can check these package versions as follows:

packageVersion("distill")
packageVersion("rmarkdown")
packageVersion("postcards")

Make a website

In RStudio, create a new project using File > New Project > New Directory > New Project. Then, inside your new empty project, use your R console to do the following:

library(distill)
create_website(dir = ".", title = "mfeo", gh_pages = TRUE)

At this point, I recommend closing RStudio completely and opening up your project again. This way you should see the “Build” tab.

Now build your site! You should see the “boilerplate” website template at this point.

Add a postcard

In your R console, use the postcards package to create a new postcard:

create_postcard(file = "tobi.Rmd") # future name of .Rmd file

Alternatively, you could use distill::create_article() to make a new page. To make a postcard, specify the template (one of: jolla, jolla-blue, onofre, trestles) and package = 'postcards':

create_article(file = "tobi",         # future name of .Rmd file
               template = "jolla",    # name of template
               package = "postcards") # package that includes the template

Let’s add a link to our new file in the top navbar. Open up your _site.yml file and add:

name: "."
title: "mfeo"
description: |
  mfeo  
output_dir: "docs"
navbar:
  right:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html
    - text: "Tobi"              # add
      href: tobi.html           # add
output: distill::distill_article

Since my file is named tobi.Rmd, that means the rendered file will be tobi.html, so that is my href key in the _site.yml. If you save that file, you should see your website refresh, and look something like this!

Add a theme

For fun, let’s go ahead and add a custom distill theme while we’re at it.

create_theme("postcards")

You can see copy my theme file from here: https://github.com/apreshill/mfeo/blob/master/postcards.css.

This should print to your R console:

v Created CSS file at postcards.css 
o TODO: Customize it to suit your needs
o TODO: Add 'theme: postcards.css' to your site or article YAML

See docs at <https://rstudio.github.io/distill/website.html#theming>

I want a full-site theme, so I added theme: postcards.css to my _site.yml file. I followed the distill docs on theming here. Re-build my website, and now I see:

Switch the homepage

Now you may be wishing that your postcards page was your homepage- the place where visitors first land when they visit your website. The homepage in a distill website is named index.Rmd, so we need to remove the current index.Rmd file and replace it with tobi.Rmd. But we cannot just rename the files…

If you open up index.Rmd, you should see this yaml:

---
title: "mfeo"
description: |
  Welcome to the website. I hope you enjoy it!  
site: distill::distill_website
---

That site key is very important to keep in the index.Rmd file. Steps:

Let’s start by adding site: distill::distill_website to the yaml of your postcards page, mine is named tobi.Rmd.
After doing that, you can delete index.Rmd.
Next, rename tobi.Rmd -> index.Rmd.
Finally, clean up your _site.yml - you can remove the link we added above to tobi.html.

Re-build your site and Tobi’s shining face should greet you from the homepage!

Fill-in your postcard

Of course, you can add your own image file to the project root at this point, and then personalize your index.Rmd using the postcards template:

---
title: "Alison Hill"
image: "alison.jpg"
links:
  - label: LinkedIn
    url: "https://www.linkedin.com/in/alisonpresmaneshill/"
  - label: Twitter
    url: "https://twitter.com/apreshill"
  - label: GitHub
    url: "https://github.com/apreshill"
  - label: ORCID iD
    url: "https://orcid.org/0000-0002-8082-1890"
site: distill::distill_website
output:
  postcards::jolla
---

Here is my “after”:

Add a blog

Back in your console, we can add a blog, using distill:

create_post("welcome")

If you do this with a blog already, it just adds a single post. But if you do this without posts set up, it does some nice things for you:

Creates a directory called _posts/ to hold all your future blog posts.
Creates a new post with a “slug” including the date and the name of the post (here, mine was "welcome").

Your new post should open up - go ahead and knit this post. Posts in distill need to be knit intentionally, so they will never be automatically built when you rebuild your website.

We also probably want to add a listing page to list all our blog posts. Do this by adding a blank .Rmd file to your project root, I’ll call mine blog.Rmd but there is no magic to this file name:

file.edit("blog.Rmd")

Then open up your new blog.Rmd and add a YAML (no content below the YAML):

---
title: "Blog"  # any name you want here
listing: posts # do this exactly
---

Finally, add a link to your blog in your upper navbar so people can actually find it! Do this by editing _site.yml one last time (remember, since my listing .Rmd is named blog.Rmd, then the href I want to link to is blog.html):

navbar:
  right:
    - text: "Home"
      href: index.html
    - text: "About"
      href: about.html
    - text: "Blog"      # add
      href: blog.html   # add

Now, admire your final polished product!

Switch your postcard

Let’s say you decide you want to switch it up and use the trestles theme, instead of jolla. Easy. Open up your index.Rmd and find these lines in the YAML:

---
output:
  postcards::jolla
---

And change to:

---
output:
  postcards::trestles
---

Re-build your site!

Publishing

I won’t be able to cover all the publishing options here, but you can read up on the options for publishing distill websites here. If you want to take a site like mine that you built, I recommend GitHub Pages. You can use the usethis package to run:

usethis::use_git()
usethis::use_github()

I also just learned about the new usethis::use_github_pages() to turn on and/or (re)configure GitHub Pages!

Then in the GitHub project, navigate over to “Settings” and scroooooooll down to choose:

For this to work, make sure your site is building to docs/ locally, and that you are committing and pushing the docs/ directory to GitHub.

Teaching students to talk about data science

Sun, 13 Dec 2020 00:00:00 +0000

Last summer (😬), I was invited to give a talk at the Joint Statistical Meetings on data science education. The session I was invited to join included Shannon Ellis, Stephanie Hicks, and Michael Love as the other speakers, and I immediately knew what I wanted to talk about!

Figure 1: L to R: Shannon Ellis, Stephanie Hicks, Michael Love, me

If you just want to skip to my actual slides, they are here.

Teaching students to talk about data science

One of the things I spent a lot of time thinking about in my 12 years as a professor was how to teach students how to communicate about data science with other human beings. It is sometimes all too easy to focus on “just” the practical skills like being able to wrangle, explore, analyze, and visualize data (preferably using code). But, teaching students to be able to describe, document, plan, collaborate, question, and communicate effectively about data science? That is way harder than it sounds.

For example, you may know learners like this:

You can ask them focused questions on an assignment, and they do fine. Maybe even great.

Figure 2: A+ writing

Then you may ask them to present their work. Also fine. Maybe even great.

Figure 3: A+ presenting

Then comes the Q&A, and maybe a colleague you invited or another student asks a good question…and your star student freezes. Or maybe they tell you about a job interview they had, and they fumbled it.

Figure 4: Oh no

As a former language researcher, I like to compare this to learning the semantics versus pragmatics of language. So semantics is concerned with getting vocabulary and meaning correct. But pragmatics is all about language use in real life. And to get a job, to engage with and contribute to the data science community, learners need pragmatics.

Figure 5: The semantics & pragmatics of data science communication

So how did I start getting them there? Sort of by accident! One day, I happened to stumble upon a syllabus by Hal Daumé from his machine learning class. I noticed something intriguing in there called “self-assessments.”

Figure 6: From Hal Daumé's syllabus

This slide was all I could find out about it, but it was enough to get my wheels turning right away. Having a Ph.D. in developmental psychology, I’d spent a lot of time studying the literature on the science of learning, and the idea of a self-assessment made me think:

Why might this actually work? It reinforces some tried and true self-directed learning strategies that are actually evidence-based like:

retrieval practice!
distributed practice!
elaborative interrogation!
self-explanation!

All that to say, self-assessment would help students talk to themselves and to me about data science- in a way that I hadn’t enabled before.

I won’t bore with all the edu literature, but if you want to know more you might enjoy reading:

I had also had this little bee in my bonnet for awhile, and that was that I spent an inordinate amount of time crafting the most beautiful homework answer keys for my students…that no one seemed to read. No one used my answer keys for learning. It bothered me because I knew there was value in reviewing these answer keys, but I hadn’t made them into an actual learning tool. When I saw Hal’s slide, it dawned on me: the solution to my problem was to give my answer keys away, and make them into a usable learning tool.^[I later found out that my palmerpenguins co-author Dr. Allison Horst does this too! https://www.allisonhorst.com/post/share-keys/]

The truth is, providing the answer keys or feedback at the end is not actually helpful for learners. Students have high motivation and set aside time for what matters for their grade, not necessarily their learning. So it’s no surprise that motivation was low and time was limited for students to devote to “extracurricular” learning.

What if the homework was less about how well students could do with little support, and more about how much they could learn with all my support?

I decided to find out. The next time I taught my statistics course, I began requiring students to turn in self-assessments. Here is my version of Hal’s slide with my rough plan:

Figure 7: Self-assessment plan

If you look carefully there, you’ll see that there are in fact two ways to succeed while really trying in my class, and I was very proud of this. At the beginning of class, I would tell students that some over-achievers might find this annoying at first, but that for me, my ultimate goal was that every single person learned. I didn’t care whether you got it right off the bat, or whether you needed more time and resources to get it right. Either way, my grades mapped onto actual learning.

Also note that the 0/1/2 points for the initial submission had nothing to do with accuracy of their initial solutions. And the accuracy for the self-assessment had only to do with the accuracy of their self-assessment! So really, we washed away the grading effect of getting it right in 1 week alone or in 2 weeks with the key. The students who got it right on the initial submission bought themselves every other week free and clear from assignments, though.

How to succeed while really trying

Submit a perfectly accurate initial solution.

If your initial submission was a good faith effort (2 points) and happened to be perfectly accurate when you reviewed the answer key (3 points), you got a 5/5 for that question.

“I found the same results as the answer key. Bada bing, bada boom.”

Submit a perfectly accurate self-assessment.

If your initial submission was a good faith effort (2 points) but you did a bang-up job analyzing all of your mistakes and misunderstandings after thoroughly reviewing the key (3 points), you got a 5/5 for that question.

“Well, well, well. I was really confused about interaction effects.”

“Gah! I didn’t actually understand the null hypothesis here.”

“I forgot to set a seed for my permutation test, so now I see why my results kept changing!”

Sample self-assessments

“Most of my code matches the answer key - there were only one or two sections where I didn’t make the correct plot or write the correct code for the desired output, but I think a good portion of my narrative was accurate, which is encouraging.”

“After doing this self-assessment, I’m realizing that I had a better grasp on this analysis than I had previously thought. I made a couple small errors, but after seeing the answer key, I think I understood why I made them and how to avoid those errors in the future. "

“I liked that the self-assessment allowed me to see where I was close and what parts I was really far off.”

“I found that, while generating this model was straightforward, interpretation of the results was more difficult than I expected.”

Logistics

OK, at this point, you may also be credibly curious. But you are probably wondering, how on earth did this actually work?

Turning it in

We advised students to color their text in R Markdown files knitted to HTML. The self-assessment portion always needed to be colored. You can find guidance on how to do that in the R Markdown cookbook: https://bookdown.org/yihui/rmarkdown-cookbook/font-color.html

Trade-offs

Yes, I did have to cut back significantly on my homeworks. Whereas I would have anywhere from 6-8 homeworks before, I went down to four per quarter (plus a final project). This was because I typically allowed 1 week for the initial submission and another for the self-assessment, with no overlap. So each homework took 2 weeks. I trimmed homework length down, and I cut out anything that wasn’t essential.

Time spent by TAs

Honestly, I would have loved for self-assessments to have saved myself and my TAs time. I cannot say this was my experience. It was about the same amount of time overall.

But, what our teaching team did notice was that we felt better with our own grade assignments, and we enjoyed the grading process more. Rather than feeling like you were searching for mistakes to remove points, you were searching for true insights gained to add points. Small code errors or typos were usually caught by the students themselves, so TAs felt less personally responsible for making sure students were made aware of everything they did wrong. Also, student self-assessments were funny, charming, and allowed us to get to know them better. We also were better able to identify students who could use 1-on-1 help…because they would tell us that.

And that brings me to the most common question I get: how did I assign grades? Truth be told, grading was my absolute least favorite part of teaching in academia. But self-assessments actually helped me get to a place where I felt like my grades mapped onto my goals. Here is an excerpt from my syllabus that describes my system:

Homework

A total of 4 homeworks will be assigned; your lowest score will be dropped at the end of the quarter. Some homeworks will require you to use R to analyze data. Although no prior R experience is required for this course, be prepared to do a lot of self-guided learning. Students are expected to run R on their own computer or a computer they have plenty of access to and control over. Please attempt to do all homeworks on your own, but you may work with other students. However, you may not submit homework assignments as a group. You should submit your own original work.

You will have 1 week to complete each homework assignment, and your initial solutions must be submitted to Sakai by 2pm on the due date (at the start of class on Thursdays). Late homeworks will not be accepted.

Homework self-assessment

After the initial solutions are due, you will be provided a solution key. Using that key, you will be asked to assess your own initial solutions for accuracy and thoroughness; where you made mistakes, you must discuss and analyze where you went wrong, and correct them without copying/pasting directly from the key (this typically means that you need to include more narrative than we provide in the key). A good self-assessment will include:

Assessment of the accuracy and completeness of your “initial solutions”
Correct worked solutions with some discussion and analysis of why your initial solution was incorrect, and reflection on the source of your confusion (if you got an answer correct, this is not necessary)
Attributions as appropriate to other students who helped you, or other sources such as lecture notes, readings, online resources, etc. that helped you

Homework grades

Homework grades will be based on:

Was your initial solution a good faith effort?
Did you catch all of your own errors in your self-assessment?
Is your updated solution correct?

Each homework includes 3 questions, worth 5 points per question, scored as follows:

2 points for each initial solution being “in-good-faith”.

2 (Strong attempt): answer reflects strong independent problem solving, with clearly thought out attempts to approach the problem and a diligent and honest effort to find the solution
1 (Weak attempt): answer reflects some attempt to approach the problem, but approach appears to be superficial and lacks depth of analysis
0 (No attempt)

3 points for the quality of the final answer / discussion.

3 (Exceptional): answer is thorough, concise, and clearly demonstrates ability to analyze and interpret statistics as well as theoretical understanding of statistical concepts
2 (Adequate): answer addresses the question with moderate inaccuracies in analysis and/or interpretation, or offers a correct but incomplete answer
1 (Inadequate): answer attempts to address question with substantial inaccuracies in analysis and/or interpretation
0 (Insufficient): answer does not attempt to address question or answer is insufficient to grade

This means that:

You can get 100% of the points if you either:
- Submit perfectly accurate initial solutions, or
- Submit a perfectly accurate self-assessment,
If you simply cannot submit any homework solutions on time, after the homework due date, you will receive the solutions key and can submit a self-assessment for a max score of 60% (3 out of 5 points per problem). We feel this is fair given that:
- You did not attempt a good faith effort, and
- We will drop your lowest homework grade.

What is a “good faith effort”?

Simply submitting nonsense or saying “I can’t do this” for each problem will not meet our criteria for a good faith effort, because there is no attempt on your part to show us why you are struggling, what you tried but didn’t work, what specific part of the problem you got stuck on, which other examples in the text/lecture you tried to work through to get a grasp on the problem, etc. ^[This is especially true if you don’t attend any office hours, post on Sakai, or otherwise seek out help before the due date.] The good faith effort is just that- we are interested in seeing evidence of a diligent and honest effort on your part, made with deliberate intention, to understand the problem and attempt an answer.

In the talk I gave at JSM, I talked about self-assessments as just one out of three strategies I used to get students talking about data science. My students often had a final project and/or presentation at the end of a course, which I also think helps them to think out loud and on their feet. I sincerely hope other educators try these kinds of methods out! I can honestly say I wouldn’t teach a university-level course any other way.

Figure 8: All three strategies

How much Hugo do I need to know?

Sat, 12 Dec 2020 00:00:00 +0000

Greetings and happy holidays! As many folks are looking forward to down time over the holidays, my inbox naturally starts filling in with questions like “What is the difference between blogdown and X?”, “How hard is Hugo to learn?”, and “Which Hugo theme do you recommend?” These are all great questions. But the best one in my mind that one needs to ask is:

“How much Hugo do I need to know right now?”

And the answer, of course, depends on where you are starting from and where you’d like to end up.

In this post, I’ll share when and why I think a typical R blogdown user needs to learn Hugo. I’ll tell you a secret: I enjoyed learning Hugo. But I learned blogdown first, and frankly was blissfully unaware of the complexity of the underlying Hugo templating language. I was a happy blogdown user for about 1.5 years before taking the plunge to actually learn Hugo. Why did I do it? I needed to build a website for the RStudio Education team, and for sustainability and maintenance, I had been burned by external themes in various ways too many times for my personal site.

We decided as a team that we didn’t want our site to depend on a third-party Hugo theme. What can go wrong with using third-party Hugo themes? For one, if you choose a not very active or well-maintained theme, then you could get stuck with a not well-maintained theme. Or worse, your theme could get orphaned, with no maintainer. But, on the flip-side, if you pick a very active and well-maintained theme, you might find yourself dealing with theme and Hugo updates more than you would like (cough cough like the Wowchemy/Academic theme).

The tidyverse.org site was built with a lot of custom HTML, CSS, and some Hugo layout files. I decided to turn that site into a real Hugo theme, and use that theme across teams. You may not have noticed any change when we switched to the new theme- at least I hope you didn’t! That site and the RStudio Education site both use the same Hugo theme I built.

Now that I’ve gone from casual Hugo user to theme developer, I have some advice. Generally, as a blanket rule, here is what you should and should not touch:

An #rstats #blogdown file hierarchy cheatsheet:

├─ archetypes <- edit me!
├─ config.toml <- edit me!
├─ content <- edit me!
├─ data <- edit me!
├─ layouts <- edit me!
├─ public <- ignore me!
├─ static <- use me! (png/pdf/csv/xls)
├─ themes <- don't touch! pic.twitter.com/gvVA703Lwa
— Alison Hill (@apreshill) December 28, 2018

But what can you do with blogdown before learning Hugo? When and how do you know when you need to get to know Hugo better? Hopefully this post will help answer these questions.

Inspired by Jenny Bryan’s talk on lazy evaluation, I’m framing these learning decision points based on what you want to get done.

You want to: make a website with blogdown

You need to know this much Hugo: Hugo takes a collection of files (called content) and generates a collection of static HTML files as a single, cohesive, navigable website (plopped in your public/ folder). How it looks depends on which Hugo theme you pick r emo::ji("paint")

You’ll need to:

pick a Hugo theme, which dictates the style and layout of your content.
build and serve your site locally.
deploy your site! If you are just starting out, I recommend everyone starts by first dragging and dropping your project’s public/ folder into Netlify. There is your site r emo::ji("boom"). With a link. That you can send to your best friend right now.
realize this is a static site. Read up on static sites!

But you probably want to do more…

You want to: customize your site

You need to know this much more Hugo: Hugo themes typically use one or more metadata files (TOML or YAML) to set up global variables to use to build your site. This is usually the way to add a site url, a site name, link social accounts for personal websites, basically take any of the default content you see and customize it for you.

The main files to edit are:

configuration files

To get familiar with TOML, I recommend:

But, since the time we published the blogdown book, Hugo introduced configuration directories, which allowed us to no longer have one giant config.toml file, and instead have multiple configuration files, like this:

├── config.toml            <- Hugo-defined variables
├── config
│   ├── _default
│   │   ├── menus.toml     <- menus :)
│   │   └── params.toml    <- theme-specific variables

Here is how you can think of these:

config.toml/config.yaml: your most direct communication with Hugo. These are standard Hugo-defined variables that have defaults you can override in this file. You can view all of them here. These are universal across themes.
menus.toml: your way of editing the content in a side or upper navigation menu bar; see example here. These work the same way across themes (with the exception of drop-down menus, which work in some themes but not others).
params.toml: your theme’s way of providing an API for Hugo. These are variables that your theme creator has made for you! This is a gift, but not the kind you can re-gift easily. This file will not work with any other theme.

If your theme uses only a single config.toml file, you can infer these subsections as you scroll down:

# before the first use of [[]]
# are all the Hugo variables

# Menu Configuration- same as menus.toml
[[menu.main]]

# Theme Configuration- same as params.toml
[params]

You still don’t need to learn Hugo…yet.

You want to: add content to your site

You need to know this much more Hugo: Remember how the input to Hugo is a “collection of files”? The input is more specifically a collection of markdown files. Hugo themes use content written in markdown files (for blogdown users, R Markdown files work too) to generate your site’s content; with one very important rule — the same structure that works to organize your site content is used to organize the rendered site.

But, what does that mean?

The main files to edit are:

files in the content/ folder (and see my post on page bundles)

First, the structure and the names inside your content/ folder is meaningful. The names of each folder determine what Hugo layout will be applied. Why do you care? If you change the content name, things may not look good because Hugo can’t find the right layout. Think of your site like going to a party at a friend’s house- you can bring food, wine, maybe a board game- your host knows what to do with these things. But if you bring a monkey, for example, your host has no idea what to do with it!

Yuo can override this by adding a layout key to your file’s YAML, as described here. The relevant bit is here:

“layout: the layout Hugo should select from the lookup order when rendering the content. If a type is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content’s section.”

The subfolders also tell you where you can find your content on your site.

.
├── content/
│   ├── authors/            # => https://example.com/authors/
│   ├── privacy/index.md    # => https://example.com/privacy/
│   └── home/               # => https://example.com/

You should take a bit of time to get the “cook’s tour” of your site. Try looking at each file and guessing the URL you’ll use to see it in the rendered site. Do this now and it will become like second nature.

You’ll no doubt run into one question: what is the difference between index.md and _index.md files? index.md are simple pages; the single file goes into the site and a single file comes back out when you view the site. This is called a leaf bundle in Hugo.

.
├── content/
│   ├── privacy/index.md       # => a leaf bundle
│   └── blog/                  # => a branch bundle
│       ├── _index.md          # => AHA!
│       ├── gorillas/index.md  # => a leaf bundle
│       ├── baboons/index.md   # => another leaf bundle
│       └── monkeys/index.md   # => yet another leaf bundle

An _index.md file, on the other hand, signals that this folder has a listing page activated. This is called a branch bundle in Hugo. Listing pages are a bit magical, so make sure you understand them now. Typically, if you edit the _index.md file at all, you edit the YAML of this file- often the page content below the YAML isn’t revealed by the theme (this is a bit hand-wavy and I’m sorry for that).

So if you have content/blog/gorillas/index.md, you get not one but two pages. Let’s pretend my baseurl is alison.rbind.io. You get a list page that will render at alison.rbind.io/blog/, and indexes all the index.md files inside that content folder. You also get a single page that will render at alison.rbind.io/blog/gorillas/, which shows you the full content of the index.md file.

You want to: customize colors and fonts on your site

You need to know this much more Hugo: It depends on your theme :) You may need to learn CSS, and you may need to learn to read Hugo now.

Many Hugo themes enable users to edit aesthetic elements like colors and fonts. So, depending on your Hugo theme, you may not need to know CSS. Other themes provide a way to “plug in” a custom CSS file to change those things and more (like spacing, font sizing, etc.). Guess where that is? Usually it is in your config.toml file in the [params] section (if no configuration directory) or the params.toml file. The theme author should leave you a breadcrumb to figure out what you should name and where you should place your custom CSS file.

For example, the Hugo academic theme provides a few ways in. In the params.toml file, you can use an included site color theme or make your own, and customize your fonts. You can also provide your own custom CSS file by including it here: https://github.com/gcushen/hugo-academic/blob/master/assets/scss/custom.scss

If your theme doesn’t provide this level of support, then you may need to learn Hugo. Sometimes the options are tough to find, unfortunately, but many theme designers provide at least a plug-in option. Others may require you to dig into some of your theme’s partial layouts (i.e., themes/theme_name/layouts/partials/) and learn to read them. Here are some examples:

Plug-in CSS: Hugo Tranquil Peak theme tells you to place the file inside your static/ folder then provide the path and filename in the config.toml file:

[params]
  # Custom CSS. Put here your custom CSS files. They are loaded after the theme CSS;
  # they have to be referred from static root. Example
  # [[params.customCSS]]
  #   href = "css/mystyle.css"         <- AHA!

Go Fish: Hugo I Am Sam theme doesn’t give you this in the config.toml file, but looking at one of the layout partials you can see that the theme is actually built to plug-in your custom CSS:

<!-- Custom css -->
{{ range .Site.Params.customCSS -}}    <- AHA!
{{ $style := resources.Get . }}
<link rel="stylesheet" href="{{ $style.RelPermalink }}" integrity="{{ $style.Data.Integrity }}" crossorigin="anonymous" media="screen">
{{- end }}

You want to: renovate the layout of content on your site

You need to know this much more Hugo: You need to learn to use Hugo variables.

I say renovate, but these can be anywhere from small to big renovation projects. The key word here is renovate, which in Hugo world, means you want to override your site’s theme. Let’s say you want different information to show up in your site’s footer. Or maybe you want add something new to the metadata for your blog posts.

Here is a great blog post to get you started:

Override a Hugo theme

tl;dr: If you adapt your existing theme’s Hugo layout files, be sure to make a copy of the layout you want to edit first and add it to your project root’s layouts/ folder before editing. Please do not edit any files anywhere in your themes/ folder.

Now, the hardest part of doing is often figuring out which layout file is the one you need to edit. Often you’ll need to do some digging to figure out which file is the one to touch.

.
├── layouts/
│   ├── _default/           # edit me!
│   ├── authors/            # edit me!
│   └── partials/           # edit me!
├── themes/
│   ├── theme_name/
│   │   ├── layouts
│   │   │   ├── _default/   # do not touch
│   │   │   ├── authors/    # do not touch (seriously)
│   │   │   └── partials/   # `r emo::ji("fire")`

You’ll also want to learn about Hugo variables, especially:

You also might need to understand Hugo logic like:

iteration and
conditionals

Important: I learned this the hard way, but you cannot wrap your Hugo code in HTML comments to deactivate it; all Hugo code even inside of HTML comments will still be evaluated when you build your site.

You want to: create your own Hugo theme

You need to know this much more Hugo: Welcome to the wizarding world of Hugo! r emo::ji("wizard") You now need to learn to write Hugo templates.

Here are some resources for writing Hugo templates:

These resources were especially helpful to me:

The blogdown book section on templates
The blogdown book section on customizing layouts
The Hugo docs are pretty strong
Make a Hugo blog from scratch | zwbetz
Hugo Community Discourse Forum
All of Mike Dane’s Hugo tutorials

I spent a lot of time looking at other Hugo themes; here are some quality ones to learn from:

Maëlle Salmon’s ROpenSci Hugo theme: https://github.com/ropensci/roweb2/tree/master/themes/ropensci
Amber Thomas’s Data Science Hugo theme: https://github.com/ProQuestionAsker/hugo-data-science
Danielle Navarro’s slum Hugo theme: https://github.com/djnavarro/hugo-slum
My own humble Hugo theme: https://github.com/rstudio/hugo-graphite

Again, this is all just based on my own experiences- your mileage may vary as always.

The download

Tue, 08 Dec 2020 20:30:00 +0000

The R Markdown family of packages has grown a lot over the past few years! While each new package is truly a bundle of joy, the past few months we have worked hard to make our family of existing packages more consistent, supportive, and intuitive. In this talk, I’ll share some of what we are up to lately and what to expect, with highlights from the distill, blogdown, bookdown, and xaringan packages.

InspiRing InstRuction: A panel on teaching #rstats for all audiences

Thu, 12 Nov 2020 09:00:00 +0000

Someone in your department, company, or class comes to you and says: “I want to learn R; where do I start?” Or, “how do I take my R skills to the next level?”

Come hear from 3 R-Ladies on how to make R pedagogy work for different groups of people!

distill

Sun, 01 Nov 2020 00:00:00 +0000

R Markdown for Pharma

Wed, 07 Oct 2020 13:00:00 +0000

A four-hour workshop that will take you on a tour of how to get from data to manuscript using R Markdown. You’ll learn:

The basics of Markdown and knitr
How to add tables for different outputs
Workflows for working with data
How to include and style graphics

Presented with Tom Mock from RStudio.

Learning without a net

Wed, 07 Oct 2020 09:00:00 +0000

In this talk, I shared my experiences learning new data science skills on my own, and some broader strategies for learning when you have to do it by yourself.

Teaching in Production

Wed, 23 Sep 2020 09:00:00 +0000

This goal of this workshop is to equip educators with the tools that can help them make their teaching more robust and reproducible with R Markdown.

Trainings offered:

2020-09-23
2020-09-20

RStudio Teaching in Production

Wed, 23 Sep 2020 00:00:00 +0000

Introduction to Machine Learning with the Tidyverse

Thu, 27 Aug 2020 13:00:00 +0000

This four-hour workshop will provide a gentle introduction to machine learning with R using the modern suite of predictive modeling packages called tidymodels. We will build, evaluate, compare, and tune predictive models. Along the way, we’ll learn about key concepts in machine learning including overfitting, the holdout method, the bias-variance trade-off, ensembling, cross-validation, and feature engineering. Learners will gain knowledge about good predictive modeling practices, as well as hands-on experience using tidymodels packages like parsnip, rsample, recipes, yardstick, tune, and workflows.

The workshop was adapted from a 2-day in-person workshop delivered at rstudio::conf(2020) in San Francisco, CA.

palmerpenguins

Thu, 11 Jun 2020 00:00:00 +0000

How I Taught Tidymodels, Virtually

Tue, 02 Jun 2020 00:00:00 +0000

A few weeks ago, I wrapped up teaching tidymodels for the third time. We say third time’s the charm, right? Even during a global pandemic? I don’t know, but this time around was fun in new ways and hard in new ways, so I wanted to take the time to write some thoughts down about how it went.

But why?

Why teach tidymodels virtually? I’ve already taught it as a 2-day workshop at rstudio::conf(2020). I had already agreed to teach intro to machine learning with tidymodels as a full-day workshop for the Cascadia R Conf (which unfortunately was cancelled due to COVID), and the R / Medicine conference (still on, and 100% virtual!).

I had three main goals:

First, I wanted to do a good job for the R / Medicine conference workshop in August. This seemed like an interesting teaching challenge. One of the best compliments I’ve ever gotten from a colleague is that I “teach with heart” — so the challenge was, can a virtual workshop have a ❤️?

Second, given current events, I saw an opportunity to document a good system (tooling + pedagogy + logistics) around virtual workshops. I don’t see them going away anytime soon. My colleague, Greg Wilson, had also been giving our RStudio certified instructor workshops virtually for over a year, so I trusted that he could help me navigate.
Third, help out the R / Medicine conference organizers. My partner-in-crime for this particular workshop, Dr. Stephan Kadauke, wanted to join me for some reconnaissance work. He is one of the conference organizers and will be leading his own workshop there, so he wanted to test out the tooling and the pedagogy too.

So we thought, three birds, one stone: I get to pilot a much shorter version of my conf workshop materials, we get to test doing it virtually, and the R / Medicine conference organizers learn how this could all work in August.

How we planned it

Starting out, I knew I had two main hurdles:

Shaving two days of workshop content into X days
Logistics (like figuring out what X should be!)

The first decision based on conversations with Greg was to offer the workshop across two half-days. This is how the RStudio instructor training is timed, and it works well because there are few people who can (or want to) be tied up for a full day, especially if under stay-at-home orders. We asked Stephan if his group at the Children’s Hospital of Philadelphia (CHOP) would be up for two 4-hour sessions. Stephan’s feedback was yes, but given that these folks at CHOP typically have weekly schedules, having two consecutive days would not work. So we opted for:

Two 4-hour sessions that were…
exactly one week apart.

I’m in Oregon, they were in Philly, so we decided to start at 9am my time (1pm for them) and wrap up at 1pm my time (5pm for them). After making this call, and again with Greg’s sage advice to take a break every hour, I started working on a rough schedule. I had about 8 hours total to work with; about half of my conf workshop. We decided on:

50 minute chunks, and
10 minute breaks at 10 till the hour every single hour.

I didn’t try to make sure my materials for each session filled exactly 50 minutes. Instead, I promised the group that I would break wherever I was at the same time, and after each break we just picked up where left off.

Here was the new topic outline:

Day 1

Session 00: Intro (include a tooling tour- orient to Google doc + Zoom)
Session 01: Build a model (mainly parsnip package)
Session 02: Resample a model (add rsample package, plus tune package for fit_resamples())
Session 03: Build a better training set (add recipes and workflows packages)

Day 2

Session 04: Build an ensemble model (back to parsnip, now with model arguments)
Session 05: Tune a model (heavy tune package)
Session 06: The Great Model-Off (a Kaggle-like group activity)

The final decision was about tooling. Luckily, Greg had advice here too. We went with:

Google doc as the “home page” + chat (no workshop website!)
RStudio Cloud for all exercises
Zoom for video

Pre-workshop launch list

Make shared Google doc and prepopulate with: Zoom link, RStudio Cloud link, bulleted list of participant names (be sure to make this editable for anyone!)
Email everyone with a Google calendar invite that includes the Zoom link and a link to a shared Google doc (be sure to make this editable for anyone!)
Ask everyone to fill in their 2-sentence bios ahead of time to ensure that you’ve done this correctly!

The Zoom link and the Google doc link should be the only links that attendees see ahead of time. Then, the Google doc is the one true source for everything. Too many links at first leads to confusion later. I also prepopulated the doc with my session outline with HTML links to each session’s slide deck.

Actual launch

In Zoom, I set it up to mute everyone as they joined. We started with an orientation of the tools, the schedule, and the general plan for how they would work and interact with each other. We tried to keep questions per session in the Google doc, which my TA Stephan fielded in real time, which now is a great resource for me as I prepare for this again in August.

What I should have done:

Have a Code of Conduct. I will next time. We didn’t have any issues, but what came up later was that I asked participants to turn on their cameras. I wished that part of my Code of Conduct was that we would not videotape or take screenshots at any point to protect the privacy of all participants.
Asked folks to make sure they had an updated version of Zoom. In particular, some newer security issues have been addressed recently, so this is nice for everyone to take advantage of. Plus the interface looked different for some.
Locked down the Zoom room. After a few minutes of starting, it was super distracting to have late arrivals who kept sending me personal chats asking for the links.
In addition to locking down after the first 10-15 minutes, I also should have assigned my TA as a co-host, so that he could have helped me manage that. We did this on day 2 and it worked great.

How did it go?

So, I’m not going to lie here. The first session of teaching spooked me a bit. This was because all attendees left their videos off and I felt like:

It was eerie to teach to a silent void. On day 2, I asked for two volunteers to turn on their cameras for a single 50 minute block each because it really helped me to see faces. Participants probably kept their own view as “speaker only”, but for me it really helped to be able to have some human feedback, even if they were muted. Much love to the head nodders out there. This conversation on day 2 broke my heart though, because several participants indicated they felt they couldn’t turn on their cameras because they had young children at home. It is hard.

Interestingly, the participants didn’t sense my discomfort at all. In fact, I heard from several that it was nice to see me up close and so personal. It actually felt more personal than a large in-person workshop, to my surprise.

On day 1, I started by asking participants to use Zoom reactions (like thumbs up) to answer questions, give me progress updates, etc. I ended up retiring this- it was distracting and the reactions disappear so it wasn’t actually useful. Instead, I asked people to use the Zoom chat to indicate “done” or give quick one-word answers (a or b, yes or no).

Stephan also had a great idea for the breaks. On day 2, I started using Garrick Aden-Buie’s countdown app to show the 10 minute break countdown full-screen. I used the hosted version here.

What can I do better?

Logistically, I got really frustrated because I kept losing my Zoom meeting controls. Later I found out about this accessibility setting, which would have helped!

More substantively, as I mentioned, I would have a Code of Conduct at the very beginning. I also think virtual workshops offer a unique opportunity to include some more creative exercise types. Here are a few I brainstormed with Greg Wilson after the fact—expect to see these at R / Medicine if you attend with me!

Spot the bug- do in groups
Unscramble code
Predict what is going to happen
Fill in the blank with the flair package

Verdict

Transitioning from primarily teaching in person to teaching virtually is hard, and I’m in awe of all the instructors I know who have had to do this on very short notice. But, can it be done with heart? Yes, I think so ❤️

Thanks

Thanks to the participants, who were the loveliest guinea pigs. It is a hard time to learn and a hard time to find time. I appreciate that you took time out of your lives to spend 8 hours with me.

Thanks also to Greg Wilson for his support, and Stephan Kadauke for being an awesome co-pilot. Extra special thanks to Desirée De Leon, who has the biggest heart of all. Knowing that I didn’t have time for creativity with my slides, she surprised me with the most beautiful xaringan slide deck theme based on tidymodels.org. I merged in her PR with glee and delight, I know the participants felt those same emotions too (while learning about machine learning, no less!) 🌼

Feedback

If you are curious, here is some of the feedback I collected at the bottom of our Google doc:

Two half days?

worked well for me. A full day would be tough.
Worked well for me also and I also think having all in one day would be a lot.
worked well.
worked well for me too.

Separated by one week?

seemed fine.
I liked this!
good. Enough time to digest the previous session
yes.

Pace: too fast, too slow?

good pace
I liked the pace. It felt like we covered a lot of ground quickly, but also like we have great resources to come back to for refreshing on what we learned.
good pace, except at “data leakage”. I still have hard time to understand that part.
good pace.

Scope: too small, too big?

nice scope
Nice scope
very nice and practical.
nice scope.

Timing in 50 min chunks: too many or too few breaks?

The 50 min chunks were great! I thought perfect length.
Perfect break up. And the 10 min breaks gave enough time to make tea, grab a snack, etc.
I am fine with that.
works well.

Timed code exercises: too easy, too hard?

good
Neither, I thought they were appropriate
good.
good.

In-between homework/reading?

maybe some light reading or practice
In theory I think I would have liked some ‘homework’, but the week turned out to be so busy that I don’t know if I would’ve made time to complete it before the workshop.
will be helpful to give some reading about different model descriptions in-between.

Final take-home project (+/- feedback)?

optional
I think this could be fun if we had access to a few different datasets to choose from. With maybe some pointers on what to look out for as we explore the data. Is it unbalanced? Could any two variables be collinear? Etc.
i would vote for take-home project to play with.

Zoom: video on/off?

I find video distracting while working/listening/learning.
I like being able to see the presenter/speaker’s video. I tend to choose “Speaker View” so that I don’t see all the participant videos (which I would find distracting).
i am fine with either. I know, from the speaker’s perspective, it will be good to have video on.
I think it was nice and respectful to ask volunteers to turn video on part time! (Kudos to Stephan for having it on the whole time!)

Google doc as our “home page” and “discussion forum”?

Great!
Yes! I thought it was a really helpful tool and ‘homebase’ to come to for all of the things (slides, R Studio Cloud project, etc.)
very good! Much easier to track.
works!

Rstudio.cloud?

pretty good except for crashing at end.
ditto.
I really enjoyed using R Studio Cloud. It makes it easier when I don’t have to worry about pre-installing packages or updating my version of R in order to go into a workshop. Having everything already set up for you in there is super convenient.
I like Rstudio cloud generally. Just not suitable for complicated model training.

How I Teach R Markdown

Thu, 28 May 2020 00:00:00 +0000

Ah, R Markdown. I love teaching R Markdown. But this was not a love at first sight story. When I first started teaching with R at Oregon Health & Science University many moons ago, my students used R Markdown for their homework assignments and in-class labs. This is a great way to start for beginners, to be honest- just use it! I found that most people are not very disoriented by a file that mixes text and code; a concern I had at first and one that I’ve heard voiced by other educators. It seems natural to use if it is your first exposure to all the data science things, especially if you’ve never used an R script.

I did notice, though, that over the course of even just a few weeks, many of my students would reach unbearable levels of R Markdown curiosity. I would see signs of growing pains in their assignments, like how can I turn off these messages and warnings when I load packages? This is so long- how can I make it easier to find things? How can I make it look better?

For all learners, there comes an uncomfortable point where you simply cannot just continue to use this awesome tool without learning how to use it. And I realized when I was teaching that ultimately it was unfair of me to assume that they would just learn an entire ecosystem while I stood idly by, clutching the secrets of being an “R Markdown Whisperer” close to my chest.

Like, why can’t you just find the piñata, kid? But more importantly, what happens when you can’t? I think the risk is that learners either won’t like or won’t appreciate a tool that I genuinely think would make their working lives better. If I believed it was worth their time to use it, it was worth my time to teach it.

So like any good educator, I evolved. I decided that the next year, I would teach R Markdown. And I did. I went from:

“Just use it”

To:

“Just tell them how to use it already”

I waited until a few weeks into a quarter, and I spent a full lab period walking students through “Hey- this bit where you put the title of each assignment and your name? That’s called YAML! Here is what it does…” I showed them how to use bootswatch themes, make a floating table of contents, control their output using the power of knitr code chunks and chunk options.

Guess what happened? The next batch of assignment my TA team and I received were…stunning. Creative. Beautiful. Thoughtful and thought-provoking. Students had taken care with their markdown headers, they played with flatly/yeti/united, they cared about not printing the giant output of a code chunk. It was a thing of beauty. I remember one of my beloved TAs, Grace Lawley, commenting that one star student’s homework “brought tears to her eyes” (and yes, I trained Grace too as she was also my research assistant, so she was already baptized into the R Markdown family).

But I have to admit, the first time I taught it, I had a hard time teaching it! I realized that I lacked vocabulary around things I used everyday, but had never really talked about out loud with anyone in words.

Now, in my role at RStudio, I’ve devoted a lot of time and energy trying to figure out how we can make R Markdown easier- easier to discover, easier to debug, easier to use, and easier to talk about.

So without further ado, here are some of my guiding principles when introducing R Markdown to beginners, for those who are ready to go beyond casual knitter:

#1. Make it. Make it again.

Knit early. Knit often. That means starting with a pre-filled Rmd document usually that you know will knit. How do you motivate repeated knitting and make it satisfying? Teach the basics of output formats and options by editing mainly the YAML. Your goal is to show how small effort –> high polish. For single docs, I love html_document() with a floating table of contents and a theme (like this), switching quickly to bookdown::html_document2() and distill::distill_article(). The latter two also enable automated figure numbering, which for scientific audiences is quite nice!

You can do something like this with #rmarkdown. Ask students to knit to HTML, then use the bootswatch themes https://t.co/J9ucdRWnIl

Bonus: you get the prettiest #rstats homeworks after this! 💐🖍️
---
title: "Habits"
output:
html_document:
theme: flatly
--- https://t.co/wMQ3Uqhc7s
— Alison Hill (@apreshill) March 2, 2019

Bonus when using a theme with html_document(): show off the code_download output option!

TIL you can embed a "code download" button in an HTML #rmarkdown doc so that users can click to download your source .Rmd from the rendered HTML version...without GitHub 🤩 #rstats

YAML:

---
output:
html_document:
code_download: true
---

Test: https://t.co/bp7w7XKF8b pic.twitter.com/uMQK0mvYcF
— Alison Hill (@apreshill) March 22, 2019

#2. Make it pretty.

The starting Rmd should have a nice ggplot2 graphic in there, and maybe a pretty gt table too. This is a motivational, aspirational document! I also try to use local data sets, so they can see how that actually works, as opposed to using a data package.

Never underestimate the power of being able to make pretty #rstats things. ⬆️ polish/effort ratio ➡️ happier users 🦚 https://t.co/LMbFRUiuLa
— Alison Hill (@apreshill) March 2, 2019

#3. Make it snappy.

I aim to get to a shareable link in the first 20 minutes (at most!). I like to use Netlify Drop for this. No account sign-up needed, and everyone knows how to drag-and-drop (see video below). It is very satisfying to get a link they can share with their mom/best friend/arch nemesis (kidding). I like to have everyone drop their links in a chat too, like a Slack, Google Doc, or a Gitter channel if doing a workshop. My favorite motto: “if it knits, it ships”

#4. Make it real.

Teach folks what they need to know to actually use the tool productively in real life. If you are an avid R Markdown user, this means that you know without a doubt that file paths will eventually be painful, for example. At the end of an intro, I go back and highlight things I just used to make sure they notice them like R Projects and the here package for data importing. I also love a good “Your Turn” exercise where you get a fresh data dump and all they have to do is re-knit. As in, “Surprise! Now instead of 3 sites, you have data from all 6 sites- what do you do?”

#5. Make it easy.

People will only keep using R Markdown if they see it making their life easier. So show them how. For example, the RStudio IDE has some very nice built-in features that make it much easier to be an R Markdown user. I point out things having a global setup chunk, and IDE features like:

What do I save until later?

Rendering with render(). I think knitting in the RStudio IDE can get you very far- this I consider an intermediate to advanced concept that is confusing if introduced too early. I’ve never heard someone say “Well there is this simple button, but how can I do the same thing from the command line?”
Parameterized reports. I actually do use parameters though! I’ll have at least one or two often in one of my Rmds, and mention them briefly in my wrap-up. I teach parameters explicitly with actual exercises when I have > 1 hour.
Multiple Rmd output formats. I tend to start with single output formats first. If I have > 1.5 hours and it matches my learning objectives, then I happily oblige- I love teaching bookdown, blogdown, and distill websites. But to start, I stay single.
Markdown. I skim markdown, and always provide a link to an interactive tutorial. This one is my favorite. Teaching markdown can be…dry. I show some bits on the slides because I cannot count on everyone doing the interactive tutorial ahead of time, but I do not linger much.

If you are curious to see some of the materials I’ve used to teach R Markdown, click on the rmarkdown button just below this post!

But remember: there is no one way to learn R Markdown, and no one way to teach it either. I love seeing the creativity of the community when introducing the R Markdown family- so keep them coming!

An Introduction to R Markdown for the CDC

Wed, 13 May 2020 14:00:00 +0000

R Markdown is an authoring format that enables easy creation of dynamic documents, presentations, and reports from R. It combines the core syntax of markdown with embedded R code chunks that are run so their output can be included in the final document. R Markdown documents are fully reproducible and can be updated whenever underlying R code or data changes.

This is a great opportunity to learn and get inspired about the capabilities for generating reports in R.

This session will introduce flexible and powerful tools for sharing your research and reports, covering topics like:

The basics of R Markdown and knitting
Output formats
Working with data
Adding text
Adding code
Adding tables
Adding plots
Options for sharing R Markdown reports

The talk will introduce R Markdown and include an overview of the core content types one can create, such as websites, PDF’s, PowerPoints, and more.

No prior knowledge of R or RStudio is needed to attend this session. There is no registration required for this Webinar.

tidymodels.org

Tue, 21 Apr 2020 00:00:00 +0000

The tidymodels framework is a collection of R packages for modeling and machine learning using tidyverse principles. This website was built with Hugo, using a theme I developed and maintain. I worked with my former intern, Desirée De Leon, to design the style of the website.

stat545.com

Tue, 21 Apr 2020 00:00:00 +0000

This online book contains a full course where users can learn to:

explore, groom, visualize, and analyze data,
make all of that reproducible, reusable, and shareable,
using R.

I led the effort, along with course author Jenny Bryan and RStudio intern Grace Lawley, to port a vintage R Markdown website into bookdown. I worked with my former intern, Desirée De Leon, to design the style of the bookdown website.

Sharing on Short Notice

Tue, 31 Mar 2020 09:00:00 +0000

This webinar was designed to help educators who needed to quickly transition to remote teaching due to COVID-19.

Educators create a lot of files for teaching- slides, exercises, solutions, assignments, data, figures- that all ultimately need to be shared with other people. Having a link for sharing your teaching materials can save you time and pain, but it is hard to get started if you’ve never shared your resources online before. In this webinar, we’ll give a tour of the R Markdown ecosystem for educators that you can start to use right away. We’ll show how it can help you make your teaching more shareable, reproducible, and resilient.

Read the accompanying Q&A blog post on the RStudio Education blog.

Take a Sad Script & Make it Better: Tidymodels Edition

Thu, 27 Feb 2020 00:00:00 +0000

A few years ago, I did a talk called “Take a Sad Plot & Make it Better,” where I showed how I took a single sad plot and tried to make it better. The process of making that plot better taught me a lot about data visualization, and about the ggplot2 package.

Fast-forward to 2019 when I started learning tidymodels, and I have accumulated some pretty sad predictive modeling scripts! And my sad plots are not so lonely anymore. Specifically, my old scripts for doing cross-validation with tidymodels are particularly sad. But, I’ve been able to make them better (one might even call them happy), primarily due to changes in the tune package and the addition of the fit_resamples() function. The process of making these scripts better taught me a lot about predictive modeling, and about the (evolving) tidymodels ecosystem. So, why write a blog post with outdated code?

I want to remember that I did this “by hand.”
I want to remember how I did this “by hand.” The code still works, even if there is now a happier path to doing the same thing.
I want to share cute penguin art and gifs.

Let’s start with some cute penguin art by Rohan Chakravarty…

My objective here is not to provide an introduction to using tidymodels, cross-validation, or to machine learning. If that is what you came for, check out the project button at the top of this post for my workshop materials for learners, and my associated blog post on the RStudio education site.

Bottom line: If you are stumbling upon this blog post in the year 2020 or beyond, know that there is a better way!

A sad script symphony 🎻 🎷 🎹

I’m not the first person to write sad tidymodels scripts- there are many out in the wild. Here were the blog posts that I found most helpful when trying to solve this particular coding conundrum:

Modelling with Tidymodels and Parsnip: A Tidy Approach to a Classification Problem by Diego Usai
A tutorial on tidy cross-validation with R by Bruno Rodrigues
Modeling with parsnip and tidymodels by Benjamin Sorensen

Packages

library(tidyverse)
library(tidymodels)
library(rpart)  # for decision tree
library(ranger) # for random forest

Data

I’m going to use data that Allison Horst helped me source on penguins from the Palmer Station (Antarctica) Long Term Ecological Research Network.

“sooo now I’m just looking at penguin pictures”

Allison Horst after slacking me this penguin data

Update! We have bundled the Palmer Station penguins data into an R data package named palmerpenguins. Enjoy 🐧 Here is the package website: https://allisonhorst.github.io/palmerpenguins/

install.packages("remotes") # to install from github
remotes::install_github("allisonhorst/palmerpenguins")

After you’ve installed the package, load it and read about the variables with ?penguins. We’ll modify this dataset lightly by:

casting all characters as factors,
dropping any observations with missing data, and
dropping the island variable.

library(palmerpenguins)

tidypenguins <- penguins %>% 
  select(-island) %>% 
  drop_na()

glimpse(tidypenguins)
#> Rows: 333
#> Columns: 7
#> $ species           <fct> Adelie, Adelie, Adelie, Adelie, Adelie, Adelie, Ade…
#> $ bill_length_mm    <dbl> 39.1, 39.5, 40.3, 36.7, 39.3, 38.9, 39.2, 41.1, 38.…
#> $ bill_depth_mm     <dbl> 18.7, 17.4, 18.0, 19.3, 20.6, 17.8, 19.6, 17.6, 21.…
#> $ flipper_length_mm <int> 181, 186, 195, 193, 190, 181, 195, 182, 191, 198, 1…
#> $ body_mass_g       <int> 3750, 3800, 3250, 3450, 3650, 3625, 4675, 3200, 380…
#> $ sex               <fct> male, female, female, female, male, female, male, f…
#> $ year              <int> 2007, 2007, 2007, 2007, 2007, 2007, 2007, 2007, 200…

Penguins

Figure 1: Artwork by @allisonhorst

This data included structural size measurements of penguins like their bill length, flipper length, and body mass. It also included each penguin’s species and sex. I’m going to use this data to try to predict penguin body mass. Sadly, we only have data for three distinct penguin species:

tidypenguins %>% 
  count(species)
#> # A tibble: 3 x 2
#>   species       n
#>   <fct>     <int>
#> 1 Adelie      146
#> 2 Chinstrap    68
#> 3 Gentoo      119

Here is a lineup:

From: https://www.bas.ac.uk/about/antarctica/wildlife/penguins/

Looks like we have data for 3 of the smaller penguin species (of those pictured here).

First, let’s build a simple linear regression model to predict body mass from flipper length.

ggplot(tidypenguins, aes(x = flipper_length_mm, y = body_mass_g)) +
  geom_point(color = "salmon", size = 3, alpha = .9) +
  geom_smooth(method = "lm") +
  theme_penguin()

Not bad! Looks promising. To actually fit a linear regression model, you might be used to something like this in R:

penguin_mod <- lm(body_mass_g ~ flipper_length_mm, data = tidypenguins)
summary(penguin_mod)
#> 
#> Call:
#> lm(formula = body_mass_g ~ flipper_length_mm, data = tidypenguins)
#> 
#> Residuals:
#>      Min       1Q   Median       3Q      Max 
#> -1057.33  -259.79   -12.24   242.97  1293.89 
#> 
#> Coefficients:
#>                   Estimate Std. Error t value Pr(>|t|)    
#> (Intercept)       -5872.09     310.29  -18.93   <2e-16 ***
#> flipper_length_mm    50.15       1.54   32.56   <2e-16 ***
#> ---
#> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
#> 
#> Residual standard error: 393.3 on 331 degrees of freedom
#> Multiple R-squared:  0.7621,	Adjusted R-squared:  0.7614 
#> F-statistic:  1060 on 1 and 331 DF,  p-value: < 2.2e-16

But we aren’t going to stick with this. We are going to use tidymodels, with the goal of generating accurate predictions for future, yet-to-be-seen penguins.

tidymodels 101

The code provided in the section below is not particularly sad 🐧. If you are embarking on learning tidymodels, you’ll need to use this same kind of code as the building blocks for any predictive modeling pipeline.

Parsnip: build the model

This step is really three, using only the parsnip package:

lm_spec <- 
  linear_reg() %>%       # pick model
  set_engine("lm") %>%   # set engine
  set_mode("regression") # set mode

lm_spec
#> Linear Regression Model Specification (regression)
#> 
#> Computational engine: lm

Things that are missing: data (we haven’t touched it yet) and a formula (no data, no variables, no twiddle ~). This is an abstract model specification. See other possible parsnip models here.

Recipe: not happening here, folks

This is where you would normally insert some code for feature engineering using the recipes package. But previously this required functions named prep(), bake(), juice()- so I’m willfully ignoring that for now. There will be no recipes involving penguins.

Rsample: initial split

We’ll use the rsample package to split (ayee! I promise no penguins were hurt in the writing of this blog post) the penguins up into two datasets: training and testing. If you are unfamiliar with this practice, read up on the holdout method.

penguin_split <- initial_split(tidypenguins, strata = species)
penguin_train <- training(penguin_split)
penguin_test  <- testing(penguin_split)

Fitting the model once

Fitting a single model once is…not exactly the hardest part.

This is essentially the workflow from this early blog post.

set.seed(0)

lm_spec %>% 
  
  # train: get fitted model
  fit(body_mass_g ~ ., data = penguin_train) %>% 
  
  # test: get predictions
  predict(new_data = penguin_test) %>% 
  
  # compare: get metrics
  bind_cols(penguin_test) %>% 
  rmse(truth = body_mass_g, estimate = .pred)
#> # A tibble: 1 x 3
#>   .metric .estimator .estimate
#>   <chr>   <chr>          <dbl>
#> 1 rmse    standard        278.

Fitting the model with a function

If you squint, you might see that I could make this into a function like below:

get_rmse <- function(model_spec, split) {
  
  model_spec %>% 
    
    # train: get fitted model
    fit(body_mass_g ~ ., data = training(split)) %>% 
    
    # test: get predictions
    predict(new_data = testing(split)) %>% 
    
    # compare: get metrics
    bind_cols(testing(split)) %>% 
    rmse(truth = body_mass_g, estimate = .pred)
  
}

And I could use it to fit a linear regression model:

set.seed(0)
get_rmse(model_spec = lm_spec, split = penguin_split)
#> # A tibble: 1 x 3
#>   .metric .estimator .estimate
#>   <chr>   <chr>          <dbl>
#> 1 rmse    standard        278.

I could also build up a tibble that includes the results, if I wanted to save the predicted values, for example:

get_preds <- function(model_spec, split){
  
  # train: get fitted model
  fit_model <- model_spec %>% 
    fit(body_mass_g ~ ., data = training(split))
  
  # test: get predictions
  preds <- fit_model %>% 
    predict(new_data = testing(split)) %>% 
    bind_cols(testing(split) %>% select(body_mass_g, species))

  preds
}

set.seed(0)
penguin_preds <- get_preds(model_spec = lm_spec, split = penguin_split)

Then I can work with the predicted values, like plotting the fitted body mass estimates against the residuals.

ggplot(penguin_preds, aes(x = .pred, y = (.pred - body_mass_g))) +
  geom_point(aes(colour = species), size = 3, alpha = .8) +
  geom_smooth(method = "lm") +
  theme_penguin() +
  scico::scale_colour_scico_d(end = .8) +
  ggtitle("Residuals vs Fitted")
#> `geom_smooth()` using formula 'y ~ x'


# compare: get metrics
penguin_preds %>% 
  rmse(truth = body_mass_g, estimate = .pred)
#> # A tibble: 1 x 3
#>   .metric .estimator .estimate
#>   <chr>   <chr>          <dbl>
#> 1 rmse    standard        278.

Or I could fit a regression tree model with a new model spec:

# regression tree model spec
rt_spec <-
  decision_tree() %>% 
  set_engine("rpart") %>% 
  set_mode("regression")

# get rmse
set.seed(0)
get_preds(model_spec = rt_spec, 
          split = penguin_split) %>% 
  rmse(truth = body_mass_g, estimate = .pred)
#> # A tibble: 1 x 3
#>   .metric .estimator .estimate
#>   <chr>   <chr>          <dbl>
#> 1 rmse    standard        312.

Or a random forest:

# random forest model spec
rf_spec <-
  rand_forest() %>% 
  set_engine("ranger") %>% 
  set_mode("regression")

# get rmse
set.seed(0)
get_preds(model_spec = rf_spec, 
          split = penguin_split) %>% 
  rmse(truth = body_mass_g, estimate = .pred)
#> # A tibble: 1 x 3
#>   .metric .estimator .estimate
#>   <chr>   <chr>          <dbl>
#> 1 rmse    standard        300.

But, unfortunately, I shouldn’t be predicting with the test set over and over again like this. It isn’t good practice to predict with the test set > 1 time. What is a good predictive modeler to do? I should be saving (holding out) the test set and use it to generate predictions exactly once, at the very end — after I’ve compared different models, selected my features, and tuned my hyperparameters. How do you do this? You do cross-validation with the training set, and you leave the testing set for the very last fit you do.

Hey Jude, don’t make it sad 🎶

Now, for the 😭 part- let’s add cross-validation! To do this, we’ll use a function called rsample::vfold_cv().

# add the cv step here
set.seed(0)
penguin_folds <- vfold_cv(data = penguin_train, strata = "species")

penguin_folds
#> #  10-fold cross-validation using stratification 
#> # A tibble: 10 x 2
#>    splits           id    
#>    <list>           <chr> 
#>  1 <split [225/26]> Fold01
#>  2 <split [226/25]> Fold02
#>  3 <split [226/25]> Fold03
#>  4 <split [226/25]> Fold04
#>  5 <split [226/25]> Fold05
#>  6 <split [226/25]> Fold06
#>  7 <split [226/25]> Fold07
#>  8 <split [226/25]> Fold08
#>  9 <split [226/25]> Fold09
#> 10 <split [226/25]> Fold10

The process of training, testing, and computing metrics gets a lot harder when you need to do this across 10 folds, each with a different data split. I eventually worked out three approaches, which I show below. All require some level of comfort with iteration using the purrr package.

Function with minimal purrr-ing

This approach is essentially a mega-function, that we then use purrr to map across each fold.

I’m going to change a few things from my previous get_preds() function:

training(split) -> analysis(split)
testing(split) -> assessment(split)
I also added the rsample::add_resample_id() function to keep track of the fold number.
I saved the predictions now as a list column.

To build up this function, my strategy was to figure out how to work with one fold, then I knew I’d be able to use purrr::map_df() to apply it across multiple folds.

# Figure it out for one fold
get_fold_results <- function(model_spec, split){
  
  # train: get fitted model for each fold
  fits <- model_spec %>% 
    fit(body_mass_g ~ ., data = analysis(split))
  
  # test: get predictions on for each fold
  preds <- fits %>% 
    predict(new_data = assessment(split)) %>% 
    bind_cols(assessment(split)) 
  
  # compare: compute metric for each fold
  rmse <- assessment(split)  %>% 
    summarize(rmse = rmse_vec(truth = body_mass_g, 
                              estimate = preds$.pred))
  
  rmse %>% 
    # add fold identifier column
    rsample::add_resample_id(split = split) %>% 
    as_tibble() %>% 
    # add predictions
    mutate(preds = list(preds))
}

I tried this function with a single fold first:

set.seed(0)
get_fold_results(
    split      = penguin_folds$splits[[1]], 
    model_spec = rt_spec
  )
#> # A tibble: 1 x 3
#>    rmse id     preds            
#>   <dbl> <chr>  <list>           
#> 1  419. Fold01 <tibble [26 × 8]>

Next, I used purrr- but just once. The function get_fold_results is doing most of the work for us, but I needed purrr to map it across each fold.

set.seed(0)
kfold_results <- 
  map_df(
    penguin_folds$splits, 
    ~get_fold_results(.x, model = rt_spec))
kfold_results
#> # A tibble: 10 x 3
#>     rmse id     preds            
#>    <dbl> <chr>  <list>           
#>  1  419. Fold01 <tibble [26 × 8]>
#>  2  326. Fold02 <tibble [25 × 8]>
#>  3  414. Fold03 <tibble [25 × 8]>
#>  4  327. Fold04 <tibble [25 × 8]>
#>  5  336. Fold05 <tibble [25 × 8]>
#>  6  406. Fold06 <tibble [25 × 8]>
#>  7  305. Fold07 <tibble [25 × 8]>
#>  8  301. Fold08 <tibble [25 × 8]>
#>  9  315. Fold09 <tibble [25 × 8]>
#> 10  319. Fold10 <tibble [25 × 8]>

Here we are still left with 10 RMSE values- one for each of the 10 folds. We don’t care too much about by fold- the power is in the aggregate. Specifically, we mainly care about the central tendency and spread of these RMSE values. Let’s finish by combining (or aggregating) these metrics.

kfold_results %>% 
  summarize(mean_rmse = mean(rmse), sd_rmse = sd(rmse))
#> # A tibble: 1 x 2
#>   mean_rmse sd_rmse
#>       <dbl>   <dbl>
#> 1      347.    46.8

So, this works. But, can you imagine doing it again? Without errors? Can you imagine teaching it?

Purrr-to-the-max

This approach is purrr::map() (and friends) on steriods. We use vanilla map(), map2(), and map2_dbl() here. We also use anonymous functions as a formula, and the pipe operator within those anonymous functions.

set.seed(0)
penguin_res <- penguin_folds %>% 
  mutate(
    
    # train: get fitted model for each fold
    train_set  = map(splits, analysis),
    fit_models = map(train_set, ~rt_spec %>% 
                                    fit(body_mass_g ~ ., 
                                        data = .x)),
    
    # test: get predictions for each fold
    test_set   = map(splits, assessment),
    estimates  = map2(fit_models, 
                      test_set, 
                      ~.x %>% 
                        predict(.y)),
    
    # compare: compute metric for each fold
    rmse       = map2_dbl(test_set, 
                          estimates, 
                          ~rmse_vec(truth = .x$body_mass_g, 
                                    estimate = .y$.pred))
  )

penguin_res
#> #  10-fold cross-validation using stratification 
#> # A tibble: 10 x 7
#>    splits       id     train_set     fit_models test_set     estimates      rmse
#>    <list>       <chr>  <list>        <list>     <list>       <list>        <dbl>
#>  1 <split [225… Fold01 <tibble [225… <fit[+]>   <tibble [26… <tibble [26 …  419.
#>  2 <split [226… Fold02 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  326.
#>  3 <split [226… Fold03 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  414.
#>  4 <split [226… Fold04 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  327.
#>  5 <split [226… Fold05 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  336.
#>  6 <split [226… Fold06 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  406.
#>  7 <split [226… Fold07 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  305.
#>  8 <split [226… Fold08 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  301.
#>  9 <split [226… Fold09 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  315.
#> 10 <split [226… Fold10 <tibble [226… <fit[+]>   <tibble [25… <tibble [25 …  319.

penguin_res %>% 
  summarise(mean_rmse = mean(rmse), sd_rmse = sd(rmse))
#> # A tibble: 1 x 2
#>   mean_rmse sd_rmse
#>       <dbl>   <dbl>
#> 1      347.    46.8

The purrr mash-up

Another way I worked out was largely after reviewing Max’s slides from previous workshops. This is basically a mash-up of my previous two approaches, where we write laser-focused functions that each do one thing, then use purrr to apply those functions across the folds. This way is nice(r) for showing in slides as you can incrementally build up the results table. Let’s see this sad script in action…

Round 1

set.seed(0) # for reproducibility

# train: get fitted model for a split
get_fits <- function(split, model_spec){
  model_spec %>% 
    fit(body_mass_g ~ ., 
        data = analysis(split))
}

# train: get fitted models across folds
penguin_purrr <- penguin_folds %>% 
  mutate(rt_fits = map(splits, get_fits, rt_spec))

penguin_purrr
#> #  10-fold cross-validation using stratification 
#> # A tibble: 10 x 3
#>    splits           id     rt_fits 
#>    <list>           <chr>  <list>  
#>  1 <split [225/26]> Fold01 <fit[+]>
#>  2 <split [226/25]> Fold02 <fit[+]>
#>  3 <split [226/25]> Fold03 <fit[+]>
#>  4 <split [226/25]> Fold04 <fit[+]>
#>  5 <split [226/25]> Fold05 <fit[+]>
#>  6 <split [226/25]> Fold06 <fit[+]>
#>  7 <split [226/25]> Fold07 <fit[+]>
#>  8 <split [226/25]> Fold08 <fit[+]>
#>  9 <split [226/25]> Fold09 <fit[+]>
#> 10 <split [226/25]> Fold10 <fit[+]>

Round 2

# test: get predictions for a split
get_preds <- function(split, fit_df) {
  
  fit_df %>% 
    predict(new_data = assessment(split)) %>% 
    bind_cols(assessment(split))
  
}

# test: get predictions across folds
penguin_purrr <- penguin_purrr %>% 
  mutate(rt_preds = map2(splits, rt_fits, get_preds))

penguin_purrr
#> #  10-fold cross-validation using stratification 
#> # A tibble: 10 x 4
#>    splits           id     rt_fits  rt_preds         
#>    <list>           <chr>  <list>   <list>           
#>  1 <split [225/26]> Fold01 <fit[+]> <tibble [26 × 8]>
#>  2 <split [226/25]> Fold02 <fit[+]> <tibble [25 × 8]>
#>  3 <split [226/25]> Fold03 <fit[+]> <tibble [25 × 8]>
#>  4 <split [226/25]> Fold04 <fit[+]> <tibble [25 × 8]>
#>  5 <split [226/25]> Fold05 <fit[+]> <tibble [25 × 8]>
#>  6 <split [226/25]> Fold06 <fit[+]> <tibble [25 × 8]>
#>  7 <split [226/25]> Fold07 <fit[+]> <tibble [25 × 8]>
#>  8 <split [226/25]> Fold08 <fit[+]> <tibble [25 × 8]>
#>  9 <split [226/25]> Fold09 <fit[+]> <tibble [25 × 8]>
#> 10 <split [226/25]> Fold10 <fit[+]> <tibble [25 × 8]>

aaaand Round 3

# compare: compute metric for a split
get_rmse <- function(pred_df) {
  
  pred_df %>% 
    rmse(truth    = body_mass_g, 
         estimate = .pred) %>% 
    pluck(".estimate")
  
}

# compare: compute metric across folds
penguin_purrr <- penguin_purrr %>% 
  mutate(rt_rmse = map_dbl(rt_preds, get_rmse))

penguin_purrr
#> #  10-fold cross-validation using stratification 
#> # A tibble: 10 x 5
#>    splits           id     rt_fits  rt_preds          rt_rmse
#>    <list>           <chr>  <list>   <list>              <dbl>
#>  1 <split [225/26]> Fold01 <fit[+]> <tibble [26 × 8]>    419.
#>  2 <split [226/25]> Fold02 <fit[+]> <tibble [25 × 8]>    326.
#>  3 <split [226/25]> Fold03 <fit[+]> <tibble [25 × 8]>    414.
#>  4 <split [226/25]> Fold04 <fit[+]> <tibble [25 × 8]>    327.
#>  5 <split [226/25]> Fold05 <fit[+]> <tibble [25 × 8]>    336.
#>  6 <split [226/25]> Fold06 <fit[+]> <tibble [25 × 8]>    406.
#>  7 <split [226/25]> Fold07 <fit[+]> <tibble [25 × 8]>    305.
#>  8 <split [226/25]> Fold08 <fit[+]> <tibble [25 × 8]>    301.
#>  9 <split [226/25]> Fold09 <fit[+]> <tibble [25 × 8]>    315.
#> 10 <split [226/25]> Fold10 <fit[+]> <tibble [25 × 8]>    319.

Finally, summarizing as I did before:

penguin_purrr %>% 
  summarize(mean_rmse = mean(rt_rmse), sd_rmse = sd(rt_rmse))
#> # A tibble: 1 x 2
#>   mean_rmse sd_rmse
#>       <dbl>   <dbl>
#> 1      347.    46.8

In practice, if you did all these at once instead of incrementally, it would look like:

set.seed(0)
penguin_folds %>% 
  
  # train: get fitted model for a split
  mutate(rt_fits = map(splits, get_fits, rt_spec)) %>% 
  
  # test: get predictions on for each fold
  mutate(rt_preds = map2(splits, rt_fits, get_preds)) %>% 
  
  # compare: compute metric for each fold
  mutate(rt_rmse = map_dbl(rt_preds, get_rmse))
#> #  10-fold cross-validation using stratification 
#> # A tibble: 10 x 5
#>    splits           id     rt_fits  rt_preds          rt_rmse
#>    <list>           <chr>  <list>   <list>              <dbl>
#>  1 <split [225/26]> Fold01 <fit[+]> <tibble [26 × 8]>    419.
#>  2 <split [226/25]> Fold02 <fit[+]> <tibble [25 × 8]>    326.
#>  3 <split [226/25]> Fold03 <fit[+]> <tibble [25 × 8]>    414.
#>  4 <split [226/25]> Fold04 <fit[+]> <tibble [25 × 8]>    327.
#>  5 <split [226/25]> Fold05 <fit[+]> <tibble [25 × 8]>    336.
#>  6 <split [226/25]> Fold06 <fit[+]> <tibble [25 × 8]>    406.
#>  7 <split [226/25]> Fold07 <fit[+]> <tibble [25 × 8]>    305.
#>  8 <split [226/25]> Fold08 <fit[+]> <tibble [25 × 8]>    301.
#>  9 <split [226/25]> Fold09 <fit[+]> <tibble [25 × 8]>    315.
#> 10 <split [226/25]> Fold10 <fit[+]> <tibble [25 × 8]>    319.

When you put it like that, it doesn’t look like so much work! But, this way hides how much work it takes to write those 3 custom functions: get_fits(), get_preds(), and get_rmse(). And we still had to use vanilla map(), map2(), and map2_dbl().

Make it better

I kept a learning log while working through the all the above code, and I wrote down these notes to myself:

It is very easy to do the wrong thing; it is very hard to do the right thing.
I lost sight many times of what the code I was writing was doing, because I was using up so much cognitive energy on getting the code to just work.
I thought I knew how to use purrr…

If you have made it this far, I’m pretty sure I don’t need to convince you that a better way to do cross-validation using tidymodels would be more pleasant to do more than once. It would also be less prone to error due to me copying-and-pasting repeatedly, and making stupid mistakes that would be difficult to spot with so much cluttered code. Luckily, tune::fit_resamples() came along to take a sad script and make it better:

penguin_party <-
  tune::fit_resamples(
    rt_spec,
    body_mass_g ~ .,
    resamples = penguin_folds
)

Here is the beautiful output from that function:

penguin_party
#> # Resampling results
#> # 10-fold cross-validation using stratification 
#> # A tibble: 10 x 4
#>    splits           id     .metrics         .notes          
#>    <list>           <chr>  <list>           <list>          
#>  1 <split [225/26]> Fold01 <tibble [2 × 3]> <tibble [0 × 1]>
#>  2 <split [226/25]> Fold02 <tibble [2 × 3]> <tibble [0 × 1]>
#>  3 <split [226/25]> Fold03 <tibble [2 × 3]> <tibble [0 × 1]>
#>  4 <split [226/25]> Fold04 <tibble [2 × 3]> <tibble [0 × 1]>
#>  5 <split [226/25]> Fold05 <tibble [2 × 3]> <tibble [0 × 1]>
#>  6 <split [226/25]> Fold06 <tibble [2 × 3]> <tibble [0 × 1]>
#>  7 <split [226/25]> Fold07 <tibble [2 × 3]> <tibble [0 × 1]>
#>  8 <split [226/25]> Fold08 <tibble [2 × 3]> <tibble [0 × 1]>
#>  9 <split [226/25]> Fold09 <tibble [2 × 3]> <tibble [0 × 1]>
#> 10 <split [226/25]> Fold10 <tibble [2 × 3]> <tibble [0 × 1]>

Now, to see all the stuff inside this penguin_party, we can use tune’s collect_* functions.

penguin_party %>% 
  collect_metrics()
#> # A tibble: 2 x 5
#>   .metric .estimator    mean     n std_err
#>   <chr>   <chr>        <dbl> <int>   <dbl>
#> 1 rmse    standard   347.       10 14.8   
#> 2 rsq     standard     0.839    10  0.0141

To see the predictions, we need to add use control_resamples():

penguin_party <-
  tune::fit_resamples(
    rt_spec,
    body_mass_g ~ .,
    resamples = penguin_folds,
    control = control_resamples(save_pred = TRUE) # add this line
)

Then we collect the predictions.

penguin_party %>% 
  collect_predictions()
#> # A tibble: 251 x 4
#>    id     .pred  .row body_mass_g
#>    <chr>  <dbl> <int>       <int>
#>  1 Fold01 3402.     4        3625
#>  2 Fold01 3402.    11        3325
#>  3 Fold01 3988.    14        3950
#>  4 Fold01 3988.    41        3700
#>  5 Fold01 3402.    54        3700
#>  6 Fold01 3988.    65        3950
#>  7 Fold01 3988.    70        4450
#>  8 Fold01 3402.    71        3300
#>  9 Fold01 3402.    76        3075
#> 10 Fold01 3402.    85        2900
#> # … with 241 more rows

Now, isn’t that better?

Introduction to Machine Learning with the Tidyverse

Mon, 27 Jan 2020 09:00:00 +0000

This two-day workshop provided a gentle introduction to supervised machine learning: concepts, methods, and R code. Participants learned how to train and assess predictive models with several common machine learning algorithms, as well as how to do feature engineering to improve the predictive accuracy of their models. We focused on teaching intuitive explanations of the models and best practices for predictive modeling. Along the way, we introduced several core tidymodels packages, which provide a grammar for modeling that makes it easy to the right thing, and harder to accidentally do the wrong thing.

Introduction to Machine Learning with the Tidyverse

Mon, 27 Jan 2020 00:00:00 +0000

These workshops provide a gentle introduction to supervised machine learning: concepts, methods, and R code. Participants learn how to train and assess predictive models with several common machine learning algorithms, as well as how to do feature engineering to improve the predictive accuracy of their models. We focus on teaching intuitive explanations of the models and best practices for predictive modeling. Along the way, we introduce several core tidymodels packages, which provide a grammar for modeling that makes it easy to the right thing, and harder to accidentally do the wrong thing.

See the workshop websites for more, including links to the GitHub repositories for all workshop materials.

Learning to Teach Machines to Learn

Mon, 23 Dec 2019 00:00:00 +0000

I’m excited to be teaching a new workshop at the upcoming rstudio::conf in January called “Introduction to Machine Learning with the Tidyverse”, with my colleague Garrett Grolemund. Our workshop just sold out over the weekend! 🎉

It is always hard to develop an entirely new workshop, especially if you are doing it at the same time as learning how to use a new API. It is even harder when that API is under active development like the tidymodels ecosystem! I’ve been so lucky to be able to work with the tidymodels team at RStudio, Max Kuhn and Davis Vaughan, to help shape how we tell the tidymodels story to ML beginners. But my favorite part of developing a new workshop like this has been studying how others teach machine learning. Spoiler alert: there are a lot of materials intended for learners that make things seem harder than they actually are! Below, I’m sharing my bookmarked resources, organized roughly in the order I think they are most helpful for beginners.

Machine Learning for Everyone. In simple words. With real-world examples. Yes, again. In my experience, the biggest hurdle to getting started is sifting through both the hype and the math. This is a readable illustrated introduction to key concepts that will help you start building your own mental model of this space. For example, “the only goal of machine learning is to predict results based on incoming data. That’s it.” There you go! Start here.
A Visual Introduction to Machine Learning by r2d3. This is a wonderful two-part series (that I wish would be extended!):
- Part I: A Decision Tree
- Part II: Model Tuning and the Bias-Variance Tradeoff
Supervised Machine Learning course by Julia Silge Taught with R and the caret package (the precursor to the in-development tidymodels ecosystem), this is a great next step in your machine learning journey as you’ll start doing ML right away in your browser using an innovative course delivery platform. You’ll also get to play with data that is not iris, titanic, or AmesHousing. This will be sweet relief because you’ll find the rest of my recommended resources all basically build models to predict home prices in Ames, Iowa.
Hands-on Machine Learning with R by Bradley Boehmke & Brandon Greenwell. Another great way to learn concepts plus code, although another one that focuses on the caret package (pre-tidymodels). Each chapter maps onto a new learning algorithm, and provides a code-through with real data from building to tuning. The authors also offer practical advice for each algorithm, and the “final thoughts” sections at the end of each chapter will help you tie it all together.

Don’t skip the “Fundamentals” section, even if you feel like you’ve got that down by now. The second chapter on the modeling process is especially good.
Interpretable Machine Learning: A Guide for Making Black Box Models Explainable by Christoph Molnar. If you only have time to read a single chapter, skip ahead to Chapter 4: Interpretable Models. I also appreciated the introduction section on terminology. But the whole book is excellent and well-written.
Model evaluation, model selection, and algorithm selection in machine learning- a 4-part series by Sebastian Raschka. I found this to be a great evidence-based, thorough overview of the methods for machine learning. I especially liked how he walks you step-by-step from the simplest methods like the holdout method up to nested cross-validation:
At this point, if you can read through the above resources and you are no longer feeling awash in new terminology, I think your vocabulary and mental model are in pretty good shape! That means you are ready for the next step, which is to read Max Kuhn and Kjell Johnson’s new book Feature Engineering and Selection: A Practical Approach for Predictive Models

In my experience, the later chapters in this book filled in a lot of lingering questions I had about certain methods, like whether to use factor or dummy variables in tree-based models. But also don’t miss the section on “important concepts” at the beginning- this should feel like a nice review if you’ve gotten this far!
Elements of Statistical Learning. The entire PDF of the book is available online. A great resource for those with a strong statistics background, and for those looking for more math and formulas.

Other note-worthy resources

For the highly visual learner, you may want to cue up some YouTube videos from Udacity’s “Machine Learning for Trading” course. I found these illustrations especially helpful:
Chris Albon’s Machine Learning Flashcards ($12)
Shirin Elsinghorst’s blog (free! and so good).

I love her sketchnotes.
I also found Rafael Irizarry’s “Introduction to Machine Learning”, a chapter from his Introduction to Data Science book, to have some helpful discussion.
Machine Learning: A primer by Danilo Bzdok, Martin Krzywinski & Naomi Altman, from the Nature Methods Points of Significance collection- this collection in general is always straight-forward with great visuals. Start with the primer, then skim these:
- Statistics versus machine learning
- Machine learning: supervised methods
- Classification and regression trees (decision trees are the “base learner” for many ensemble methods - this is a good intro)
- Ensemble methods: bagging and random forests

That’s all for now- if you are taking my workshop in January I look forward to meeting you in person! If not, rest assured that all code and materials will be shared openly after the workshop. Until then, happy learning 🤖

Plot Twist: 10 Bake Offs, Visualized 11 Ways

Fri, 04 Oct 2019 18:00:00 +0000

Using data from 10 series of The Great British Bake Off, we will walk through eleven ways to visualize the same data using the ggplot2 package. We’ll talk a lot about geoms and variable mappings, but also about what it means to “tidy your data”, plus the new pivot functions in the tidyr package.

You won’t need your laptops but you will get the most out of this talk if you know some basics about using ggplot2. To brush up (or start learning now), you may want to play with the free RStudio.cloud data visualization primer (you may use an existing Google or GitHub account to log in). Or of course you can check out R-Ladies Sydney’s own VizW(h)iz Module of #RYouWithMe!

The Art of Literate Projecting

Wed, 02 Oct 2019 09:00:00 +0000

“Literate programming” is an approach to writing software programs that weaves together the source code and documentation at the time of creation. The idea is to create programs that are easier for users to understand. But they are also easier for programmers to work on and maintain. In this talk, I will describe how data scientists can be inspired by this programming approach and start what I refer to as “literate projecting.” Literate projects are not only more pleasant to work on — they are also easier for others to discover and explore. In my experiences as a researcher and now a data scientist at RStudio, I’ve had the pleasure to work on many literate projects, and I’ve felt the pain of working on illiterate ones too. What is the difference? What are the benefits? Based on my experiences, I’ll share good literate projecting practices that have the potential to shift your mindset and reshape your workflow.

Communicating with R Markdown Workshop

Mon, 30 Sep 2019 09:00:00 +0000

A full-day workshop for users who want to get more out of R Markdown (and friends). In this workshop, you will create, publish, and share some beautiful data products. You’ll learn to make:

Parameterized reports
Version-controlled R Markdown projects
Templates within a package
Shareable scientific/technical articles, slides, dashboards, and websites

Take a Sad Plot & Make It Better

Thu, 26 Sep 2019 18:15:00 +0000

In this talk, Alison will talk about one plot’s life cycle, from a sad Powerpoint slide to an Excel chart and finally to the finished product made with the ggplot2 package in R. Along the way, she will discuss why each version of the plot fails in different ways and how each iteration improved on the last one.

Latest event

This talk was most recently given at the University of South Wales on 2019/10/04.

education.rstudio.com

Tue, 24 Sep 2019 00:00:00 +0000

RStudio’s mission is:

“To equip everyone, regardless of means, to participate in a global economy that rewards data literacy.”

Our education team supports this mission broadly by supporting people who want to learn R (or learn new things in R), and those who want to teach them. This website is designed for both. This website was built with Hugo, using a theme I developed and maintain. I worked with my former intern, Desirée De Leon, to create the original artwork we used for the website.

R Markdown for Medicine Workshop

Thu, 12 Sep 2019 08:00:00 +0000

R Markdown for Medicine

Thu, 12 Sep 2019 00:00:00 +0000

Starting with a mock clinical trial dataset, we’ll use R Markdown to combine prose, R code, and figures and tables created with R code into a nicely formatted and reproducible final manuscript.

For the 2019 R / Medicine conference.

Teaching Students to Talk about Data Science

Mon, 29 Jul 2019 14:00:01 -0700

Data science educators have a unique opportunity to teach students the skills they need in their future careers. We know that practical skills matter, like being able to wrangle, explore, analyze, and visualize data (preferably using code), but what is easy to overlook is teaching students how to communicate about data science with other people. Being able to communicate about data, code, and insights gained are important skills we can strengthen in the classroom to make a real impact on students. I will talk about three ways to help strengthen data science communication skills that matter: self-reflection, iteration, and broadcasting. Self-reflection involves asking students to reflect on concepts and/or code that they struggled with to increase engagement with materials and independent problem-solving. Iteration involves revisiting old concepts/code, identifying areas for improvement, and making them better, either independently or in collaboration with peers or other experts/advanced users. Broadcasting involves practice (practice, practice, practice) “wrapping up” code with words into coherent narratives about what a data analysis or visualization means.

Summer of blogdown: Day 04

Thu, 13 Jun 2019 09:00:00 +0000

A hands-on workshop to creating a personal website using blogdown and the Hugo Academic theme.

Four daily 1-hour sessions (see slides) plus 30-60 minutes of homework for 3 nights.

See the project link for all the days of the summer of blogdown.

Summer of blogdown: Day 03

Wed, 12 Jun 2019 09:00:00 +0000

A hands-on workshop to creating a personal website using blogdown and the Hugo Academic theme.

Four daily 1-hour sessions (see slides) plus 30-60 minutes of homework for 3 nights.

See the project link for all the days of the summer of blogdown.

Summer of blogdown: Day 02

Tue, 11 Jun 2019 09:00:00 +0000

A hands-on workshop to creating a personal website using blogdown and the Hugo Academic theme.

Four daily 1-hour sessions (see slides) plus 30-60 minutes of homework for 3 nights.

See the project link for all the days of the summer of blogdown.

Summer of blogdown: Day 01

Mon, 10 Jun 2019 09:00:00 +0000

A hands-on workshop to creating a personal website using blogdown and the Hugo Academic theme.

Four daily 1-hour sessions (see slides) plus 30-60 minutes of homework for 3 nights.

See the project link for all the days of the summer of blogdown.

Using blogdown to Connect Beyond the Classroom

Thu, 30 May 2019 08:00:00 +0000

Troubleshooting Your Build

Mon, 04 Mar 2019 00:00:00 +0000

“Just a spoonful of Hugo helps the blog go down.”

me, only somewhat kidding

In this series, I’m sharing small spoonfuls of Hugo that I have learned that hopefully can help you get your site UP (and even better- more efficient, more streamlined, more automated). You can read the previous posts about my “Spoonful of Hugo” series about Hugo archetypes, Hugo versions, and Hugo page bundles.

The following are a few steps that I always start with to troubleshoot any blogdown/Hugo/Netlify problems. These steps would solve what I would anecdotally estimate as ~50% of blogdown problems that I see posted in the GitHub repository and on the community site.

#1: Update Hugo

Figure 1: Don't be like this

If things have gone south and you are getting Hugo errors when you use the “Serve Site” Addin locally, it is possible that you need to update your version of Hugo. From R, you can check your Hugo version with blogdown:

blogdown::hugo_version()

Then you can reference your Hugo theme to find the minimum version of Hugo required by your theme:

Figure 2: Check your theme's minimum Hugo version

You can go higher than the minimum version though, so it’s good practice to update your Hugo, again from within R:

blogdown::update_hugo()

Check your version again post-update:

blogdown::hugo_version()

## [1] '0.80.0'

If you are using Netlify to build your site using Hugo, you’ll want this version to match that- the best way to do that is with a netlify.toml file.

#2: Change the baseurl

Open up your config.toml file and look for the baseurl field, usually pretty close to the top. Here is mine^[Yes that’s right, I don’t have a trailing slash- read on for why I can get away with this.]:

baseurl = "https://alison.rbind.io"

Now if you are just starting with Hugo and don’t actually have a domain name yet, try taking the advice that blogdown automatically prints out for you:

Warning: You should change the "baseurl" option in config.toml 
from https://example.org to your actual domain; 
if you do not have a domain, set "baseurl" to "/"

But be careful here- you shouldn’t leave it as “/”- once you do have your domain name you should update the baseurl as “/” is a not a valid URL.

Care to know more?

Here is a quote from the person who writes the Hugo docs:

“…the only purpose for the baseurl field in the config is to define the full base URL of your website for deployment purposes.” - @ rdwatters

The main error that would happen without the trailing slash in the past is that you would end up with a site where the theme’s CSS would be all wrong. This was probably because the theme designer used code like this buried in a layout file:

<link rel="stylesheet" href="{{ .Site.BaseURL }}css/style.css"/>

Now, if you set baseurl = "http://mysite.com" but only rendered locally, things would look just peachy, because the default local server already included the trailing slash. So, the link in the html file would be^[https://discourse.gohugo.io/t/how-not-to-specify-url-site/5691/5]:

<link rel="stylesheet" href="http://localhost:1313/css/style.css">

But, at build, the link in the html file would turn into:

<link rel="stylesheet" href="http://mysite.comcss/style.css">

Which creates sites that look like this:

Figure 3: Hugo tranquil peak theme

GitHub issue #369

Figure 4: Hugo universal theme

GitHub issue #131

GitHub issue #114

However, Hugo authors and theme developers have largely been moving towards using relative URLs instead of the baseurl to build paths. This was based on public advice voiced by the Hugo authors on the discourse forum. For example:

“The recommended way to reference resources is to use either relURL or absURL template funcs, which handles the slash issues.”- @ bep

Following that advice, a more up-to-date theme would have code that looks like this buried in a layout file:

<link rel="stylesheet" href="{{ "css/style.css" | relURL }}"/>  →

Bottom line? If your theme uses relURL or absURL to link to site resources like CSS, JavaScript, or static images, then whether or not you include a trailing slash in your baseurl should not matter at all.

And here is some tough love about your theme: if the most recent version does still require the trailing slash in the baseurl to “work” out of the box, I would seriously consider switching themes. This is a pretty good “canary in the coal mine” test regarding how up-to-date the theme author is, and how well the theme you have chosen adheres to Hugo templating best practices. If you are having pain with this now, it is likely not the only thing that will be painful about working with your theme.

#3: Netlify drag-and-drop

If you can render your site locally but your published site looks different, try the drag-and-drop method:

Use the “Serve Site” Addin, then drag-and-drop the public/ folder straight into Netlify. What does this do? You can now see your public site…that you built…with your local version of Hugo. Netlify is doing none of the site building here.

One of the first benefits of this approach is that it ensures that you are able to actually generate a public/ folder locally! I have seen folks struggle to deploy the wrong repo. This simple step can force you to make sure to use the “Serve Site” Addin to generate the public/ folder, and that the repo you are trying to link to Netlify actually contains a Hugo site because you must physically move the public/ folder. But this method can also help you diagnose other problems too.

If your public/ folder does not render on Netlify, you have work to do locally. I can’t tell you what it is as it can be a number of things, but you can be sure that your problem is not just the Netlify build- it is your local build too.

If your public/ folder does render perfectly on Netlify, but you are getting a Netlify build error, then you likely have a Hugo version problem. It might be that the version you are running locally is more recent than the version run by Netlify by default to actually build your site. The good news is there is a quick fix for this! The solution is to upgrade the Hugo version Netlify is using- see my advice here for how to do that.

If you are happy with how your site looks but you are missing content and/or seeing old deleted content, then you may need the next few strategies to troubleshoot.

#4: Torch `public/`

When you are seeing very weird things locally, try deleting your local public/ folder. Then serve site again. Sometimes it can get “junked up”. I’ve found that sometimes deleted content can be a little sticky. As recommended in the blogdown book:

“you are strongly recommended to delete the /public/ directory before you rebuild the site for publishing every time, because Hugo never deletes it”

Also, this has a bonus of reinforcing for you exactly what the “Serve Site” Addin does - it regenerates the public/ folder. This is also the folder that, if you are using Netlify to build your site, is in your .gitignore file because Netlify (+ Hugo) generates this file “fresh” with each push to your GitHub repository.

#5: Peruse `public/`

When you notice weird things, try actually looking inside public/- don’t be afraid to spelunk around in there! If you are seeing something wrong with your site, try to figure out how blogdown/Hugo is processing and rendering your content. This folder can tell you a lot! Keep in mind that your local public/ folder will still contain future/draft/expired content if you used the “Serve Site” Addin.

#6: Back to the future

Figure 5: Where are my posts?

If your site renders beautifully locally, and your drag-and-drop site from public/ looks the same, but you are missing key content when you actually deploy to Netlify using a Hugo build, you may have inadvertently stumbled into a Hugo date time warp. This is a fairly common gotcha. Try using the drag-and-drop method again, this time first delete public/, then instead of using the “Serve Site” Addin, run this in your console:

blogdown::build_site(local = FALSE)

Plop this new public folder in Netlify to see what your site will look like when it is actually published. What does this show you? Your local Hugo build (read: your public/ folder generated by “Serve Site”) differs by design in 3 important ways from your deployed site built by Netlify/Hugo. By default, Hugo will not publish:

Content with a future publishDate value
Content with draft: true status
Content with a past expiryDate value

You can see that these are defaults. The behavior of the “Serve Site” Addin is also documented in the blogdown book:

“This is for you to preview draft and future posts locally.”

Blogdown’s build_site(local = FALSE) differs from the “Serve Site” Addin in that it will not render draft, future, or expired content. So your public/ folder from build_site(local = FALSE) shows you exactly what Netlify should publish. Seeing it can help you troubleshoot why some content was showing up locally but not when you publish.

The defaults are pretty sensible and nice to have, as you can still put these kinds of content under version control, and hence collaborate with other team members on the content without having the content publish (or expire) until you say so.

To show content that Hugo was hiding, you’ll want to edit some YAML fields in the individual offending content files. For example, in the YAML of an individual content file (like a blog post), if you want to un-draft it, add or change this key/value:

title: 'A Spoonful of Hugo: Troubleshooting your Build'
author: "Alison Hill"
date: '2019-03-04'
draft: false

Alternatively, if you want to date something in the future (like to advertise the date of an upcoming talk) but publish now, you can use the publishDate field. The publishDate field is a newer addition to Hugo (>= v0.54.0) which, if left unset, will default to the date field, which means in the individual content file YAML you can do:

title: 'A Spoonful of Hugo: Get excited!!'
author: "Alison Hill"
date: '2025-03-04'
publishDate: '2019-03-04'

Hopefully these 6 things can help you get unstuck. If not, the RStudio community forums are a great place to ask questions!

Hi there

Mon, 25 Feb 2019 13:38:41 -0600

** Contact page don’t contain a body, just the front matter above. See form.html in the layouts folder

Formspree requires a (free) account and new form to be set up. The link is made on the final published url in the field: Restrict to Domain. It is possible to register up to 2 emails free and you can select which one you want the forms to go to within Formspree in the Settings tab. **

Hugo Page Bundles

Thu, 21 Feb 2019 00:00:00 +0000

“Just a spoonful of Hugo helps the blog go down.”

me, only somewhat kidding

This is my third post in this series and it is breaking news.

Hugo Page Bundles

Well, not really breaking news, but you still may not know about it! Hugo v0.32 introduced a new feature called Page Bundles, as a way to organize the content files. Blogdown users rejoice that Davis Vaughn posted an issue on the rstudio/blogdown repo to enable this option, which Yihui added shortly before rstudio::conf 2019 🎉. Here is the snippet from the NEWS.md:

“One benefit of using a page bundle instead of a normal page is that you can put resource files associated with the post (such as images) under the same directory of the post itself. This means you no longer have to put them under the static/ directory, which has been quite confusing to Hugo beginners.”

What does a blogdown/Hugo site begin to look like without page bundles? I think here is a representative example from tidyverse.org (sorry tidyverse team- it’s not you, it’s the old Hugo).

For this team, they need an image for every post, which gets out of control pretty fast. Also, some ended up in static/ too, organized by post (which I have done on my own blog, though not well or consistently).

What would it look like to use page bundles?

content/
├── about
│   ├── index.md
├── posts
│   ├── 2015-07-23-hi-world
│   │   ├── bakers.csv
│   │   ├── image1.jpg
│   │   ├── image2.png
│   │   └── index.Rmd
│   └── 2015-07-24-bye-world
│       └── index.Rmd

One could call this bundled file structure “tidier” 🍱.

In the above, after serving site, index.html files also get added to the bundle. In Hugo’s terms, these are leaf bundles. The resource files allowed in a bundle include page and non-page items like images, pdf, .csv files, etc.

This is instead of:

content/
├── about
│   ├── index.md
├── posts
│   ├── 2015-07-23-hi-world.Rmd
│   ├── bakers.csv
│   ├── image1.jpg
│   ├── image2.png
│   └── 2015-07-24-bye-world.Rmd

When you create a new bundled post, the actual content of the post goes in the index file of a page bundle. So:

# not bundled post
post/2015-07-23-hi-world.Rmd
# bundled post
post/2015-07-24-bye-world/index.Rmd

Bundle Me, blogdown!

First, read the previous post on setting up a netlify.toml file. Since using Hugo page bundles depends on Hugo v0.32 or higher, you should go ahead and update hugo then update your netlify.toml with your updated version:

blogdown::update_hugo()
blogdown::hugo_version()

Now, let’s use the usethis package.

Project-specific .Rprofile

First, I’m going to demo here how to create a project-specific .Rprofile file- but know that you can do a user-level .Rprofile file too.

# install.packages("usethis") # uncomment this to install
usethis::edit_r_profile(scope = "project")

These helpful messages should print to your console: please note the “restart” reminder…

> usethis::edit_r_profile(scope = "project")
● Restart R for changes to take effect
✔ Setting active project to '/Users/alison/rprojs/alison.rbind.io'
● Modify '.Rprofile'

Now you could add this to your file:

# in .Rprofile of the website project
if (file.exists("~/.Rprofile")) {
  base::sys.source("~/.Rprofile", envir = environment())
}

options(blogdown.new_bundle = TRUE)

The first code chunk above is from the blogdown book, where we describe a workaround for loading both user and project .Rprofile files (since R technically only reads one startup profile file).

If you don’t want this, you could add the blogdown options to your user .Rprofile instead using:

usethis::edit_r_profile(scope = "user")

Heck, while you are at it, you could set a bunch of options to make your blogdown life easier:

# in .Rprofile of the website project
if (file.exists("~/.Rprofile")) {
  base::sys.source("~/.Rprofile", envir = environment())
}

options(
  blogdown.author = "Alison Hill",
  blogdown.ext = ".Rmd",
  blogdown.subdir = "post",
  blogdown.yaml.empty = TRUE,
  blogdown.new_bundle = TRUE,
  blogdown.title_case = TRUE
)

For the blogdown-specific options, any of these prepopulate content in your “New Post” Addin (I told you to use this here). There is a handy table from the blogdown book, summarized here:

blogdown.author = author of new posts
blogdown.ext = default extension of new posts (can also be “.md” or “.Rmarkdown”)
blogdown.subdir = theme-specific, you need to know your theme and content folder here
blogdown.yaml.empty = I told you to do that here
blogdown.new_bundle = what this whole post is about!
blogdown.title_case = “nEed More coFFee” –> “Need More Coffee” (it tidies all your post titles to title case)

The Newline Thing

Here is a massive .Rprofile gotcha: this file must end with a blank line. So make sure you add an empty line at the end of the file, then save it, and restart your R session.

Want to make your general R life easier in the future? Follow Yihui’s advice and do this in RStudio to ensure that all source files end with a newline:

Use Bundles

After restarting R, try using the “New Post” Addin, this time with feeling. There is still one more gotcha though. Use the Addin to create your new bundled post. The only catch is that once you are looking at your exciting new post, you should delete the slug in the YAML (I posted an issue about this here).

The reason is that you want the link to your post to be:

http://alison.rbind.io/post/2019-02-21-hugo-page-bundles/

If you include the slug, the link to your post will be:

http://alison.rbind.io/post/2019-02-21-hugo-page-bundles/hugo-page-bundles

Another option is to update your config.toml file with permalinks like Yihui suggests (but beware: this will change all your past links as well, requiring some Netlify redirects):

[permalinks]
    post = "/:year/:month/:day/:slug/"

The default here from Hugo was /post/:year-:month-:day-:slug/:slug/.

A small note: if you want to add relative links from a blog post to another post in your same blog. So [this](/post/2019-02-19-hugo-archetypes/) becomes this.

Now, add images and data files to your ❤️’s content! But you may want to do one more thing…

Update Metadata

If you are anything like me, you may draft a blog post then come back to it later. For example, I started this post 2 days ago, but want to publish it today, 2021-05-24. The cool thing that was already built-in to blogdown is the “Update Metadata” Addin. With your blog post open (it should be called index.Rmd)^[If no post is open, you will get an error: Warning message: The current document does not seem to contain YAML metadata], click on Addins and select “Update Metadata”. You should see a window like this:

Check the box to rename the file if the date has changed. RStudio will tell you your file has been deleted- which is technically true since the folder was renamed, but don’t panic!

Click YES. The index.Rmd file that is now open should have an updated date field in the YAML. In your RStudio file viewer, you may want to click on “content” at this point then navigate back to view your post- then you will then see that the folder name now has an updated date too.

The netlify.toml File

Wed, 20 Feb 2019 00:00:00 +0000

“Just a spoonful of Hugo helps the blog go down.”

me, only somewhat kidding

You can read the previous post about my “Spoonful of Hugo” series here. In this series, I’m sharing small spoonfuls of Hugo that I have learned that hopefully can help you get your site UP (and even better- more efficient, more streamlined, more automated).

This is my second post in this series, and it is a relatively quick one. Just do this. This one is a no-brainer.

Thanks to Mara Averick for alerting me that with Hugo version 0.54.0 and onward, there is a trailing zero at the end of Hugo versions now. So for versions before 0.54.0, use the format: 0.53; for later versions use 0.54.0 (0.54 will not work).

Use Netlify to Deploy

First, you’ll need to use Netlify! I am a very happy Netlify user and currently have approximately 33 sites deployed. To setup a new account, navigate to Netlify and click on the Sign Up link.

If you use a different version control service, select GitLab or BitBucket instead.

The last step is to use the Netlify UI in browser do New Site from Git > pick your repo. You’ll be prompted to fill in these fields, they are probably already filled in correctly for you:

The next part is the advanced build settings:

See that pro tip about the netlify.toml? Let’s do that! You can leave these fields as is.

Why netlify.toml?

In their Build Gotchas:

“If your build works locally, the next debugging step is to ensure the package versions we use to build match yours. You can find the settings for these in the Build Settings doc. That’s the leading cause of build failure.”

Yes that is right- package version mismatches are the leading cause of build failure with Netlify. What does this look like for blogdown users? This means that you are running a version of Hugo locally that doesn’t match the version that Netlify is using to build your site. Most of the time, you are using a more recent version of Hugo than the one Netlify uses. This means that the files your theme relies on may be using newer Hugo functions that were introduced in later Hugo versions- functions that Netlify won’t be able to find working from an older Hugo version. You’ll get all the build errors.

You can check your local Hugo version by running this code in your R console:

blogdown::hugo_version()

## [1] '0.80.0'

Now, we want Netlify to use this same version of Hugo when it builds your site. You can do this two ways:

Do this in your browser (👎)
Do this in your project root directory in a netlify.toml file (👍)

Add the netlify.toml File

Adding this file means that team members can see for themselves what version of Hugo you are running- if it is buried in the Netlify UI, you can’t see that information unless you sift through the public build logs (no thanks). Making the file as plain text in the root of your blogdown project directory means that:

it is version controlled (yay!) and
other people who use/learn from/contribute to your blog can actually reproduce your site with the same site configuration.
Bonus: you can set the Hugo versions for branch deploys too.

Here is an example from my own netlify.toml file^[the leading zero matters for Hugo versions, so 0.53 works but .53 will not. For versions >= 0.54.0, the trailing zero also matters, so 0.54.0 works but 0.54 will not.]:

[build] 
  publish = "public"
  command = "hugo"

[context.production.environment]
  HUGO_VERSION = "0.54.0" # if older, use format: 0.53 (no trailing zero)
  HUGO_ENV = "production"
  HUGO_ENABLEGITINFO = "true"
  
[context.branch-deploy.environment]
  HUGO_VERSION = "0.54.0" # if older, use format: 0.53 (no trailing zero)

[context.deploy-preview.environment]
  HUGO_VERSION = "0.54.0"

You can leave off the last two chunk if you don’t want to use branch deploys or preview deploys, but I ❤️ these two Netlify features and encourage you to try them out. I’ve starting drafting individual blog posts and tutorials in branches, and then I can see them rendered and share them for feedback without asking collaborators to clone and build the repository locally. It is lovely. Every branch and pull request gets a link 🎉.

So add this file to your blogdown site repo and push to GitHub.

Note that, according to the Netlify docs:

“During a build, the following ordering determines which context covers a particular deploy: UI settings are overridden if a netlify.toml file is present in the root folder of the repo and there exists a setting for the same property/redirect/header in the toml file.”

If you look in your site’s Netlify deploy log, you should see entries like this:

7:47:13 PM: Found netlify.toml. Overriding site configuration
7:47:13 PM: Starting build script
7:47:13 PM: Installing dependencies
7:47:14 PM: Started restoring cached node version
7:47:17 PM: Finished restoring cached node version
7:47:18 PM: v8.15.0 is already installed.
7:47:19 PM: Now using node v8.15.0 (npm v6.4.1)
7:47:19 PM: Attempting ruby version 2.3.6, read from environment
7:47:20 PM: Using ruby version 2.3.6
7:47:20 PM: Using PHP version 5.6
7:47:20 PM: Installing Hugo 0.54.0

Success!

Hugo Archetypes

Tue, 19 Feb 2019 00:00:00 +0000

“Just a spoonful of Hugo helps the blog go down.”

me, only somewhat kidding

As a happy blogdown user, a common story I hear from other #rstats users is that you try to change one little thing in Hugo, and the whole site breaks. Here be dragons for folks who aren’t web developers.

I’m here to tell you that there are small spoonfuls of Hugo that can help you get your site UP (and even better- more efficient, more streamlined, more automated), even if you are not in the least bit interested in transitioning into a career in web development 😏.

My Project

The education team at RStudio needs a website and we have a short wishlist:

We want something we can maintain ourselves,
We want to look consistent with other RStudio sites on the outside, and
We want to be consistent on the inside so that we can get help if/when we need it.

This led me to the current tidyverse.org blogdown site. I wanted to make a copy of the site then customize for the education team, but I noticed that the source code for the site didn’t make it easy for me to copy the structure of the site and edit only the content of the site. This is one of the real strengths of Hugo, so I embarked on a learning adventure.

via GIPHY

As a result, I have been living and breathing Hugo lately. As in, my husband now recognizes Mike Dane’s voice. You may not have have met Mike yet, but he appears in all the video tutorials in the Hugo docs. His screencasts have been really helpful to me, like this one on templating. I’ve also spent a lot of time actually reading the docs (which are pretty good!), reading posts and answers on the Hugo discourse community site, and spelunking around inside the actual source code for two very well structured Hugo sites:

The actual Hugo site: https://github.com/gohugoio/hugoDocs
The rOpenSci site: https://github.com/ropensci/roweb2

I’ll be using this post and other later posts to share some of the things I’ve learned about Hugo along the way. Mainly breadcrumbs to myself, but I hope these help other people too.

For reference, I’m using Hugo via the blogdown R package, and within the RStudio IDE. These are my blogdown and Hugo versions:

packageVersion("blogdown")

## [1] '1.3.1'

blogdown::hugo_version()

## [1] '0.80.0'

tl;dr: A Teaspoon of Archetypes

Add custom archetypes as .md files to your project root directory (do not touch the archetypes folder in your themes/archetypes folder).
- If you don’t have that as an empty folder in your project root, make one, then add your archetype files to it.
- If you are making a new blogdown site, I recommend using these options to keep your empty directories^[These setup options are newish to the blogdown package: https://github.com/rstudio-education/arm-workshop-rsc2019/issues/8]:
```
library(blogdown)
new_site(theme = "jpescador/hugo-future-imperfect", 
         sample = TRUE, 
         theme_example = TRUE, 
         empty_dirs = TRUE, # this!
         to_yaml = TRUE)
```
(\#fig:proj-wizard)Using the RStudio Project Wizard
Use the “New Post” Addin in RStudio to create any and all new content for your site (not just posts!). Be sure to use the handy dropdown menu to select from all the possible archetypes. Also, careful about the subdirectory here- some themes use blog, others use news, articles, or posts.
Your archetypes, while only markdown files, can include R code. When you use the Addin, be sure to choose R Markdown (.Rmd) as the format so that you can run the code.
- Don’t miss this great blog post by my friend and the great educator Leo Collado-Torres on archetypes.

A Tablespoon of Archetypes

One of the easiest things you can do for yourself is customize your site’s archetypes. From the Hugo docs:

“Archetypes are templates used when creating new content.”

Right away when I cloned the tidyverse site, I noticed that there were instructions for how to contribute a new article (or blog post) in the README.md and in a separate CONTRIBUTING.md file. Then I noticed this open GitHub issue from Mara Averick (the tidyverse developer advocate) titled “Fix README/CONTRIBUTING so there’s one source of mechanical info?”.

I also noticed that there was no project root folder called archetypes, which is where you would store your custom site archetype files as .md files. In fact, there is no theme folder as you might expect either, which is where you could view the default theme archetypes. Let’s look at some from other Hugo themes:

The default Hugo theme for blogdown, Lithium, has just one archetype: default.md
```
---
title: ''
date: ''
---
```

In contrast, the Hugo Academic theme has A LOT: https://github.com/gcushen/hugo-academic/tree/master/archetypes; here is the content of the one for new posts:

+++
title = "{{ replace .Name "-" " " | title }}"
subtitle = ""

# Add a summary to display on homepage (optional).
summary = ""

date = {{ .Date }}
draft = false

# Authors. Comma separated list, e.g. `["Bob Smith", "David Jones"]`.
authors = []

# Tags and categories
# For example, use `tags = []` for no tags, or the form `tags = ["A Tag", "Another Tag"]` for one or more tags.
tags = []
categories = []

# Projects (optional).
#   Associate this post with one or more of your projects.
#   Simply enter your project's folder or file name without extension.
#   E.g. `projects = ["deep-learning"]` references 
#   `content/project/deep-learning/index.md`.
#   Otherwise, set `projects = []`.
# projects = ["internal-project"]

# Featured image
# To use, add an image named `featured.jpg/png` to your page's folder. 
[image]
  # Caption (optional)
  caption = ""

  # Focal point (optional)
  # Options: Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight
  focal_point = ""
+++

A quick note: you may have noticed differences in both the content between these two files but also the structure. The first is a YAML file, the second is a TOML file. For blogdown users, you may want to use YAML. This is also why I recommend when you set up your site to use the to_yaml = TRUE option (in the Project Wizard from figure 1, check the “Convert all metadata to YAML” box; otherwise, the exampleSite will contain TOML instead of YAML)^[If you end up with TOML in your content files, run this R code: hugo_convert(to = "YAML", unsafe = TRUE)].

If you read the original tidyverse CONTRIBUTING.md file, the instructions include a fair bit of R code that I would guess means a lot of copying and pasting into new posts. For example, the R Markdown setup chunk and the code for using usethis::use_tidy_thanks() for package releases. I studied the contributing guidelines, and parsed three different “kinds” of articles that are commonly contributed, each with a different archetype:

The default.md- this is just for plain old markdown posts and basically sets up the YAML of the post to be the same as it is now (currently, there is no archetype dictating the content- it is pulling from a project-level .Rprofile).
A default-rmarkdown.md which should only be used with an R Markdown post and provides only the setup chunk at the top.
A package-release.md which also should only be used with an R Markdown post and adds the usethis::use_tidy_thanks() code chunk (this is pseudo-code so the default chunk option is set to eval = FALSE).

So I drafted a pull request that adds these three archetypes to the GitHub repository for the tidyverse.org. Here is the “after” Addin view:

Here’s hoping Hugo archetypes make some things about adding new content to your site easier. There is no Hugo involved, other than realizing that Hugo will look first in your themes/<THEME-NAME>/archetypes/ folder, then in your project root archetypes/ folder next. DO NOT TOUCH any files in your themes/ directory.^[Trust me on this one- if you ever want to update your site this will make that process way harder.]

You may want to set up archetypes for your blogdown site if you have a “signature” R setup chunk that loads your preferred knitr chunk options, common libraries you always load at setup like tidyverse, ggplot2 themes you prefer (theme_minimal() FTW), etc. This may be especially helpful if you have multiple team members contributing to a single site and you want their posts to have a uniform setup. Then archetypes can be a real time- and sanity-saver. Get more ideas from Leo’s blog post on archetypes. You can also make directory based archetypes if you use Hugo page bundles, which is a topic of a future post.

Meet blogdown

Tue, 15 Jan 2019 16:00:00 +0000

Meet bookdown

Tue, 15 Jan 2019 14:00:00 +0000

Meet flexdashboard

Tue, 15 Jan 2019 11:00:00 +0000

Meet xaringan

Tue, 15 Jan 2019 09:00:00 +0000

Hugo Graphite

Tue, 01 Jan 2019 00:00:00 +0000

Data Visualization in the Tidyverse

Mon, 29 Oct 2018 16:00:00 +0000

Using one dataset from The Great British Bake Off, I show eleven ways to visualize one dataset using eleven different versions of “tidy data.” Take-away messages:

Tidy data is the start of your data wrangling journey, not the end
There is not a single “tidy” version of a dataset
Tidy data does make you more nimble!

Read Data with Multiple Header Rows into R

Sun, 08 Jul 2018 00:00:00 +0000

A shorter version of this blog post now appears as an article vignette for the readxl package, thank you to Jenny Bryan for the invitation!

A problem I run up against a lot when working with other people’s data is having multiple header rows in the source data file. I like to use readr functions to read in rectangular data like .csv and .tsv files, but if you skip rows at import using the skip argument, you lose the header row as well, which usually has column names. The problem I often have is that the header row has column names that I want to keep, but I’d like to skip the second row (or more), which has some junk in it. Usually this row is some kind of data dictionary inserted between the row of column names and the actual data.

In this post, I’ll walk through a solution to this problem, using the readr package. You can also watch along in the video.

<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen="allowfullscreen" loading="eager" referrerpolicy="strict-origin-when-cross-origin" src="https://www.youtube-nocookie.com/embed/Mayf_XhsQDE?autoplay=0&controls=1&end=0&loop=0&mute=0&start=0" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" title="YouTube video"
  ></iframe>
</div>

Warning!: I made a mistake when I said readr uses the first 100 rows of your data to predict column types- it uses the first 1000 rows.

Download stickers.csv

Being sticker rich

This dataset is from an article published in PLOS ONE called “Being Sticker Rich: Numerical Context Influences Children’s Sharing Behavior”. In this study, children (ages 3–11) received a small (12, “sticker poor”) or large (30, “sticker rich”) number of stickers, and were then given the opportunity to share their windfall with either one or multiple anonymous recipients. This type of experimental design is a version of the Dictator Game.

The main research questions the authors explored were: do the number of available resources and/or the number of potential recipients alter the likelihood of a child donating and/or the amount they donate? But, in order to answer this question, we have to be able to read in the data! Luckily, these lovely developmental psychologists opted to share their data on the Harvard Dataverse as a tab-delimited file.

If you download the file, you can open it up in a plain text editor.

You can also open it with Microsoft Excel.

Read in the file

Let’s start by creating a variable called link to store the link to the data file.

# create variable to store url
link <- "https://dataverse.harvard.edu/api/access/datafile/2712105"

The file has a .tab extension, so we know it is tab-delimited. This means that the right readr function for reading this file is read_tsv. Since we stored our link already as a character string, that is the only argument to the read_tsv function.

#install.packages("readr")
library(readr) # load the readr package
stickers <- read_tsv(link) 
# spec()

Now, we know the second row of data is wonky, but how can we see that in R? There are a number of ways we can go spelunking around into our data file. The easiest to print it. Since we used readr, we have a tibble, which nicely prints to screen.

stickers

# # A tibble: 402 × 18
#    SubjectNumber       Condition NumberStickers NumberEnvelopes Gender Agemonths
#    <chr>               <chr>     <chr>          <chr>           <chr>      <dbl>
#  1 [Included Sample O… 1=12:1; … 1=12; 2=30     1=1 recipient;… 1=fem…        NA
#  2 1                   1         1              1               1             36
#  3 2                   1         1              1               2             36
#  4 3                   1         1              1               2             36
#  5 4                   1         1              1               1             36
#  6 5                   1         1              1               2             36
#  7 6                   1         1              1               2             36
#  8 7                   2         1              2               1             36
#  9 8                   2         1              2               2             36
# 10 9                   3         2              1               2             36
# # ℹ 392 more rows
# # ℹ 12 more variables: Ageyears <dbl>, Agegroups <chr>,
# #   `Subject'sEnvelope` <chr>, LeftEnvelope <chr>, RightEnvelope <chr>,
# #   `absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)` <chr>,
# #   `PercentGiven(Outof100percent)` <chr>, Giveornot <chr>,
# #   LargerEnvelopeabs <chr>, LargeEnvelopepercent <chr>,
# #   SmallerEnvelopeabs <chr>, SmallEnvelopepercent <chr>

Unfortunately, dplyr::glimpse can’t help us much, because we have one variable name that is ridiculously long (absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)). We’ll fix that with dplyr::rename.

library(dplyr)
glimpse(stickers)

# Rows: 402
# Columns: 18
# $ SubjectNumber                                                                  <chr> …
# $ Condition                                                                      <chr> …
# $ NumberStickers                                                                 <chr> …
# $ NumberEnvelopes                                                                <chr> …
# $ Gender                                                                         <chr> …
# $ Agemonths                                                                      <dbl> …
# $ Ageyears                                                                       <dbl> …
# $ Agegroups                                                                      <chr> …
# $ `Subject'sEnvelope`                                                            <chr> …
# $ LeftEnvelope                                                                   <chr> …
# $ RightEnvelope                                                                  <chr> …
# $ `absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)` <chr> …
# $ `PercentGiven(Outof100percent)`                                                <chr> …
# $ Giveornot                                                                      <chr> …
# $ LargerEnvelopeabs                                                              <chr> …
# $ LargeEnvelopepercent                                                           <chr> …
# $ SmallerEnvelopeabs                                                             <chr> …
# $ SmallEnvelopepercent                                                           <chr> …

More options:

head(stickers)

# # A tibble: 6 × 18
#   SubjectNumber        Condition NumberStickers NumberEnvelopes Gender Agemonths
#   <chr>                <chr>     <chr>          <chr>           <chr>      <dbl>
# 1 [Included Sample On… 1=12:1; … 1=12; 2=30     1=1 recipient;… 1=fem…        NA
# 2 1                    1         1              1               1             36
# 3 2                    1         1              1               2             36
# 4 3                    1         1              1               2             36
# 5 4                    1         1              1               1             36
# 6 5                    1         1              1               2             36
# # ℹ 12 more variables: Ageyears <dbl>, Agegroups <chr>,
# #   `Subject'sEnvelope` <chr>, LeftEnvelope <chr>, RightEnvelope <chr>,
# #   `absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)` <chr>,
# #   `PercentGiven(Outof100percent)` <chr>, Giveornot <chr>,
# #   LargerEnvelopeabs <chr>, LargeEnvelopepercent <chr>,
# #   SmallerEnvelopeabs <chr>, SmallEnvelopepercent <chr>

tail(stickers)

# # A tibble: 6 × 18
#   SubjectNumber Condition NumberStickers NumberEnvelopes Gender Agemonths
#   <chr>         <chr>     <chr>          <chr>           <chr>      <dbl>
# 1 396           1         1              1               2            136
# 2 397           4         2              2               1            136
# 3 398           1         1              1               1            137
# 4 399           1         1              1               2            137
# 5 400           4         2              2               2            139
# 6 401           3         2              1               1            143
# # ℹ 12 more variables: Ageyears <dbl>, Agegroups <chr>,
# #   `Subject'sEnvelope` <chr>, LeftEnvelope <chr>, RightEnvelope <chr>,
# #   `absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)` <chr>,
# #   `PercentGiven(Outof100percent)` <chr>, Giveornot <chr>,
# #   LargerEnvelopeabs <chr>, LargeEnvelopepercent <chr>,
# #   SmallerEnvelopeabs <chr>, SmallEnvelopepercent <chr>

names(stickers)

#  [1] "SubjectNumber"                                                               
#  [2] "Condition"                                                                   
#  [3] "NumberStickers"                                                              
#  [4] "NumberEnvelopes"                                                             
#  [5] "Gender"                                                                      
#  [6] "Agemonths"                                                                   
#  [7] "Ageyears"                                                                    
#  [8] "Agegroups"                                                                   
#  [9] "Subject'sEnvelope"                                                           
# [10] "LeftEnvelope"                                                                
# [11] "RightEnvelope"                                                               
# [12] "absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)"
# [13] "PercentGiven(Outof100percent)"                                               
# [14] "Giveornot"                                                                   
# [15] "LargerEnvelopeabs"                                                           
# [16] "LargeEnvelopepercent"                                                        
# [17] "SmallerEnvelopeabs"                                                          
# [18] "SmallEnvelopepercent"

# View()

Now we are ready to diagnose the problem!

Problem: the first row is not really data. It is metadata about the variables, and it is screwing up readr’s ability to predict our column types.

Solution: we’ll use readr and the read_tsv() function to read in the data twice. In Step 1, we’ll create a character vector of the column names only. In Step 2, we’ll read in the actual data and skip the multiple header rows at the top. When we do this, we lose the column names, so we use the character vector of column names we created in Step 1 instead.

Read in the file (again)

Step 1

Goal: we want to read in the first row only and save it as a character vector called sticker_names. This row contains the correct column names that we’ll need in Step 2.

sticker_names <- link %>% 
  read_tsv(n_max = 0) %>% # default: col_names = TRUE
  rename(stickersgiven = 'absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)') %>% 
  names()
sticker_names

#  [1] "SubjectNumber"                 "Condition"                    
#  [3] "NumberStickers"                "NumberEnvelopes"              
#  [5] "Gender"                        "Agemonths"                    
#  [7] "Ageyears"                      "Agegroups"                    
#  [9] "Subject'sEnvelope"             "LeftEnvelope"                 
# [11] "RightEnvelope"                 "stickersgiven"                
# [13] "PercentGiven(Outof100percent)" "Giveornot"                    
# [15] "LargerEnvelopeabs"             "LargeEnvelopepercent"         
# [17] "SmallerEnvelopeabs"            "SmallEnvelopepercent"

glimpse(sticker_names)

#  chr [1:18] "SubjectNumber" "Condition" "NumberStickers" "NumberEnvelopes" ...

Step 2

Goal: we want to read in all the rows except for the first two rows, which contained the variable names and variable descriptions. We want to save this as stickers, and set the column names to the sticker_names object we created in Step 1.

stickers <- link %>% 
  read_tsv(skip = 2, col_names = sticker_names)
glimpse(stickers)

# Rows: 401
# Columns: 18
# $ SubjectNumber                   <dbl> 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,…
# $ Condition                       <dbl> 1, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3, 3, 3,…
# $ NumberStickers                  <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2,…
# $ NumberEnvelopes                 <dbl> 1, 1, 1, 1, 1, 1, 2, 2, 1, 1, 1, 1, 1,…
# $ Gender                          <dbl> 1, 2, 2, 1, 2, 2, 1, 2, 2, 2, 2, 1, 1,…
# $ Agemonths                       <dbl> 36, 36, 36, 36, 36, 36, 36, 36, 36, 36…
# $ Ageyears                        <dbl> 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,…
# $ Agegroups                       <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,…
# $ `Subject'sEnvelope`             <dbl> 7, 12, 4, 7, 12, 8, 8, 11, 26, 30, 12,…
# $ LeftEnvelope                    <dbl> 5, 0, 8, 5, 0, 4, 2, 1, 4, 0, 18, 18, …
# $ RightEnvelope                   <dbl> NA, NA, NA, NA, NA, NA, 2, 0, NA, NA, …
# $ stickersgiven                   <dbl> 5, 0, 8, 5, 0, 4, 4, 1, 4, 0, 18, 18, …
# $ `PercentGiven(Outof100percent)` <dbl> 0.42, 0.00, 0.67, 0.42, 0.00, 0.33, 0.…
# $ Giveornot                       <dbl> 1, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 0,…
# $ LargerEnvelopeabs               <dbl> NA, NA, NA, NA, NA, NA, 2, 1, NA, NA, …
# $ LargeEnvelopepercent            <dbl> NA, NA, NA, NA, NA, NA, 0.5000000, 1.0…
# $ SmallerEnvelopeabs              <dbl> NA, NA, NA, NA, NA, NA, 2, 0, NA, NA, …
# $ SmallEnvelopepercent            <dbl> NA, NA, NA, NA, NA, NA, 0.5000000, 0.0…

Fin!

All together now: the final solution!

# load packages
library(readr)
library(dplyr)

# create variable to store url
link <- "https://dataverse.harvard.edu/api/access/datafile/2712105"

# read in column names only
sticker_names <- link %>% 
  read_tsv(n_max = 0) %>% # default: col_names = TRUE
  rename(stickersgiven = 'absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)') %>% 
  names()

# read in data, set column names
stickers <- link %>% 
  read_tsv(skip = 2, col_names = sticker_names)

Addendum

For good measure, I would add a final step to everything above and use janitor::clean_names() to put all the variable names into snake case. So my final final solution is here:

# load packages
library(readr)
library(dplyr)
library(janitor)

# create variable to store url
link <- "https://dataverse.harvard.edu/api/access/datafile/2712105"

# read in column names only
sticker_names <- link %>% 
  read_tsv(n_max = 0) %>% # default: col_names = TRUE
  rename(stickersgiven = 'absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)') %>% 
  names()

# read in data, set column names
stickers <- link %>% 
  read_tsv(skip = 2, col_names = sticker_names) %>% 
  clean_names()

stickers

# # A tibble: 401 × 18
#    subject_number condition number_stickers number_envelopes gender agemonths
#             <dbl>     <dbl>           <dbl>            <dbl>  <dbl>     <dbl>
#  1              1         1               1                1      1        36
#  2              2         1               1                1      2        36
#  3              3         1               1                1      2        36
#  4              4         1               1                1      1        36
#  5              5         1               1                1      2        36
#  6              6         1               1                1      2        36
#  7              7         2               1                2      1        36
#  8              8         2               1                2      2        36
#  9              9         3               2                1      2        36
# 10             10         3               2                1      2        36
# # ℹ 391 more rows
# # ℹ 12 more variables: ageyears <dbl>, agegroups <dbl>,
# #   subjects_envelope <dbl>, left_envelope <dbl>, right_envelope <dbl>,
# #   stickersgiven <dbl>, percent_given_outof100percent <dbl>, giveornot <dbl>,
# #   larger_envelopeabs <dbl>, large_envelopepercent <dbl>,
# #   smaller_envelopeabs <dbl>, small_envelopepercent <dbl>

glimpse(stickers)

# Rows: 401
# Columns: 18
# $ subject_number                <dbl> 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 1…
# $ condition                     <dbl> 1, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3, 3, 3, 4…
# $ number_stickers               <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2…
# $ number_envelopes              <dbl> 1, 1, 1, 1, 1, 1, 2, 2, 1, 1, 1, 1, 1, 2…
# $ gender                        <dbl> 1, 2, 2, 1, 2, 2, 1, 2, 2, 2, 2, 1, 1, 1…
# $ agemonths                     <dbl> 36, 36, 36, 36, 36, 36, 36, 36, 36, 36, …
# $ ageyears                      <dbl> 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3…
# $ agegroups                     <dbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1…
# $ subjects_envelope             <dbl> 7, 12, 4, 7, 12, 8, 8, 11, 26, 30, 12, 1…
# $ left_envelope                 <dbl> 5, 0, 8, 5, 0, 4, 2, 1, 4, 0, 18, 18, 0,…
# $ right_envelope                <dbl> NA, NA, NA, NA, NA, NA, 2, 0, NA, NA, NA…
# $ stickersgiven                 <dbl> 5, 0, 8, 5, 0, 4, 4, 1, 4, 0, 18, 18, 0,…
# $ percent_given_outof100percent <dbl> 0.42, 0.00, 0.67, 0.42, 0.00, 0.33, 0.33…
# $ giveornot                     <dbl> 1, 0, 1, 1, 0, 1, 1, 1, 1, 0, 1, 1, 0, 1…
# $ larger_envelopeabs            <dbl> NA, NA, NA, NA, NA, NA, 2, 1, NA, NA, NA…
# $ large_envelopepercent         <dbl> NA, NA, NA, NA, NA, NA, 0.5000000, 1.000…
# $ smaller_envelopeabs           <dbl> NA, NA, NA, NA, NA, NA, 2, 0, NA, NA, NA…
# $ small_envelopepercent         <dbl> NA, NA, NA, NA, NA, NA, 0.5000000, 0.000…

Bonus data dictionary

As an extra bonus, when you do have extra header rows, you can create a data dictionary using the gather() function from the tidyr package.

library(tidyr)
stickers_dict <- read_tsv(link, n_max = 1) %>% 
  rename(stickersgiven = 'absolutenumberofstickersgiven(Conditions1or3:Outof12;Conditions2or4:Outof30)') %>% 
  clean_names() %>% 
  gather(variable_name, variable_description)
stickers_dict

# # A tibble: 18 × 2
#    variable_name                 variable_description                           
#    <chr>                         <chr>                                          
#  1 subject_number                [Included Sample Only]                         
#  2 condition                     1=12:1; 2=12:2, 3=30:1, 4=30:2                 
#  3 number_stickers               1=12; 2=30                                     
#  4 number_envelopes              1=1 recipient; 2=2 recipients                  
#  5 gender                        1=female; 2=male                               
#  6 agemonths                     <NA>                                           
#  7 ageyears                      <NA>                                           
#  8 agegroups                     1=3-4yrs; 2=5-6yrs; 3=7-8yrs; 4=9-11yrs        
#  9 subjects_envelope             How many stickers did the child keep for thems…
# 10 left_envelope                 1 recipient conditions: How many stickers the …
# 11 right_envelope                1 recipient conditions: N/A; 2 recipient condi…
# 12 stickersgiven                 Regardless of condition, the number of sticker…
# 13 percent_given_outof100percent Regardless of condition, the proportion of sti…
# 14 giveornot                     1=Donated 1 or more stickers to the recipient(…
# 15 larger_envelopeabs            Raw number of stickers (out of 30: Condition 2…
# 16 large_envelopepercent         Proportion of stickers (out of 100%; Condition…
# 17 smaller_envelopeabs           Raw number of stickers (out of 30: Condition 2…
# 18 small_envelopepercent         Proportion of stickers (out of 100%; Condition…

Useful resources

Great blog post from Lisa DeBruine using readxl to read in data with multiple header rows (including those with merged cells!): https://debruine.github.io/multirow_headers.html
This GitHub issue with Hadley’s response that solved all my problems: https://github.com/tidyverse/readr/issues/179
My original tweet when I discovered this trick!

Neat #rstats #readr #tidyverse solution to read data when 1st row is header + 2nd row is junk, thanks @hadleywickham https://t.co/5TuH7vNaID pic.twitter.com/woZ3HuECge
— Alison Hill (@apreshill) September 4, 2017

LICENSE: CC-BY-SA

Thu, 28 Jun 2018 00:00:00 +0100

My blog posts are released under a Creative Commons Attribution-ShareAlike 4.0 International License.

Big Magic with R: Creative Learning Beyond Fear

Sat, 02 Jun 2018 08:00:00 +0000

Inspired by the book “Big Magic: Creative Living Beyond Fear” by Elizabeth Gilbert, Alison will talk about the five essential ingredients needed to creatively learn R and why these elements are also essential for advanced users to take their R skills to the next level. You will hear practical advice for when, where, and how to start a project in R, and how your learning can add value- both to your own knowledge and to contribute to the larger community of R learners. Along the way, she will share recommended resources and evidence-based strategies for project-based learning. Alison’s background working with both new and advanced R users gives her a unique perspective on this topic.

Take a Sad Plot & Make It Better

Fri, 06 Apr 2018 16:00:00 +0000

Join us on April 6 for a walk-through of how to take a sad plot and make it better by Alison Hill, who co-teaches the CS631 Data Visualization course. Alison will take us through one plot’s life cycle, from a sad Powerpoint slide to an Excel chart and finally to the finished product made with the ggplot2 package in R. We will discuss why each version of the plot fails in different ways, how each iteration improved on the last one, and which data visualization principles are at work in the final plot to communicate a clear scientific story.

Following this, Eric Earl (Senior RA in the DCAN Labs) will show a case study of visualization in neuroimaging research.

Subtyping cognitive profiles in Autism Spectrum Disorder using a random forest algorithm

Wed, 20 Dec 2017 00:00:00 +0000

R-Ladies Presentation Ninja

Mon, 18 Dec 2017 00:00:00 +0000

So, you are doing an R-Ladies presentation…that’s awesome!

The short version

I made an R-Ladies theme for xaringan slides. My original tweet about it:

if you want to use @xieyihui's awesome #xaringan package for #rstats slides but want more #Rladies flavor, there is now a built-in theme for that (with code highlighting)! Thanks to the awesome @RLadiesGlobal starter kit. Update the CSS in your YAML to use 🧙🏽‍♀️🧞‍♀️ pic.twitter.com/YnlGSVAMsl
— Alison Hill (@apreshill) November 29, 2017

The way to use the theme is to update the YAML like so:

output:
  xaringan::moon_reader:
    css: ["default", "rladies", "rladies-fonts"]

Make sure your version of xaringan is up-to-date.

Below is a demo slide deck using the theme.

(view the source .Rmd on GitHub)

The longer story

I recommend Yihui’s xaringan package for slides. This is an R package, available through GitHub, for creating slideshows with remark.js through R Markdown. This means that you can:

write all your slides in Markdown text
include chunks of R code and rendered output like plots, results, tables, etc. in your slides
use git for version control and share your GitHub repository

This makes xaringan ideal for an R-Ladies presentation!¹

To use the package, you’ll need the devtools package installed so that you can use the install_github function. Then do:

devtools::install_github('yihui/xaringan')

As Yihui points out in the documentation, if you use RStudio, you can use the menu to navigate to File -> New File -> R Markdown -> From Template -> Ninja Presentation, and you will see an R Markdown example.

I first used xaringan a few months ago. I was working with Yihui on the blogdown book, and had signed up to lead a workshop for the Portland R User group. Obviously, such a workshop could not have powerpoint slides, so it seemed like the perfect time to learn xaringan.

For my workshop, I made a simple website for the newly founded R-Ladies PDX using blogdown (Thanks to Augustina and Deeksha, our fearless organizers). So naturally, my slides needed more purple.

Luckily, the R-Ladies run a tight ship- they have a starter kit on GitHub that details all the pretty purples they like.

About a month after I did the R-Ladies blogdown workshop, I saw this blog post by Yihui:

First, I thought this was such a cool idea and I hope more people make and submit themes. Then I realized, I had already made a theme! I submitted a pull request², Yihui helped me make some edits to the CSS files to make them more parsimonious with the default theme, I electronically signed a contributor agreement, and now the theme is there for you all to enjoy and use! You use the theme by editing the YAML:

output:
  xaringan::moon_reader:
    css: ["default", "rladies", "rladies-fonts"]

If you use the theme and you are on twitter, I’d love to see it- please mention me on twitter!

Examples!

My blogdown workshop slides: “Up and running with blogdown” (view the source .Rmd on GitHub)

Jessica Minnier’s slides for “Building Shiny Apps: With Great Power Comes Great Responsibility”

If you are new to xaringan, don’t miss the wiki! ↩︎
Yihui’s technical instructions for contributors section of that blog post has been revised and is very detailed ↩︎

blogdown: Creating Websites with R Markdown

Thu, 14 Dec 2017 00:00:00 +0000

Labhub Workshop

Fri, 08 Dec 2017 16:00:00 +0000

The landscape of scientific communication is changing dramatically. Diverse stakeholders, including major funders and universities are demonstrating a growing interest and investment in open scientific principles and practices. Researchers, students, and the institutions that support them are needing to navigate new expectations, workflows, and policies against a backdrop of relatively unchanged means and measures of scientific success.

Sound complicated? Join us on December 8th from 3:00 to 4:00 PM for a panel discussion with OHSU leaders and early career researchers on the evolving landscape of scientific communication. We’ll explore the drivers behind the calls for “openness”, what this means in practice, and the real world compatibility and tensions between open science and student, researcher, and institutional success.

Confirmed panelists include:

Dr. Gary Westbrook, Vollum Institute Senior Scientist and Director of the Neuroscience Graduate Program

Dr. Bita Moghaddam, Chair of the Department of Behavioral Neuroscience

Dr. Abhinav Nellore, Assistant Professor, Biomedical Engineering and the Department of Surgery

Dr. Alison Hill, Associate Professor, Center for Spoken Language Understanding

The panel will be followed by food, drinks, and two hands on workshops from 4:00 - 5:30:

In this workshop, Dr. Alison Hill and Robin Champieux demonstrated tools and methods for building transparency within a lab, and onboarding new graduate students and postdocs. We provided a template GitHub repository and code of conduct designed to facilitate a healthy and productive learning and research environment. You are encouraged to use these tools to communicate expectations, document protocols, receive feedback, and facilitate the long-term value of students’ and trainees’ contributions.

Labhub is a work in progress. We created this repository as an education and demonstration tool for faculty, postdocs, and students curious about how documentation, open science workflows, and tools like Github can contribute to a healthy and productive research environment. Your ideas and contributions are welcome!

Up & Running with blogdown

Thu, 14 Sep 2017 00:00:00 +0000

See project links for more details.

Up & Running with blogdown

Thu, 14 Sep 2017 00:00:00 +0000

We will cover:

The blogdown R package
Hugo themes
Adding content to personalize your site
Posting
Don’t want to blog? / just want to knit?
Customizing themes
Troubleshooting common problems
Deployment options and recommendations
Domain options available through RStudio/rbind

If you are planning on attending this workshop, please click on the HTML link above for how to prepare before the workshop.

Labhub

Thu, 14 Sep 2017 00:00:00 +0000

Up & Running with blogdown

Mon, 12 Jun 2017 00:00:00 +0000

Greetings from the future!

A lot has changed about blogdown, Hugo, and the Academic theme (now Wowchemy) since the time this post was written.

An updated tutorial can now be found here 🎉

Read up on blogdown

Before you start, I recommend reading the following:

blogdown: Creating Websites with R Markdown by Yihui Xie and Amber Thomas
Making a Website Using blogdown, Hugo, and GitHub pages also by Amber Thomas

I also found this comment by Eric Nantz, the creator of the R-Podcast, in the rbind/support issues section on GitHub to be helpful:

https://github.com/rbind/support/issues/12

Caveats, disclaimers, etc.

Even with all the great resources I listed above, getting myself up and running took a few tries, so in this post I’m passing along what ended up working for me. Everyone’s mileage may vary, though, depending on your operating system and your approach. About me: I am a macOS user, and I use R, RStudio, Git (usually via GitLab, sometimes via GitHub), and terminal regularly, so I’m assuming familiarity here with all of these. If that is not you, here are some places to get started:

For Git: Happy Git with R by Jenny Bryan et al.
For RStudio: DataCamp’s Working with the RStudio IDE (free) by Garrett Grolemund
For Terminal: The Command Line Murder Mystery by Noah Veltman, and The UNIX Workbench by Sean Kross

I also have Xcode and Homebrew installed- you will probably need these to download Hugo. If you don’t have either but are on a mac, this link may help:

How to install Xcode, Homebrew, Git, RVM, Ruby & Rails on Mac OS X

Finally, I did not want to learn more about a lot of things! For instance, the nitty gritty of static site generators and how domain names work. I am a new mom, and just in the process of writing all this up, I filled up my tea mug twice with ice cold water, and filled my water bottle with scalding hot water. So, where offered, I followed the advice of Yihui and Amber. For example:

In GitHub

Go online to your GitHub account, and create a new repository (check to initialize with a README but don’t add .gitignore- this will be taken care of later). For naming your repo, consider your future deployment plan:
- If you are going to use Netlify to host the site, you can name this repository anything you want!

You can see some of the repo names used by members of the rbind organization here.

* If you want to host your site as a [GitHub Page](https://pages.github.com), you should name your repository `yourgithubusername.github.io` (so mine would have been `apreshill.github.io`). If you are going this route, I suggest you follow [Amber's instructions](https://proquestionasker.github.io/blog/Making_Site/) instead of mine!

Go to the main page of your new repository, and under the repository name, click the green Clone or download button.
In the Clone with HTTPs section, click on the clipboard icon to copy the clone URL for your new repository. You’ll paste this text into terminal in the next section.

In terminal

Now you will clone your remote repository and create a local copy on your computer so you can sync between the two locations (using terminal or your alternative command line tool for a Windows machine).

Use cd to navigate into the directory where you want your repo to be
Once there, type: git clone [paste]. So my command looked like this:

git clone https://github.com/apreshill/apreshill.git

And this is what printed to my terminal window:

Cloning into 'apreshill'...
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.
Checking connectivity... done.

Close terminal, you are done in there.

In RStudio

Install blogdown from your RStudio console. If you already have devtools installed like I did, you can just use the second line below:

if (!requireNamespace("devtools")) install.packages("devtools")
devtools::install_github("rstudio/blogdown")

Install Hugo using the blogdown package helper function:

blogdown::install_hugo()
# or
library(blogdown)
install_hugo()

This is where my instructions diverge from Ed’s- he states that blogdown won’t create a website in your root folder because the README.md file is already there. I didn’t find that to be the case- I tested this with a new site as well. If one way doesn’t work for you, try the other!

Use the top menu buttons in RStudio to select File -> New Project -> Existing Directory, then browse to the directory on your computer where your GitHub repo is and click on the Create Project button.

Now you should be “in” your project in RStudio. If you are using git for version control, edit your *gitignore file. This file should be viewable in your file viewer pane in RStudio. Below is what it should look like: the first four lines will automatically be in this file if you have set up your RStudio Project, but if you plan to use Netlify to deploy, you need to add the public/ line ( read about here.)

.Rproj.user
.Rhistory
.RData
.Ruserdata
blogdown
.DS_Store # if a windows user, Thumbs.db instead
public/ # if using Netlify

Build your site in RStudio

Now you can finally build your site using the blogdown::new_site() function. But first you should at least think about themes…

Picking a theme

There are over 90 Hugo themes. So I went back to the blogdown book. Thankfully, Yihui and Amber offer “to save you some time, we list a few themes below that match our taste…”. Huzzah- I went with hugo-academic! Whatever theme you choose, you’ll need to pick one of 3 ways to make your new site:

If you are happy with the default theme, which is the lithium theme, you can use:

blogdown::new_site() # default theme is lithium

If you want a theme other than the default, you can specify the theme at the same time as you call the new_site function:

# for example, create a new site with the academic theme
blogdown::new_site(theme = "gcushen/hugo-academic", theme_example = TRUE)

If instead you want to add the theme later (like I did, because I didn’t see the above example until it was too late!), you can do this:

library(blogdown)
new_site() # default theme is lithium
# need to stop serving so can use the console again
install_theme("gcushen/hugo-academic", theme_example = TRUE, update_config = TRUE)

Now is a good time to re-read about blogdown::serve_site() and how LiveReload works (and how it blocks your R console by default)

I recommend setting theme_example = TRUE- some themes won’t provide an example site, but the academic theme did and I found it helpful to see. You can always delete the example content.

Update project options

In your project in RStudio, go to the top menu bar of RStudio and select Tools -> Project Options and update following Yihui and Amber’s instructions.

Edit your configurations

Relevant reading:

blogdown book chapter on configuration
Additional detail from Amber
You can also view my config.toml file

Now, edit the baseurl in your config.toml file. The URL should always end with a / trailing slash. At this point, you probably haven’t deployed your site yet, so to view it locally you can use the Serve Site add-in, or run the blogdown::serve_site function. Both of these baseurls worked for me when viewing locally:

baseurl = "https://example.com/"
baseurl = "/"

Make sure that the baseurl = listed ends with a trailing slash /!

Go ahead and edit all the other elements in the config.toml file now as you please- this is how you personalize your site!

Addins & workflow

Relevant reading:

blogdown book chapter on the RStudio IDE

Addins: use them- you won’t need the blogdown library loaded in the console if you use the Addins. My workflow in RStudio at this point (again, just viewing locally because we haven’t deployed yet) works best like this:

Open the RStudio project for the site
Use the Serve Site add-in (only once due to the magic of LiveReload)
View site in the RStudio viewer pane, and open in a new browser window while I work
Select existing files to edit using the file pane in RStudio
After making changes, click the save button (don’t knit!)- the console will reload, the viewer pane will update, and if you hit refresh in the browser your local view will also be updated
When happy with changes, add/commit/push changes to GitHub

Started building sites ...
ERROR 2017/06/08 16:22:34 failed to parse page metadata for home/about.md: (18, 6): missing comma
Error: Error building site: Errors reading pages: Error: failed to parse page metadata for home/about.md: (18, 6): missing comma for about.md

The above workflow is only for editing existing files or posts, but not for creating new posts. For that, read on…

Posting

Relevant reading:

blogdown book chapter on RStudio IDE
blogdown book chapter on output formats: on .md versus .Rmd posts
Additional detail from Amber on adding a blog post

Bottom line:

Use the New Post addin. But, you need the console to do this, so you have to stop blogdown::serve_site by clicking on the red Stop button first. The Addin is a Shiny interface that runs this code in your console: blogdown:::new_post_addin(). So, your console needs to be unblocked for it to run. You also need to be “in” your RStudio project or it won’t work.

Draft posts

Relevant reading:

blogdown book chapter on building a website for local preview

Whether you do a markdown or R Markdown post (see below), you should know that in the YAML front matter of your new file, you can add draft: TRUE and you will be able to preview your post using blogdown::serve_site(), but conveniently your post will not show up on your deployed site until you set it to false. Because this is a function built into Hugo, all posts (draft or not) will still end up in your GitHub repo though.

New markdown posts

Pick one of 2 methods:

Use the New Post addin and with the radio button at the bottom select Format: Markdown (recommended)
Use the console to author a new .md post:

blogdown::new_post()
blogdown::new_post(ext = '.md') # md is the default!

Here are the ?new_post arguments:

new_post(title, kind = "", open = interactive(),
    author = getOption("blogdown.author"), categories = NULL, tags = NULL,
    date = Sys.Date(), file = NULL, slug = NULL,
    title_case = getOption("blogdown.title_case"),
    subdir = getOption("blogdown.subdir", "post"),
    ext = getOption("blogdown.ext", ".md"))

Remember to use the Serve Site addin again so that you can immediately view your changes with every save using LiveReload.

New R Markdown (.Rmd) posts

Again, you have your choice of one of 2 methods:

Use the New Post addin and with the radio button at the bottom select Format: R Markdown (.Rmd) (recommended)
Use the console to author a new .Rmd post:

blogdown::new_post(ext = '.Rmd') # md is the default!

After you edit your .Rmd post, in addition to saving the changes in your .Rmd file, you must use blogdown::serve_site- this is how the output html file needs to be generated.

Do not knit your .Rmd posts- use blogdown::serve_site instead. If you happen to hit the knit button, just Serve Site again to rewrite the .html file.

Ultimately, your YAML front matter looks something like this; note that some but not all features of rmarkdown::html_document are supported in blogdown:

---
title: "My Awesome Post"
author: "John Doe"
date: "2017-02-14"
output:
  blogdown::html_page:
    toc: true
    toc_depth: 1
    number_sections: true
    fig_width: 6
---

Remember to use the Serve Site addin again so that you can immediately view your changes with every save using LiveReload and your .html file is properly output.

Adding images to a post

If you want to include an image that is not a figure created from an R chunk, the recommended method is to:

Add the image to your /static/img/ folder, then
Reference the image using the relative file path as follows:

![my-image](/img/my-image.png)

Deploy in Netlify

Deploying in Netlify through GitHub is smooth. Yihui and Amber give some beginner instructions, but Netlify is so easy, I recommend that you skip dragging your public folder in and instead automate the process through GitHub.

When you are ready to deploy, commit your changes and push to GitHub, then go online to Netlify.
Click on the Sign Up button and sign up using your existing GitHub account (no need to create another account)
Log in, and select: New site from Git -> Continuous Deployment: GitHub.
From there, Netlify will allow you to select from your existing GitHub repositories. You’ll pick the repo you’ve been working from with blogdown, then you’ll configure your build. This involves specifying two important things: the build command and the publish directory (this should be public).
- More about the build command from Netlify: “For Hugo hosting, hugo will build and deploy with the version 0.17 of hugo. You can specify a specific hugo release like this: hugo_0.15. Currently 0.13, 0.14, 0.15, 0.16, 0.17, 0.18 and 0.19 are supported. For version 0.20 and above, you’ll need to create a Build environment variable called HUGO_VERSION and set it to the version of your choice.” I opted for the former, and specified hugo_0.19.

You can check your hugo version in terminal using the command hugo version. This is what my output looked like, so I could run version 0.20 if I wanted to through Netlify, but I went with 0.19 and it works just fine.

$ hugo version
Hugo Static Site Generator v0.20.7 darwin/amd64 BuildDate: 2017-05-08T18:37:40-07:00

Netlify will deploy your site and assign you a random subdomain name of the form random-word-12345.netlify.com. Mine was particularly unfortunate, with the random word garbage-collector-janice. You should know that you can change this; I changed mine to apreshill.netlify.com.

Anytime you change your subdomain name, you need to update the baseurl in your config.toml file (so I changed mine to baseurl = “ https://apreshill.netlify.com/").

At this point, you should be up and running with blogdown, GitHub, and Netlify, but here are some ideas if you want to go further…

Going further

Custom CSS

I like to tinker with default theme settings like colors and fonts. Every Hugo theme is structured a little differently, but if you are interested, you can check out my custom css to see how I customized the academic theme, which provides a way to link to a custom CSS file in the config.toml file:

  # Link custom CSS and JS assets
  #   (relative to /static/css and /static/js respectively)
  custom_css = ["blue.css"]

Formspree

I used Formspree to make a contact form, which is an online service (managed on GitHub) that allows you to add an HTML form to your static site. No registration, just use the form and confirm your email address once. I added the following code into my contact widget:

<form action="https://formspree.io/your@email.com" method="POST">
  <label for="name">Your name: </label>
  <input type="text" name="name" required="required" placeholder="here"><br>
  <label for="email">Your email: </label>
  <input type="email" name="_replyto" required="required" placeholder="here"><br>
  <label for="message">Your message:</label><br>
  <textarea rows="4" name="message" id="message" required="required" class="form-control" placeholder="I can't wait to read this!"></textarea>
  <input type="hidden" name="_next" value="/html/thanks.html" />
  <input type="submit" value="Send" name="submit" class="btn btn-primary btn-outline">
  <input type="hidden" name="_subject" value="Website message" />
  <input type="text" name="_gotcha" style="display:none" />
</form>

`*.rbind.io` domain names

You may want a different domain name than the one provided by Netlify. I opted for a free subdomain *.rbind.io offered by RStudio. To do the same, head over to the rbind/support GitHub page and open a new issue. All you need to do is let them know what your Netlify subdomain name is (*.netlify.com), and what you want your subdomain name to be (*.rbind.io). The awesome rbind support team will help you take it from there!

Again, you will need to update the baseurl in your config.toml file to reflect your new rbind subdomain name (so mine is baseurl = “ https://alison.rbind.io/").

Have fun!

Lastly, don’t forget to just have fun with it. Happy blogdowning!

via GIPHY

Quantitative Analysis of Disfluency in Children with Autism Spectrum Disorder or Language Impairment

Wed, 15 Mar 2017 00:00:00 +0000

Code Your Graph Workshop

Fri, 24 Jun 2016 00:00:00 +0000

Code Your Graph Workshop

Fri, 24 Jun 2016 00:00:00 +0000

Summer of blogdown