Sessions (Day 2)

Day 2

Pour Some Glitter On It: Custom Quarto Outputs

Wednesday, Aug 14 1:00 PM - 2:20 PM PDT

Report Design in R: Small Tweaks that Make a Big Difference

Session Info
  • Framework for good design
    • Do: Be consistent
    • Don’t: Use defaults
  • What is a report?
    • Create a layout
    • Add brand colors
    • Add brand fonts
    • Add plots
      • Brand colors, brand colors
  • Steps
    • Identify brand colors
    • Identify brand fonts
    • Create a layout
      • typst overall process:
        • report.qmd -> typst-show.typ -> typst-template.typ -> report.pdf
          • format: typst
          • template-partials:
            • - typst-show.typ
            • - typst-template.typ
          • typst-show.typ will take the variables from Quarto and pass them into typst -> typst-template.typ will set up the template (fonts, colors, margins, backgrounds, etc.)
    • Use functions to make your plots consistent
    • Use brand fonts in plots
      • Make a custom theme
      • Note that geom_text is not impacted by theme - use update_geom_defaults()
library(tidyverse)
library(scales)

# Define brand colors as variables
psc_blue <- "#15397F"
psc_red <- "#9F3515"

# Create a function (call-out numbers using ggplot)
big_number_plot <- function(value, text, value_color) {
  ggplot() + 
    # Add value
    geom_text(
      aes(
        x = 1,
        y = 1,
        label = value
      ),
      color = value_color,
      fontface = "bold",
      size = 20,
      hjust = 0
    ) +
    # Add text
    geom_text(
      aes(
        x = 1,
        y = 2,
        label = str_to_upper(text)
      ),
      color = "gray70",
      size = 7,
      hjust = 0
    ) +
    theme_void()
}

big_number_plot(
  value = "19%",
  text = "Single-Family Homes as\nPercent of All Homes",
  value_color = psc_blue
)
# Use brand fonts in plots

## Make a custom theme
theme_psc <- function() {
  theme_void(base_family = "Open Sans") +
    theme()
}

## Use update_geom_defaults() as geom_text is not impacted by theme

update_geom_defaults(
  geom = "text",
  aes(family = "Open Sans")
) # at beginning of script or quarto document

Reproducible, dynamic, and elegant books with Quarto

Session Info
  • Book with multiple outputs: HTML, PDF
    • Wanted different outputs to look similar in style
    • Fenced div (:::) (::: {.chapterintro data-latex""} :::)
      • With SCSS for HTML
      • With TeX for PDF (define new environments)
    • Quarto YAML
      • HTML: pull in .scss file (theme: [cosmo, scss/ims-style.scss])
      • PDF: pull in .tex file (include-in-header: latex/ims-style.tex)
    • “Litter” your qmd file with LaTeX tags like \clearpage or \newpage that qmd -> LaTeX will process and qmd -> HTML will ignore
    • Build on things qmd -> HTML will ignore and qmd -> LaTeX will process: \index{}
        1. \index{} tags
        1. Write a .tex file to be appended to the end during render (that includes \printindex)
        1. Include that file in Quarto YAML (include-after-body: latex/after-body.tex)
    • Looking forward to typst for styling and for tables
      • Today
        • One source + 2 style files -> 2 outputs
        • Need to declare things some for HTML and some for PDF using the kableExtra R package
      • Future
        • One source + 1 style file -> 2 outputs
        • Maybe we can get away with not having to declare separate options using the gt R package
  • Accessibility check
    • Use fig-alt for alternative text
      • Check for missing fig-alts by finding cells that have ggplot() but not fig-alt using the parsermd R package (dev version)
    • Sim Daltonism: Open source tool that will put a color filter on your screen to check for color accessibility on the fly
  • Set global options with _common.R
    • Leverage your R knowledge to achieve consistent output
      • set.seed(1014)
      • knitr::opts_chunk$set()
      • options() # R options
      • ggplot2::theme_set() # set theme and base size
  • Set status of work-in-progress chapters
    • With _common.R - use your R function writing skills to avoid duplication
    • Today’s solution: use Quarto’s Announcement Bar
  • Keeping things in check daily
    • Leveraging GitHub actions
      • Avoid freeze: re-run all code in GitHub actions (may be overkill for many projects)
      • Set daily checks
  • Multiple languages
    • Two languages in one .qmd file each being executed with their own engine
      • Use embed shortcode to insert from two source notebooks to include two recognizable outputs on a single page
    • Productivity with freeze

Designing and Deploying Internal Quarto Templates

Session Info
  • Quarto templates using corporate styling
  • Why bother?
    • Ensures all documents produced by the org have a similar style/structure
    • Saves analysts from having to learn & implement html & css
    • Provides an analytical skeleton to set people up for success
    • Lowers the lift for writeups (make it easier and people might do it!)
  • How to do this?
    • Add custom css/scss files to the YAML
    • Start tinkering with custom scss files that you can put in the YAML (theme:)

Example:

qmd file

#| echo: true
#| eval: false

::: confidential
CONFIDENTIAL \| NOT FOR DISTRIBUTION
:::

scss file

/* confidential banner */
.confidential {
  background-color: $headings-color;
  font-family: $headings-font-family !important;
  border-radius: 0.375rem;
  text-align: center;
  color: white;
}
  • Resources on writing css
    • Use DevTools to see skeleton of the page:
      • [right-click -> Inspect] in browser for css/html style elements
      • Can change style elements in DevTools to see what changes what
    • MDN Web Docs
  • How do I share this?
    • Put it all in an internal package
    • Example: create_zelus_html()
      • 2 things
        • The files to copy (templates, images, logos) in a folder (e.g., inst)
        • The function to copy the files
      • What this function does
        • Creates an _extensions folder
        • Copy over the files from inst.
        • Create new .qmd file from the file name argument
  • Takeaways
    • Create an internal package if you don’t have one
    • If multiple people are creating Quarto docs, consider creating a template
    • Use DevTools (Inspect) & Mozilla Web Docs to learn more about CSS
  • Q&A
    • Internal package vs. Quarto use template command on a GitHub repository?

Closeread: bringing Scrollytelling to Quarto

Session Info
  • Presenter: Andrew Bray
  • Example: A Poem (and a Painting) About the Suffering That Hides in Plain Sight NYT Article
  • Scrollytelling: where you have a narrative that’s scrolling down the page as you scroll, but that scrolling behavior is modifying what you’re looking at (e.g., panning across images, highlighting text, zooming into text, playing a video)
  • Some jargon
    • Fenced Div (:::{#myid .myclass myattr="val"} :::)
    • Bracketed Span ([bing]{#myid .myclass myattr="val"})
  • Closeread | GitHub
    • A quarto extension that enables scrollytelling to study text, study images, study code for a stronger, more focused narrative
      • format: closeread-html
      • Wrap content in a fenced div and give it the class .cr-section (:::{.cr-section}) to make it a two-column layout where the content goes into a sidebar
      • Be clear on what you want to study by flagging it - come up with an ID (e.g., poem)
        • Sticky: Wrap content in a fenced div; prefix that ID with cr- (e.g., :::{#cr-poem})
          • Add “focus effects” by specifying with a bracketed span where we want to highlight and zoom (e.g., [About suffering]{#cr-suffering} they were never wrong,); add to trigger (e.g., [@cr-poem]{hlz="cr-suffering"})
        • Trigger: Provide a reference to it in the paragraph where we’d like it to appear when that paragraph hits the middle of the view point (e.g., @cr-poem)
  • How to write a closeread story
      1. Create a closeread section
      • :::{.cr-section}
      1. Flag content as “stickies”
      • :::{#cr-mysticky}
      1. Identify blocks to serve as “triggers”
      • @cr-mysticky
  • Scrollytelling uses spatial cross-references
  • How to closeread images
      1. Focus on your sticky image
      • :::{.cr-sticky}
      1. Pan to coordinates by adding an attribute
      • [@cr-sticky]{pan-to="10%,5%"}
      1. Scale the image by adding an attribute
      • [@cr-sticky]{pan-to="10%,5%" scale-by="2"}
  • Focus effect attributes
    • pan-to: pan across the sticky
    • scale-by: scale the sticky up or down
    • hlz: highlight and zoom to a line
    • highlight: highlight lines or spans
    • zoom-to: zoom to a line
  • Scrollytelling allows the reader to focus on the what instead of the where
  • How to closeread code
      1. Highlight lines of code with highlight="1,3" or highlight="1-3"
      1. Code = Text
  • How to interact with graphics
      1. Span narrative blocks by wrapping with .progress-block div then use the crProgressBlock OJS Variable.
      1. Other variables:
      • crActiveSticky
      • crTriggerIndex
      • crTriggerProgress
      • crDirection
  • Layouts
    • sidebar-left
    • sidebar-right
    • overlay-left
    • overlay-center
    • overlay-right
  • Scrollytelling is a great match for interactive graphics with lots of potential for storytelling in a teaching context and a data journalism context.
  • Ways to use closeread
    • Integrate a closeread section into a data journalism piece.
    • Write a tutorial of a particularly tricky concept or piece of code.
    • Have your students write closeread stories to share their projects.
    • Communicate the central insight of an analysis to company decision-makers.
    • Use it as a guide to your software.

Level Up Your Data Science Skills

Wednesday, Aug 14 1:00 PM - 2:20 PM PDT

Level up! Empowering industry R users with different levels of experience

Session Info
  • Presenter: Seth Copolnix
  • Internal R packages: Why?
    • Reuse code
    • Reduce boilerplate
    • Updating the package updates your code
    • Team members use the same functionality
  • How?
    • Start small and iterate
      • A handful of functions
      • Use code you’ve already written
    • Get your package to build without errors
    • Use your package yourself
    • Involve your teammates
  • Further reading
  • Hosting content on Posit Connect (paid product)
    • Reproducible, scheduleable Rmd/Quarto reports
    • R Shiny dashboards
    • No emailing attachments
    • Teammates see complete examples, with code
  • Culture
    • Maintaining a wiki
      • A website editable by its users
      • Highly discoverable
      • Advertise your contributions
    • Holding office hours to give folks a place to ask for advice

Quarto for Knowledge Management

Session Info
  • Using Quarto to get started with simple, powerful, and fun note-taking/knowledge management
    • Websites
    • Computations
    • Extensions
  • Quarto websites provide structure and variety for minimal effort
    • YAML
      • Listings, TOCs
    • Themes & Custom CSS offer visual variety
    • Search
    • Listings & Search
    • Plain text makes reorganizing simple
  • Quarto computations & extensions
    • Code chunks + {dplyr} + {ggplot2}
    • Code chunks + {glue}
    • Extensions + Javascript: interactive image gallery using Masonry.js & Lightbox.js

Data Science Case Studies

Wednesday, Aug 14 1:00 PM - 2:20 PM PDT

Open Source Software in Action: Expanding the Spatial Equity Data Tool

Session Info
  • Presenter: Gabriel Morrison
  • Online Quarto Book for Documentation
    • Handle code
    • “Home page” for API
    • Handle text
    • Chapter and section references
    • Equation-handling
    • Better hierarchy
  • Example
    • Quarto Book

Data Visualizations: Idea > Process > Sharing

Wednesday, Aug 14 2:40 PM - 4:00 PM PDT

Creating multi-figure visualizations with Patchwork

Session Info
  • Presenter: Thomas Lin Pedersen
  • patchwork R package
    • Concerned with aligning everything because one of its main uses is to create a cohesive single visualization containing multiple plots
  • API-first package design

From idea to code to image: Creative data visualizations in R

Session Info
  • Presenter: Georgios Karamanis
  • Finding inspiration
    • Look at other people’s work
      • Dissect their choices, imitate their style/techniques, remix
    • Try out new packages
    • Sketch before coding
    • Break the rules
    • Try data art
    • Ask a LLM
  • Getting creative with code
    • Look at other people’s code
    • Recreate data visualizations made with other tools
    • Try out different options in ggplot2 functions
      • Try to break things
    • Creative use of geoms
    • Use geom_text()
    • Create your own geoms
    • Use ggplot_build()
    • Participate in challenges (experiment, learn, get feedback)
  • Making it personal
    • Don’t use the defaults (colors, fonts, etc.)
    • Remember accessibility!
    • When in doubt, subtract - simiplicity in design can be highly creative
    • Try new techniques - step out of comfort zones
    • Choose subjects that resonate with you - blend your interests, hobbies, knowledge
    • Always give credit!
    • Keep a list of ideas, packages, code snippets, etc. - don’t wait for inspiration
    • Just do it, creativity shouldn’t be the goal - You can’t be creative all the time

Be Kind, Rewind

Session Info
  • camcorder R package: allows you to preview your visualizations exactly as they will be saved, but also records every plot you create, turning your creative process into a compelling narrative
    • puts into a GIF format
  • Applications
    • Animations
    • Comparisons
    • Creative