Yet preparing replication materials can be daunting, especially for researchers new to data science. It is not uncommon for scholars to struggle to reproduce even their own results, due to issues such as disorganized code and data, software version mismatches, missing random seeds, or differences in operating systems and platforms. While some of these challenges are complex, many reproducibility problems stem from preventable organizational issues. Structuring code and data in a clear, consistent, and tool-friendly manner can significantly reduce these difficulties — and brings additional benefits at virtually no cost, including smoother collaboration and easier integration with AI tools.

In this post, I’ll walk through the project structure I use in my own research. It has evolved over time and reflects what I currently consider best practice for reproducible academic work. Adopting a clear structure from the outset makes it significantly easier to reproduce results, onboard collaborators, and maintain projects over the long term.

The structure covers the full research lifecycle: from data cleaning and analysis to manuscript preparation and presentation. The template is built around R and Quarto (the successor to R Markdown), but the underlying principles translate easily to Python and other publishing workflows, including LaTeX. For convenience, I’ve created a ready-to-use template on GitHub that you can clone and adapt for your own projects.

The project structure looks like this:

I’ll now break down each component in turn, explaining the purpose of the key folders and files, and the reasoning behind the design.

Git and GitHub

One major threat to reproducibility is a file named latest_final_v3_definitive.R. While this naming convention feels natural during exploratory analysis—especially under deadline pressure—it quickly becomes impossible to reconstruct what actually changed, when, and why. Future-you (and your collaborators) will not be grateful.

Version control systems like Git solve this problem by recording a structured history of changes through commits. Instead of creating new files for every iteration, you preserve a single evolving project with a transparent timeline. This makes it easy to revisit earlier versions, understand how results evolved, and collaborate without overwriting each other’s work.

GitHub builds on this by providing a shared platform for hosting repositories, reviewing changes, managing issues, and coordinating collaboration. It also makes it very clear who introduced a particular change—an accountability feature that tends to concentrate the mind when committing code.

In the example project structure, several files and folders are Git-related:

.git/ (invisible folder created by Git)
.gitignore
*.gitattributes
*/
└── .gitignore

The .git/ folder is created automatically when you initialize a repository. It contains the full version history and metadata of the project. You generally do not need to interact with it directly—just avoid modifying or deleting it.

The .gitignore file specifies which files and folders should be tracked or ignored by Git. Since all changes to tracked files are recorded in the project history, a useful rule of thumb is to track only what is necessary to reproduce your results. Files that can be regenerated from code—such as intermediate data, plots, tables, or compiled PDFs—are often better ignored to keep the repository clean and lightweight.

The .gitattributes file defines additional rules for how Git should handle specific file types. Compared with .gitignore, it appears less often in many repositories, but it is especially useful when you need file-type-specific behavior. In particular, large raw data files (e.g., large .csv files) and binary formats (such as .rds, .RData, or images) can significantly increase repository size if tracked directly. In these cases, Git Large File Storage (Git LFS) can be used to store the actual files separately, while keeping lightweight pointer files in the main repository history.

Data directories

I use two separate folders to store raw (data_raw/) and cleaned data (data_processed/). Keeping these distinct makes the workflow more transparent: the original data remains untouched, while processed data can be saved in a format that is fast to load during analysis.

This structure also aligns with common journal expectations that replication code should be able to reproduce results starting from the raw data. By preserving raw inputs and separating preprocessing steps, you make the transformation pipeline explicit rather than implicit.

data_raw/
└── *.csv (tracked through Git LFS)

data_processed/
├── *.rds (not tracked in Git)
└── .gitignore

In the template, the example raw data file (data_raw/Brexit.csv) is tracked using Git LFS. While the file itself is neither large nor binary (unlike formats such as .dta or .rds), LFS is used here for demonstration purposes. In real-world research projects, raw datasets are often substantial in size, and setting up LFS early helps avoid repository bloat later on.

The data_processed/ folder contains the cleaned dataset in .rds format, along with a .gitignore file that excludes all files in this folder (except the .gitignore file itself) from version control. This design encourages regeneration of cleaned data from raw inputs via code, rather than relying on previously saved intermediate objects. It also helps keep the repository lightweight.

The .rds format is used for several reasons. First, it is a native R format that preserves data types and attributes faithfully. Second, it encourages the use of RDS over .RData. Unlike .RData, which loads all stored objects into the global environment under their original names, .rds files require explicit assignment when loaded. This reduces the risk of unintentionally overwriting existing objects and promotes more transparent workflows.

Finally, the .gitignore file inside data_processed/ serves an additional purpose: it ensures that the folder itself is tracked by Git. Since Git does not record empty directories, this placeholder guarantees that the directory exists when the project is cloned. This is important because saving cleaned data to a non-existent directory will otherwise result in an error in R.

For researchers working with confidential or restricted data, it is often helpful to separate sensitive materials from those that can be shared publicly. In some cases, this may mean maintaining a private repository during the research phase and preparing a separate public-facing repository upon publication.

Importantly, simply deleting confidential files before making a repository public is not sufficient. Git preserves the full commit history, meaning sensitive data may still be accessible in earlier revisions. Creating a fresh repository that contains only the materials intended for public release—such as replication code and non-sensitive data—helps prevent unintended data leakage.

This approach also makes it easier to curate a clean, well-documented version of the project specifically designed for replication and reuse.

Code organization and outputs

code/
├── 1_data_cleaning.R
├── 2_descriptive.R
└── 3_main_analysis.R

outputs/
├── *.rds (not tracked in Git)
└── .gitignore

The code/ folder contains all scripts related to data processing and analysis. In the template, these are written in R, but the same structure works equally well for Python scripts (.py), notebooks (.ipynb), or other programming languages.

A key principle is to prefix scripts with numbers and descriptive names that reflect the research workflow: data cleaning, descriptive analysis, and then inferential analysis. If the logical order of steps is unclear, following the sequence in which results appear in the manuscript is often a reliable guide. This makes the analytical pipeline explicit and allows others (and future-you) to reproduce results step-by-step.

Each script should include a header section with basic metadata about its role in the project. This may include the paper title, authors, purpose of the script, input files, and output files. Making inputs and outputs explicit helps clarify dependencies and encourages scripts that transform data rather than rely on objects lingering in the global environment.

Below is an example of an analysis script (code/3_main_analysis.R) I used in the template that follows these principles:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

######## INFO ########

# PROJECT
## Paper: YOUR PAPER TITLE
## Authors: YOUR NAME

# R Script
## Purpose: This script performs linear regression analysis.
## Inputs: data_processed/Brexit.rds
## Outputs: outputs/regression_table.rds

# Setup ----

library(tidyverse)
library(here)
library(modelsummary)

i_am("code/3_main_analysis.R") # helps with relative paths

# Read in the cleaned data ----

brexit_data <- read_rds(here("data_processed/Brexit.rds"))

# Main analysis ----

model <- lm(leave ~ turnout + income + noqual, data = brexit_data)

# Output the model summary ----

reg_table <- modelsummary(model, stars = TRUE, output = "latex")
write_rds(reg_table, here("outputs/regression_table.rds"))

Two additional tips are worth noting. First, the # SECTION ---- syntax creates collapsible sections and structured outlines in RStudio and the Positron IDE. This makes longer scripts significantly easier to navigate and encourages more intentional organization of code.

Second, managing working directories is a seemingly basic task that is frequently mishandled—especially in collaborative projects. In RStudio, the recommended approach is to work within an .Rproj file, which defines a project root and ensures that relative paths behave consistently across machines. However, in many academic settings (including political science), this practice is not systematically taught. As a result, it is still common to see replication files from top journals that begin with something like setwd("~/Path/To/Project"), often commented out with the expectation that collaborators will manually adjust it.

This approach is fragile. It assumes a specific directory structure on every machine and introduces hidden dependencies on local file paths. Code that depends on setwd() is difficult to port, share, or automate.

Positron improves this situation by automatically setting the working directory to the folder opened in the IDE, encouraging a project-level workflow by default. However, many users carry over the habit of opening individual scripts rather than entire project directories.

The here package provides a robust solution that avoids reliance on the working directory altogether. By anchoring a script to the project root using here::i_am() and constructing paths with here(), file references become explicit and portable. This ensures that scripts run consistently across machines, IDEs, and collaboration environments—regardless of local directory structures.

The outputs/ folder complements this approach by providing a dedicated location for all results generated by the code. This includes intermediate objects (e.g., fitted models) and final products (e.g., tables and figures). If intermediate artifacts become numerous, they can be stored in a separate objects/ folder. The accompanying .gitignore file ensures that these generated files are not versioned, reinforcing the principle that results should be regenerated from code rather than preserved as static artifacts.

Virtual environments and dependencies (renv)

Many R users do not update their R or package versions regularly. In practice, the version in use is often determined by when the researcher first learned R—or when the machine was purchased, whichever is later. Deprecation warnings are politely ignored as long as the code continues to run.

The problem only becomes visible when code that worked perfectly on your old machine suddenly fails on a new machine—or worse, on a collaborator’s machine. At that point, dependency management stops being an abstract concern and becomes a very practical one.

A common solution to this problem is the use of virtual environments, which capture the exact package versions used in a project—a concept long established in the Python ecosystem. In R, the renv package provides a convenient way to create and manage project-specific libraries. Package versions remain fixed within the project, independent of updates to the global R installation or differences across collaborators’ machines.

The state of the environment is recorded in the renv.lock file, which is committed to Git. This file serves as a snapshot of the project’s dependency graph at a given point in time, including package versions and their sources. As a result, the same software environment can be reproduced on any machine with a simple call to renv::restore().

Three key components related to renv appear in the template structure:

renv/
.Rprofile
renv.lock

The renv/ folder contains the project-specific package library. Most of its contents are not tracked in Git, since the environment can be regenerated from the information stored in renv.lock. Additionally, some packages include compiled C or C++ code that is platform-specific, meaning those installed binaries are not portable across operating systems.

The .Rprofile file includes a line that automatically activates the renv environment when the project is loaded, ensuring that the correct package versions are used without manual setup.

Automatic activation, however, only works when the project is opened as a whole—for example, by opening the .Rproj file or the project folder in Positron. If individual scripts are opened in isolation, the working directory will not be set to the project root at startup, and the project-level .Rprofile will not be executed. This is yet another reason to adopt a project-level workflow rather than treating scripts as standalone files.

Quarto: manuscripts and presentations

The most visible stage of the research lifecycle is the dissemination of results—through manuscripts, presentations, and other public outputs. For quantitatively oriented researchers (which, if you have read this far, likely includes you), producing well-formatted documents that do justice to your carefully constructed tables and figures is essential.

Quarto is an open-source scientific and technical publishing system built on Pandoc. I use it for all of my manuscript writing and presentation slides, and I recommend it for researchers working in R, Python, or Julia. The template presented here is deliberately centered around Quarto, and in what follows I will briefly explain the reasoning behind that choice.

Why Quarto?

What makes Quarto stand out is its ability to run R, Python, or Julia code directly within a document, seamlessly integrating analysis and writing. Tables, figures, and results can therefore be generated and updated automatically as the underlying code changes, ensuring that the manuscript always reflects the current state of the analysis.

Quarto is not a replacement for output formats such as HTML, Microsoft Word, LaTeX, or Typst. Rather, it acts as a unifying layer that can render the same .qmd source file into multiple formats simultaneously. This flexibility allows format decisions to be postponed and adapted to collaborators, institutions, or journal requirements.

Beyond manuscripts, Quarto also supports presentation formats and full websites. Learning a single tool therefore enables the production of academic papers, conference slides, and project or personal websites within a consistent workflow.

While these capabilities may sound familiar to experienced R Markdown users, I would still argue that Quarto is worth trying—even for those already comfortable with R Markdown—for four main reasons:

1. Language-agnostic support: Quarto is designed to work seamlessly with multiple programming languages (R, Python, Julia). A document can be executed using the native engine for each language—for example, a Python-only document runs through a Jupyter kernel without requiring R¹, which is more friendly to non-R users.

2. Native support for extended features: Quarto includes built-in support for cross-referencing, citations, and advanced formatting without requiring additional packages or complex configurations. In contrast, R Markdown often relies on extensions such as bookdown to achieve similar functionality, which introduces additional dependencies. In practice, many students are taught only the basic R Markdown setup and may not be aware of these extensions. Quarto provides these features out of the box.

3. More scannable code cell/chunk options and syntax: R Markdown users may be familiar with setting document-wide execution options inside a setup chunk using knitr::opts_chunk$set(...), and specifying chunk options inline in a comma-separated format. While functional, this approach can become difficult to scan and maintain in larger documents.

   1 2 3 4 5 6 7

   ```{r} knitr::opts_chunk$set(echo = FALSE, message = FALSE, warning = FALSE, error = FALSE) ``` ```{r barplot, fig.cap='Bar plot for y by x.', fig.height=3, fig.width=5} # code for the bar plot ```

   In Quarto, document-level execution options are defined declaratively in YAML, while cell-level options use a multi-line, command-style syntax. This makes both levels of configuration easier to scan, and typically easier to review in diffs and modify.

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   ```yaml execute: echo: false warning: false error: false message: false ``` ```{r} #| label: fig-barplot #| fig-cap: 'Bar plot for y by x.' #| fig-height: 3 #| fig-width: 5 # code for the bar plot ```

4. Centralized documentation: While R Markdown benefits from a large community and extensive online resources, its documentation is distributed across multiple sites². Quarto, by contrast, maintains a single, comprehensive documentation portal that covers core usage and advanced features in one place, making it easier to navigate and learn systematically.

Quarto project structure

The remaining components of the template are primarily related to Quarto. Below, I break down the key elements and explain the reasoning behind their organization.

_extensions
.quarto (created by Quarto; not tracked in Git)
extras/
manuscript/
├── manuscript.pdf (not tracked in Git)
└── manuscript.qmd
slides/
├── slides.pdf (not tracked in Git)
└── slides.qmd
_quarto.yml

Configuration file

The _quarto.yml file serves two main purposes.

First, it defines project-level execution behavior. In particular, the following setting ensures that code is executed relative to the project root, regardless of where individual .qmd files are located:

1
2

project:
  execute-dir: project

This provides an additional layer of protection for resolving relative paths correctly. Used together with the here package, it helps ensure that file paths behave consistently across different machines and execution contexts.

Second, _quarto.yml centralizes shared configuration options so they do not need to be repeated in each individual .qmd file. This reduces duplication, minimizes the risk of inconsistencies, and improves readability across documents.

In the template, shared options include the bibliography file and citation style:

1
2

bibliography: extras/references.bib
csl: extras/apa.csl

Because these settings are defined at the project level, they apply automatically to both the manuscript and presentation slides.

Extras: bibliography and citation styles

As mentioned above, the extras/ folder contains the bibliography file (references.bib) and citation style file (apa.csl). These are referenced in the _quarto.yml configuration file, which means they are automatically available to all .qmd files in the project without needing to specify them individually.

extras/
├── references.bib
└── apa.csl

Ideally, if you have other supplementary materials that are not part of the core code or data but are still relevant to the project (e.g., codebooks), they could also be stored in this folder. However, I have kept it focused on bibliography-related files for simplicity.

Bibliography file

The references.bib file is a standard BibTeX/BibLaTeX bibliography file familiar to LaTeX users. It contains structured reference entries, including fields such as author, title, journal, year, and other publication metadata.

Entries can be exported from reference managers such as Zotero or Mendeley, or generated directly within Quarto using the Visual Editor. Crucially, the bibliography file is kept separate from both the manuscript and the citation style. This separation allows the same reference database to be shared across manuscripts and slides, while making it easy to change formatting styles without modifying the source content.

Citation style file

The apa.csl file is a Citation Style Language (CSL) file that defines how citations and bibliography entries are formatted. It acts as a translation layer between the structured data in references.bib and the rendered output format.

In this template, the CSL file specifies APA style, which is common in the social sciences. However, switching styles is straightforward: replace the apa.csl file with another CSL file (e.g., Chicago, MLA, or a journal-specific style) and update the reference in _quarto.yml. No changes to the manuscript text are required.

To find a CSL file for a specific discipline or journal, you can browse the CSL Style Repository , which contains thousands of maintained styles.

Manuscript

Dissemination of research findings is the ultimate goal of the research process, and the manuscript remains its primary vehicle.

manuscript/
├── manuscript.pdf (not tracked in Git)
└── manuscript.qmd
_extensions/
└── kv9898/
    └── orcid/

The manuscript/ folder contains the Quarto source file (manuscript.qmd) and the compiled PDF output (manuscript.pdf). As with other generated artifacts, the PDF is excluded from version control because it can always be regenerated from the source document.

The example manuscript.qmd provides a minimal template illustrating a typical academic structure, including numbered sections, figures, tables, cross-references, and citations. The template is intentionally simple but can be extended with additional formatting and structural elements as needed.

While Quarto’s built-in PDF format supports core elements such as title, authors, date, and abstract, more specialized academic requirements—such as detailed affiliation formatting, ORCID display, keywords, custom headers, or journal-style front matter—often require additional customization.

To address this, I created a custom extension that builds on the default PDF format and adds features commonly required in academic manuscripts. The extension is included in the template under _extensions/kv9898/orcid/.

Packaging the manuscript format as a Quarto extension ensures that formatting logic is versioned and shared alongside the project, rather than maintained as ad hoc local tweaks. The extension is activated via the YAML front matter of manuscript.qmd:

1
2

format:
  orcid-pdf:

The resulting PDF output more closely resembles a conventional academic paper, with structured author information, affiliations, ORCID identifiers, and keywords clearly presented. Because the template is implemented as a Quarto extension, it remains portable and reusable across projects, and can be further modified, particularly by those comfortable with LaTeX, to accommodate journal-specific formatting requirements.

Slides

Researchers often need to present their findings at conferences, seminars, or in teaching settings. Quarto supports multiple presentation formats, including Reveal.js, Beamer, and PowerPoint. In this template, I use Beamer to produce PDF slides, which are widely accepted in academic contexts and easy to share or print.

slides/
├── slides.pdf (not tracked in Git)
└── slides.qmd

The slides/ folder contains the Quarto source file (slides.qmd) and the compiled PDF output (slides.pdf). As with the manuscript, the PDF is treated as a generated artifact and excluded from version control.

The resulting slides are indistinguishable from those produced using a traditional LaTeX Beamer workflow. The key difference is that all content—including code, tables, and figures—can be generated directly from the same analytical pipeline.

In this example, I deliberately reuse the same output objects (e.g., tables and figures) in both the manuscript and the slides. This guarantees consistency across formats and eliminates the risk of discrepancies between what appears in the paper and what is presented publicly.

The example slides also demonstrate practical considerations such as resizing tables and figures to fit slide layouts. They reference the same shared bibliography file used in the manuscript, ensuring consistent citation formatting across outputs. Although only a single reference is included in the example, the template is configured to allow references to span multiple frames, accommodating a realistic bibliography.

README file

README.md

Following both GitHub conventions and academic best practice, every project should include a README.md file. This file serves as the primary entry point for others who wish to understand, reproduce, or build upon the research.

In the template, the README provides:

• A brief project description
• Instructions for setting up the environment
• Steps to reproduce the analysis, manuscript, and slides

Additional placeholders are included for information such as the machine model and operating system used during development. While not always necessary, this metadata can be helpful when troubleshooting platform-specific issues, particularly for projects involving compiled dependencies. The README also notes the approximate time required to run the full analysis and render outputs, which helps set realistic expectations for replication.

Notably, the template does not include a LICENSE file by default. This is intentional. The appropriate license for academic code and data depends on disciplinary norms, institutional policies, journal requirements, and the researcher’s intended level of openness. Common choices include MIT or GPL licenses for code, and Creative Commons licenses for data. In some cases, more restrictive or custom licenses may be appropriate. Researchers should select a license deliberately, ensuring it aligns with their sharing goals and complies with relevant policies.

GitHub as infrastructure — not just hosting

Once a project is structured clearly and pushed to GitHub, it becomes more than a collection of files. It becomes infrastructure.

A well-organized repository makes collaboration dramatically smoother. Issues can serve as lightweight meeting minutes, evolving naturally into task lists. They can be assigned to specific contributors, grouped into milestones, and tracked over time. Pull requests and branching strategies help keep the main branch stable while allowing experimentation and iterative refinement. Code reviews become part of the workflow rather than an afterthought.

These practices, borrowed from software development, translate surprisingly well into academic collaboration. Instead of emailing attachments back and forth, collaborators work against a shared, versioned source of truth.

A clear project structure also makes modern AI tools significantly more useful. When your data, scripts, outputs, and manuscripts are logically organized, AI assistants in VS Code, Positron, or GitHub can reason about your project more effectively. They can trace how tables were generated, suggest improvements to analysis code, help refine writing based on the underlying results, or flag inconsistencies between figures and text. In other words, organization enables context — and context is what makes AI assistance meaningful rather than superficial.

There are also practical benefits. Once your work is version-controlled and backed up remotely, you no longer fear data loss due to a failed hard drive, a stolen laptop, or accidental overwrites. The repository itself becomes a durable record of the project’s evolution.

Perhaps most importantly, a well-structured project reduces the asymmetry of knowledge among collaborators. Instead of each co-author being familiar with only one portion of the workflow, everyone can develop a holistic understanding of how the project fits together — from raw data to final manuscript. This makes feedback more constructive, collaboration more efficient, and the research process more transparent.

Reproducibility, then, is not merely about satisfying journal requirements. It is about building research projects that are resilient, collaborative, and adaptable — projects that scale not only across machines, but across people.

Conclusion

At its core, none of the tools discussed here—Git, renv, Quarto, or GitHub—are revolutionary on their own. What matters is how they are combined into a coherent project structure. Once that structure becomes habitual, reproducibility stops being an afterthought and becomes the default.

Adopting this workflow does not require perfect foresight or advanced technical expertise. It simply requires deciding, from the outset, that clarity, versioning, and regeneration will guide the project. The payoff is substantial: fewer replication headaches, smoother collaboration, better integration with modern tooling, and greater confidence in the durability of your work.

In the long run, a well-structured project is not just easier to reproduce—it is easier to think with.

Welcome to the first edition of our Positron newsletter! Here, we will share highlights from our latest release, tips on how to be more productive with Positron, and useful resources.

We just returned from an in-person onsite in beautiful Monterey, California. During the trip, we got a chance to meet (some of us for the first time), touch grass and sand, and brainstorm ways we can improve to build better products for you.

Let’s get into the updates.

Key Product Updates

The April 2026 release of Positron brings significant improvements across:

• Positron Server for Academic Use via JupyterHub
• AI enhancements : Next Steps in Jupyter Notebooks, Agent Skills, and Azure AI Foundry Support
• Telemetry updates
• R improvements : Addins, Debugging, and more
• Data Explorer Performance Improvement
• Windows ARM in GA
• What’s Coming Next : Inline Outputs, Packages Pane, and Posit Assistant

Here’s a look at the key features that shipped with the April 2026 release.

Positron Server for Academic Use via JupyterHub

What we built: Academic institutions can now offer Positron Server to their students at no cost through JupyterHub ( blog post ). If your institution already runs JupyterHub, you can add Positron as a launcher option alongside JupyterLab, with no additional infrastructure required. Students simply log in and select Positron from the launcher, getting the full Positron experience including rich Python and R support, the extension marketplace, and (optionally) Positron Assistant.

Why this matters: This removes the barrier for students and educators who want to use Positron in a classroom setting. No local installs, no configuration headaches — just a familiar JupyterHub login with Positron ready to go.

Get started: Review the eligibility criteria and send an email to academic-licenses@posit.co to request a free teaching license.

AI Next Steps in the Native Jupyter Notebook Editor

What we built: AI Next Steps uses the Positron Assistant to analyze your current cell output and suggest a logical next step in a “ghost cell” at the bottom of your notebook. If you just loaded a CSV, it might suggest data cleaning steps or a visualization, without you needing to open a chat pane or write a prompt. Suggestions stay aligned with the notebook’s live kernel state, updating as your code and outputs change.

Why this matters: The design came out of interviews with data scientists who kept telling us the same thing: switching to a chat pane mid-analysis breaks their concentration. AI Next Steps sits at the bottom of your notebook and updates as your outputs change. You just run a cell, and if there’s a logical next step, it surfaces, with no prompt required.

Get started: Enable the feature by setting positron.assistant.notebook.ghostCellSuggestions.enabled to true in your settings. When you run a cell, look for the ghost cell suggestion at the bottom of the notebook, accept, reject, or hide it.

Agent Skills in Positron Assistant

What we built: Agent skills — reusable, structured capabilities that extend what agents can do in agent.md files — are now integrated into Positron ( #11753 ). Skills let agents execute multi-step workflows like “profile this dataset and suggest cleaning steps” or “run this test suite and summarize failures,” so you define a task once and reuse it across sessions and projects.

Why this matters: Skills make agents composable building blocks rather than one-off chat interactions. Instead of re-explaining a complex workflow every time, you codify it as a skill that any team member can use.

Get started: Open the chat gear icon and select Skills, or run Chat: Configure Skills from the Command Palette.

Positron Assistant Now Supports Microsoft Foundry as a Provider

What we built: Positron Assistant now supports Microsoft Foundry as a model provider ( #8583 ) with API key-based access via a custom base URL.

Why this matters: If your team runs on Azure and uses LLMs through Foundry, you can now use Positron Assistant with them.

Get Started: In Positron Assistant’s provider settings, set positron.assistant.provider.msFoundry.enable to true to select Microsoft Foundry as a provider. You can authenticate with an API key and your Foundry endpoint URL.

Telemetry Update: Anonymous Session Identifiers

What we changed: Positron now generates an anonymous, random session identifier to help us understand usage patterns like session frequency and retention across releases. This identifier contains no personal information, account data, or workspace content; it’s a cryptographically random UUID that cannot be linked to any other identifiers, including the identifier that VS Code uses for telemetry.

Why we’re doing this: As a free, source available project, we don’t have traditional product analytics. Understanding whether people come back, how often they use Positron, and whether releases improve or regress the experience helps us prioritize the right work to build a better experience for you.

You can opt out by updating your settings outlined here , or you can reset the anonymous identifier with the command Preferences: Reset Anonymous Telemetry ID. If you’ve opted out of product updates, no session identifier is generated or sent.

RStudio Addins Support

What we built: Positron now supports running RStudio addins from R packages. If a package registers an addin (like styler, reprex, clipr, or shinyuieditor), you can run it directly from Positron ( #1313 ).

Why this matters: This was one of our most upvoted issues this release (25 👍). Many R users rely on addins as part of their daily workflow for code formatting, generating reproducible examples, or launching Shiny tools.

Get started: Open the Command Palette (Ctrl-Shift-P (windows), Ctrl-Shift-P (linux), Command-Shift-P (mac)) and search for Run RStudio Addin. You’ll see a quick pick with all available addins from your installed packages.

R Debugger & Workflow Improvements

What we built: The R debugger received a suite of improvements this release. In addition to conditional breakpoints, hit count breakpoints, and log breakpoints ( #12360 ), the debugger now supports error and warning breakpoints ( #11797 ), the ability to pause R at any time ( #11799 ), Watch Pane support ( #1765 ), and synchronization between the Console and Variables pane with the selected call stack frame ( #3078 and #12131 ).

Why this matters: Advanced debugging in R has traditionally meant scattering if (...) browser() calls through your code or setting options(error = recover) by hand. These new features put Positron’s R debugger on par with what you’d expect from any modern language:

• Conditional, hit count, and log breakpoints let you control exactly when breakpoints fire and print diagnostic info, all without touching your source code.
• Error and warning breakpoints drop you into the debugger the moment an error or warning is emitted, so you can inspect the state that caused it.
• Pause R at any time. If R is stuck in a long computation or an infinite loop, you can drop into the debugger mid-execution, look around, and resume by clicking Continue.
• Watch Pane lets you track expressions across debug steps. Prefix an expression with /print to see R’s printed output (hover to get full output) instead of a structured variable.
• Synchronization with the call stack. Click any frame in the Call Stack view and the Console, completions, and Variables pane all switch to that frame’s environment. The Console synchronization is like recover(), but built into the IDE.

Get started: Set a breakpoint in any R file, then right-click it and choose Edit Breakpoint. Select “Expression” to add a condition (e.g., i > 100), “Hit Count” to break after N hits, or “Log Message” to print a message without pausing. For error and warning breakpoints, open the Breakpoints pane and enable them there. To pause R while code is running, use the command Debug: Pause or check the Interrupt breakpoint option in the Breakpoints pane. While debugging, add expressions in the Watch section of the debug sidebar and click on frames in the Call Stack to navigate environments.

Data Explorer: Faster with Multiple DataFrames

What we built: We fixed two long-standing performance issues in the Data Explorer. Background Data Explorer tabs no longer trigger backend recomputation, and the summary panel no longer recalculates summary statistics for large DataFrames on every cell execution ( #4279 and #2795 ).

Why this matters: If you work with multiple DataFrames open, you may have noticed lag as Positron recomputed statistics for tabs you weren’t even looking at. That’s gone now.

Get started: Nothing to configure. When you open multiple DataFrames in the Data Explorer and switch between them, you should notice snappier performance, especially with large datasets.

Windows ARM Is Generally Available

What we built: We started creating experimental builds for Windows ARM several months ago, and our early users have had good experiences with them. This release, we promoted the Windows ARM builds from experimental to stable and they are now available through all standard installation channels ( #12207 ).

Why this matters: ARM-based devices are increasingly common for Windows users, whether you’re a student or a professional. GA support means these users get the same Positron experience, including Quarto with R and Python support, without needing workarounds or experimental builds. Do be aware that the Windows ARM build bundles the non-ARM version of Quarto, which runs under emulation.

Get started: Install Positron on your ARM-based Windows device through standard installation channels .

View all issues in the 2026.04.0 Release milestone .

What’s Coming Next

We are currently building the following features and we’d love your feedback. Please share on GitHub . These early alpha features with some rough edges are available for testing by enabling their respective settings.

Inline Outputs for Quarto and R Markdown Files

This was the second most upvoted issue we have ever, ever had! We just completed an initial run to allow displaying inline outputs within Quarto and R Markdown files ( #5640 ), and it is available for early testing. Note that this experimental version, while it does get the basics into Positron, does not have support for many popular RStudio features. You can opt in to the experimental feature using the positron.quarto.inlineOutput.enabled setting.

Packages Pane for Managing Environments

We are currently building out a new Packages pane that will allow you to install, update, and uninstall packages without leaving your workspace or needing to use the terminal ( #11214 ). We’d love to hear your feedback on this discussion thread .

Events and Resources

Explore Positron’s Video Walkthroughs on YouTube

We hosted a walkthrough of exploring GitHub data in a Jupyter Notebook and converting this into an interactive Shiny app with AI. Catch up on the recording or explore more Positron videos .

Registration for posit::conf(2026) Is Now Open!

Registration is officially open for posit::conf(2026)! Join the global data community in Houston or tune in online from September 14–16. Register today!

How We Chose a Python Type Checker

Ever wondered about the decision making process behind how we chose which Python type checker to bundle in Positron? Check out Austin Dickey’s blog post walking through his research and decision making process.

Community Affirmations

Thank you all for your support, ideas and engagement. We’re building Positron in the open because the best ideas come from the people using it. If there’s a feature you’d love to see, open an issue or upvote an existing one, it genuinely shapes what we work on next.

Have a great April!

Positron Team

The open-source Python type checker and language server ecosystem has exploded. Over the past year or two, four language server extensions have appeared, each with a different take on what Python type checking should look like. We evaluated each of them to decide which one to bundle with Positron to enhance the Python data science experience.

Background

The Language Server Protocol (LSP) is a cross-language, cross-IDE specification that allows different IDE extensions to contribute smart features like tab completions, hover info, and more. The four¹ Python extensions in this post are powered by type checkers, which are Python-specific tools that catch bugs in your code before runtime by guessing and checking the types of your variables. They do this by statically analyzing your code before you run it.

With AI tools writing more of your code, a good language server helps you read and navigate code you didn’t write. LLM-generated code also introduces bugs that type checkers catch before you run anything. For data scientists, who rely on code to be the reproducibility layer, and who can’t automate away human judgment, what matters is a tool that helps you understand and trust your code.

We did this evaluation in November 2025 but have refreshed the data in this post at the time of publish.

The contenders

Pyrefly is Meta’s successor to Pyre. It takes a fast, aggressive approach to type inference, being able to catch issues even in code with no type annotations. It reached beta status in November 2025.

ty is from Astral, the team behind uv and ruff. OpenAI announced its acquisition of Astral recently; Astral has stated that ty, ruff, and uv will remain open source and MIT-licensed. It’s the newest project, with a focus on speed and tight integration with the Astral toolchain. It reached beta status in December 2025 and follows a “gradual guarantee” philosophy (more on that below).

Basedpyright is a community fork of Microsoft’s Pyright type checker, with additional type-checking rules and LSP features baked in. It’s the most mature of the four and has the largest contributor base.

Zuban is from David Halter, the author of Jedi (the longtime Python autocompletion library). It aims for mypy compatibility and ships as a pip-installable tool.

What we tested

We tested each language server across several dimensions, roughly following the rubric we outlined publicly :

• Feature completeness: Completions, hover, go-to-definition, rename, code actions, diagnostics, inlay hints, call hierarchy
• Correctness: How well does the type checker handle real-world Python code?
• Performance: Startup time and time to first completion
• Ecosystem: License, community health, development velocity, production readiness

We tested inside Positron with a mix of data science and general Python code.

Feature completeness

Here are some screenshots of hovers, tab-completions, and diagnostics from each extension:

• Pyrefly
• ty
• Basedpyright
• Zuban

All four provide the core features you’d expect: completions, hover documentation, go-to-definition, semantic highlighting, and diagnostics. The differences show up in the details.

Pyrefly

Strong feature set. The hover documentation is the best of the four; Pyrefly renders it cleanly and sometimes includes hyperlinks to class definitions.

ty

Fast and clean, now in beta. The completion details can sometimes feel a little overwhelming, but can help when expanded.

Basedpyright

Handles type checking comprehensively well. The main friction point: it surfaces a lot of warnings out of the box. If you’re doing exploratory data science, a wall of type errors on your first pandas import can feel hostile. You can tune this down, but the defaults are oriented toward stricter use cases like package development.

Zuban

The least mature of the four so far. Installation requires a two-step process (pip install zuban, then configure the interpreter), and the analysis is tied to that specific Python installation on saved files only. Third-party library completions only work when stubs are available, not from installed packages. Symbol renaming once broke standard library code in our testing.

Type checking philosophy

The bigger difference between these tools isn’t features but how they think about type checking.

Gradual guarantee vs. aggressive inference

ty follows what’s called the gradual guarantee: removing a type annotation from correct code should never introduce a type error. The idea is that type checking should be additive. You opt in by adding types, and the checker only flags things it’s sure about.

The other extensions take the opposite approach. They always infer types from your code, even when you haven’t written any annotations. This means they can catch bugs in completely untyped code, but it also means they may flag code that runs perfectly fine.

For example:

1
2
3
4
5
6
7

my_list = [1, 2, 3]
my_list.append("foo")

# Pyrefly: bad-argument-type
# ty: <no error>
# Basedpyright: reportArgumentType
# Zuban: arg-type

Pyrefly infers my_list as list[int] and flags the append("foo") call as a type error. ty sees no annotations and stays silent. The code is dynamically typed and that’s fine.

If you’re doing exploratory data analysis and don’t want to annotate everything, ty’s restraint might be more comfortable. But if you’re writing a library and want to catch bugs early, Pyrefly’s aggressiveness is helpful. For example:

1
2
3
4
5
6
7
8
9

def process(data):
    return str(data)

process(42) + 1  # Raises a runtime AttributeError

# Pyrefly: unsupported-operation
# ty: <no error>
# Basedpyright: reportOperatorIssue
# Zuban: operator

Basedpyright and Zuban land somewhere in between, with Basedpyright leaning toward stricter checking and Zuban aiming for mypy compatibility. Each of these extensions has the ability to suppress certain diagnostics you actually see when typing if you wish.

For a deeper dive on this topic, Edward Li’s comparison of Pyrefly and ty and Rob Hand’s overview of future Python type checkers are both worth reading, though some bugs have been fixed since they were published.

Performance

We measured startup time (how long until the language server responds to an initialize request) and time to first completion (how long a textDocument/completion request takes after initialization) in a relatively small repository. We ran each measurement five times and averaged. As always, these results only represent our computer’s experimental setup.

ty was the fastest across the board. But the practical differences are small: a 3-second difference in startup happens once per session, and a 100ms difference in completions is imperceptible. All four are fast enough that differences are negligible for daily use.

Ecosystem health

We also looked at each project’s development velocity and community health metrics. A language server you rely on daily needs to keep up with Python’s evolution.

ty and Pyrefly are shipping fast. Both are on a weekly release cadence or higher with high issue throughput. ty’s issue volume is notable: 789 issues opened in 90 days reflects both heavy adoption and active bug reporting. Pyrefly is closing more issues than it’s opening, a good sign for a beta project.

Response times are quick. In a spot-check of recent issues, ty and Pyrefly both had first responses from core maintainers within minutes to hours. Basedpyright’s maintainer responds quickly too, though at a lower volume. Zuban’s maintainer often replies within an hour.

What we chose

We bundled Pyrefly as Positron’s default Python language server.

The deciding factors:

• Pyrefly’s clean design decisions felt like the best fit for Positron. The hover docs are rendered and hyperlinked, with sources for type inference. The type inference catches real bugs without requiring you to annotate everything. While it has the strictest type checking, this is configured to a moderate level by default.
• It has active development with strong backing. Meta has committed to making Pyrefly genuinely open-source and community-driven, with biweekly office hours and a public Discord. Development velocity is high.
• It is MIT licensed, which allows us to bundle it into Positron.

It wasn’t a runaway winner. Basedpyright is more mature and feature-complete. ty has a lot of long-term potential, especially for ruff users and fans of the gradual guarantee, and is closing feature gaps fast. But for the specific use case of “Python data science in an IDE,” Pyrefly had the best balance of features, UX, and readiness.

How to switch

This space is competitive and moving fast, and you shouldn’t feel locked in. Positron makes it straightforward to switch language servers:

1. Open the Extensions view (Ctrl-Shift-X (linux), Ctrl-Shift-X (windows), Command-Shift-X (mac)).
2. Search for and install the language server you want to try (e.g., basedpyright, ty, or zuban).
3. Disable Pyrefly: search for pyrefly in Extensions, click Disable.
4. Reload the window with the command Developer: Reload Window.

Or, if you want to keep Pyrefly installed but prevent it from auto-activating, you can use the extensions.allowed setting:

1
2
3
4
5
6

{
    "extensions.allowed": {
        "meta.pyrefly": false,
        "*": true
    }
}

What’s next

We started bundling Pyrefly in November and have been quite pleased with the results. It solved some longstanding user-requested issues (like better semantic highlighting) and feels snappier to users than our previous internal solution.

ty is adding features at an aggressive pace and will likely close its remaining gaps. OpenAI’s acquisition of Astral adds resources but also uncertainty; it’s unclear how it will affect ty’s priorities. Pyrefly continues to improve its type checking and performance (a recent release noted 20% faster PyTorch benchmarks ). Basedpyright tracks upstream Pyright closely and keeps shipping.

Both ty and Pyrefly have been receptive to PRs that improve the experience for Positron users, which suggests they care about working well across editors, not just VS Code. For example, both contribute hover, completions, and semantic highlighting in the Positron Console.

We’ll keep evaluating as these tools mature! Want to try Positron? Download it here .

Why we built our own notebook editor

We built the Positron Notebook Editor to treat your .ipynb files as first-class citizens in an IDE tailored specifically for data science workflows.

Up to this point, Positron used the legacy Code OSS notebook editor that powers VS Code. While functional, this editor was designed for general-purpose development and not specifically for data science workflows. The tradeoffs show up in small ways that compound over time: limited context for AI assistance, no deep integration with your variables or data, and a user experience that treats .ipynb files as just another file type.

We wanted notebooks to feel like a first-class part of a data science IDE, so we built our own native notebook editor.

If you missed the original February announcement , that post covers our initial reasoning in more detail.

What’s included out of the box

The Positron Notebook Editor brings the core capabilities of Positron directly into your notebook workflow:

Variables Pane : Variables update in real time as you run cells. No need to print or inspect manually.

Data Explorer : When a cell returns a Pandas or Polars DataFrame, you get an inline data viewer. Open the full Data Explorer to sort, filter, and profile your data. Any filtering or cleaning you do can be converted into code, so your analysis stays reproducible without writing repetitive df.head() or df.describe() calls.

AI Assistant : The Assistant has access to your notebook’s full context, including cell states, execution history, and outputs like images and tables. It can suggest edits, reorder cells, and run code with your permission. You can inspect exactly what context it’s using and follow along as it works.

Help Pane : Python and R documentation is available inline, with hyperlinks, without switching to a browser.

Publisher : Deploy your .ipynb notebooks directly to Connect or Connect Cloud, where you can manage access, schedule runs, and view telemetry.

A sample notebook workflow

Now that you have all these capabilities in one place, your workflow might look something like this:

1. Import your data using Pandas or Polars.
2. Run your notebook cells and watch variables update in the pane as cells run.
3. Explore your DataFrame in the inline Data Explorer. Sort and filter without writing any code.
4. Use Assistant to generate a visualization based on your filtered data or AI quick actions to recommend next steps.
5. When the analysis is ready to share, use an AI action to add markdown headers and notes.
6. Publish the notebook to Connect or Connect Cloud to share with your colleagues.

What’s coming next

The roadmap includes SQL support, improved version control, R improvements, and more. You can view and vote on items in the GitHub roadmap .

Get started with the alpha

1. Download Positron and install a release from February 2026 or later.
2. Enable the alpha by setting positron.notebook.enabled to true in your settings.
3. Try the tutorial repository for examples that use the new features.
4. Share feedback in GitHub Discussions or book time to talk with us directly .

We’re excited to hear how you use the Positron Notebook Editor as we continuously improve the experience.

Why a command-line interface for R?

A command-line interface (CLI) lets you run programs from a terminal, without opening an IDE or starting an interactive R session. This is useful when you want to:

• automate tasks via cron jobs, scheduled tasks, or CI/CD pipelines
• chain R scripts together with other tools in data pipelines
• let others run your R code without needing to know R
• package reusable tools that feel native to the terminal
• expose specific actions through a clean interface that LLM agents can invoke

There are several established packages for building CLIs in R, including argparse, optparse, and docopt, where you explicitly parse and handle command-line arguments in code. Rapp takes a different approach: it derives the CLI surface from the structure of your R script and injects values at runtime, so you never need to handle CLI arguments manually.

How Rapp works

At its core, Rapp is an alternative front-end to R: a drop-in replacement for Rscript that automatically turns common R expression patterns into command-line options, switches, positional arguments, and subcommands. You write normal R code and Rapp handles the CLI surface.

Rapp also uses special #| comments (similar to Quarto’s YAML-in-comments syntax) to add metadata such as help descriptions and short aliases.

A tiny example

Here’s a complete Rapp script (from the package examples), a coin flipper:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

#!/usr/bin/env Rapp
#| name: flip-coin
#| description: |
#|   Flip a coin.

#| description: Number of coin flips
#| short: 'n'
flips <- 1L

sep <- " "
wrap <- TRUE

seed <- NA_integer_
if (!is.na(seed)) {
  set.seed(seed)
}

cat(sample(c("heads", "tails"), flips, TRUE), sep = sep, fill = wrap)

Let’s break down how Rapp interprets this script:

The #| short: 'n' comment adds -n as a short alias for --flips. The #!/usr/bin/env Rapp line (called a “shebang”) lets you run the script directly on macOS and Linux without typing Rapp first.

Running the script

With Rapp installed and flip-coin available on your PATH (see Get started below), you can run the app from the terminal:

1
2
3
4
5

flip-coin -n 3
#> heads tails heads

flip-coin --seed 42 -n 5
#> tails heads tails tails heads

Auto-generated help

Rapp generates --help from your script (and --help-yaml if you want a machine-readable spec):

1

flip-coin --help

1
2
3
4
5
6
7
8
9

Usage: flip-coin [OPTIONS]

Flip a coin.

Options:
  -n, --flips <FLIPS>  Number of coin flips [default: 1] [type: integer]
  --sep <SEP>          [default: " "] [type: string]
  --wrap / --no-wrap   [default: true] Disable with `--no-wrap`.
  --seed <SEED>        [default: NA] [type: integer]

1
2
3
4
5
6

# Before 0.3.0: this positional was optional
name <- NULL

# In 0.3.0+: add this comment to keep it optional
#| required: false
name <- NULL

Highlights in 0.3.0

Rapp will be new to most readers, so rather than listing every change, here are the main ideas (and what’s improved in 0.3.0).

Options, switches, and repeatable flags from plain R

Rapp recognizes a small set of “declarative” patterns at the top level of your script:

• Scalar literals like flips <- 1L become options like --flips 10.
• Logical defaults like wrap <- TRUE become toggles like --wrap / --no-wrap.
• #| short: n adds a short alias like -n (new in 0.3.0).
• c() and list() defaults declare repeatable options (new in 0.3.0): callers can supply the same flag multiple times and values are appended.

Subcommands with switch()

Rapp can now turn a switch() block into subcommands (and you can nest switch() blocks for nested commands). Here’s a small sketch of a todo-style app:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#!/usr/bin/env Rapp
#| name: todo
#| description: Manage a simple todo list.

#| description: Path to the todo list file.
#| short: s
store <- ".todo.yml"

switch(
  command <- "",

  #| description: Display the todos
  list = {
    limit <- 30L
    # ...
  },

  #| description: Add a new todo
  add = {
    task <- NULL
    # ...
  }
)

Help is scoped to the command you’re asking about, so todo --help lists the commands, and todo list --help shows just the options/arguments for list (plus any parent/global options).

Installable launchers for package CLIs

A big part of sharing CLI tools is making them easy to run after installation. In 0.3.0, install_pkg_cli_apps() installs lightweight launchers for scripts in a package’s exec/ directory that use either #!/usr/bin/env Rapp or #!/usr/bin/env Rscript:

1

Rapp::install_pkg_cli_apps("mypackage")

(There’s also uninstall_pkg_cli_apps() to remove a package’s launchers.)

Get started

Here’s the quickest path to your first Rapp script:

1
2

# 1. Install the package
install.packages("Rapp")

1
2

# 2. Install the command-line launcher
Rapp::install_pkg_cli_apps("Rapp")

Then create a script (e.g., hello.R):

1
2
3
4
5
6

#!/usr/bin/env Rapp
#| name: hello
#| description: Say hello

name <- "world"
cat("Hello,", name, "\n")

And run it:

1
2

Rapp hello.R --name "R users"
#> Hello, R users

Learn more

To dig deeper into Rapp:

• browse examples in the package: system.file("examples", package = "Rapp")
• read the full documentation: https://github.com/r-lib/Rapp
• note that Rapp requires R ≥ 4.1.0

If you try Rapp, we’d love feedback! We especially want to hear about your experiences with edge cases in argument parsing, help output, and how commands should feel. Issues and ideas are welcome at https://github.com/r-lib/Rapp/issues .

With this release, it bridges the gap between your laptop and enterprise infrastructure – the same code you prototype locally now deploys to Posit Workbench or any cloud HTTP API, with a single function call.

You can install it from CRAN with:

1

install.packages("mirai")

The flagship feature for this release is the HTTP launcher for deploying daemons to cloud and enterprise platforms. This release also brings a C-level dispatcher for minimal task dispatch overhead, race_mirai() for process-as-completed patterns, synchronous mode for debugging, and daemon synchronization for remote deployments. You can see a full list of changes in the release notes .

How mirai works

If you’ve ever waited for a loop to finish fitting models, processing files, or calling APIs, mirai can help. Any task that’s repeated independently across items is a candidate for parallel execution.

The previous release post covered mirai’s design philosophy in detail. Here’s a brief overview for readers encountering mirai for the first time.

library(mirai)
# Set up 4 background processes
daemons(4)

# Send work -- non-blocking, returns immediately
m <- mirai({
  Sys.sleep(1)
  100 + 42
})
m
#> < mirai [] >

# Collect the result when ready
m[]
#> [1] 142

# Shut down
daemons(0)

That’s mirai in a nutshell: daemons() to set up workers, mirai() to send work, [] to collect results. Everything else builds on this.

In mirai’s hub architecture, the host session listens at a URL and daemons – background R processes that do the actual work – connect to it. You send tasks with mirai() , and the dispatcher routes them to available daemons in first-in, first-out (FIFO) order.

This design enables dynamic scaling: daemons can connect and disconnect at any time without disrupting the host. Add capacity when you need it, release it when you don’t.

A single compute profile can mix daemons launched by different methods, and you can run multiple profiles simultaneously to direct different tasks to different resources. The basic syntax for each deployment method:

Change one line and your local prototype runs on a Slurm cluster. Change it again and it runs on Posit Workbench. Your analysis code stays identical.

The async foundation for the modern R stack

mirai has become the convergence point for asynchronous and parallel computing across the R ecosystem.

It is the recommended async backend for Shiny – if you’re building production Shiny apps, you should be using mirai. It is the only async backend for the next-generation plumber2 – if you’re building APIs with plumber2, you’re already using mirai.

It is the parallel backend for purrr – if you use map(), mirai is how you make it parallel. Wrap your function in in_parallel() , set up daemons, and your map calls run across all of them:

1
2
3
4
5

library(purrr)
daemons(4)
models <- split(mtcars, mtcars$cyl) |>
  map(in_parallel(\(x) lm(mpg ~ wt + hp, data = x)))
daemons(0)

It powers targets – the pipeline orchestration tool for reproducible analysis. And most recently, ragnar – the Tidyverse package for retrieval-augmented generation (RAG) – adopted mirai for its parallel processing.

As an official alternative communications backend for R’s parallel package, mirai underpins workflows from interactive web applications to pipeline orchestration to AI-powered document processing.

Learn mirai, and you’ve learned the async primitive that powers the modern R stack. The same two concepts – daemons() to set up workers, mirai() to send work – are all you need to keep a Shiny app responsive or run async tasks in production.

HTTP launcher

This release extends the “deploy everywhere” principle with http_config() , a new remote launch configuration that deploys daemons via HTTP API calls – any platform with an HTTP API for launching jobs.

Posit Workbench

Many organizations use Posit Workbench to run research and data science at scale. mirai now integrates directly with it.¹ Call http_config() with no arguments and it auto-configures using the Workbench environment:

1

daemons(n = 4, url = host_url(), remote = http_config())

That’s it. Four daemons launch as Workbench jobs, connect back to your session, and you can start sending work to them.

Here’s what that looks like in practice: you’re developing a model in your Workbench session. Fitting it locally is slow. Add that line, and those fits fan out across four Workbench-managed compute jobs. When you’re done, daemons(0) releases them. No YAML, no job scripts, no leaving your R session – resource allocation, access control, and job lifecycle are all handled by the platform.

If you’ve been bitten by expired tokens in long-running sessions, http_config() is designed to prevent that. Under the hood, it stores functions rather than static values for credentials and endpoint URLs. These functions are called at the moment daemons actually launch, so session cookies and API tokens are always fresh – even if you created the configuration hours earlier.

See the mirai vignette for troubleshooting remote launches.

Custom APIs

The HTTP launcher works with any HTTP API, not just Workbench. Supply your own endpoint, authentication, and request body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

daemons(
  n = 2,
  url = host_url(),
  remote = http_config(
    url = "https://api.example.com/launch",
    method = "POST",
    token = function() Sys.getenv("MY_API_KEY"),
    data = '{"command": "%s"}'
  )
)

The "%s" placeholder in data is where mirai inserts the daemon launch command at launch time. Each argument can be a plain value or a function – use functions for anything that changes between launches (tokens, cookies, dynamic URLs).

This opens up a wide range of deployment targets: Kubernetes job APIs, other cloud container services, or any internal job scheduler with an HTTP interface. If you can launch a process with an HTTP call, mirai can use it.

C-level dispatcher

The overhead of distributing your tasks is now negligible. In a mirai_map() over thousands of items, what you measure is the time of your actual computation, not the framework – per-task dispatch overhead is now in the tens of microseconds, where existing R parallelism solutions typically operate in the millisecond range.

Under the hood, the dispatcher – the process that sits between your session and the daemons, routing tasks to available workers – has been re-implemented entirely in C code within nanonext . This eliminates the R interpreter overhead that remained, while the dispatcher continues to be event-driven and consume zero CPU when idle.

This also removes the bottleneck when coordinating large numbers of daemons, which matters directly for the kind of scaled-out deployments that the HTTP launcher enables – dozens of Workbench jobs or cloud instances all connecting to a single dispatcher. The two features are designed to work together: deploy broadly, dispatch efficiently. mirai is built to scale from 2 cores on your laptop to 200 across a cluster, without the framework slowing you down.

race_mirai()

race_mirai() lets you process results as they arrive, rather than waiting for the slowest task. Suppose you’re fitting 10 models with different hyperparameters in parallel – some converge quickly, others take much longer. Without race_mirai() , you wait for the slowest fit to complete before seeing any results. With it, you can inspect or save each model the instant it finishes – updating a progress display, freeing memory, or deciding whether to continue the remaining fits at all.

race_mirai() returns the integer index of the first resolved mirai. This makes the “process as completed” pattern clean and efficient:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

daemons(4)

# Launch 10 model fits in parallel
fits <- lapply(param_grid, function(p) mirai(fit_model(data, p), data = data, p = p))

# Process each result as soon as it's ready
remaining <- fits
while (length(remaining) > 0) {
  idx <- race_mirai(remaining)
  cat("Finished model with params:", remaining[[idx]]$data$p, "\n")
  remaining <- remaining[-idx]
}

daemons(0)

Send off a batch of tasks, then process results in the order they finish – no polling, no wasted time waiting on the slowest one. If any mirai is already resolved when you call race_mirai() , it returns immediately. This pattern applies whenever tasks have variable completion times – parallel model fits, API calls, simulations, or any batch where you want to stream results as they land.

Synchronous mode

When tasks don’t behave as expected, you need a way to inspect them interactively.

Without synchronous mode, errors in a mirai return as miraiError objects – you can see that something went wrong, but you can’t step through the code to find out why. The task ran in a separate process, and by the time you see the error, that process has moved on.

daemons(sync = TRUE), introduced in 2.5.1, solves this. It runs everything in the current process – no background processes, no networking – just sequential execution. You can use browser() and other interactive debugging tools directly:

1
2
3
4
5
6
7
8

daemons(sync = TRUE)
mirai(
  {
    browser()
    mypkg::some_complex_function(x)
  },
  x = my_data
)

You can scope synchronous mode to a specific compute profile, isolating the problematic task for inspection while the rest of your pipeline keeps running in parallel.

Daemon synchronization with everywhere()

everywhere() runs setup operations on all daemons – loading packages, sourcing scripts, or preparing datasets – so they’re ready before you send work.

When launching remote daemons – via SSH, HPC schedulers, or the new HTTP launcher – there’s an inherent delay between requesting a daemon and that daemon being ready to accept work. The new .min argument ensures that setup has completed on at least that many daemons before returning:

1
2
3
4
5
6
7

daemons(n = 8, url = host_url(), remote = http_config())

# Wait until all 8 daemons are connected before continuing
everywhere(library(mypackage), .min = 8)

# Now send work once all daemons are ready
mp <- mirai_map(tasks, process)

This creates a synchronization point, ensuring your pipeline doesn’t start sending work before all daemons are ready. It’s especially useful for remote deployments where connection times are unpredictable.

Minor improvements and fixes

• miraiError objects now have conditionCall() and conditionMessage() methods, making them easier to use with R’s standard condition handling.
• The default exit behavior for daemons has been updated with a 200ms grace period before forceful termination, which allows OpenTelemetry disconnection events to be traced.
• OpenTelemetry span names and attributes have been revised to better follow semantic conventions.
• daemons() now properly validates that url is a character value where supplied.
• Fixed a bug where repeated mirai cancellation could sometimes cause a daemon to exit prematurely.

Try it now

1
2
3
4
5
6
7
8

install.packages("mirai")
library(mirai)

daemons(4)
system.time(mirai_map(1:4, \(x) Sys.sleep(1))[])
#>    user  system elapsed
#>   0.000   0.001   1.003
daemons(0)

Four one-second tasks, one second of wall time. If those were four model fits that each took a minute, you’d go from four minutes down to one – and if you needed more power, switching to Workbench or a Slurm cluster is a one-line change. Visit mirai.r-lib.org for the full documentation.

Acknowledgements

A big thank you to all the folks who helped make this release happen:

@agilly , @aimundo , @barnabasharris , @beevabeeva , @boshek , @eliocamp , @jan-swissre , @jeroenjanssens , @kentqin-cve , @mcol , @michaelmayer2 , @pmac0451 , @r2evans , @shikokuchuo , @t-kalinowski , @VincentGuyader , @wlandau , and @xwanner .

When we introduced nanonext last year, we showed how it connects R directly to Python, Go, Rust, and other languages through NNG’s messaging protocols. We hinted at its web capabilities – but that was just the beginning.

R already has excellent web infrastructure. Shiny and plumber2 are the go-to tools for building interactive applications and REST APIs in R. They are both powered by httpuv . nanonext adds a complementary option at the httpuv level of the stack – a low-level streaming HTTP and WebSocket server built on NNG, giving developers fine-grained control over connections, streaming, and static file serving over TLS. nanonext is for when you need lower-level control – custom protocols, infrastructure endpoints, or embedding a server alongside an existing Shiny or plumber2 application.

You can install it from CRAN with:

1

install.packages("nanonext")

You can see a full list of changes in the release notes .

Streaming HTTP/WebSocket server

The flagship feature of this release is http_server() , a streaming HTTP and WebSocket server with full TLS support. Built on NNG’s HTTP server architecture, it brings the same performance that powers nanonext’s messaging layer to web serving.

One server, one port – HTTP endpoints, WebSocket connections, and streaming all coexist. Static files bypass R entirely, served natively by NNG. WebSocket and streaming connections run callbacks on R’s main thread via the later package. Mbed TLS is built in for HTTPS/WSS, and there’s no need to run separate processes or bind additional ports.

Because it shares the same event loop that Shiny uses, http_server() can run alongside a Shiny app in the same R process. You could spin up a nanonext server to handle health checks, serve static assets, or stream real-time events – while Shiny or plumber2 handles the application logic. They’re designed to work together.

As part of our investment in expanding what’s possible with R, we’re already using nanonext at Posit to explore new real-time capabilities, and we’re excited to see what the community builds with it.

Basic HTTP server

Where frameworks like plumber2 give you a full-featured API layer with routing, serialization, and documentation out of the box, http_server() gives you direct control over requests and responses – the kind of direct access you’d reach for when building custom infrastructure or embedding a server inside a larger system.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

library(nanonext)

server <- http_server(
  url = "http://127.0.0.1:8080",
  handlers = list(
    handler("/", function(req) {
      list(status = 200L, body = "Hello from nanonext!")
    }),
    handler("/api/data", function(req) {
      list(
        status = 200L,
        headers = c("Content-Type" = "application/json"),
        body = '{"value": 42}'
      )
    }, method = "GET")
  )
)
server$start()

Handlers receive a request and return a response list. You can freely mix handler types in a single server:

Specifying port 0 in the URL lets the operating system assign an available port. The actual port is reflected in server$url after $start(), so you can set up test servers without worrying about port conflicts.

Static file serving

Static handlers bypass R entirely – NNG serves content directly and efficiently:

1
2
3
4
5
6
7

handler_directory("/static", "www/assets")  # serve a folder
handler_file("/favicon.ico", "favicon.ico") # serve a single file
handler_inline(
  "/robots.txt",
  "User-agent: *\nDisallow:",
  content_type = "text/plain"
) # serve in-memory content

For example, you can serve a rendered Quarto website with a single handler:

1
2
3
4
5
6
7

server <- http_server(
  url = "http://127.0.0.1:0",
  handlers = handler_directory("/", "_site")
)
server$start()
server$url
# Browse to the URL to see your Quarto site

WebSocket server

WebSockets provide full bidirectional communication – the server can push messages to the client, and the client can send messages back. WebSocket and HTTP handlers share the same server and port, so a browser can load a page over HTTP and open a WebSocket to the same origin – no cross-origin configuration needed:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

server <- http_server(
  url = "http://127.0.0.1:8080",
  handlers = list(
    handler("/", function(req) list(status = 200L, body = "<html>...</html>")),
    handler_ws("/ws",
      on_message = function(ws, data) ws$send(data),
      on_open = function(ws) cat("connected:", ws$id, "\n"),
      on_close = function(ws) cat("disconnected:", ws$id, "\n")
    )
  )
)

This makes it easy to build lightweight real-time services – monitoring endpoints or live-updating feeds that push results to the browser as they arrive.

HTTP streaming and Server-Sent Events

When you only need to push data in one direction – server to client – streaming is a lighter-weight alternative to WebSockets. It works over plain HTTP, so any client that speaks HTTP can consume the stream without needing a WebSocket library. handler_stream() enables chunked transfer encoding for streaming responses:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

conns <- list()

handler_stream("/events",
  on_request = function(conn, req) {
    conn$set_header("Content-Type", "text/event-stream")
    conn$set_header("Cache-Control", "no-cache")
    conns[[as.character(conn$id)]] <<- conn
    conn$send(format_sse(data = "connected", id = "1"))
  },
  on_close = function(conn) {
    conns[[as.character(conn$id)]] <<- NULL
  }
)

The format_sse() helper formats messages per the SSE specification. On the browser side, updates arrive automatically as they happen – no page refreshes or repeated requests needed. Streaming also supports NDJSON and custom formats – useful for streaming model training progress, sensor readings, monitoring endpoints, or pipeline notifications.

TLS/SSL support

For HTTPS, pass a TLS configuration. nanonext bundles Mbed TLS, so there’s nothing extra to install:

1
2
3
4
5
6

cert <- write_cert(cn = "127.0.0.1")
server <- http_server(
  url = "https://127.0.0.1:0",
  handlers = handler("/", function(req) list(status = 200L, body = "Secure!")),
  tls = tls_config(server = cert$server)
)

Full response headers for HTTP client

ncurl() now accepts response = TRUE to return all response headers:

resp <- ncurl("https://postman-echo.com/get", response = TRUE)
resp$headers |> names()
#>  [1] "Date"                          "Content-Type"                 
#>  [3] "Content-Length"                "Connection"                   
#>  [5] "CF-RAY"                        "etag"                         
#>  [7] "vary"                          "Set-Cookie"                   
#>  [9] "x-envoy-upstream-service-time" "cf-cache-status"              
#> [11] "Server"

Previously you could only request specific headers by name. Now you can retrieve the complete set – useful for inspecting rate limits, caching directives, and other metadata from REST APIs.

Async HTTP with Shiny

If your Shiny app calls a REST API, a slow or unresponsive endpoint will block the R process and freeze the app for all users, not just the one who triggered the request. ncurl_aio() avoids this – it performs the HTTP call on a background thread and returns a promise, so the R process stays free to serve other sessions. It works anywhere that accepts a promise, including Shiny’s ExtendedTask:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

library(shiny)
library(bslib)
library(nanonext)

ui <- page_fluid(
  p("The time is ", textOutput("current_time", inline = TRUE)),
  hr(),
  input_task_button("btn", "Fetch data"),
  verbatimTextOutput("result")
)

server <- function(input, output, session) {
  output$current_time <- renderText({
    invalidateLater(1000)
    format(Sys.time(), "%H:%M:%S %p")
  })

  task <- ExtendedTask$new(
    function() ncurl_aio("https://postman-echo.com/get", response = TRUE)
  ) |> bind_task_button("btn")

  observeEvent(input$btn, task$invoke())
  output$result <- renderPrint(task$result()$headers)
}

shinyApp(ui, server)

New documentation

The package documentation has been reorganized into focused, self-contained guides:

Whether you need a quick API cheatsheet or a deep dive into WebSocket chat servers, the new vignettes are designed to get you up and running fast.

Bug fixes and improvements

A new race_aio() function returns the index of the first resolved async operation in a list – useful when waiting on multiple concurrent operations and you want to act on whichever completes first.

This release also fixes two critical issues – one affecting TLS operations in fresh sessions with newer system versions of Mbed TLS, another when custom serialization hooks threw errors. Error handling is now more graceful throughout, with closed streams returning error values instead of throwing. Under the hood, serialization, streaming, and async sends are all faster, and the bundled Mbed TLS is updated to 3.6.5 LTS. Building from source no longer requires xz.

Looking ahead

nanonext gives R a new building block for web infrastructure – one that complements httpuv. We see it as part of a broader investment in making R a first-class platform for real-time, connected applications. If you want to dig deeper, visit the package website or explore the source on GitHub .

Acknowledgements

A big thank you to everyone who contributed to this release:

@jeroenjanssens and @shikokuchuo .

Today we’re announcing two new packages for parsing and emitting YAML 1.2: yaml12 for R and py-yaml12 for Python.

Both packages are implemented in Rust and built on the excellent saphyr crate. They share the same design goals: predictable YAML 1.2 typing, explicit control over tag interpretation via handlers, and clean round-tripping of unhandled tags.

Before we get into the details, a quick note on how this relates to the existing R yaml package. The R yaml package is now in r-lib , and we’ve taken over maintenance after years of stewardship by its original author, Jeremy Stephens, and later by Shawn Garbett.

If yaml already works for you, there’s no need to switch. yaml12 is an experiment providing consistent R and Python bindings to a new Rust library specifically for YAML 1.2, which, as we’ll see below, has some particular advantages.

Install

Install the R package from CRAN:

install.packages("yaml12")

Install the Python package from PyPI:

1

pip install py-yaml12

Quick start (R)

library(yaml12)

yaml <- "
title: A modern YAML parser and emitter written in Rust
properties: [fast, correct, safe, simple]
"

doc <- parse_yaml(yaml)
str(doc)
#> List of 2
#>  $ title     : chr "A modern YAML parser and emitter written in Rust"
#>  $ properties: chr [1:4] "fast" "correct" "safe" "simple"

Round-trip back to YAML:

obj <- list(
  seq = 1:2,
  map = list(key = "value"),
  tagged = structure("1 + 1", yaml_tag = "!expr")
)
write_yaml(obj)
#> ---
#> seq:
#>   - 1
#>   - 2
#> map:
#>   key: value
#> tagged: !expr 1 + 1
#> ...

identical(obj, parse_yaml(format_yaml(obj)))
#> [1] TRUE

Quick start (Python)

# Install from PyPI:
#   python -m pip install py-yaml12
from yaml12 import parse_yaml, format_yaml, Yaml

yaml_text = """
title: A modern YAML parser and emitter written in Rust
properties: [fast, correct, safe, simple]
"""

doc = parse_yaml(yaml_text)

assert doc == {
  "title": "A modern YAML parser and emitter written in Rust",
  "properties": ["fast", "correct", "safe", "simple"]
}

assert doc == parse_yaml(format_yaml(doc))

# Tagged values
tagged = parse_yaml("!expr 1 + 1")
assert tagged == Yaml(value="1 + 1", tag="!expr")

Why YAML 1.2?

YAML 1.2 tightened up a number of ambiguous implicit conversions. In particular, plain scalars like on/off/yes/no/y/n are strings in the 1.2 core schema, and YAML 1.2 removed sexagesimal (base-60) parsing, so values like 1:2 are not treated as numbers.

YAML 1.2 also removed !!timestamp, !!binary, and !!omap from the set of core types, which further reduces implicit coercions (for example, getting a date/time object when you expected a string). If you want to interpret those values, you can do so explicitly via tags and handlers.

That makes YAML a better default for configuration files, front matter, and data interchange. You get fewer surprises and fewer “why did this become a boolean?” moments (or “why did this become a date?”).

Highlights

A consistent API in R and Python

The two packages intentionally share the same high-level functions:

• parse_yaml() : Parse YAML from a string
• read_yaml() : Read YAML from a file
• format_yaml() : Format values as YAML (to a string)
• write_yaml() : Write YAML to a file (or stdout)

Tags and handlers (opt-in, meaning, safe defaults)

In YAML, tags are explicit annotations like !expr or !!timestamp that attach type and meaning to a value.

Tags are preserved by default:

• In R, tags are kept in a yaml_tag attribute.
• In Python, tags are kept by wrapping values in a Yaml() object.

Handlers let you opt into custom behavior for tags (including tags on mapping keys) while keeping parsing as a data-only operation by default.

If you used R yaml’s !expr tag to evaluate expressions, you can recreate that behavior by registering a handler, but it’s only recommended when parsing trusted YAML, since evaluating arbitrary code is a security risk. For untrusted input, the default behavior is safer because it keeps !expr as data and does not execute code.

R example:

# by default, tags are kept as data
dput(parse_yaml("!expr 1 + 1"))
#> structure("1 + 1", yaml_tag = "!expr")

# Add a handler to process tagged nodes (like the {yaml} package does)
handlers <- list("!expr" = \(x) eval(str2expression(x), globalenv()))
parse_yaml("!expr 1 + 1", handlers = handlers)
#> [1] 2

Python example:

from yaml12 import parse_yaml

handlers = {"!expr": eval}  # use with trusted input only
parse_yaml("!expr 1 + 1", handlers=handlers)

#> 2

Simplification and missing values (R)

In R, parse_yaml() can simplify homogeneous sequences to vectors. When it does, YAML null becomes the appropriate NA type:

parse_yaml("[1, 2, 3, null]")
#> [1]  1  2  3 NA

str(parse_yaml("[1, 2, 3, null]", simplify = FALSE))
#> List of 4
#>  $ : int 1
#>  $ : int 2
#>  $ : int 3
#>  $ : NULL

Non-string mapping keys

YAML allows mapping keys that aren’t plain strings (numbers, booleans, tagged scalars, even sequences and mappings). Both packages preserve these safely:

• In R, you’ll get a regular named list plus a yaml_keys attribute when needed.
• In Python, unhashable keys (like lists/dicts) are wrapped in Yaml so they can still be used as dict keys and round-trip correctly.

R example:

dput(parse_yaml("{a: b}: c"))
#> structure(list("c"), names = "", yaml_keys = list(list(a = "b")))

Python example:

from yaml12 import parse_yaml, Yaml

doc = parse_yaml("{a: b}: c")
assert doc == {Yaml({'a': 'b'}): 'c'}

Mapping order is preserved

YAML mappings are ordered. yaml12 preserves mapping/dictionary order when parsing and formatting, so the order you see in a YAML file (or emit) round-trips in both R and Python.

Document streams and front matter

Both packages support multi-document YAML streams with multi = TRUE. When multi = FALSE (the default), parsing stops after the first document, which is handy for extracting YAML front matter from text that continues with non-YAML content.

Example:

yaml <- "
---
title: Extracting YAML front matter
---
This is technically now the second document in a YAML stream
"
str(parse_yaml(yaml))
#> List of 1
#>  $ title: chr "Extracting YAML front matter"
str(parse_yaml(yaml, multi = TRUE))
#> List of 2
#>  $ :List of 1
#>   ..$ title: chr "Extracting YAML front matter"
#>  $ : chr "This is technically now the second document in a YAML stream"

Performance and safety notes

yaml12 is implemented in Rust and written with performance and safety in mind. It avoids unnecessary allocations, copies, and extra traversals where possible. In Python, py-yaml12 (imported as yaml12) also releases the GIL for large parses and serializations.

In typical usage, the R package yaml12 is ~2× faster than the yaml package, and the Python package py-yaml12 is ≥50× faster than default PyYAML in the benchmarks ( R benchmarks ; Python benchmarks ).

Tags are preserved by default, and interpreting them (including any kind of evaluation) is always an explicit opt-in via handlers. Plain scalars follow the YAML 1.2 core schema rules for predictable typing.

In Python, py-yaml12 ships prebuilt wheels for common platforms. If you do need to build from source, you’ll need a Rust toolchain. In R, yaml12 is available from CRAN (including binaries on common platforms).

Wrapping up

If you work with YAML as a data format for configuration, front matter, or data interchange, we hope yaml12 (R) and py-yaml12 (Python) help you parse and emit YAML 1.2 predictably. If you run into YAML that doesn’t behave as expected, we’d love to hear about it in the issue trackers: r-yaml12 and py-yaml12 .

Learn more

• R package docs: https://posit-dev.github.io/r-yaml12/
• R package on CRAN: https://cran.r-project.org/package=yaml12
• Python package docs: https://posit-dev.github.io/py-yaml12/
• Python package on PyPI: https://pypi.org/project/py-yaml12/

Acknowledgements

Both packages build on the fantastic work in the YAML ecosystem, especially the saphyr Rust crate and the yaml-test-suite .

We’re chuffed to announce the release of testthat 3.3.0. testthat is a testing framework for R that makes it easy to turn your existing informal tests into formal, automated tests that you can rerun quickly and easily.

You can install it from CRAN with:

install.packages("testthat")

This blog post highlights the most important changes in this release, including lifecycle changes that removed long-deprecated mocking functions, improvements to expectations and their error messages, and a variety of new features that make testing easier and more robust. You can see a full list of changes in the release notes .

library(testthat)

Claude Code experiences

Before we dive into the changes, I wanted to talk a little bit about some changes to my development process, as I used this release as an opportunity to learn Claude Code . This is the first package where I’ve really used AI to support the development of many features and I thought it might be useful to share my experience.

Overall it was a successful experiment. It helped me close over 100 issues in what felt like less time than usual. I don’t have any hard numbers, but my gut feeling is that it was maybe a 10-20% improvement to my development velocity. This is still significant, especially since I’m an experienced R programmer and my workflow has been pretty stable for the last few years. I mostly used Claude for smaller, well-defined tasks where I had a good sense of what was needed. I found it particularly useful for refactoring, where it was easy to say precisely what I wanted, but executing the changes required a bunch of fiddly edits across many files.

I also found it generally useful for getting over the “activation energy hump”: there were a few issues that had been stagnating for years because they felt like they were going to be hard to do and with relatively limited payoff. I let Claude Code loose on a few of these and found it super useful. It only produced code I was really happy with a couple of times, but every time it gave me something to react to (often with strong negative feelings!) and that got me started actually engaging with the problem.

If you’re interested in using Claude Code yourself, there are a couple of files you might find useful. My CLAUDE.md tells Claude how to execute a devtools-based workflow, along with a few pointers to resolve common issues. My settings.json allows Claude to run longer without human intervention, doing things that should mostly be safe. One note of caution: these settings do allow Claude to run R code, which does allow it to do practically anything. In my experience, Claude only used R to run tests or documentation.

I also experimented with using Claude Code to review PRs. It was just barely useful enough that I kept it turned on for my own PRs, but I didn’t bother trying to get it to work for contributed PRs. Most of the time it either gave a thumbs up or bad advice, but every now and then it would pick up a small error.

(I’ve also used Claude Code to proofread this blog post!)

Lifecycle changes

The biggest change in this release is that local_mock() and with_mock() are defunct. They were deprecated in 3.0.0 (2020-10-31) because it was becoming clear that the technique that made them work would be disallowed in a future version of R. This has now happened in R 4.5.0, so the functions have been removed. Removing local_mock() and with_mock() was a fairly disruptive change, affecting ~100 CRAN packages, but it had to be done, and I’ve been working on notifying package developers since January so everyone had plenty of time to update. Fortunately, the needed changes are generally small, since the newer local_mocked_bindings() and with_mocked_bindings() can solve most additional needs. (If you haven’t heard of mocking before, you can read the new vignette("mocking") to learn what it is and why you might want to use it.)

Other lifecycle changes:

• testthat now requires R 4.1. This follows our supported version policy , which documents our commitment to support five versions of R (the current version and four previous versions). We’re excited to be able to finally take advantage of the base pipe and compact anonymous functions (i.e. \(x) x + 1)!

• is_null()/matches(), deprecated in 2.0.0 (2017-12-19), and is_true()/is_false(), deprecated in 2.1.0 (2019-04-23), have been removed. These conflicted with other tidyverse functions so we pushed their deprecation through, even though we have generally left the old test_that() API untouched.

• expect_snapshot(binary), soft deprecated in 3.0.3 (2021-06-16), is now fully deprecated. test_files(wrap), deprecated in 3.0.0 (2020-10-31), has now been removed.

• There were a few other changes that broke existing packages. The most impactful change was to start checking the inputs to expect() which, despite the name, is actually an internal helper. That revealed a surprising number of packages were accidentally using expect() instead of expect_true() or expect_equal() . We don’t technically consider this a breaking change because it revealed off-label function usage: the function API hasn’t changed; you just now learn when you’re using it incorrectly.

If you’re interested in the process we use to manage the release of a package that breaks its reverse dependencies, you might like to read the issue where I track all the problems and prepare PRs to fix them.

Expectations and the interactive testing experience

A lot of work in this release was prompted by an overhaul of vignette("custom-expectations"), which describes how to create your own expectations that work just like testthat’s. This is a long time coming, and as I was working on it, I realized that I didn’t really know how to write new expectations, which had led to a lot of variation in the existing implementations. This kicked off a bunch of experimentation and iterating, leading to a swath of improvements:

• All expectations have new failure messages: they now state what was expected, what was actually received, and, if possible, they clearly illustrate the difference.

• Expectations now consistently return the value of the first argument, regardless of whether the expectation succeeds or fails (the only exception is expect_error() and friends which return the captured condition so that you can perform additional checks on the condition object). This is a relatively subtle change that won’t affect tests that already pass, but it does improve failures when you pipe together multiple expectations.

• A new pass() function makes it clear how to signal when an expectation succeeds. All existing expectations were rewritten to use pass() and (the existing) fail() instead of expect() , which I think makes the flow of logic easier to understand.

• Improved expect_success() and expect_failure() expectations now test that an expectation always returns exactly one success or failure (this ensures that the counts that you see in the reporters are correct).

This new framework helped us write six new expectations:

• expect_all_equal() , expect_all_true() , and expect_all_false() check that every element of a vector has the same value, giving better error messages than expect_true(all(...)):

  test_that("some test", {
    x <- c(0.408, 0.961, 0.883, 0.46, 0.537, 0.961, 0.851, 0.887, 0.023)
    expect_all_true(x < 0.95)
  })
  #> ── Failure: some test ────────────────────────────────────────────────
  #> Expected every element of `x < 0.95` to equal TRUE.
  #> Differences:
  #> `actual`:   TRUE FALSE TRUE TRUE TRUE FALSE TRUE TRUE TRUE
  #> `expected`: TRUE TRUE  TRUE TRUE TRUE TRUE  TRUE TRUE TRUE
  #> Error:
  #> ! Test failed with 1 failure and 0 successes.
  

• expect_disjoint() , by @stibu81 , expects values to be absent:

  test_that("", {
    expect_disjoint(c("a", "b", "c"), c("c", "d", "e"))
  })
  #> ── Failure:  ─────────────────────────────────────────────────────────
  #> Expected `c("a", "b", "c")` to be disjoint from `c("c", "d", "e")`.
  #> Actual: "a", "b", "c"
  #> Expected: None of "c", "d", "e"
  #> Invalid: "c"
  #> Error:
  #> ! Test failed with 1 failure and 0 successes.
  

• expect_r6_class() expects an R6 object:

  test_that("", {
    x <- 10
    expect_r6_class(x, "foo")
  
    x <- R6::R6Class("bar")$new()
    expect_r6_class(x, "foo")
  })
  #> ── Failure:  ─────────────────────────────────────────────────────────
  #> Expected `x` to be an R6 object.
  #> Actual OO type: none.
  #> ── Failure:  ─────────────────────────────────────────────────────────
  #> Expected `x` to inherit from "foo".
  #> Actual class: "bar"/"R6".
  #> Error:
  #> ! Test failed with 2 failures and 0 successes.
  

• expect_shape() , by @michaelchirico , expects a specific shape (i.e., nrow() , ncol() , or dim() ):

  test_that("show off expect_shape() failure messages", {
    x <- matrix(1:9, nrow = 3)
    expect_shape(x, nrow = 4)
    expect_shape(x, dim = c(3, 3, 3))
    expect_shape(x, dim = c(3, 4))
  })
  #> ── Failure: show off expect_shape() failure messages ─────────────────
  #> Expected `x` to have 4 rows.
  #> Actual rows: 3.
  #> ── Failure: show off expect_shape() failure messages ─────────────────
  #> Expected `x` to have 3 dimensions.
  #> Actual dimensions: 2.
  #> ── Failure: show off expect_shape() failure messages ─────────────────
  #> Expected `x` to have dim (3, 4).
  #> Actual dim: (3, 3).
  #> Error:
  #> ! Test failed with 3 failures and 0 successes.
  

As you can see from the examples above, when you run a single test interactively (i.e. not as a part of a test suite) you now see exactly how many expectations succeeded and failed.

Other new features

• testthat generally does a better job of handling nested tests, aka subtests, where you put a test_that() inside another test_that() , or more typically it() inside of describe() . Subtests will now generate more informative failure messages, free from duplication, with more informative skips if any subtests don’t contain any expectations.

• The snapshot experience has been significantly improved, with all known bugs fixed and some new helpers added: snapshot_reject() rejects all modified snapshots by deleting the .new variants, and snapshot_download_gh() makes it easy to get snapshots off GitHub and into your local package. Additionally, expect_snapshot() and friends will now fail when creating a new snapshot on CI, as that’s usually a signal that you’ve forgotten to run the snapshot code locally before committing.

• On CRAN, test_that() will automatically skip if a package is not installed, which means that you no longer need to check if suggested packages are installed in your tests.

• vignette("mocking") explains mocking in detail, and new local_mocked_s3_method() , local_mocked_s4_method() , and local_mocked_r6_class() make it easier to mock S3 and S4 methods and R6 classes.

• test_dir() , test_check() , and friends gain a shuffle argument that uses sample() to randomly reorder the top-level expressions in each test file. This random reordering surfaces dependencies between tests and code outside of any test, as well as dependencies between tests, helping you find and eliminate unintentional dependencies.

• try_again() is now publicized, as it’s a useful tool for testing flaky code:

  flaky_function <- function() {
      if (runif(1) < 0.1) 0 else 1
    }
    
    # 10% chance of failure:
    test_that("my flaky test is ok", {
      skip_on_cran()
      expect_equal(flaky_function(), 1)
    })
    
    # 1% chance of failure:
    test_that("my flaky test is ok", {
      skip_on_cran()
      try_again(1, expect_equal(flaky_function(), 1))
    })
    
    # 0.1% chance of failure:
    test_that("my flaky test is ok", {
      skip_on_cran()
      try_again(2, expect_equal(flaky_function(), 1))
    })

  Note that it’s still good practice to skip such tests on CRAN.

• New skip_unless_r() skips tests on unsuitable versions of R. It has a convenient syntax so you can use, e.g., skip_unless_r(">= 4.1.0") to skip tests that require ...names() .

• New SlowReporter makes it easier to find the slowest tests in your package. You can run it with devtools::test(reporter = "slow").

• New vignette("challenging-functions") provides an index to other documentation organized by various challenges.

Acknowledgements

A big thank you to all the folks who helped make this release happen: @3styleJam , @afinez , @andybeet , @atheriel , @averissimo , @d-morrison , @DanChaltiel , @DanielHermosilla , @eitsupi , @EmilHvitfeldt , @emstruong , @gaborcsardi , @gael-millot , @hadley , @hoeflerb , @jamesfowkes , @jan-swissre , @jdblischak , @jennybc , @jeroenjanssens , @kevinushey , @krivit , @kubajal , @lawalter , @m-muecke , @maelle , @math-mcshane , @mcol , @metanoid , @MichaelChirico , @moodymudskipper , @njtierney , @nunotexbsd , @pabangan , @pachadotdev , @plietar , @schloerke , @schuemie , @sebkopf , @shikokuchuo , @snystrom , @stibu81 , @TimTaylor , and @tylermorganwall .

We’re delighted to announce the release of pkgdown 2.2.0. pkgdown is designed to make it quick and easy to build a beautiful and accessible website for your package.

You can install it from CRAN with:

install.packages("pkgdown")

This version of pkgdown has one major change: a new pkgdown::build_llm_docs() function that automatically creates files that make it easier for LLMs to read your documentation. Concretely, this means two things:

• You’ll get an llms.txt at the root directory of your site. llms.txt is an emerging standard that provides an easy way for an LLM to get an overview of your site. pkgdown creates an overview by combining your README, your function index, and your article index: this should give the LLM a broad overview of what your package does, along with links to find out more.

• Every existing .html on your site gets a corresponding .md file. These are generally easier for LLMs to understand because they contain just the content of the site, without any extraneous styling.

If you don’t want to generate these files, just add the following to your _pkgdown.yaml:

llm-docs: false

This release also includes new translations for Dutch and Japanese, removal of the long-deprecated autolink_html() and preview_page(), and a handful of other bug fixes and minor improvements. You can read about them all in the release notes .

Acknowledgements

As always, a big thanks to everyone who helped make this release possible: @cderv , @chabld , @Danny-dK , @davidorme , @dmurdoch , @hadley , @hfrick , @IndrajeetPatil , @jayhesselberth , @jeroenjanssens , @jmgirard , @krlmlr , @lorenzwalthert , @maelle , @MichaelChirico , @pepijn-devries , @remlapmot , @rempsyc , @Rohit-Satyam , @royfrancis , @rparmm , @schloerke , @TimTaylor , and @usrbinr .

We’re excited to announce mirai 2.5.0, bringing production-grade async computing to R!

This milestone release delivers enhanced observability through OpenTelemetry, reproducible parallel RNG, and key user interface improvements. We’ve also packed in twice as many changes as usual - going all out in delivering a round of quality-of-life fixes to make your use of mirai even smoother!

You can install it from CRAN with:

install.packages("mirai")

Introduction to mirai

mirai (Japanese for ‘future’) provides a clean, modern approach to parallel computing in R. Built on current communication technologies, it delivers extreme performance through professional-grade scheduling and an event-driven architecture.

It continues to evolve as the foundation for asynchronous and parallel computing across the R ecosystem, powering everything from async Shiny applications to parallel map in purrr to hyperparameter tuning in tidymodels.

library(mirai)

# Set up persistent background processes
daemons(4)

# Async evaluation - non-blocking
m <- mirai({
  Sys.sleep(1)
  100 + 42
})
m
#> < mirai [] >

# Results are available when ready
m[]
#> [1] 142

# Shut down persistent background processes
daemons(0)

A unique design philosophy

Modern foundation: mirai builds on nanonext , the R binding to Nanomsg Next Generation, a high-performance messaging library designed for distributed systems. This means that it’s using the very latest technologies, and supports the most optimal connections out of the box: IPC (inter-process communications), TCP or secure TLS. It also extends base R’s serialization mechanism to support custom serialization of newer cross-language data formats such as safetensors, Arrow and Polars.

Extreme performance: as a consequence of its solid technological foundation, mirai has the proven capacity to scale to millions of concurrent tasks over thousands of connections. Moreover, it delivers up to 1,000x the efficiency and responsiveness of other alternatives. A key innovation is the implementation of event-driven promises that react with zero latency - this provides an extra edge for real-time applications such as live inference or Shiny apps.

Production first: mirai provides a clear mental model for parallel computation, with a clean separation of a user’s current environment with that in which a mirai is evaluated. This explicitness and simplicity helps avoid common pitfalls that can afflict parallel processing, such as capturing incorrect or extraneous variables. Transparency and robustness are key to mirai’s design, and are achieved by minimizing complexity, and eliminating all hidden state with no reliance on options or environment variables. Finally, its integration with OpenTelemetry provides for production-grade observability.

Deploy everywhere: deployment of daemon processes is made through a consistent interface across local, remote (SSH), and HPC environments (Slurm, SGE, PBS, LSF). Compute profiles are daemons settings that are managed independently, such that you can be connected to all three resource types simultaneously. You then have the freedom to distribute workload to the most appropriate resource for any given task - especially important if tasks have differing requirements such as GPU compute.

OpenTelemetry integration

New in mirai 2.5.0: complete observability of mirai requests through OpenTelemetry traces. This is a core feature that completes the final pillar in mirai’s ‘production first’ design philosophy.

When tracing is enabled via the otel and otelsdk packages, you can monitor the entire lifecycle of your async computations, from creation through to evaluation, making it easier to debug and optimize performance in production environments. This is especially powerful when used in conjunction with other otel-enabled packages (such as an upcoming Shiny release), providing end-to-end observability across your entire application stack.

Reproducible parallel RNG

Introduced in mirai 2.4.1: reproducible parallel random number generation. Developed in consultation with our tidymodels colleagues and core members of the mlr team, this is a great example of the R community pulling together to solve a common problem. It addresses a long-standing challenge in parallel computing in R, important for reproducible science.

mirai has, since its early days, used L’Ecuyer-CMRG streams for statistically-sound parallel RNG. Streams essentially cut into the RNG’s period (a very long sequence of pseudo-random numbers) at intervals that are far apart from each other that they do not in practice overlap. This ensures that statistical results obtained from parallel computations remain correct and valid.

Previously, we only offered the following option, matching the behaviour of base R’s parallel package:

Default behaviour daemons(seed = NULL): creates independent streams for each daemon. This ensures statistical validity but not numerical reproducibility between runs.

Now, we also offer the following option:

Reproducible mode daemons(seed = integer): creates a stream for each mirai() call rather than each daemon. This guarantees identical results across runs, regardless of the number of daemons used.

# Always provides identical results:

with(
  daemons(3, seed = 1234L),
  mirai_map(1:3, rnorm, .args = list(mean = 20, sd = 2))[]
)
#> [[1]]
#> [1] 19.86409
#> 
#> [[2]]
#> [1] 19.55834 22.30159
#> 
#> [[3]]
#> [1] 20.62193 23.06144 19.61896

User interface improvements

Compute profile helper functions

with_daemons() and local_daemons() make working with compute profiles much more convenient by allowing the temporary switching of contexts. This means that developers can continue to write mirai code without worrying about the resources on which it is eventually run. End-users now have the ability to change the destination of any mirai computation dynamically using one of these scoped helpers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Work with specific compute profiles
with_daemons("gpu", {
  result <- mirai(gpu_intensive_task())
})

# Local version for use inside functions
async_gpu_intensive_task <- function() {
  local_daemons("gpu")
  mirai(gpu_intensive_task())
}

Re-designed daemons()

Creating new daemons is now more ergonomic, as it automatically resets existing ones. This provides for more convenient use in contexts such as notebooks, where cells may be run out of order. Manual daemons(0) calls are no longer required to reset daemons.

1
2
3
4
5
6

# Old approach
daemons(0)  # Had to reset first
daemons(4)

# New approach - automatic reset
daemons(4)  # Just works, resets if needed

New info() function

Provides a more succinct alternative to status() for reporting key statistics. This is optimized and is now a supported developer interface for programmatic use.

info()
#> connections  cumulative    awaiting   executing   completed 
#>           4           4           8           4           2

Acknowledgements

We extend our gratitude to the R community for their continued feedback and contributions. Special thanks to all contributors who helped shape this release through feature requests, bug reports, and code contributions: @agilly , @D3SL , @DavZim , @dipterix , @eliocamp , @erydit , @karangattu , @louisaslett , @mikkmart , @sebffischer , @shikokuchuo , and @wlandau .

Introducing nanonext: breaking down language barriers in data science

We’re excited to welcome nanonext to the r-lib family! nanonext is R’s binding to NNG (Nanomsg Next Generation), a high-performance C messaging library that implements scalability protocols for distributed systems. Because NNG has bindings and ports across multiple languages—including Python, Go, Rust, C++, and many others—nanonext enables seamless interoperability between R and other modern programming languages.

The latest version 1.7.0 brings enhanced reliability with improved HTTP client functionality, better handling of custom serialization methods, and more robust event-driven promises.

Get started by installing the package from CRAN now:

1

install.packages("nanonext")

The challenge: multi-language data science

If you’ve worked in data science, you’ve likely encountered this scenario: your workflow spans multiple programming languages. Perhaps you have Python models, R analysis scripts, Go services, or C++ performance libraries that all need to work together.

Traditionally, making these components communicate means:

• Writing data to files and reading them back
• Building REST APIs and making HTTP calls
• Handling different serialization formats like JSON or protocol buffers
• Dealing with the latency and complexity that comes with each approach

The solution: NNG’s scalability protocols

nanonext changes this by bringing NNG’s scalability protocols to R. NNG is a high-performance C library that implements standardized communication patterns like request/reply, publish/subscribe, and pipeline architectures. Any process using NNG can communicate directly with any other NNG process using the same protocol—regardless of the programming language.

This means that for simple atomic vector types, your R data doesn’t even need to be serialized and converted to a common format, enabling direct, real-time communication between processes. For more complex data types, as long as serialization and unserialization methods exist in both languages, then nanonext can be used to send and receive arbitrary binary data.

What can you do with nanonext?

nanonext opens up several powerful possibilities for R users:

🔗 Cross-language integration: Connect R directly with Python machine learning models, Go microservices, Rust compute engines, or C libraries without intermediate files or complex APIs.

⚡ Real-time data pipelines: Build data systems where different components process data as it flows, perfect for live dashboards or high-frequency analytics.

📡 Modern web integration: Create WebSocket clients, make asynchronous HTTP requests, or build real-time APIs that integrate with web services.

🚀 Asynchronous programming: Write non-blocking R code that can handle multiple operations simultaneously, improving performance for concurrent tasks.

Python ↔ R interoperability example

Here’s a concrete example of R and Python working together through NNG’s protocols. Both processes use their respective NNG bindings to establish a direct communication channel using NNG’s ‘pair’ protocol—a simple one-to-one bidirectional communication pattern.

Python side (using pynng):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

import numpy as np
import pynng

# Create socket to communicate with R
socket = pynng.Pair0(listen="ipc:///tmp/nanonext.socket")

# Wait for data from R
raw = socket.recv()
array = np.frombuffer(raw)
print(array)  # [1.1 2.2 3.3 4.4 5.5]

# Process data (could be ML model prediction, transformation, etc.)
processed = array * 2  # Simple example: multiply by 2

# Send back to R as bytes
socket.send(processed.tobytes())
socket.close()

R side (using nanonext):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

library(nanonext)

# Connect to Python process
sock <- socket("pair", dial = "ipc:///tmp/nanonext.socket")

# Send numeric data directly to Python (no serialization needed!)
sock |> send(c(1.1, 2.2, 3.3, 4.4, 5.5), mode = "raw")

# Receive processed results back from Python
processed_data <- sock |> recv(mode = "double")
print(processed_data)  # [1] 2.2 4.4 6.6 8.8 11.0

# Continue with R-specific analysis
summary(processed_data)
plot(processed_data)

close(sock)

What just happened? Your R session sent numerical data directly to Python’s memory space, Python processed it (possibly performing inference on a complex ML model), and sent results back—all happening in memory without touching the disk. This is orders of magnitude faster than traditional file-based approaches.

Why this matters

Speed: Direct memory communication is dramatically faster than file I/O or HTTP requests. Your R session doesn’t wait for disk writes or network round-trips.

Simplicity: No need to design REST APIs, manage file formats, or handle serialization. Send R vectors directly and receive results back.

Flexibility: nanonext supports different communication patterns (one-to-one, one-to-many, publish/subscribe) and transport methods (IPC, TCP, WebSocket).

Reliability: Built on NNG, a mature library that powers mission-critical systems in technology, finance and many other industries.

Asynchronous: Your R session stays responsive. Send a request for a long-running computation and continue working while it processes in the background.

The future is multi-language

nanonext facilitates a shift toward more flexible, performance-oriented data science workflows. Instead of being locked into a single language or accepting the overhead of traditional integration methods, you can now build systems where each component uses the best tool for the job.

We’re excited to see how the R community uses these capabilities.

Ready to try it? Visit the package website for comprehensive documentation, or explore the code at the GitHub repository .

Positron

The Air extension is now included in Positron by default, and will automatically keep itself up to date. We’ve been working hard to ensure that Air leaves a positive first impression, and we think that having Positron come batteries included with Air really helps with that! Positron now also ships with Ruff , the extremely fast Python formatter and linter, ensuring that you have a great editing experience out of the box, no matter which language you prefer.

We’ve also streamlined the process of adding Air to a new or existing project. With dev usethis, you can now run usethis::use_air() to automatically configure recommended Air settings. In particular, this will:

• Create an empty air.toml .

• Create .vscode/settings.json filled with the following settings. This enables Format on Save within your workspace.

  1 2 3 4 5 6

  { "[r]": { "editor.formatOnSave": true, "editor.defaultFormatter": "Posit.air-vscode" } }

• Create .vscode/extensions.json filled with the following settings. This automatically prompts contributors that don’t have the Air extension to install it when they open your workspace, ensuring that everyone is using the same formatter!

  1 2 3 4 5

  { "recommendations": [ "Posit.air-vscode" ] }

• Update your .Rbuildignore to exclude Air related configuration, if you’re working on an R package.

Once you’ve used usethis to configure Air, you can now immediately reformat your entire workspace by running Air: Format Workspace Folder from the Command Palette (accessible via Cmd + Shift + P on Mac/Linux, or Ctrl + Shift + P on Windows). I’ve found that this is invaluable for adopting Air in an existing project!

To summarize, we’ve reduced our advice on adding Air to an existing project down to:

• Open Positron

• Run usethis::use_air()

• Run Air: Format Workspace Folder

• Commit, push, and then enjoy using Format on Save forevermore 😄

More editors!

Positron isn’t the only editor that’s received some love! We now have official documentation for using Air in the following editors:

• Zed

• Neovim

• Helix

We’re very proud of the fact that Air can be used within any editor, not just RStudio and Positron! This documentation was a community effort - thanks in particular to @taplasz , @PMassicotte , @m-muecke , @TymekDev , and @wurli .

Autobracing

Autobracing is the process of adding braces (i.e.  { } ) to if statements, loops, and function definitions to create more consistent, readable, and portable code. It looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

for (i in seq_along(x)) x[[i]] <- x[[i]] + 1L

# Becomes:
for (i in seq_along(x)) {
  x[[i]] <- x[[i]] + 1L
}

function(x, y)
  call_that_spans_lines(
    x,
    y,
    fixed_option = FALSE
  )

# Becomes:
function(x, y) {
  call_that_spans_lines(
    x,
    y,
    fixed_option = FALSE
  )
}

It’s particularly important to autobrace multiline if statements for portability, which we roughly define as the ability to copy and paste that if statement into any context and have it still parse correctly. Consider the following if statement:

1
2
3
4
5
6

do_something <- function(this = TRUE) {
  if (this)
    do_this()
  else 
    do_that()
}

As written, this is correct R code, but if you were to pull out the if statement and place it in a file at “top level” and try to run it, you’d see a parse error:

1
2
3
4
5

if (this)
  do_this()
else 
  do_that()
#> Error: unexpected 'else'

In practice, this typically bites you when you’re debugging and you send a chunk of lines to the console:

Air autobraces this if statement to the following, which has no issues with portability:

1
2
3
4
5
6
7

do_something <- function(this = TRUE) {
  if (this) {
    do_this()
  } else {
    do_that()
  }
}

Give side effects some Air

We believe code that create side effects which modify state or affect control flow are important enough to live on their own line. For example, the following stop() call is an example of a side effect, so it moves to its own line and is autobraced:

1
2
3
4
5
6

if (anyNA(x)) stop("`x` can't contain missing values.")

# Becomes:
if (anyNA(x)) {
  stop("`x` can't contain missing values.")
}

You might be thinking, “But I like my single line if statements!” We do too! Air still allows single line if statements if they look to be used for their value rather than for their side effect. These single line if statements are still allowed:

1
2
3
4
5

x <- if (condition) this else that

x <- x %||% if (condition) this else that

list(a = if (condition) this else that)

Similarly, single line function definitions are also still allowed if they don’t already have braces and don’t exceed the line length:

1
2
3

add_one <- function(x) x + 1

bools <- map_lgl(xs, function(x) is.logical(x) && length(x) == 1L && !is.na(x))

For the full set of rules, check out our documentation on autobracing .

Empty braces

You may have noticed the following forced expansion of empty {} in previous versions of Air:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

dummy <- function() {}

# Previously became:
dummy <- function() {
}

tryCatch(fn, error = function(e) {})

# Previously became:
tryCatch(fn, error = function(e) {
})

my_fn(expr = {}, option = TRUE)

# Previously became:
my_fn(
  expr = {
  }, 
  option = TRUE
)

As of 0.7.0, empty braces {} are now never expanded, which retains the original form of each of these examples.

skip configuration

In our release post , we detailed how to disable formatting using a # fmt: skip comment for a single expression, or a # fmt: skip file comment for an entire file. Skip comments are useful for disabling formatting for one-off function calls, but sometimes you may find yourself repeatedly using functions from a domain specific language (DSL) that doesn’t follow conventional formatting rules. For example, the igraph package contains a DSL for constructing a graph from a literal representation:

1

igraph::graph_from_literal(A +-+ B +---+ C ++ D + E)

By default, Air would format this as:

1

igraph::graph_from_literal(A + -+B + ---+C + +D + E)

If you use graph_from_literal() often, it would be annoying to add # fmt: skip comments at every call site. Instead, air.toml now supports a skip field that allows you to specify function names that you never want formatting for. Specifying this would retain the original formatting of the graph_from_literal() call, even without a # fmt: skip comment:

1

skip = ["graph_from_literal"]

In the short term, you may also want to use this for tibble::tribble() calls, i.e. skip = ["tribble"]. In the long term, we’re hoping to provide more sophisticated tooling for formatting using a specified alignment .

GitHub Action

Air now has an official GitHub Action, setup-air . This action really only has one job - to get Air installed on your GitHub runner and put on the PATH. The basic usage is:

1
2

- name: Install Air
  uses: posit-dev/setup-air@v1

If you need to pin a version:

1
2
3
4

- name: Install Air 0.4.4
  uses: posit-dev/setup-air@v1
  with:
    version: "0.4.4"

From there, you can call Air’s CLI in downstream steps. A minimal workflow that errors if any files require formatting might look like:

1
2
3
4
5

- name: Install Air
  uses: posit-dev/setup-air@v1

- name: Check formatting
  run: air format . --check

Rather than creating the workflow file yourself, we instead recommend using usethis to pull in our example workflow :

1

usethis::use_github_action(url = "https://github.com/posit-dev/setup-air/blob/main/examples/format-suggest.yaml")

This is a special workflow that runs on pull requests. It calls air format and then uses reviewdog/action-suggester to push any formatting diffs as GitHub Suggestion comments on your pull request. It looks like this:

You can accept all suggestions in a single batch, which will then rerun the format check, along with any other GitHub workflows (like an R package check), so you can feel confident that accepting the changes hasn’t broken anything.

We like this workflow because it provides an easy way for external contributors who aren’t using Air to still abide by your formatting rules. The external contributor can even accept the suggestions themselves, so by the time you look at their pull request it’s already good to go from a formatting perspective ✅!

Acknowledgements

A big thanks to the 49 users who helped make this release possible by finding bugs, discussing issues, contributing documentation, and writing code: @adisarid , @aronatkins , @ateucher , @avhz , @aymennasri , @christophe-gouel , @dkStevensNZed , @eitsupi , @ELICHOS , @fh-mthomson , @fzenoni , @gaborcsardi , @grasshoppermouse , @hadley , @idavydov , @j-dobner , @jacpete , @jeffkeller-einc , @jhk0530 , @joakimlinde , @JosephBARBIERDARNAL , @JosiahParry , @kkanden , @krlmlr , @Kupac , @kv9898 , @lcolladotor , @lulunac27a , @m-muecke , @maelle , @matanhakim , @njtierney , @novica , @ntluong95 , @philibe , @PMassicotte , @RobinKohrs , @salim-b , @sawelch-NIVA , @schochastics , @Sebastian-T-T , @stevenpav-helm , @t-kalinowski , @taplasz , @tbadams45cdm , @wurli , @xx02al , @Yunuuuu , and @yutannihilation .

(An updated version of this blog post will be available at the systemfonts webpage )

The purpose of this document is to give you a thorough overview of fonts in R. However, for this to be possible, you’ll first need a basic understanding of fonts in general. If you already have a thorough understanding of digital typography you can skip to the next section .

Digital typography

Many books could be, and have been, written about the subject of typography. This blog post is not meant to be an exhaustive deep dive into all areas of this vast subject. Rather, it is meant to give you just enough understanding of core concepts and terminology to appreciate how it all plays into using fonts in R.

Typeface or font?

There is a good chance that you, like 99% of world, use “font” as the term describing “the look” of the letters you type. You may, perhaps, have heard the term “typeface” as well and thought it synonymous. This is in fact slightly wrong, and a great deal of typography snobbery has been dealt out on that account (much like the distinction between packages and libraries in R). It is a rather inconsequential mix-up for the most part, especially because 99% of the population wouldn’t bat an eye if you use them interchangeably. However, the distinction between the two serves as a good starting point to talk about other terms in digital typography as well as the nature of font files, so let’s dive in.

When most people use the word “font” or “font family”, what they are actually describing is a typeface. A typeface is a style of lettering that forms a cohesive whole. As an example, consider the well-known “Helvetica” typeface. This name embraces many different weights (bold, normal, light) as well as slanted (italic) and upright. However, all of these variations are all as much Helvetica as the others - they are all part of the same typeface.

A font is a subset of a typeface, describing a particular variation of the typeface, i.e. the combination of weight, width, and slant that comes together to describe the specific subset of a typeface that is used. We typically give a specific combination of these features a name, like “bold” or “medium” or “italic”, which we call the font style¹. In other words, a font is a particularly style within a typeface.

Different fonts from the Avenir Next typeface

In the rest of this document we will use the terms typeface and font with the meaning described above.

Font files

Next, we need to talk about how typefaces are represented for use by computers. Font files record information on how to draw the individual glyphs (characters), but also instructions about how to draw sequences of glyphs like distance adjustments (kerning) and substitution rules (ligatures). Font files typically encode a single font but can encode a full typeface:

typefaces <- systemfonts::system_fonts()[, c("path", "index", "family", "style")]

# Full typeface in one file
typefaces[typefaces$family == "Helvetica", ]
#> # A tibble: 6 × 4
#>   path                                index family    style        
#>   <chr>                               <int> <chr>     <chr>        
#> 1 /System/Library/Fonts/Helvetica.ttc     2 Helvetica Oblique      
#> 2 /System/Library/Fonts/Helvetica.ttc     4 Helvetica Light        
#> 3 /System/Library/Fonts/Helvetica.ttc     5 Helvetica Light Oblique
#> 4 /System/Library/Fonts/Helvetica.ttc     1 Helvetica Bold         
#> 5 /System/Library/Fonts/Helvetica.ttc     3 Helvetica Bold Oblique 
#> 6 /System/Library/Fonts/Helvetica.ttc     0 Helvetica Regular

# One font per font file
typefaces[typefaces$family == "Arial", ]
#> # A tibble: 4 × 4
#>   path                                                     index family style      
#>   <chr>                                                    <int> <chr>  <chr>      
#> 1 /System/Library/Fonts/Supplemental/Arial.ttf                 0 Arial  Regular    
#> 2 /System/Library/Fonts/Supplemental/Arial Bold.ttf            0 Arial  Bold       
#> 3 /System/Library/Fonts/Supplemental/Arial Bold Italic.ttf     0 Arial  Bold Italic
#> 4 /System/Library/Fonts/Supplemental/Arial Italic.ttf          0 Arial  Italic

Here, each row is a font, with family giving the name of the typeface, and style the font style.

It took a considerable number of tries before the world managed to nail the digitial representation of fonts, leading to a proliferation of file types. As an R user, there are three formats that are particularly improtant:

• TrueType (ttf/ttc). Truetype is the baseline format that all modern formats stand on top of. It was developed by Apple in the ’80s and became popular due to its great balance between size and quality. Fonts can be encoded, either as scalable paths, or as bitmaps of various sizes, the former generally being preferred as it allows for seamless scaling and small file size at the same time.

• OpenType (otf/otc). OpenType was created by Microsoft and Adobe to improve upon TrueType. While TrueType was a great success, the number of glyphs it could contain was limited and so was its support for selecting different features during shaping . OpenType resolved these issues, so if you want access to advanced typography features you’ll need a font in OpenType format.

• Web Open Font Format (woff/woff2). TrueType and OpenType tend to create large files. Since a large percentage of the text consumed today is delivered over the internet this creates a problem. WOFF resolves this problem by acting as a compression wrapper around TrueType/OpenType to reduce file sizes while also limiting the number of advanced features provided to those relevant to web fonts. The woff2 format is basically identical to woff except it uses the more efficient brotli compression algorithm. WOFF was designed specifically to be delivered over the internet and support is still a bit limited outside of browsers.

While we have mainly talked about font files as containers for the shape of glyphs, they also carries a lot of other information needed for rendering text in a way pleasant for reading. Font level information records a lot of stylistic information about typeface/font, statistics on the number of glyphs and how many different mappings between character encodings and glyphs it contains, and overall sizing information such as the maximum descend of the font, the position of an underline relative to the baseline etc. systemfonts provdies a convenient way to access this data from R:

dplyr::glimpse(systemfonts::font_info(family = "Helvetica"))
#> Rows: 1
#> Columns: 24
#> $ path               <chr> "/System/Library/Fonts/Helvetica.ttc"
#> $ index              <int> 0
#> $ family             <chr> "Helvetica"
#> $ style              <chr> "Regular"
#> $ italic             <lgl> FALSE
#> $ bold               <lgl> FALSE
#> $ monospace          <lgl> FALSE
#> $ weight             <ord> normal
#> $ width              <ord> normal
#> $ kerning            <lgl> FALSE
#> $ color              <lgl> FALSE
#> $ scalable           <lgl> TRUE
#> $ vertical           <lgl> FALSE
#> $ n_glyphs           <int> 2252
#> $ n_sizes            <int> 0
#> $ n_charmaps         <int> 10
#> $ bbox               <list> <-11.406250, 17.343750, -5.765625, 13.453125>
#> $ max_ascend         <dbl> 9.234375
#> $ max_descend        <dbl> -2.765625
#> $ max_advance_width  <dbl> 18
#> $ max_advance_height <dbl> 12
#> $ lineheight         <dbl> 12
#> $ underline_pos      <dbl> -1.203125
#> $ underline_size     <dbl> 0.59375

Further, for each glyph there is a range of information in addition to its shape:

systemfonts::glyph_info("j", family = "Helvetica", size = 30)
#> # A tibble: 1 × 9
#>   glyph index width height x_bearing y_bearing x_advance y_advance bbox     
#>   <chr> <int> <dbl>  <dbl>     <dbl>     <dbl>     <dbl>     <dbl> <list>   
#> 1 j        77     6     27        -1        21         7         0 <dbl [4]>

These terms are more easily understood with a diagram:

The x_advance in particular is important when rendering text because it tells you how far to move to the right before rendering the next glyph (ignoring for a bit the concept of kerning)

Text shaping

The next important concept to understand is text shaping, which, in the simplest of terms, is to convert a succession of characters into a sequence of glyphs along with their locations. Important here is the distinction between characters, the things you think of as letters, and glyphs, which is what the font will draw. For example, think of the character “f”, which is often tricky to draw because the “hook” of the f can interfere with other characters. To solve this problem, many typefaces include ligatures, like “fi”, which are used for specific pairs of characaters. Ligatures are extremely important for languages like Arabic.

A few of the challenges of text shaping include kerning, bidirectional text, and font substitution. Kerning is the adjustment of distance between specific pairs of characters. For example, you can put “VM” a little closer together but “OO” needs to be a little further apart. Kerning is an integral part of all modern text rendering and you will almost solemnly notice it when it is absent (or worse, wrongly applied ).

Not every language writes text in the same direction, but regardless of your native script, you are likely to use arabic numerals which are always written left-to-right. This gives rise to the challenge of bidirectional (or bidi) text, which mixes text flowing in different directions. This imposes a whole new range of challenges!

Finally, you might request a character that a font doesn’t contain. One way to deal with this is to render a glyph representing a missing glyph, usually an empty box or a question mark. But it’s typically more useful to use the correct glyph from a different font. This is called font fallback and happens all the time for emojis, but can also happen when you suddenly change script without bothering to pick a new font. Font fallback is an imprecise science, typically relying on an operating system font that has a very large number of characters, but might look very different from your existing font.

Once you have determined the order and location of glyphs, you are still not done. Text often needs to be wrapped to fit into a specific width, it may need a specific justification, perhaps, indentation or tracking must be applied, etc. Thankfully, all of this is generally a matter of (often gnarly) math that you just have to get right. That is, all except text wrapping which should happen at the right boundaries, and may need to break up a word and inserting a hyphen etc.

Like I said, the pit of despair is bottomless…

Font handling in R

You hopefully arrive at this section with an appreciation of the horrors that goes into rendering text. If not, maybe this blog post will convince you.

Are you still here? Good.

Now that you understand the basics of what goes into handling fonts and text, we can now discuss the details of fonts in R specifically.

Fonts and text from a user perspective

The users perception of working with fonts in R is largely shaped by plots. This means using either base or grid graphics or one of the packages that have been build on top of it, like ggplot2 . While the choice of tool will affect where you specify the font to use, they generally agree on how to specify it.

From the table it is clear that in R fontfamily/family is used to describe the typeface and font/fontface/face is used to select a font from the typeface. Size settings is just a plain mess.

The major limitation in fontface (and friends) is that it takes a number, not a string, and you can only select from four options: 1: plain, 2: bold, 3: italic, and 4: bold-italic. This means, for example, that there’s no way to select Futura Condensed Extra Bold. Another limitation is that it’s not possible to specify any font variations such as using tabular numbers or stylistic ligatures.

Fonts and text from a graphics device perspective

In R, a graphics device is the part responsible for doing the rendering you request and put it on your screen or in a file. When you call png() or ragg::agg_png() you open up a graphics device that will receive all the plotting instructions from R. Both graphics devices will ultimately produce the same file type (PNG), but how they choose to handle and respond to the plotting instructions may differ (greatly). Nowhere is this difference more true than when it comes to text rendering.

After a user has made a call that renders some text, it is funneled through the graphic system (base or grid), handed off to the graphics engine, which ultimately asks the graphics device to render the text. From the perspective of the graphics device it is much the same information that the user provided which are presented to it. The text() method of the device are given an array of characters, the typeface, the size in points, and an integer denoting if the style is regular, bold, italic, or bold-italic.

This means that it is up to the graphics device to find the approprate font file (using the provided typeface and font style) and shape the text with all that that entails. This is a lot of work, which is why text is handled so inconsistently between graphics devices. Issues can range from not being able to find fonts installed on the computer, to not providing font fallback mechanisms, or even handling right-to-left text. It may also be that certain font file formats are not well supported so that e.g. color emojis are not rendered correctly.

There have been a number of efforts to resolve these problems over the years:

• extrafont: Developed by Winston Chang, extrafont sought to mainly improve the situation for the pdf() device which generally only had access to the postscript fonts that comes with R. The package allows the pdf() device to get access to TrueType fonts installed on the computer, as well as provide means for embedding the font into the PDF so that it can be opened on systems where the font is not installed. (It also provides the capabilities to the Windows png() device).

• sysfonts and showtext. These packages are developed by Yixuan Qiu and provide support for system fonts to all graphics devices, by hijacking the text() method of the graphics device to treat text as polygons or raster images. This guarantees your plots will look the same on every device, but it doesn’t do advanced text shaping, so there’s no support for ligatures or font substitution. Additionally, it produces large files with inaccessible text when used to produce pdf and svg outputs.

• systemfonts and textshaping. These packages are developed by me to provide a soup-to-nuts solution to text rendering for graphics devices. systemfonts provides access to fonts installed on the system along with font fallback mechanisms, registration of non-system fonts, reading of font files etc. textshaping builds on top of systemfonts and provides a fully modern engine for shaping text. The functionality is exposed both at the R level and at the C level, so that graphics devices can directly access to font lookup and shaping.

We will fosus on systemfonts, because it’s designed to give R a modern text rendering stack. That’s unfortunately impossible without coordination with the graphics device, which means that to use all these features you need a supported graphics device. There are currently two options:

• The ragg package provides graphics devices for rendering raster graphics in a variety of formats (PNG, JPEG, TIFF) and uses systemfonts and textshaping extensively.
• The svglite package provides a graphic device for rendering vector graphics to SVG using systemfonts and textshaping for text.

You might notice there’s currently a big hole in this workflow: PDFs. This is something we plan to work on in the future.

A systemfonts based workflow

With all that said, how do you actually use systemfonts to use custom fonts in your plots? First, you’ll need to use ragg or svglite.

Using ragg

While there is no way to unilaterally make ragg::agg_png() the default everywhere, it’s possible to get close:

• Positron: recent versions automatically use ragg for the plot pane if it’s installed.

• RStudio IDE: set “AGG” as the backend under Global Options > General > Graphics.

• ggplot2::ggsave() : ragg will be automatically used for raster output if installed.

• R Markdown and Quarto: you need to set the dev option to "ragg_png". You can either do this with code:

  1 2	#| include: false knitr::opts_chunk$set(dev = "ragg_png")

  Or in Quarto, you can set it in the yaml metadata:

  1 2 3 4 5 6 7

  --- title: "My Document" format: html knitr: opts_chunk: dev: "ragg_png" ---

If you want to use a font installed on your computer, you’re done!

grid::grid.text(
  "FUTURA 🎉",
  gp = grid::gpar(fontfamily = "Futura", fontface = 3, fontsize = 30)
)

Or, if using ggplot2

ggplot(na.omit(penguins)) +
  geom_point(aes(x = bill_len, y = body_mass, colour = species)) +
  labs(x = "Bill Length", y = "Body Mass", colour = "Species") +
  theme_minimal(base_family = "Futura")

If the results don’t look as you expect, you can use various systemfonts helpers to diagnose the problem:

systemfonts::match_fonts("Futura", weight = "bold")
#> # A tibble: 1 × 3
#>   path                                          index features  
#>   <chr>                                         <int> <list>    
#> 1 /System/Library/Fonts/Supplemental/Futura.ttc     2 <font_ftr>
systemfonts::font_fallback("🎉", family = "Futura", weight = "bold")
#>                                          path index
#> 1 /System/Library/Fonts/Apple Color Emoji.ttc     0

If you want to see all the fonts that are available for use, you can use systemfonts::system_fonts()

systemfonts::system_fonts()

#> # A tibble: 570 × 9
#>    path                                         index name  family style weight width italic monospace
#>    <chr>                                        <int> <chr> <chr>  <chr> <ord>  <ord> <lgl>  <lgl>    
#>  1 /System/Library/Fonts/Supplemental/Rockwell…     2 Rock… Rockw… Bold  bold   norm… FALSE  FALSE    
#>  2 /System/Library/Fonts/Noteworthy.ttc             0 Note… Notew… Light normal norm… FALSE  FALSE    
#>  3 /System/Library/Fonts/Supplemental/Devanaga…     1 Deva… Devan… Bold  bold   norm… FALSE  FALSE    
#>  4 /System/Library/Fonts/Supplemental/Kannada …     0 Kann… Kanna… Regu… normal norm… FALSE  FALSE    
#>  5 /System/Library/Fonts/Supplemental/Verdana …     0 Verd… Verda… Bold  bold   norm… FALSE  FALSE    
#>  6 /System/Library/Fonts/ArialHB.ttc                8 Aria… Arial… Light light  norm… FALSE  FALSE    
#>  7 /System/Library/Fonts/AppleSDGothicNeo.ttc      10 Appl… Apple… Thin  thin   norm… FALSE  FALSE    
#>  8 /System/Library/Fonts/Supplemental/DecoType…     0 Deco… DecoT… Regu… normal norm… FALSE  FALSE    
#>  9 /System/Library/Fonts/Supplemental/Trebuche…     0 Treb… Trebu… Ital… normal norm… TRUE   FALSE    
#> 10 /System/Library/Fonts/Supplemental/Khmer MN…     0 Khme… Khmer… Regu… normal norm… FALSE  FALSE    
#> # ℹ 560 more rows

Extra font styles

As we discussed above, the R interface only allows you to select between four styles: plain, italic, bold, and bold-italic. If you want to use a thin font, you have no way of communicating this wish to the device. To overcome this, systemfonts provides register_variant() which allows you to register a font with a new typeface name. For example, to use the thin font from the Avenir Next typeface you can register it as follows:

systemfonts::register_variant(
  name = "Avenir Thin",
  family = "Avenir Next",
  weight = "thin"
)

Now you can use Avenir Thin where you would otherwise specify the typeface:

grid::grid.text(
  "Thin weight is soo classy",
  gp = grid::gpar(fontfamily = "Avenir Thin", fontsize = 30)
)

register_variant() also allows you to turn on font features otherwise hidden away:

systemfonts::register_variant(
  name = "Avenir Small Caps",
  family = "Avenir Next",
  features = systemfonts::font_feature(
    letters = "small_caps"
  )
)
grid::grid.text(
  "All caps — Small caps",
  gp = grid::gpar(fontfamily = "Avenir Small Caps", fontsize = 30)
)

Fonts from other places

Historically, systemfonts primary role was to access the font installed on your computer, the system fonts. But what if you’re using a computer where you don’t have the rights to install new fonts, or you don’t want the hassle of installing a font just to use it for a single plot? That’s the problem solved by systemfonts::add_font() which makes it easy to use a font based on a path. But in many cases you don’t even need that as systemfont now scans ./fonts and ~/fonts and adds any font files it find. This means that you can put personal fonts in a fonts folder in your home directory, and project fonts in a fonts directory at the root of the project. This is a great way to ensure that specific fonts are available when you deploy some code to a server.

And you don’t even need to leave R to populate these folders. systemfonts::get_from_google_fonts() will download and install a google font in ~/fonts:

systemfonts::get_from_google_fonts("Barrio")

grid::grid.text(
  "A new font a day keeps Tufte away",
  gp = grid::gpar(fontfamily = "Barrio", fontsize = 30)
)

And if you want to make sure this code works for anyone using your code (regardless of whether or not they already have the font installed), you can use systemfonts::require_font() . If the font isn’t already installed, this function download it from one of the repositories it knows about. If it can’t find it it will either throw an error (the default) or remap the name to another font so that plotting will still succeed.

systemfonts::require_font("Rubik Distressed")
#> Trying Google Fonts... Found! Downloading font to /var/folders/l4/tvfrd0ps4dqdr2z7kvnl9xh40000gn/T//Rtmp2qw4bE

grid::grid.text(
  "There are no bad fonts\nonly bad text",
  gp = grid::gpar(fontfamily = "Rubik Distressed", fontsize = 30)
)

By default, require_font() places new fonts in a temporary folder so it doesn’t pollute your carefully curated collection of fonts.

Font embedding in SVG

Fonts work a little differently in vector formats like SVG. These formats include the raw text and only render the font when you open the file. This makes for small, accessible files with crisp text at every level of zoom. But it comes with a price: since the text is rendered when it’s opened, it relies on the font in use being available on the viewer’s computer. This obviously puts you at the mercy of their font selection, so if you want consistent outputs you’ll need to embed the font.

In SVG, you can embed fonts using an @import statement in the stylesheet, and can point to a web resource so the SVG doesn’t need to contain the entire font. systemfonts provides facilities to generate URLs for import statements and can provide them in a variety of formats:

systemfonts::fonts_as_import("Barrio")
#> [1] "https://fonts.bunny.net/css2?family=Barrio&display=swap"
systemfonts::fonts_as_import("Rubik Distressed", type = "link")
#> [1] "<link rel=\"stylesheet\" href=\"https://fonts.bunny.net/css2?family=Rubik+Distressed&display=swap\"/>"

Further, if the font is not available from an online repository, it can embed the font data directly into the URL:

substr(systemfonts::fonts_as_import("Chalkduster"), 1, 200)
#> [1] "data:text/css,@font-face%20%7B%0A%20%20font-family:%20%22Chalkduster%22;%0A%20%20src:%20url(data:font/ttf;charset=utf-8;base64,AAEAAAAMAIAAAwC4T1MvMmk8+wsAAAFIAAAAYGNtYXBJhgfNAAAEOAAACspnbHlmLDPYGwAAf"

svglite uses this feature to allow seamless font embedding with the web_fonts argument. It can take a URL as returned by fonts_as_import() or just the name of the typeface and the URL will automatically be resolved. Look at line 6 in the SVG generated below

svg <- svglite::svgstring(web_fonts = "Barrio")
grid::grid.text("Example", gp = grid::gpar(fontfamily = "Barrio"))
invisible(dev.off())
svg()
#> <?xml version='1.0' encoding='UTF-8' ?>
#> <svg xmlns='http://www.w3.org/2000/svg' xmlns:xlink='http://www.w3.org/1999/xlink' width='720.00pt' height='576.00pt' viewBox='0 0 720.00 576.00'>
#> <g class='svglite'>
#> <defs>
#>   <style type='text/css'><![CDATA[
#>     @import url('https://fonts.bunny.net/css2?family=Barrio&display=swap');
#>     .svglite line, .svglite polyline, .svglite polygon, .svglite path, .svglite rect, .svglite circle {
#>       fill: none;
#>       stroke: #000000;
#>       stroke-linecap: round;
#>       stroke-linejoin: round;
#>       stroke-miterlimit: 10.00;
#>     }
#>     .svglite text {
#>       white-space: pre;
#>     }
#>     .svglite g.glyphgroup path {
#>       fill: inherit;
#>       stroke: none;
#>     }
#>   ]]></style>
#> </defs>
#> <rect width='100%' height='100%' style='stroke: none; fill: #FFFFFF;'/>
#> <defs>
#>   <clipPath id='cpMC4wMHw3MjAuMDB8MC4wMHw1NzYuMDA='>
#>     <rect x='0.00' y='0.00' width='720.00' height='576.00' />
#>   </clipPath>
#> </defs>
#> <g clip-path='url(#cpMC4wMHw3MjAuMDB8MC4wMHw1NzYuMDA=)'>
#> <text x='360.00' y='292.32' text-anchor='middle' style='font-size: 12.00px; font-family: "Barrio";' textLength='48.12px' lengthAdjust='spacingAndGlyphs'>Example</text>
#> </g>
#> </g>
#> </svg>

Want more?

This document has mainly focused on how to use the fonts you desire from within R. R has other limitations when it comes to text rendering specifically how to render text that consists of a mix of fonts. This has been solved by marquee and the curious soul can continue there in order to up their skills in rendering text with R

grid::grid.draw(
  marquee::marquee_grob(
    "_This_ **is** the {.red end}",
    marquee::classic_style(base_size = 30)
  )
)

We’re excited to announce that S7 v0.2.0 is now available on CRAN! S7 is a new object-oriented programming (OOP) system designed to supersede both S3 and S4. You might wonder why R needs a new OOP system when we already have two. The reason lies in the history of R’s OOP journey: S3 is a simple and effective system for single dispatch, while S4 adds formal class definitions and multiple dispatch, but at the cost of complexity. This has forced developers to choose between the simplicity of S3 and the sophistication of S4.

The goal of S7 is to unify the OOP landscape by building on S3’s existing dispatch system and incorporating the most useful features of S4 (along with some new ones), all with a simpler syntax. S7’s design and implementation have been a collaborative effort by a working group from the R Consortium , including representatives from R-Core, Bioconductor, tidyverse/Posit, ROpenSci, and the wider R community. Since S7 builds on S3, it is fully compatible with existing S3-based code. It’s also been thoughtfully designed to work with S4, and as we learn more about the challenges of transitioning from S4 to S7, we’ll continue to add features to ease this process.

Our long-term goal is to include S7 in base R, but for now, you can install it from CRAN:

install.packages("S7")

What’s new in the second release

The second release of S7 brings refinements and bug fixes. Highlights include:

• Support for lazy property defaults, making class setup more flexible.
• Custom property setters now run on object initialization.
• Significant speed improvements for setting and getting properties with @ and @<-.
• Expanded compatibility with base S3 classes.
• convert() now provides a default method for transforming a parent class into a subclass.

Additionally, there are numerous bug fixes and quality-of-life improvements, such as better error messages, improved support for base Ops methods, and compatibility improvements for using @ in R versions prior to 4.3. You can see a full list of changes in the release notes .

Who should use S7

S7 is a great fit for R users who like to try new things but don’t need to be the first. It’s already used in several CRAN packages, and the tidyverse team is applying it in new projects. While you may still run into a few issues, many early problems have been resolved.

Usage

library(S7)

Let’s dive into the basics of S7. To learn more, check out the package vignettes, including a more detailed introduction in vignette("S7") , and coverage of generics and methods in vignette("generics-methods") , and classes and objects in vignette("classes-objects") .

Classes and objects

S7 classes have formal definitions, specified by new_class() , which includes a list of properties and an optional validator. For example, the following code creates a Range class with start and end properties, and a validator to ensure that start is always less than end:

Range <- new_class("Range",
  properties = list(
    start = class_double,
    end = class_double
  ),
  validator = function(self) {
    if (length(self@start) != 1) {
      "@start must be length 1"
    } else if (length(self@end) != 1) {
      "@end must be length 1"
    } else if (self@end < self@start) {
      "@end must be greater than or equal to @start"
    }
  }
)