sessions_day2.qmd

---
title: "Sessions (Day 2)"
---

:::{.callout-tip}

## Day 2
* **08/14/2024 | [[GitHub](https://github.com/rstudio/rstudio-conf/blob/master/2024/README.md)]**

:::



### Pour Some Glitter On It: Custom Quarto Outputs

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

#### Report Design in R: Small Tweaks that Make a Big Difference {#sec-typstexample}

:::{.callout-tip}

## Session Info
* Presenter: David Keyes
* [[Slides](https://positconf2024.rfortherestofus.com/slides.html) | [GitHub Repo](https://github.com/rfortherestofus/report-design)]

:::

* 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()`

```{r}
#| echo: true
#| eval: false

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
)
```

```{r}
#| echo: true
#| eval: false

# 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

:::{.callout-tip}

## Session Info
* Presenter: Mine Cetinkaya-Rundel
* [[Slides](https://mine-cetinkaya-rundel.github.io/quarto-books-conf24) | [GitHub Repo](https://github.com/mine-cetinkaya-rundel/quarto-books-conf24)]

:::

* 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
    + 2. Write a .tex file to be appended to the end during render (that includes `\printindex`)
    + 3. 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-alt`s by finding cells that have `ggplot()` but not `fig-alt` using the `parsermd` R package (dev version)
  + [Sim Daltonism](https://michelf.ca/projects/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](https://quarto.org/docs/websites/website-tools.html#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

:::{.callout-tip}

## Session Info
* Presenter: Meghan Hall
* [Text of talk](https://meghan.rbind.io/blog/2024-08-14-quarto-templates/)

:::

* 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

```markdown
#| echo: true
#| eval: false

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

scss file

```{scss}
#| echo: true
#| eval: false

/* 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](https://developer.mozilla.org/en-US/)
* How do I share this?
  + Put it all in an internal package
    + Read [Building a team of internal R packages](https://www.emilyriederer.com/post/team-of-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
    + 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 {#sec-scrollytelling}

:::{.callout-tip}

## Session Info
* Presenter: Andrew Bray

:::

* Example: [A Poem (and a Painting) About the Suffering That Hides in Plain Sight NYT Article](https://www.nytimes.com/interactive/2022/03/06/books/auden-musee-des-beaux-arts.html)
* 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](closeread.netlify.app) | [GitHub](https://github.com/andrewpbray/gg-close-read)
  + 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}`
  + 2. Flag content as "stickies"
    + `:::{#cr-mysticky}`
  + 3. 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}`
  + 2. Pan to coordinates by adding an attribute
    + `[@cr-sticky]{pan-to="10%,5%"}`
  + 3. 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"`
  + 2. Code = Text
* How to interact with graphics
  + 1. Span narrative blocks by wrapping with `.progress-block` div then use the `crProgressBlock` OJS Variable.
  + 2. 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

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

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

:::{.callout-tip}

## 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
  + [R packages](https://r-pkgs.org/)
  + [`devtools`  package](https://cran.r-project.org/web/packages/devtools/index.html)
  + [Field Guide to Writing Your First R Package - posit::conf(2023)](https://youtu.be/-bzgFg_bZXM?si=0xDnzUd0rdv2aiy1)
  + 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

#### Quarto for Knowledge Management

:::{.callout-tip}

## Session Info
* Presenter: Cynthia Huang
* [[Slides](https://github.com/cynthiahqy/positconf2024/blob/main/slides.pdf) | [GitHub Repo](https://github.com/cynthiahqy/positconf2024)]

:::

* 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

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

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

:::{.callout-tip}

## 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](https://ui-research.github.io/sedt_documentation/)
  + Quarto Book



### Data Visualizations: Idea > Process > Sharing

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

#### Creating multi-figure visualizations with Patchwork

:::{.callout-tip}

## Session Info
* Presenter: Thomas Lin Pedersen

:::

* [`patchwork` R package](https://patchwork.data-imaginist.com/)
  + 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

:::{.callout-tip}

## 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

:::{.callout-tip}

## Session Info
* Presenter: Ellis Hughes
* [[GitHub Repo](https://github.com/thebioengineer/posit_conf_2024_be_kind_rewind)]

:::

* [`camcorder` R package](https://cran.r-project.org/web/packages/camcorder/index.html): 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