In dieghernan/cffR: Generate Citation File Format ('cff') Metadata for R Packages

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

cffr

cffr provides utilities to generate, coerce, modify and validate CITATION.cff files automatically for R packages, as well as tools and examples for working with .cff more generally.

What is a CITATION.cff file?

Citation File Format (CFF) [@druskat_citation_2021] (v1.2.0) are plain text files with human- and machine-readable citation information for software (and datasets). Code developers can include them in their repositories to let others know how to correctly cite their software.

This format is becoming popular within the software citation ecosystem. Recently GitHub, Zenodo and Zotero have included full support of this citation format [@druskat_stephan_making_2021]. GitHub support is of special interest:

knitr::include_graphics("vignettes/tweet-1.png")

--- Nat Friedman (\@natfriedman) July 27, 2021

See Enhanced support for citations on GitHub [@smith2021] for more info.

Related projects

The CodeMeta Project [@jones2017] creates a concept vocabulary that can be used to standardize the exchange of software metadata across repositories and organizations. One of the many uses of a codemeta.json file (created following the standards defined on The CodeMeta Project) is to provide citation metadata such as title, authors, publication year, and venue [@fenner2021]. The packages codemeta [@codemeta] / codemetar [@codemetar2021] allows to generate codemeta.json files from R packages metadata.

The cffr package

cffr maximizes the data extraction by using both the DESCRIPTION file and the CITATION file (if present) of your package. Note that cffr works best if your package pass R CMD check/devtools::check().

cat("\n")
today <- Sys.Date()
# Try get the count of GitHub repos here
token <- (Sys.getenv(c("GITHUB_PAT", "GITHUB_TOKEN")))
token <- token[!token %in% c(NA, NULL, "")][1]
ghtoken <- paste("token", token)
tmpfile <- tempfile(fileext = ".json")
# Get numbers of repos
api_url <- paste0(
  "https://api.github.com/search/code?q=cffr+extension:",
  "cff+filename:CITATION"
)
res <- tryCatch(
  download.file(api_url,
    tmpfile,
    quiet = TRUE,
    headers = c(Authorization = ghtoken)
  ),
  warning = function(e) {
    return(TRUE)
  },
  error = function(e) {
    return(TRUE)
  }
)
# If not successful
if (isTRUE(res)) {
  cat(paste0(
    "\n", "See [some projects already using **cffr**]",
    "(https://github.com/search?q=cffr%20path%3A**%2FCITATION.cff&type=code)",
    "."
  ))
} else {
  nreps <- as.integer(jsonlite::read_json(tmpfile)$total_count)
  cat(paste0(
    "As per ", today, " there are at least ", nreps,
    " repos on GitHub using **cffr**. ", "[Check them out here]",
    "(https://github.com/search?q=cffr%20path%3A**%2FCITATION.",
    "cff&type=code)."
  ))
}
cat("\n")

Installation

Install cffr from CRAN:

install.packages("cffr")

You can install the developing version of cffr with:

remotes::install_github("ropensci/cffr")

Alternatively, you can install cffr using the r-universe:

# Install cffr in R:
install.packages("cffr",
  repos = c("https://ropensci.r-universe.dev", "https://cloud.r-project.org")
)

Example

By default most often from within your package folder you'll simply run cff_write(), that creates a cff object, write it on a CITATION.cff file and validates it on a single command:

library(cffr)

# For in-development packages
cff_write()
#>
#> CITATION.cff generated
#>
#> cff_validate results-----
#> Congratulations! This .cff file is valid

However, cffr provides also custom print methods and mechanisms that allows you to customize the CITATION.cff and integrate them in your workflows.

This is a basic example which shows you how to create a cff object (see ?cff for more info). In this case, we are creating a cff object from the metadata of the rmarkdown package:

library(cffr)

# Example with an installed package
test <- cff_create("rmarkdown")

CITATION.cff for rmarkdown

test

We can validate the result using `cff_validate()`: wzxhzdk:9 Check the [docs](https://docs.ropensci.org/cffr//reference/index.html) and `vignette("cffr", package = "cffr")` to learn how to work with `cff` objects. ### Keep your `CITATION.cff` file up-to-date #### GitHub Actions The easiest way for keeping you `CITATION.cff` file up-to-date is using GitHub Actions. Use `cff_gha_update()`function to install a GitHub Action that would update your `CITATION.cff` file on the following events: - When you publish a new release of the package on your GitHub repo. - Each time that you modify your DESCRIPTION or inst/CITATION files. - The action can be run also manually. wzxhzdk:10 See the example workflow file [here](https://github.com/ropensci/cffr/blob/main/.github/workflows/update-citation-cff.yaml). #### Git pre-commit hook [](https://lifecycle.r-lib.org/articles/stages.html#experimental) You can also use a [git pre-commit hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks#_committing_workflow_hooks): > The `pre-commit` hook is run first, before you even type in a commit message. > It's used to inspect the snapshot that's about to be committed, to see if > you've forgotten something, to make sure tests run, or to examine whatever you > need to inspect in the code. Exiting non-zero from this hook aborts the > commit, although you can bypass it with `git commit --no-verify`. A specific pre-commit hook can be installed with `cff_git_hook_install()`. If you want to use a pre-commit hook, please make sure you have the **testthat** package installed. ### Learn more Check the following articles to learn more about **cffr**: - [cffr: Create a CITATION.cff File for your R Package](https://ropensci.org/blog/2021/11/23/cffr/) - [How I Test cffr on (about) 2,000 Packages using GitHub Actions and R-universe](https://ropensci.org/blog/2021/11/23/how-i-test-cffr/) ## Related packages - **citation** [@citation22] includes a function `r2cff` that creates a `CITATION.cff` file (v1.1.0) using the information of your `DESCRIPTION` file. It also provide minimal validity checks. - **handlr** [@handlr]: Tool for converting among citation formats, including `*.cff` files. - **codemeta** [@codemeta] / **codemetar** [@codemetar2021] provides similar solutions for creating `codemeta.json` file, another format for storing and sharing software metadata. ## Citation Hernangómez, D., (2021). cffr: Generate Citation File Format Metadata for R Packages. Journal of Open Source Software, 6(67), 3900, A BibTeX entry for LaTeX users is: wzxhzdk:11 You can also use the [citation provided by GitHub](https://github.com/ropensci/cffr), that is generated from the information of a `CITATION.cff` created with **cffr**. See [About CITATION files](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) for more info. ## References ::: {#refs} ::: [](https://ropensci.org) ## Contributors All contributions to this project are gratefully acknowledged using the [`allcontributors` package](https://github.com/ropensci/allcontributors) following the [allcontributors](https://allcontributors.org) specification. Contributions of any kind are welcome! ### Code

dieghernan

dpprdan

### Issue Authors

Bisaloo	jeroen	joelnitta	jeyabbalas	aadler	larnsce	iembry	IndrajeetPatil
roaldarbol	nfrerebeau	Pakillo

### Issue Contributors

arfon

hainesr

llrs

njtierney

zeileis

dieghernan/cffR documentation built on April 17, 2025, 4:33 a.m.