11. Sharing research

Communicating research findings

In this recipe, I cover the tools and strategies for sharing research findings with the public and peers. We will begin assuming we are using Quarto websites as the primary tool for sharing research findings in both forums. From there, we will enter into some of the details of articles, presentations, and publishing research code and data.

Concepts and strategies

Public facing communication

R (or Python) research projects that take advantage of Quarto websites have access to a wide range of tools for sharing research. First, the entire research tool chain can be published as a website, which is a great way to share the research process. Second, the website can be used to share the research findings in particular formats including articles and presentations. Let’s focus in on these later formats and discuss strategies for setting up and formatting research articles and presentations.

We will assume the project directory structure in Snippet 1.

Snippet 1: Quarto website structure for reproducible research

project/
  ├── data/
  │   ├── analysis/
  │   ├── derived/
  │   └── original/
  ├── process/
  │   ├── 1_acquire.qmd
  │   ├── 2_curate.qmd
  │   ├── 3_transform.qmd
  │   └── 4_analyze.qmd
  ├── reports/
  │   ├── figures/
  │   ├── slides/
  │   │   ├── workshop/
  │   │   │    └── index.qmd
  │   │   └── conference/
  │   ├── tables/
  │   ├── article.qmd
  │   ├── citation-style.csl
  │   ├── presentations.qmd
  │   └── bibliography.bib
  ├── renv/
  │   └── ...
  ├── _quarto.yml
  ├── index.qmd
  ├── README.md
  └── renv.lock

1

Project root: The root directory for the project.

2

Data directory: The directory for storing data files.

3

Process directory: The directory for storing process files.

4

Reports directory: The directory for storing reports.

5

Figures directory: The directory for storing figures.

6

Slides directory: The directory for storing presentations.

7

Workshop directory: The directory for storing a “workshop” presentation.

8

Workshop presentation file: The file for the “workshop” presentation.

9

Tables directory: The directory for storing tables.

10

Article file: The file for the article.

11

Citation style file: The file for the citation style.

12

Presentations listing file: The file for the presentations listing.

13

References file: The file for the references.

14

Quarto configuration file: The file for the Quarto configuration.

I will also assume the following Quarto configuration file _quarto.yml in Snippet 2.

Snippet 2: Quarto configuration file for reproducible research

project:
  title: "Web project"
  type: website
  execute-dir: project
  render:
    - index.qmd
    - process/1_acquire.qmd
    - process/2_curate.qmd
    - process/3_transform.qmd
    - process/4_analyze.qmd
    - reports/

website:
  sidebar:
    style: "docked"
    contents:
      - index.qmd
      - section: "Process"
        contents: process/*
      - section: "Reports"
        contents: reports/*

format:
  html:
    theme: cosmo
    toc: true

execute:
  freeze: auto

1

Execution directory: The root directory for all execution.

2

Render order: The order in which files are rendered.

3

Sidebar style: The style of the sidebar.

4

Sidebar contents: The contents of the sidebar.

5

Process contents: The contents of the process section.

6

Reports contents: The contents of the reports section.

7

Freeze option: The option for rendering only changed files.

Looking more closely at the directory structure in Snippet 1, let’s focus on the aspects that are shared between articles and presentations. You will notice that the reports/ directory contains a figures/ directory for saving figures, a tables/ directory for saving tables, and a references.bib file for saving references. These are shared resources that can be used in both articles and presentations. In the process directory, you can save tables, figures, and other resources that are generated during the research process that you believe will be useful in commmunicating the research findings. Then, when you create your presentations, you can include the same materials in either format with the same files. If changes are made to the figures or tables, they will be updated in both the article and the presentation(s).

Next, it is worth pointing out some important features that appear in the Snippet 2 configuration file. The execute-dir specifies the root directory for all execution. That is the path to directories and files will be the same no matter from what file the code is executed. The render option specifies the order in which the files are rendered. This is important for ensuring that the research process is executed in the correct order. The files that are executed and rendered for display appear in the website and the style and contents options specify the style and contents of the sidebar, respectively. Another key option is the freeze option under execute. This option specifies that only changed files will be rendered. This helps avoid re-rendering files that have not changed, which can be time-consuming and computationally expensive.

Articles

In the reports/ directory a file named article.qmd appears. This file, which can be named anything, will be the document in which we will draft the research article. This file is a standard Quarto document. However, we can take advantage of some options that we have not seen so far that adds functionality to the document.

In Snippet 3, we see an example of the YAML frontmatter for a Quarto article.

Snippet 3: Quarto article YAML frontmatter

title: "Article"
date: 2024-02-20
author:
  - name: "Your name"
    email: youremail@school.edu
    affiliation: "Your affiliation"
abstract: |
  This is a sample article. It is a work in progress and will be updated as the research progresses.
keywords:
  - article
  - example
csl: citation-style.csl
bibliography: ../bibliography.bib
citation: true
format:
  html: default
  pdf:
    number-sections: true

1

Author information: The author information for the article.

2

Abstract: The abstract for the article.

3

Keywords: The keywords for the article.

4

Citation style: The citation style for the article.

5

Bibliography: The bibliography for the article.

6

Citation: The citation for the article itself.

7

Format: The format for the article.

8

HTML format: The HTML format for the article (for web presentation)

9

PDF format: The PDF format for the article (for printing)

In addition to typical YAML frontmatter, we see a number of new times. Looking at the first three, we see that we can add author information, an abstract, and keywords. These are standard for articles and are used to provide information about the article to readers.

When rendered, the article header information will now contain this new information, as seen in Figure 1.

Figure 1: Appearance of the header format for a Quarto article.

The next two items are the citation style and bibliography. These are used to create and format citations in the article. The citation style is a CSL file that specifies the citation style. You can find a database of various citation styles at the Zotero Style Repository. You can search for a style or by field. Once you find a style you like, you can download the CSL file and add it to your project. The bibliography is a BibTeX file that contains the references for the article. You can create this file (as mentioned before) in a reference manager like Zotero or Mendeley.

Now the citation option is not for references that we have gathered. Rather, it is for generating a citation for the current article. This is useful if someone else would like to cite your article. When the article is rendered, the citation will appear at the bottom of the article, as seen in Figure 2.

Figure 2: Appearance of the citation attribution in a Quarto article.

There are two other features to mention. One is the format option. Since the article is a Quarto document, it can be rendered in multiple formats. The html option ensures that our article is rendered in HTML format as part of the website. However, in addition, we can add a pdf option that will render the article in PDF format. Note that in Figure 1, the pdf option has created an “Other formats” listing on the right side below the table of contents. Clicking this will open the PDF version of the article.

Although not employed in this example, it is also possible to use more extensive format changes with Quarto extensions. Currently, there are various extensions for different journals and publishing houses. For more information and examples, consult the documentation above.

Presentations

In the reports/ directory we can also include presentations and associated slide decks. A popular web-based presentation framework is reveal.js. This framework is used in Quarto to create presentations. In Snippet 1, the slides/ directory contains a directory for each presentation and an index.qmd file within. The index.qmd file contains the presentation content, which we will see soon. To provide a listings page each presentation, the presentations.qmd file contains special YAML instructions to be a listings page.

Let’s first dive into the index.qmd file for a presentation and discuss some of the key features. In Snippet 4, we see a basic example of a Quarto presentation.

Snippet 4: Quarto presentation YAML frontmatter index.qmd

title: "Examle presentation"
date: 2024-02-20
author: "Jerid Francom"
format: revealjs

The YAML frontmatter for a Quarto presentation is similar to that of most Quarto documents. The title, date, and author are all included. The format option specifies that the presentation will be rendered in reveal.js format. When rendered, the presentation the slide deck will be interactive and can be navigated by the user. The slide deck will also be responsive and can be viewed on any device.

In Figure 3, we see an example of a Quarto presentation rendered in reveal.js format. I will discuss some of the key features of the presentation, in the presentation itself.

Figure 3

Peer facing communication

TBD

Check your understanding

1. TRUEFALSE Using Quarto websites for sharing research findings is the only way to meet the requirements of a reproducible research project.
2. Using Snippet 2, what option specifies the order in which files are rendered? execute-dirrendersidebarcontentsfreeze
3. What is the name of the framework that Quarto uses to create presentations?
4. TBD
5. TBD
6. TBD

Lab preparation

TBD