We’ve now talked about tools (functions) and harnesses (a system for running tools on behalf of the LLM). And you know that an agent is a harness with tools for reading and writing. So what makes an agent a coding agent? The answer is the specific tools that it supplies: ones that let an LLM explore and edit a codebase the same way a human would.

Most coding agents provide some variation on the following tools:

• Read file: read the contents of a file, or a subset of one.

• Write file: create a new file with fresh content.

• Edit file: make a targeted change to an existing file, usually by replacing one chunk of text with another.

• List files: show the files and directories at a given path so the agent can orient itself in the project structure.

• Search: find lines matching a pattern across the codebase so the agent can locate relevant code quickly.

• Run command: execute an arbitrary shell command, which allows the agent to do anything else it might need.

A good coding agent also usually contains a big prompt with advice about good practices. While these prompts are not open source, they are fairly easy to sniff out, so various folks have extracted them. It’s informative to take a look just to get a sense of how complex they are.

Building a minimal coding agent

Of the six tools above, only three are really essential for a basic coding agent. To prove it, I’m going to build a tiny coding agent in R with ellmer. We’ll start ruthlessly minimal — with just read file, write file, and run command — and then work our way up. We’ll lose some niceties, but in exchange we get something you can read in one sitting.

First, the three tool functions. I’ve written them with deliberately boring R:

read_file <- function(path) {
  paste(readLines(path), collapse = "\n")
}

write_file <- function(path, content) {
  writeLines(content, path)
  paste0("Wrote ", path, ".")
}

run_command <- function(command) {
  paste(system(command, intern = TRUE), collapse = "\n")
}

Each function returns a string which is fed back to the LLM as the result of the tool call: read_file returns the file’s contents, write_file confirms what it did, and run_command returns whatever the command printed to the console.

Next we create a chat and register the three functions as tools. As before, the descriptions matter: they tell the LLM when and how to reach for each tool. We also include a very basic prompt.

library(ellmer)
#> Warning: replacing previous import 'S7:::=' by 'rlang:::=' when loading
#> 'ellmer'
chat <- chat_anthropic(
  system_prompt = "
    You are a coding assistant working in the user's current directory.
    Use the tools to explore and modify their project. Before editing a
    file, read it first. After making changes, run any relevant tests or
    checks to confirm your work. Keep going until the task is done.
  "
)
#> Using model = "claude-sonnet-4-5-20250929".

chat$register_tool(tool(
  read_file,
  description = "Read the entire contents of a text file.",
  arguments = list(
    path = type_string("Path to the file, relative to the working directory.")
  )
))

chat$register_tool(tool(
  write_file,
  description = "Write content to a file, overwriting it if it already exists.
    Always read the file first if you only want to change part of it.",
  arguments = list(
    path = type_string("Path to the file, relative to the working directory."),
    content = type_string("The full new contents of the file.")
  )
))

chat$register_tool(tool(
  run_command,
  description = "Run a shell command and return its output. Use this to list
    files (ls), search code (grep), run tests, or use git.",
  arguments = list(
    command = type_string("The shell command to run.")
  )
))

And that’s the whole agent!

The shell tool is our “get out of jail free” card because if you can run a shell command you can do anything: you can call ls to list directories, grep to search for code, Rscript to run R code, and git for git. (Technically we don’t even need read and write tools because the agent could use echo and cat, but we’re going to throw the agent a bone here.) The shell tool is also rather dangerous; we’ll come back to that later.

You can now use this agent for a simple task:

chat$chat("Find the function that parses dates and add a unit test for it.")

Behind the scenes the model might use run_command to grep for the function then read_file to study it. Next, to create the test, it will need to read the existing test files with read_file, then write_file to add the new test, and finish up by using run_command to run the test suite. It’s no Claude Code, but it’s in the same galaxy.

Finding files: list and search

Our minimal agent can already list and search files via run_command, but leaning on the shell for everything has downsides. Shell commands vary between platforms (Windows doesn’t have ls or grep) and their output is noisy. More importantly, handing the model a general-purpose shell is a security nightmare: it’s very difficult to tell if a specific shell command is safe or dangerous. It’s much easier to add safeguards to stricter tools.

Let’s see what that might look like by implementing list and search tools, then seeing how we could make them safer.

list_files <- function(path = ".") {
  paste(list.files(path), collapse = "\n")
}

search_files <- function(pattern, path = ".") {
  files <- list.files(path, recursive = TRUE, full.names = TRUE)
  hits <- character()
  for (file in files) {
    lines <- readLines(file, warn = FALSE)
    matches <- grep(pattern, lines)
    hits <- c(hits, paste0(file, ":", matches, ": ", lines[matches]))
  }
  paste(hits, collapse = "\n")
}

And then add them to our harness:

chat$register_tool(tool(
  list_files,
  description = "List the files and directories at a given path.",
  arguments = list(
    path = type_string("Directory to list. Defaults to the working directory.")
  )
))

chat$register_tool(tool(
  search_files,
  description = "Search the contents of all files for a regular expression,
    returning matching lines as 'path:line: text'.",
  arguments = list(
    pattern = type_string("A regular expression to search for."),
    path = type_string("Directory to search. Defaults to the working directory.")
  )
))

Keeping it safe

These list and search tools are easier to make safe than a general shell, because they have simpler inputs. But they’re not automatically safe: there’s nothing stopping the model passing path = ".." or an absolute path like /etc, so our “search the project” tool could happily read your entire hard drive, including your passwords.

Let’s make them safer by checking that paths stay within the project directory. We resolve the path (which collapses .. and follows symlinks) and check that it still sits underneath the working directory:

safe_path <- function(path) {
  root <- normalizePath(".", winslash = "/", mustWork = TRUE)
  full <- normalizePath(path, winslash = "/", mustWork = FALSE)
  within_root <- full == root || startsWith(full, paste0(root, "/"))

  if (!within_root) {
    stop("Path is outside the project directory: ", path)
  }
  path
}

It’s also worth verifying that they can’t read the .Renviron file, where R programmers conventionally stash API keys and other secrets. Luckily we get that for free: list.files() defaults to all.files = FALSE, which skips dotfiles, so .Renviron, .Rhistory, and the contents of .git/ are already excluded from our search.

Putting both together, search_files becomes:

search_files <- function(pattern, path = ".") {
  files <- list.files(safe_path(path), recursive = TRUE, full.names = TRUE)

  hits <- character()
  for (file in files) {
    lines <- readLines(file, warn = FALSE)
    matches <- grep(pattern, lines)
    hits <- c(hits, paste0(file, ":", matches, ": ", lines[matches]))
  }
  paste(hits, collapse = "\n")
}

The same safe_path() wrapper belongs on read_file, write_file, and list_files too; otherwise the model can still reach outside the project by reading or writing a file directly.

Making it efficient

The biggest weakness of our minimal agent is that the only way to change a file is to rewrite it from scratch with write_file. For a 500-line file where you want to change one line, that means the model has to reproduce all 500 lines perfectly — slow, expensive, and challenging for today’s models. The fix is a targeted edit tool that swaps one chunk of text for another:

edit_file <- function(path, old, new) {
  path <- safe_path(path)
  content <- paste(readLines(path), collapse = "\n")

  if (!grepl(old, content, fixed = TRUE)) {
    stop("Could not find the text to replace in ", path, ".")
  }

  content <- sub(old, new, content, fixed = TRUE)
  writeLines(content, path)
  paste0("Edited ", path, ".")
}

chat$register_tool(tool(
  edit_file,
  description = "Replace an exact span of text in a file with new text. The
    'old' text must appear exactly once in the file. Prefer this over
    write_file for changing part of an existing file.",
  arguments = list(
    path = type_string("Path to the file to edit."),
    old = type_string("The exact existing text to replace."),
    new = type_string("The text to replace it with.")
  )
))

This is useful for two reasons. First, the model only has to write the few lines that change, not the whole file, so it’s both faster and cheaper. Second, it’s much safer: because the old text has to match exactly, a botched edit fails loudly instead of silently corrupting the file. This is exactly how the edit tools in real coding agents work, give or take some cleverness with whitespace, safeguards against multiple matches, and detecting when a human is also editing the file.

Next we’ll we come back to the topic of security in more detail, and explore the approaches you can use to make general tools (like running a shell command) as safe as possible.

But my definition of tools contained a deliberate simplification that I want to dig into this week. Previously, I said tools run on your computer, but that’s not generally true: tools are run by the harness. In many cases (like with ellmer or a coding agent), the harness runs locally, but when using web chat (like claude.ai or chatgpt.com), the harness runs on the server.

Multiplying numbers

Let’s explore what that means, starting with a simple example using a bare ellmer chat with no tools. What happens if we ask it to multiply two large numbers, a task that we know LLMs are not good at?

library(ellmer)

x <- 20598162
y <- 83106206

chat <- chat_openai()
chat$chat(interpolate("What's {{x}} * {{y}}?"))
#> The product of **20,598,162** and **83,106,206** is:
#> 
#> **1,711,067,239,026,172**

We can check the answer with R, which does know how to multiply correctly. This reveals that the model was confidently wrong:

format(x * y, big.mark = ",", scientific = FALSE)
#> [1] "1,711,835,094,393,372"

However, if you ask this same question on chatgpt.com or claude.ai, they both get it right. Why? Because the web chats are also harnesses that come with a variety of useful tools. One of those tools is a calculator, because both OpenAI and Anthropic know that LLMs are bad at math.

We can give our ellmer chat a similar tool. First we’ll implement a basic calculator function that takes a mathematical expression as a string and returns the result:

calculator <- function(code) {
  math_env <- new.env(parent = emptyenv())
  math_env$`+` <- `+`
  math_env$`-` <- `-`
  math_env$`*` <- `*`
  math_env$`/` <- `/`
  math_env$`^` <- `^`
  math_env$`(` <- `(`
  math_env$sqrt <- sqrt
  math_env$exp <- exp
  math_env$log <- log

  eval(parse(text = code), envir = math_env)
}

calculator("15 * 11")
#> [1] 165
calculator("read.csv('foo.bar')")
#> Error in `read.csv()`:
#> ! could not find function "read.csv"

This code uses some environment and evaluation magic (which you can learn more about in Advanced R) to restrict R to a set of safe operations. In the future, I’ll talk about why you might want to free this up to run any R code and how you can do that (mostly) safely.

Next we register the function as a tool. Note that we give some advice to the LLM on when to use it. Like with all LLM prompting, there’s no guarantee that the LLM will listen, but it’s likely to help (in the sense that the average quality of responses with the tool should be better than without it).

chat <- chat_openai()
#> Using model = "gpt-4.1".
chat$register_tool(tool(
  calculator,
  description = "Evaluate a mathematical expression.
    Use this for any arithmetic, since you can't reliably compute it yourself.
    Supports +, -, *, /, ^, parentheses, sqrt(), exp(), and log(), following 
    standard precedence rules.",
  arguments = list(
    code = type_string(
      "Mathematical expression to evaluate, e.g. '1 + 2 * 3'."
    )
  )
))

Now if we re-ask the same question we get the right result!

chat$chat(interpolate("What's {{x}} * {{y}}?"))
#> ◯ [tool call] calculator(code = "20598162 * 83106206")
#> ● #> 1711835094393372
#> 20598162 multiplied by 83106206 equals 1,711,835,094,393,372.

Other tools

The harnesses used by current chatbots provide the LLM with a whole raft of tools. Here are a few that you might have noticed:

• Search the web: when the model needs information outside of its training data (like something recent or hyperspecific), it can search the web. Here the model writes a search query, the tool runs it and returns the results (titles, snippets, and links) back to the conversation.

• Fetch a page: when the model needs to read a webpage, the tool downloads it and returns its contents as text. This often goes hand-in-hand with web search, but is also what lets you paste in a URL and ask the model to summarise it. (I often use this to extract recipes into a format I like: strip the blather at the start, repeat the ingredients needed at each step, and convert to metric measurements.)

• Make a memory: when you tell the LLM to remember something, it edits some central markdown file that’s included in the prompt for all future conversations. This is how an assistant can “remember” your name, or that you use British English, or that you prefer sentence case for headings, without you repeating yourself every time.

• Draw a picture: when you ask the LLM to generate an image, it doesn’t draw anything itself but instead acts as a skilled prompt-writer for a separate, specialised model. The model writes a detailed text prompt, uses a tool call to an image model to generate the image, then adds that to the conversation. This is how ChatGPT and Gemini generate images.

Why does it matter that these are all tool calls and not some intrinsic property of the model? Because it shows that even if the underlying model is static, the abilities of the system can grow over time. And importantly, because you can make a harness with your own tools, you can extend the model in whatever way you want. When you combine that insight with tools like shinychat, you have the potential to create tailored systems that can do better than the best generic chatbots for your specific domain.

One last wrinkle

There’s one last wrinkle to cover. I said tool calls were the responsibility of the harness, but that’s another simplification: there’s also a selection of built-in tool calls that the models can do themselves. (Or maybe the right way to describe this is that models also come with a limited server-side harness.)

For example, the big three (OpenAI, Anthropic, and Google) all provide a built-in web search tool call:

chat <- chat_openai("Be terse", model = "gpt-5.4-mini", echo = FALSE)
chat$register_tool(openai_tool_web_search())
. <- chat$chat("When is Hadley Wickham's birthday?")
chat
#> <Chat OpenAI/gpt-5.4-mini turns=3 input=8501 output=72 cost=$0.01>
#> ── system ──────────────────────────────────────────────────────────────────────
#> Be terse
#> ── user ────────────────────────────────────────────────────────────────────────
#> When is Hadley Wickham's birthday?
#> ── assistant [input=8501 output=72 cost=$0.01] ─────────────────────────────────
#> [web search request]: "Hadley Wickham birthday birth date"
#> Hadley Wickham’s birthday is **October 14, 1979**. ([en.wikipedia.org](https://en.wikipedia.org/wiki/Hadley_Wickham?utm_source=openai))

This is nice because instead of user -> LLM -> harness -> LLM we can eliminate one HTTP request and response, reducing it to user -> LLM (with tool call), saving some time. You can see that in the result above: the final response acknowledges that a web search was performed before including the text response. (And as an added benefit, you now know when to send me a birthday card 🎂.)

To understand what an agent is, you first need to understand what a tool call is. And to understand a tool call, you need to understand the basic human <-> LLM conversational loop. So we’ll start there and then work our way back up.

Conversation basics

A conversation with an LLM is a sequence of HTTP requests and HTTP responses: you say something then the LLM responds. LLMs (like pretty much all modern web APIs) communicate with JSON. So when you send a request to Claude (my personal favourite LLM), the request body includes some JSON like this:

"role": "user",
"content": [
  {
    "type": "text",
    "text": "Tell me a joke",
  }
]

(I’ve trimmed these snippets for readability. That means they’re not valid JSON, but should give you the flavour of what’s going on under the hood.)

This message is from the user (me, the human) and includes text asking Claude to tell me a joke. Then Claude sends a message back:

"role": "assistant",
"content": [
  {
    "type": "text",
    "text": "Why don't scientists trust atoms?\n\nBecause they make up everything!"
  }
]

This message is from the assistant (Claude) and gives the joke I requested in text format.

We call each of these two messages a turn. Turns always come in pairs and always happen in the same order: user then assistant. The LLM will always listen to everything you have to say, and only then respond. (This is something we can all strive for in our own conversations 😆.)

It’s worth noting that the LLM API is stateless. That means if we continue this conversation, we have to resend the entire conversation so far:

messages: [
  {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "Tell me a joke",
      }
    ]
  },
  {
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Why don't..."
      }
    ]
  }
]

This is why token costs grow over the course of a conversation; each new request has to include the contents of all the previous turns.

Tools

Things get more complicated when we introduce tools. Tools are a way for LLMs to break free from their limits: they allow LLMs to get data about the world as it is today and allow them to take actions. But what exactly is a tool? A tool is just a different name for a function, but importantly it’s a function that’s run on your computer.

Let’s see how that works in ellmer by registering a very simple tool:

chat <- chat_claude(model = "claude-sonnet-4-5")
chat$register_tool(tool(
  \() Sys.Date(),
  name = "today",
  description = "Get today's date"
))

Now we can use the tool to allow Claude to answer a question that cannot be part of its training data: today’s date. So our request includes a description of that tool:

"tools": [
  {
    "name": "today",
    "description": "Get today's date",
    "input_schema": {
      "type": "object",
      "description": "",
    }
  }, 
]

(This is everything the model knows about the tool, which is why writing a good description is important for more complex tools.)

Then the request continues as before:

"role": "user",
"content": [
  {
    "type": "text",
    "text": "What day is it today?",
  }
]

Claude can’t respond immediately because it doesn’t know the answer. So instead it responds with type “tool_use”:

"role": "assistant",
"content": [
  {
    "type": "tool_use",
    "id": "toolu_012g5Pv3hqogjmTSWFpwPPnE",
    "name": "today",
    "input": {}
  }
]

This is a request for you to do some work, i.e. call the today() function with no arguments. This workflow wouldn’t be very appealing if you personally had to call this function, which is where the harness comes in. A harness is a program that wraps around the raw LLM and can (among other things) run these local functions for you. Harnesses include the web chat interface, more complicated tools like Claude Code or Codex, and in this case, ellmer.

So now ellmer takes over, sending a new message back to the assistant that contains the results of calling today(). It also includes the complete prior conversational history, but I’ve omitted that to stay focused on what’s changed:

"role": "user",
"content": [
  {
    "type": "tool_result",
    "tool_use_id": "toolu_012g5Pv3hqogjmTSWFpwPPnE",
    "content": "2026-06-01",
    "is_error": false
  }
]

(The role here is a little confusing; it would be clearer to say that this response was generated by the harness, rather than the user.)

Now that Claude knows what day it is, it can respond to our initial query:

"role": "assistant",
"content": [
  {
    "type": "text",
    "text": "Today is **Monday, June 1st, 2026**."
  }
]

We call the complete sequence of human, harness, and LLM turns a round, which in this case consists of four turns/two pairs (human -> LLM, harness -> LLM).

So what’s an agent?

With all these pieces in place we can now define an agent. An agent is an LLM, in a harness, that calls tools repeatedly in a loop, deciding each next step from the last result. Most agents have two types of tools: read tools that can observe the world, and write tools that can change the world. This combination leads to a natural iterative cycle where the LLM does some initial exploration (read), makes a change (write), observes the result of the change (read), etc etc. That’s why our example above wasn’t an agent; there’s no need for iteration.

So now let’s make a real, if simple, agent. The goal of this agent is to help you delete files. So we give it a read tool that lists the files in the current directory and a write tool that deletes files:

chat <- chat_claude(model = "claude-sonnet-4-5")
chat$register_tool(tool(
  function() dir(),
  name = "ls",
  description = "Lists the files in the current directory"
))
chat$register_tool(tool(
  function(path) unlink(path),
  name = "rm",
  description = "Delete a file",
  arguments = list(path = type_string())
))

Now we can use the agent to effect change in the world:

chat$chat("Delete all the csv files in the current directory")

I won’t show the full sequence of JSON requests and responses here because it’s a bit long, but in summary it looks like this:

• User: Delete all the csv files in the current directory.

• Claude: Run the ls() tool

• ellmer: a.csv, b.csv, a.R, b.R, c.R

• Claude: [Run rm("a.csv"), Run rm("b.csv")]

• ellmer: [TRUE, TRUE]

• Claude: I’ve deleted two csv files for you.

This is one round made up of six turns/three pairs (human-LLM, harness-LLM, harness-LLM).

Now let’s talk about the elephant in the room: I just gave an LLM the ability to delete files on my computer! Hopefully you find this a little worrying, as we know that LLMs are never 100% trustworthy.

This is one of the biggest challenges of agents. An agent isn’t useful unless it can take actions on your behalf, but how do you know it’s always taking the right actions? This is one of the biggest questions posed by AI agents. There are some things you can do locally to protect yourself when the agent is scoped to actions on your computer, like sandboxing, using git, and making backups. But what if actions are in the real world like sending emails or spending money? That feels high risk to me!

Subscribe now

As usual, I’d love to know how this article landed with you. Did you learn something new or is this old hat? What questions are you left wondering about?

In future posts, I’ll get more technical, but I wanted to begin by acknowledging your likely deeply conflicted feelings about AI.

Let me start with the bits of AI that I feel genuinely excited about:

Programming accessibility. There are tons of people who could benefit from a programming language like R, but can’t justify the investment in learning it. AI has dramatically lowered that barrier and you can now get many of the benefits of reproducible programming with R much faster than you could before. Similarly, effective usage of git is now within reach to a much broader audience.

Translation. While machine translations are still far from perfect, their quality has improved radically in the last few years. This means that much more of the programming ecosystem is now available to the majority of the world who are not fluent English speakers.

Voice input. Voice input is a super exciting technology because it means that you no longer need to be a fluent touch typist in order to quickly get your thoughts into a computer. (Not to mention making a lot more technology available if you can’t read or write.) That’s a meaningful expansion of who gets to participate in technology.

Wide and shallow expertise. I love Tukey’s quote that statisticians get to play in everyone’s backyard. And it’s now easier than ever thanks to AI. AI will not make you an expert but can give you shallow expertise in basically anything you’re curious about. I think that’s pretty cool.

Finally, I have found AI to be a tremendous accelerator in my own work. It’s allowed me to fix 100s of issue in core infrastructure packages like roxygen2 and testthat. This is not AI slop; this is carefully vetted code that I can now write ~2-5x faster than I could before.

But you can’t use AI without also considering the harms, of which there are many.

Environmental impact. At the individual level, I believe that if you want to reduce your environmental footprint, there are higher-leverage changes that you can make. But at the societal level, the picture is more concerning: the rush to create new data centers is increasing need for electricity and water, and leading companies to rollback their climate commitments.

Copyright theft. LLMs are trained on vast quantities of copyrighted material, taken at an unprecedented and industrial scale, without permission or compensation.

Concentration of wealth. The AI craze is pushing more and more money into the hands of fewer and fewer people. I find the concentration of wealth and power into the hands of a very small number of people to be genuinely disturbing and I think is something that we should all be concerned about.

Intellectual laziness. AI supports a kind of shallow engagement where you never have to strain your brain on any task. The path of least resistance is to disengage and just let the model handle it. You no longer have to experience any mental discomfort, and thus you never really learn.

Equity and access. I’ve built my career around open source software, and one of the things I love about it is that it’s available to everyone, everywhere in the world, regardless of their means. That’s not possible with AI. The best tools cost real money, usually charged in US dollars, and that makes them out of reach for a lot of people in a lot of places.

How do you resolve the tension between the empowering and harmful parts of AI? I wish I could give you an answer. All I can suggest is to sit with this conflict. Acknowledge that it’s complicated and there are no easy answers. And do your best to ignore the AI boosters and AI doomers who want to make it easy.

Why am I engaging so heavily with AI? Firstly, I see my job as broadly empowering data scientists. If data scientists are now using AI, then it’s my job to look at what they’re doing and see if I can help them to do it better. Secondly, it feels crucial for the future of Posit. We’re a successful company and doing well, but if we don’t seriously engage with AI then I don’t think we can survive. And while I’m admittedly biased, I do think the failure of Posit would be a loss for the world since we invest so much into free and open source tools.

So that’s why I’m bringing this substack back to life to talk about AI. But I want to know how I can best serve you. What are your concerns about using AI for data science? Where are you seeing successes and failures? What do you want to learn about? Please let me know in the comments, or if you’d like a deeper discussion you can find a time to chat with me1.

Over the last couple of weeks I’ve been noodling on the idea of strategies: what happens if your function contains a few different approaches to the problem, and you want to expose to the user select. I believe that it’s best to expose these explicitly like the ties.method argument to rank(), the method argument to p.adjust(), or the .keep argument to dplyr::mutate().

In functions that expose a strategy, it’s common to see a character vector in the function interface. For example, rank() looks like this:

rank(
  x,
  na.last = TRUE,
  ties.method = c("average", "first", "last", "random", "max", "min")
)

I call this character vector an enumeration and discuss it in “Enumerate possible options”. This vector enumerates (itemises) the possible options (six here) and it also tells you the default value, the first value in the vector ("average"). This type of default value is usually paired with either match.arg() or rlang::arg_match() to give an informative error if the user supplies an unsupported value. The chief difference between the base and rlang versions of this function is that the base version supports partial matching (e.g. you can write rank(x, ties.method = "r") for short), which we believe is no longer a good idea.

One of the reasons it’s useful to understand this pattern is that you might want to apply it even when there are only two options. In such a case, it’s tempting to expose the option as a Boolean argument, accepting either TRUE or FALSE. But this has two problems:

• You might later discover that there’s a third option. Now you’re going to need to make more radical changes to your function interface to allow this.

• It’s often trickier to understand a negative. For example, I recently discovered the cancel_on_error argument in an httr2 function. I think it’s pretty clear what cancel_on_error = TRUE does (it cancels if there’s an error), but what does cancel_on_error = FALSE do? I wrote this code and now I couldn’t tell you what it actually does.

I explore this idea in more detail in “Prefer a enum, even if only two choices”, including a deeper look at the decreasing and na.last arguments to sort().

A more complicated example of the strategy pattern comes about when different strategies require different arguments. The best example of this sort of pattern is stringr, which uses the functions regex(), fixed(), boundary(), and coll() to define the pattern matching engine:

library(stringr)
x <- "The quick brown fox jumped over the lazy dog."

str_view(x, regex("[aeiou]+", ignore_case = TRUE))
#> [1] │ Th<e> q<ui>ck br<o>wn f<o>x j<u>mp<e>d <o>v<e>r th<e> l<a>zy d<o>g.
str_view(x, fixed("."))
#> [1] │ The quick brown fox jumped over the lazy dog<.>
str_view(x, boundary("word"))
#> [1] │ <The> <quick> <brown> <fox> <jumped> <over> <the> <lazy> <dog>.

I explore this idea more in “Extract strategies into objects” (which really needs a catchier name), motivated by the perl, fixed, and ignore.case arguments to grepl() and friends.

Finally, sometimes exposing multiple strategies in one function isn’t the right move, and you’re better off creating more simpler functions. I think of this problem as “three functions in a trench coat” because it can feel like three or more functions crammed into one breaking apart at the seems. forcats::fct_lump() is a good example of this problem: it started off simple and then gained new strategies over time. Eventually it got so hard to explain that we decided to split apart in to three simpler functions. Another good example of this problem is the rep() function: I think it’s actually two functions in trench coat and it gets easier to understand if you pull them apart. See the rep() case study for a full exploration including some of my thoughts about what you might name the functions and arguments.

Do these patterns resonate with you? Are there other functions in the tidyverse that you think do a particularly good or bad job of exposing a strategy? Please let me know in the comments!

Subscribe now

I was lucky to have access to computers from a very young age (I don't remember when exactly, but I think around 10), thanks to Dad having a laptop for work. This was in the era where laptops were extremely expensive, heavy, and barely transportable, but I still I have fond memories of using Lotus 1-2-3 (an early spreadsheeting tool), learning DOS, and playing Dune 2. In my early teens, I remember being greatly excited to find a documentation manual for DOS in a computer shop and convincing Dad to buy it for me.

Databases have been a big part of Dad's work through out his life, and he gave me "the talk" about Codd's third normal form when I was around 15. This sparked my interest in MS Access, which lead to part time jobs creating and documenting databases in high school and university. One projects involved creating a database for the library at his work, and I still remember the feeling after I accidentally deleted a file that contained a week's worth of data entry. This lead to "the talk" about backups, the principles of which I have followed ever since. Dad's knowledge about and use of databases had a deep impact on my life, leading many years later to the idea of tidy data, a framing of Codd's rules that were easier to understand and apply to statistical data.

Much of Dad's work involved collecting data about cows (hence the databases), and one of his strong beliefs was that farmers should own their own data, and it should live together in a central database that could be used for the good of all. This made open source seem natural to me: why not build a community where developers collaboratively owned their code, and could work together to solve problems that were hard to tackle individually. Dad's belief in sharing his work for the betterment of all made adopting the principles of open source software seen obvious to me when I started producing software of my own.

Dad did his PhD at Cornell, so growing up it made doing a PhD overseas seem like a totally normal and reasonable to do. So when I got interested in statistics and computer science in my undergrad, applying to universities in the US seemed like the obvious choice. Unfortunately Dad had given me unrealistic sense of how long a PhD would take, since he finished his in only two years!

One of the things that most impressed me about Dad was his commitment to life long learning. He loved to embrace new technologies, and was a fluent user of FaceTime, AirBnB, and Uber (although he also loved to strike up conversations with strangers in a way that is very foreign to me). In his early 70s, he learned how to use GitHub and markdown so that he could edit "People and Places of Clonakilty", a book that my mum wrote and that Charlotte and I produced with Quarto. He’s a great role model as I get older; I want to continue to learn new things and embrace new technologies

Dad taught me how to chair a meeting, how to grill a steak, and how to change a tire. I admire his optimism, calm and thoughtful manner, and endless patience, and hope I can live up to his legacy. He will be greatly missed.

This week I wanted to talk through a bit of tidyverse design that I have mixed feelings about: !!!. What is !!! and when might you need it? To understand it, you’ll need a little back story…

Some functions want to work with both individual values and a list of values. For example, take rbind(). Sometimes you’ve created a couple of data frames by hand and want to join them together:

df1 <- data.frame(x = 1)
df2 <- data.frame(x = 2)
both <- rbind(df1, df2)

But other times you have created an entire list of data frames, typically through the application of lapply() or friends:

xs <- 1:5
dfs <- lapply(xs, \(x) data.frame(x = x))

How can you join these into a single data frame? Just calling rbind() doesn’t do what you want:

rbind(dfs)
#>     [,1]         [,2]         [,3]         [,4]         [,5]        
#> dfs data.frame,1 data.frame,1 data.frame,1 data.frame,1 data.frame,1

And while you certainly could index them by hand, you lose much of the advantage of using lapply() in the first place:

rbind(dfs[[1]], dfs[[2]], dfs[[3]], dfs[[4]], dfs[[5]])

This problem is sometimes called splicing or splatting and occurs whenever you have a single object that contains elements that you want to be individual arguments.

The recommended solution for this problem in base R is to use do.call(). do.call(rbind, dfs) generates the call rbind(dfs[[1]], rbind[[2]], …, rbind[[5]]) for you:

do.call(rbind, dfs)
#>   x
#> 1 1
#> 2 2
#> 3 3
#> 4 4
#> 5 5

do.call() is an effective, if advanced, technique but it gets a little tricky if you want to supply additional arguments. For example, historically, it used to be important to set stringsAsFactors = FALSE which requires gymnastics like this:

do.call(rbind, c(dfs, list(stringsAsFactors = FALSE)))

This was one of the challenges I wanted to tackle in dplyr, so I came up with bind_rows() which tries to automatically figure out if you have a list of data frames or you’re supplying them individually:

library(dplyr, warn.conflicts = FALSE)

bind_rows(df1, df2)
#>   x
#> 1 1
#> 2 2

bind_rows(dfs)
#>   x
#> 1 1
#> 2 2
#> 3 3
#> 4 4
#> 5 5

Unfortunately the heuristic we used to decide whether we were in the first case or the second case grew progressively more complicated over time, as people found problems or asked for new functionality. Now, while bind_rows() works correctly 99% of the time, it has some weird special cases, like below where the inputs can become columns, rather than rows.

bind_rows(x = 1, y = 2)
#> # A tibble: 1 × 2
#>       x     y
#>   <dbl> <dbl>
#> 1     1     2

These problems soured us on the idea of “automatic” splicing so we started looking for other solutions:

• We could have a pair of functions, one that takes … and one that takes a list. This works for bind_rows() it turns out there are a lot of functions that take … where it would be nice to also take a list of objects so it lead to a substantial amount of duplication.

• We could have a pair of arguments, … .dots, where you can supply individual arguments to … or a list of arguments to .dots. (I think I first recall seeing this approach in the RCurl package by Duncan Temple Lang.) But this would requires adding an additional argument to every function that uses …, and wouldn’t it be nice if we didn’t have to do that?

Instead we found inspiration from tidy evaluation where we had recently solved a similar problem with !!!:

library(rlang)

args <- exprs(a, b, c + d)
expr(f(!!!args))
#> f(a, b, c + d)

So we introduced the idea of “dynamic dots”, an extension to … that incorporates some features we thought we useful from tidy evaluation: splicing with !!! and dynamic names with :=. Dynamic dots is implemented via rlang::list2() and it’s easy to use in your own functions if you find the idea appealing.

One place you can see this idea in use is forcats::fct_cross(), which creates a factor that contains all combinations of its inputs:

library(forcats)

fruit <- factor(c("apple", "kiwi", "apple", "apple"))
colour <- factor(c("green", "green", "red", "green"))
fct_cross(fruit, colour)
#> [1] apple:green kiwi:green  apple:red   apple:green
#> Levels: apple:green kiwi:green apple:red

Because fct_cross() uses dynamic dots (which you can find out by looking at the dots), if you happen to have a list of values, you can use !!! to splice them in:

x <- list(fruit = fruit, colour = colour)
fct_cross(!!!x)
#> [1] apple:green kiwi:green  apple:red   apple:green
#> Levels: apple:green kiwi:green apple:red

(fct_cross() does a similar job to interaction(), which interestingly takes the automatic approach, so you can just call interaction(x) here. I don’t love the approach it takes because if interaction(list(f1, f2)) works, you might expect interaction(list(f1, f2), f3) to work, but it does not, and it doesn’t give you a particularly useful error message).

We have yet to figure out a way to use dynamic dots in dplyr::bind_rows() without breaking existing usage, but it’s provided by the function that now does most of the work: vctrs::vec_rbind(). (vctrs is the package where we stick low-level operations on vectors and data frames that we use in multiple packages. It’s designed to be programmer-friendly rather than analyst-friendly so we don’t talk about it that much).

vctrs::vec_rbind(!!!dfs)
#>   x
#> 1 1
#> 2 2
#> 3 3
#> 4 4
#> 5 5

Because binding lists of data frames together is such a common operation we also provide purrr::list_rbind() and purrr::list_cbind(). If you look you’ll see their implementations are very simple!

Overall, I have mixed feelings about !!!. I love the elegance of it: it makes it easy to splices lists into … and it has a beautiful connection to tidy evaluation. But I worry it feels like magic to most R users and because it’s only supported by some functions, it’s not super clear how you know when you can use it, and you still also have to learn do.call or similar. And, at least for bind_rows(), we’ve still ended up with two functions!

All that said, !!! still feels like the “least worst” solution to me, although looking back I wonder if we might have been better off using the more explicit .dots argument. What do you think? Had you heard of !!! before reading this post? Have you ever used it to successfully solve a problem? Do you prefer do.call() or are their other approaches used by other packages that you think are better?

New this week is a new chapter on reducing argument clutter by adding an options object. Sometimes you have a set of “second class” arguments that you don’t expect people to use very commonly, so you don’t want them cluttering up the function specification. If you want to give the user the ability to control them when needed, you can lump them all together into an “options” object.

These are used in base R modelling functions (e.g. glm(), loess()) to control the details of the underlying numerical algorithm. For example, take this model from the glm docs:

data(anorexia, package = "MASS")

mod <- glm(
  Postwt ~ Prewt + Treat + offset(Prewt),
  family = gaussian,
  data = anorexia
)

If you want to understand how model convergence is going you can set the trace = TRUE in glm.control():

mod <- glm(
  Postwt ~ Prewt + Treat + offset(Prewt),
  family = gaussian,
  data = anorexia,
  control = glm.control(trace = TRUE)
)
#> Deviance = 3311.263 Iterations - 1
#> Deviance = 3311.263 Iterations - 2
#> Deviance = 4525.386 Iterations - 1
#> Deviance = 4525.386 Iterations - 2

99% of the time you don’t need to know these arguments exist, but they are available if you ever need to debug a convergence failure.

Subscribe now

You can see the same pattern in readr::locale() and readr::date_names(). When parsing dates, you often need to know the names of the month, and that obviously varies by location. locale() allows you to set date_names to a two-letter country code to use common locations that baked in readr, but what happens if you want to parse dates from an unsupported language?

For example, take Austrian which came up in a recent readr issue. Austrian month names are mostly the same as German but use Jänner instead of Januar and Feber instead of Februar. We can parse Austrian date times by first taking the German date names structure and modifying it:

library(readr)

au <- readr::date_names_lang("de")
au$mon[1:2] <- c("Jänner", "Feber")
au
#> <date_names>
#> Days:   Sonntag (So.), Montag (Mo.), Dienstag (Di.), Mittwoch (Mi.), Donnerstag
#>         (Do.), Freitag (Fr.), Samstag (Sa.)
#> Months: Jänner (Jan.), Feber (Feb.), März (März), April (Apr.), Mai (Mai), Juni
#>         (Juni), Juli (Juli), August (Aug.), September (Sep.), Oktober
#>         (Okt.), November (Nov.), Dezember (Dez.)
#> AM/PM:  vorm./nachm.

Now we can pass this to object to locale(), and the locale object to a parsing function:

parse_date("15. Jänner 2015", "%d. %B %Y", locale = locale(date_names = au))
#> [1] "2015-01-15"

I like how this hierarchy of option arguments buries something that you rarely need but still makes it accessible.

Where else have you seen this pattern? Have you written functions where it would be useful? Are there places in the tidyverse that you think should use this pattern but don’t? Please let me know in the comments!

Thanks to everyone who contributed in the comments last week! The results aren’t ready to read yet, but have really helped my thinking for two new chapters “make strategies explicit” and “argument meaning should be independent”.

The goal of this newsletter is to get feedback as I work on a new book called "Tidy design principles". But what's the point of that book? R has a very rich literature on statistics and data science, there are relatively few books that focus on programming. I've written a couple (Advanced R and R Packages) but neither really talks about how to write good code R code (or even discusses what good code means).

That's what I want to focus on in "Tidy design principles": how do you write high-quality R code that's easy to understand, unlikely to fail in unexpected ways, and flexible enough to grow with your needs. This book will be organised around the idea of "design patterns". This was an idea that I encountered early in my programming journey and I found it very impactful.

The idea of a design pattern is to come up with a catchy name that maps a common programming challenge to an effective solution. The catchy name is important because it serves as a handle for your memory and a convenient shorthand when discussing code with others. I first heard about design patterns when I was a CS undergrad learning Java (a much less flexible language than R) and I read the popular read Design Patterns: Elements of Reusable Object-Oriented Software book.

I later learned that the idea of design patterns originated not from computer science, but from architecture, particularly A Pattern Language: Towns, Buildings, Construction by Christopher Alexander. This book resonated with me even more strongly than the CS patterns, and if you have any interest in architecture, I highly recommend reading it. I particularly liked that the patterns spanned many levels of detail, all the way from organising entire communities to how you might select chairs for a single room.

That's the spirit in which I write "Tidy design principles". I want to name common problem solving patterns in R, and write them up so that others can easily use them. That means that this book will have rather a different structure to my previous books. It will have a large number of relatively short chapters, each of which describes a pattern: what it is, why it's important, where you can see it in the wild, and how you can apply it to your code. You might skim the whole book once, but you'll generally use it by referring to the patterns that apply specifically to your current problem.

I also want to include some bigger principles that help you weigh conflicting patterns as well as case studies that illuminate some of our thinking when we've designed various parts of tidyverse (particularly parts that we now regret).

This week I've identified one bigger principle: the definition of a function should be scannable, giving you useful information at a glance. This principle is important because you see the function definition in lots of places, like in autocomplete and at the top of the documentation. It's super useful if that glance can give you useful insight into the function.

So far, I've gathered six patterns related to this principle:

• You should be able to tell what affects the output of the function because all inputs are explicit arguments.

• You know which arguments are most important because they come first.

• You can tell if an argument is required or optional based on the the presence or absence of a default and whether it comes before or after ….

• You can easily figure out the defaults because they are short and sweet.

• And if an argument has a small set of valid inputs, they are explicitly enumerated in the default.

What do you think of this principle and the various patterns that make it up? Does it resonate with you? Do you think I’ve missed something important?

One other pattern I've been noodling on is the idea that one argument shouldn't affect the meaning of another argument. This seems like an important principle, but so far I've only been able to come up with one example: library(), where the character.only argument affects the meaning of the package argument:

ggplot2 <- "dplyr"

# Loads ggplot2
library(ggplot2)

# Loads dplyr
library(ggplot2, character.only = TRUE)

Given that I only have one example, it doesn't seem worthwhile to write it up as a pattern, but maybe you've encountered other examples of this problem. If so, please let me know in the comments!

This week I’ve focussed on bringing the tidy design principles website back to life. Jenny Bryan and I started on this book all the way back in 2018, and there have obviously been some quite a few technology changes in the meantime. (Un)fortunately I have quite a bit of experience converting bookdown books to Quarto and tools like knitr::convert_chunk_header() do much of the heavy lifting, so overall it was just a couple of hours of work. But it’s highly likely I missed some stuff in the translation, so please let me know if you see anything that looks odd.

I also managed to get some thoughts in place about how you might think about ordering function arguments. I think both patterns are fairly obvious (please let me know if you think otherwise!) but worth writing down.

The first principle is that you should put the most important arguments first. Of course, this raises the question of what makes an argument important? It’s hard for me to make this concrete (so I hope you’ll send me your thoughts too), but there are three clear cases:

• If a function transforms some existing object, that object is most important and should be the first argument.

• Other arguments that affect the “shape” of the output (either the size or the type) are usually very important and should be near the front.

• Optional arguments are clearly least important and should be at the end.

Do you think there are tidyverse functions that break this rule? Please let me know so I can include them as examples!

The second principle is that if you use …, it should be placed between the required and optional arguments. This is important because of the way that argument matching works in R: you can supply arguments by position (like mean(x)), by full name (like mean(na.rm = TRUE)), or by part of the name (like mean(na = TRUE)). Placing arguments after … means that you can only supply them by their full name; not only does this force users into a clearer style, it also makes it easier for you to change the order of arguments in the future (e.g. to move important arguments earlier, as above).

The goal of writing this newsletter is to get your thoughts. So please let me know if you think these patterns are useful or wrong or anything in between!

— Hadley

This is my substack where I plan to regular post about progress on my current book project, tidy design principles. The goal of this book is to write up what the tidyverse team and I know about designing and implementing quality R code. It’s roughly aimed at someone who’s comfortable doing data science in R (e.g. someone who’s read R for Data Science) has been writing R functions (or even packages) for a while, and now wants to understand what makes for a “good” function (and maybe wonders what that even means). I also hope it will serve as a useful resource when reviewing code since you’ll be able to link to a chapter that discusses a potential pain point without having to write it up yourself.

Subscribe now