"Best" Workaround for Passing NAs to quarto::quarto_render?

[Shea-Fyffe]

I wanted to get some thoughts on why the workaround (i.e., my interpretation of implementing #264 during runtime) below might be a bad idea, and if there is a more agreed upon recommendation for addressing my issue. Specifically, how to navigate situations where there are NAs in your execute_params when calling quarto::quarto_render. I realize this is a bit of a moot point and there are some high-level constraints (see #168 ); however, this likelihood of this situation in the wild compelled me to bring it up (...again, my apologies for that).

Workarounds for NA in Execute Params

I do appreciate the helpful error message (see #264 ). As a bit of a novice with quarto and its dependencies, I found the recommended alternatives/workarounds a little unclear in terms of how to best implement them. I don't feel that elaborating on this falls on the authors/maintainers of quarto—the current error message is super helpful as-is—which is another motivator for starting this discussion.

The first suggestion:

• Remove NA values from your data before passing to Quarto

This gets at more of a philosophical issue, and the difference in values that are missing versus values that don't exist. Within the context of a quarto document, NA values might still be meaningful/informative. If, for example, one is creating reports for students or test-takers and they are missing scores that they should have. But I'll concede that this works in a lot of situations, though unfortunately not in my situation.

The suggested workaround:

• Handle missing values within your document code using conditional logic

This one is a little murky to me because it seems like it relates to a situation where you have NAs as pre-existing defaults in your params, or you are knitting from within the qmd file. The "handle" part made me think of using a custom handler to deal with NAs when r params are converted to YAML, but I given the internal method quarto:::as_yaml() and existing handlers quarto:::yaml_handlers, I didn't know if this was appropriate.

The other suggestion:

• Use NULL instead of NA for missing optional parameters

Seemed a bit more tenable, but also more brittle--which is why I am soliciting feedback. Here, is how I interpreted it:

Example Passing list(NULL) instead of NA to quarto_render

My File looks like this:

na-test.qmd

---
title: "Quarto NA Param Test"
format: html
engine: knitr
params:
  x: [0]
  y: [""]
---

## Testing How NA is Passed to R > YAML > Quarto

 ```{r}
unlist(params$x)
```

```{r}
unlist(params$y)
```

Running Test

# define params
## list(NULL) replacing NA
x <- c(1:5, list(NULL))
y <- c(list(NULL), letters)

# run render
quarto::quarto_render("na-test.qmd", execute_params = list(x = x, y = y))

Output

na-test.html

Testing How NA is Passed to R > YAML > Quarto

unlist(params$x)

[1]  1  2  3  4  5 NA

unlist(params$y)

 [1] NA  "a" "b" "c" "d" "e" "f" "g" "h" "i" "j" "k" "l" "m" "n" "o" "p" "q" "r"
[20] "s" "t" "u" "v" "w" "x" "y" "z"

Limitations

• Substituting NAs with list(NULL) makes atomic vectors recursive (so unlist() may need to be called)
• yaml::as.yaml(c(letters, NA)) is not identical to yaml::as.yaml(c(letters, list(NULL)), in the former NA in converted to .na.character in the latter it's converted to ~

Anything else?

[cderv]

Thanks for sharing.

The fundamental problem that we have with calling Quarto CLI with parameters is that it uses YAML syntax.

This is not a quarto-r package problem. If you were calling quarto CLI directly from terminal, you would need to find a way to pass your NA.

YAML does not have a NA logic - no specific syntax for that.

So when this data point value is important (indeed NA are meaningful), I believe the data value itself should not be passed.

• You have data in R where NA exists and is meaningful. You want to pass that information in a Quarto document, using parameters.
• Best way in that case is to save R data to disk. Inside a .Rdata file, a .Rds file, or any other format that can keep NA information.
• Then you pass the filename as parameter, and your document reads the data inside a code cell.
• Your NA is kept without transformation.

What happens in quarto R 📦 to pass parameter to quarto is similar but uses YAML which expected by quarto CLI flags.

• You are in R, and you set parameters to quarto_render()
• Those objects are serialize to YAML using R function and save on disk in a yaml file.
• the R function calls Quarto CLI and pass the YAML file as a flag for quarto CLI to handle
• Quarto CLI will reload this YAML file, deserialize it to JSON, and pass it to the R knitr engine via stdin. R then parses the JSON back into R objects using jsonlite.
• Params are back as R objects through this R => YAML => JSON => R

This transformation can lose stuff like NA.

By saving first to disk you decide of the serialization, and by passing only filename as parameters, you control the deserialization in your document. By using a native R formats like RDS you keep all R objects.

Hope this helps understand the constraint.