Title:	Facilitate Citation of R Packages
Version:	0.2.12
Description:	Facilitates the citation of R packages used in analysis projects. Scans project for packages used, gets their citations, and produces a document with citations in the preferred bibliography format, ready to be pasted into reports or manuscripts. Alternatively, 'grateful' can be used directly within an 'R Markdown' or 'Quarto' document.
License:	MIT + file LICENSE
URL:	https://pakillo.github.io/grateful/
BugReports:	https://github.com/Pakillo/grateful/issues
Depends:	R (≥ 3.0.0)
Imports:	knitr, remotes, renv, rmarkdown, rstudioapi, utils
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-04-30 11:10:58 UTC; frs
Author:	Francisco Rodriguez-Sanchez [aut, cre, cph], Connor P. Jackson [aut], Shaurita D. Hutchins [ctb], James M. Clawson [ctb]
Maintainer:	Francisco Rodriguez-Sanchez <f.rodriguez.sanc@gmail.com>
Repository:	CRAN
Date/Publication:	2025-04-30 11:20:02 UTC

grateful: Facilitate Citation of R Packages

Description

Facilitates the citation of R packages used in analysis projects. Scans project for packages used, gets their citations, and produces a document with citations in the preferred bibliography format, ready to be pasted into reports or manuscripts. Alternatively, 'grateful' can be used directly within an 'R Markdown' or 'Quarto' document.

Author(s)

Maintainer: Francisco Rodriguez-Sanchez f.rodriguez.sanc@gmail.com (ORCID) [copyright holder]

Authors:

• Connor P. Jackson connor@cpjackson.net (ORCID)

Other contributors:

• Shaurita D. Hutchins [contributor]

• James M. Clawson [contributor]

See Also

Useful links:

• https://pakillo.github.io/grateful/

• Report bugs at https://github.com/Pakillo/grateful/issues

Cite R packages used in a project

Description

Find R packages used in a project, create a BibTeX file of references, and generate a document with formatted package citations. Alternatively, cite_packages can be run directly within an 'R Markdown' or 'Quarto' document to automatically include a paragraph citing all used packages and generate a bibliography.

Usage

cite_packages(
  output = c("file", "paragraph", "table", "citekeys"),
  out.dir = NULL,
  out.format = c("html", "docx", "pdf", "Rmd", "md", "tex-fragment", "tex-document"),
  citation.style = NULL,
  pkgs = "All",
  omit = c("grateful"),
  cite.tidyverse = TRUE,
  dependencies = FALSE,
  include.RStudio = FALSE,
  passive.voice = FALSE,
  out.file = "grateful-report",
  bib.file = "grateful-refs",
  ...
)

Arguments

Details

cite_packages is a wrapper function that collects package names and versions and saves their citation information in a BibTeX file (using get_pkgs_info()).

Then, the function is designed to handle different use cases:

If output = "file", cite_packages() will generate an 'R Markdown' file which includes a paragraph with in-text citations of all packages, as well as a references list. This document can be knitted to various formats via out.format. References can be formatted for a particular journal using citation.style. Thus, output = "file" is best for obtaining a document separate from R, to just cut and paste citations.

If output = "paragraph", cite_packages() will return a paragraph with in-text citations of all packages, suitable to be used directly in an 'R Markdown' or 'Quarto' document. To do so, include a reference to the generated bib.file bibliography file in the YAML header of the document (see https://pakillo.github.io/grateful/index.html#using-grateful-within-rmarkdown).

Alternatively, if output = "table", cite_packages() will return a table with package names, versions, and citations. Thus, if using 'R Markdown' or 'Quarto', you can choose between getting a table or a text paragraph citing all packages.

Finally, you can use output = "citekeys" to obtain a vector of citation keys, and then call nocite_references() within an 'R Markdown' or 'Quarto' document to cite these packages in the reference list without mentioning them in the text.

Value

If output = "file", cite_packages will save two files in out.dir: a BibTeX file containing package references and a citation report with formatted citations. cite_packages will return the path to the citation report invisibly. If output = "table" or output = "paragraph", cite_packages will return a table or paragraph with package citations suitable to be used within 'R Markdown' or 'Quarto' documents.

Limitations

Citation keys are not guaranteed to be preserved when regenerated, particularly when packages are updated. This instability is not an issue when citations are used programmatically, as in the example below. But if references are put into the text manually, they may need to be updated periodically.

Examples

# To build a standalone document for citations
cite_packages(out.dir = tempdir())

# Format references for a particular journal:
cite_packages(citation.style = "peerj", out.dir = tempdir())

# Choose different output format:
cite_packages(out.format = "docx", out.dir = tempdir())

# Cite only packages currently loaded:
cite_packages(pkgs = "Session", out.dir = tempdir())

# Cite only user-provided packages:
cite_packages(pkgs = c("renv", "remotes", "knitr"), out.dir = tempdir())

# Cite R as well as user-provided packages
cite_packages(pkgs = c("base", "renv", "remotes", "knitr"), out.dir = tempdir())


# To include citations in an R Markdown or Quarto file

# include this in YAML header:
# bibliography: grateful-refs.bib

# then call cite_packages within an R chunk:
cite_packages(output = "paragraph", out.dir = tempdir())

# To include package citations in the reference list of an Rmarkdown document
# without citing them in the text, include this in a chunk:
nocite_references(cite_packages(output = "citekeys", out.dir = tempdir()))

Get citations for packages

Description

Get citations for packages

Usage

get_citations(
  pkgs = NULL,
  out.dir = NULL,
  bib.file = "grateful-refs",
  include.RStudio = FALSE
)

Arguments

Value

A file on the specified out.dir containing the package references in BibTeX format. If assigned a name, get_citations will also return a list with citation keys for each package (without @).

Examples

citekeys <- get_citations(c("knitr", "renv"), out.dir = tempdir())

pkgs <- scan_packages()
citekeys <- get_citations(pkgs$pkg, out.dir = tempdir())

Get a journal citation style from the official internet repository

Description

Get a journal citation style from the official internet repository

Usage

get_csl(name = NULL, out.dir = NULL)

Arguments

Value

The CSL file is saved in the selected directory, and the path is returned invisibly.

Examples

get_csl("peerj", out.dir = tempdir())

Get information about packages used in a project

Description

This function scans the project for R packages used, saves a BibTeX file with package references, and returns a data frame with package names, version, and citation keys.

Usage

get_pkgs_info(
  pkgs = "All",
  out.dir = NULL,
  omit = c("grateful"),
  cite.tidyverse = TRUE,
  dependencies = FALSE,
  bib.file = "grateful-refs",
  include.RStudio = FALSE,
  ...
)

Arguments

Value

A data.frame with package info, and a file containing package references in BibTeX format.

Examples

get_pkgs_info(out.dir = tempdir())
get_pkgs_info(pkgs = c("renv", "remotes"), out.dir = tempdir())

Generate Nocite Block

Description

Include a metadata block of citation keys for including citations in references file without in-text citations.

Usage

nocite_references(citekeys, citation_processor = c("pandoc", "latex"))

Arguments

Details

When passed a list of citation keys, adds the @ to each, then builds the nocite metadata field, returning via "as-is" output. Run this function either inline or within a code chunk (with echo = FALSE) to include this metadata block within an RMarkdown document. The code chunk need not explicitly state results = 'asis'.

Call nocite_references with either style = 'pandoc' or style = 'latex' depending on whether you are processing citations with pandoc-citeproc or a LaTeX citation processor such as biblatex or natbib.

This function is intended to cite R packages with citation keys passed from get_citations() or cite_packages(output = "citekeys"), but can accept an arbitrary vector of citation keys (without @) found in a BibTeX file referenced in the YAML header.

Value

"As is" text of metadata block, with comma-separated list of citation keys.

Author(s)

Connor P. Jackson

Examples

# include in YAML header:
# bibliography: grateful-refs.bib

# Get citation keys for the current RMarkdown document
# (run after all packages have been loaded).
citekeys <- cite_packages(output = "citekeys", out.dir = tempdir())

# Include in RMarkdown body for use with pandoc-citeproc:
# `r nocite_references(citekeys, citation_processor = 'pandoc')`

Scan a project or folder for packages used

Description

Scan a project or folder for packages used

Usage

scan_packages(
  pkgs = "All",
  omit = c("grateful"),
  cite.tidyverse = TRUE,
  dependencies = FALSE,
  ...
)

Arguments

Value

a data.frame with package names and versions

Examples

scan_packages()
scan_packages(pkgs = "Session")
scan_packages(pkgs = c("renv", "remotes", "knitr"))