pakret: a new package to cite and reference R and R packages on the fly in Quarto

[arnaudgallou]

Description

I've just released pakret, a very easy-to-use and flexible tool to cite and reference R and R packages in Quarto and R Markdown. The package might be particularly useful to people using Quarto and R for their research. The full documentation of the package is accessible here.

Here's a simple example of how it works:

---
bibliography: refs.bib
---

```{r}
#| include: false
library(pakret)
```

We used `r pkrt("ape")` to compute phylogenetic distances.

We performed all the analyses in `r pkrt("R")` using `r pkrt_list("tidyverse", "rstanarm")`.

## References

The document above will generate the following .md output:

We used the ‘ape’ package version 5.7-1 (Paradis and Schliep 2019) to
compute phylogenetic distances.

We performed all the analyses in R version 4.3.2 (R Core Team 2023) using
‘tidyverse’ v. 2.0.0 (Wickham et al. 2019), ‘rstanarm’ v. 2.32.1
(Goodrich et al. 2024).

## References

Goodrich, Ben, Jonah Gabry, Imad Ali, and Sam Brilleman. 2024.
“Rstanarm: Bayesian Applied Regression Modeling via Stan.”
<https://mc-stan.org/rstanarm/>.

Paradis, Emmanuel, and Klaus Schliep. 2019. “Ape 5.0: An Environment for
Modern Phylogenetics and Evolutionary Analyses in R.” *Bioinformatics*
35: 526–28. <https://doi.org/10.1093/bioinformatics/bty633>.

R Core Team. 2023. *R: A Language and Environment for Statistical
Computing*. Vienna, Austria: R Foundation for Statistical Computing.
<https://www.R-project.org/>.

Wickham, Hadley, Mara Averick, Jennifer Bryan, Winston Chang, Lucy
D’Agostino McGowan, Romain François, Garrett Grolemund, et al. 2019.
“Welcome to the <span class="nocase">tidyverse</span>.” *Journal of Open
Source Software* 4 (43): 1686. <https://doi.org/10.21105/joss.01686>.

[cscheid]

This is very cool; I wonder if there's any way we can make it a bit more Quarto-friendly. The main issue that will arise is that citations need to be rendered precisely once, and this will split the citations. That will cause trouble with custom CSL files, for example.

[arnaudgallou]

One of the things to consider is to not render the .bib file yourself, but instead create a new bib file and add a new metadata block with a new bibliography: refs.bib entry.

Just to be sure to understand, what's the rationale of creating the .bib file internally rather than using a user-defined one? What should happen when rendering the document again? Deleting that .bib file and regenerating a new one or appending new citations (if there's any) to the existing file?

[mcanouil]

I've tried your package.

Just to be sure to understand, what's the rationale of creating the .bib file internally rather than using a user-defined one?

My main concern is that your package is writing to the first bibliography file defined in bibliography without any heads up.
Users might not like a third party messing with their organised bibliography, especially if they intend to use several files.

You don't seem to have used knitr::write_bib(), is there any particular reason?

[cscheid]

@mcanouil Oooof. That's very annoying and you're right. I was thinking about the semantics we have with (eg) one array of values in _quarto.yml and another in the document, where merging those metadata means concatenating the arrays. It's a huge bummer that we can't do that within the same document. I now almost want to preprocess these in front of Pandoc to fix that behavior!

[arnaudgallou]

My main concern is that your package is writing to the first bibliography file defined in bibliography without any heads up. Users might not like a third party messing with their organised bibliography, especially if they intend to use several files.

By default, the package adds the references to the first .bib file specified in bibliography as mentionned in the doc. It's easy to change that setting to write to another file though.

I designed the package to be as simple as possible with no particular requirements from the user to use it. I personally don't mind the organization of the .bib file and I find that creating a file with a specific name just to use the package is annoying so for me that was the obvious way to do it. Now creating a file programmatically has similar downsides, e.g. that means saving the new file in a default directory which might change the file structure in an undesired way or asking for a path to the user.

You don't seem to have used knitr::write_bib(), is there any particular reason?

From what I remember (I wrote most of the code last year) knitr::write_bib() wasn't flexible enough for me. For example, knitr::write_bib("rmarkdown") references all 3 bib entries when pakret only uses 1 by package to avoid bloating the reference list. If there're multiple bibtex entries, it uses the manual in priority, otherwise it uses the first bibtex entry. bib_write() also overwrites the original file meaning I've to store the entire content somewhere, including references that aren't packages. Although technically that shouldn't be an issue, to me it's easier and more logical to deal with the information that matters only, i.e. new references, and append them to the bib file when knitr finishes without touching to the rest.

The logic of the package is here and the initialization part is in the aaa.R and zzz.R files. In total it's about 200 lines, blank lines included. It's relatively short in case you want to know more on how it works.

[mcanouil]

Thanks for the design choice explanation.