library(tidyverse)
library(scales)
# Define brand colors as variables
<- "#15397F"
psc_blue <- "#9F3515"
psc_red
# Create a function (call-out numbers using ggplot)
<- function(value, text, value_color) {
big_number_plot 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
)
Sessions (Day 2)
Day 2
- 08/14/2024 | [GitHub]
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
- Presenter: David Keyes
- [Slides | GitHub Repo]
- 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.)
- report.qmd -> typst-show.typ -> typst-template.typ -> report.pdf
- typst overall process:
- 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 - useupdate_geom_defaults()
# Use brand fonts in plots
## Make a custom theme
<- function() {
theme_psc 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
- Presenter: Mine Cetinkaya-Rundel
- [Slides | GitHub Repo]
- 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
)
- HTML: pull in .scss file (
- “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{}
\index{}
tags
- Write a .tex file to be appended to the end during render (that includes
\printindex
)
- Write a .tex file to be appended to the end during render (that includes
- Include that file in Quarto YAML (
include-after-body: latex/after-body.tex
)
- Include that file in Quarto YAML (
- 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
- Today
- Accessibility check
- Use
fig-alt
for alternative text- Check for missing
fig-alt
s by finding cells that haveggplot()
but notfig-alt
using theparsermd
R package (dev version)
- Check for missing
- Sim Daltonism: Open source tool that will put a color filter on your screen to check for color accessibility on the fly
- Use
- Set global options with
_common.R
- Leverage your R knowledge to achieve consistent output
set.seed(1014)
knitr::opts_chunk$set()
options()
# R optionsggplot2::theme_set()
# set theme and base size
- Leverage your R knowledge to achieve consistent output
- 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
- With
- 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
- Avoid
- Leveraging GitHub actions
- 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
- Use
- Productivity with
freeze
- Two languages in one .qmd file each being executed with their own engine
Designing and Deploying Internal Quarto Templates
Session Info
- Presenter: Meghan Hall
- Text of talk
- 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
- Use DevTools to see skeleton of the page:
- How do I share this?
- Put it all in an internal package
- Read Building a team of internal R packages for the utility of packages
- 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
- The files to copy (templates, images, logos) in a folder (e.g.,
- What this function does
- Creates an _extensions folder
- Copy over the files from inst.
- Create new .qmd file from the file name argument
- 2 things
- Put it all in an internal package
- 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"}
)
- Fenced Div (
- 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"}
)
- Add “focus effects” by specifying with a bracketed span where we want to highlight and zoom (e.g.,
- 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
)
- Sticky: Wrap content in a fenced div; prefix that ID with cr- (e.g.,
- A quarto extension that enables scrollytelling to study text, study images, study code for a stronger, more focused narrative
- How to write a closeread story
- Create a closeread section
:::{.cr-section}
- Flag content as “stickies”
:::{#cr-mysticky}
- Identify blocks to serve as “triggers”
@cr-mysticky
- Scrollytelling uses spatial cross-references
- How to closeread images
- Focus on your sticky image
:::{.cr-sticky}
- Pan to coordinates by adding an attribute
[@cr-sticky]{pan-to="10%,5%"}
- Scale the image by adding an attribute
[@cr-sticky]{pan-to="10%,5%" scale-by="2"}
- Focus effect attributes
pan-to
: pan across the stickyscale-by
: scale the sticky up or downhlz
: highlight and zoom to a linehighlight
: highlight lines or spanszoom-to
: zoom to a line
- Scrollytelling allows the reader to focus on the what instead of the where
- How to closeread code
- Highlight lines of code with
highlight="1,3"
orhighlight="1-3"
- Highlight lines of code with
- Code = Text
- How to interact with graphics
- Span narrative blocks by wrapping with
.progress-block
div then use thecrProgressBlock
OJS Variable.
- Span narrative blocks by wrapping with
- 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
- Start small and iterate
- Further reading
- R packages
devtools
package- Field Guide to Writing Your First R Package - posit::conf(2023)
- Posit Package Manager
- Can host your package on Posit Package Manager (paid service)
- 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
- Maintaining a wiki
Quarto for Knowledge Management
Session Info
- Presenter: Cynthia Huang
- [Slides | GitHub Repo]
- 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
- YAML
- 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
- Look at other people’s work
- 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
- Presenter: Ellis Hughes
- [GitHub Repo]
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