cffr provides utilities to generate, parse, 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 et al. 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 2021). GitHub support is of special interest:

GitHub-link

— Nat Friedman (@natfriedman) July 27, 2021

See Enhanced support for citations on GitHub (Smith 2021) for more info.

The CodeMeta Project (Jones et al. 2017) 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 (Fenner 2021). The packages codemeta/ codemetar 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().

See some projects already using cffr.

Installation

Install cffr from CRAN:

You can install the developing version of cffr with:

devtools::install_github("ropensci/cffr")

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


# Enable this universe
options(repos = c(
  ropensci = "https://ropensci.r-universe.dev",
  CRAN = "https://cloud.r-project.org"
))

# Install some packages
install.packages("cffr")

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

cff-version: 1.2.0
message: 'To cite package "rmarkdown" in publications use:'
type: software
license: GPL-3.0-only
title: 'rmarkdown: Dynamic Documents for R'
version: '2.11'
abstract: Convert R Markdown documents into a variety of formats.
authors:
- family-names: Allaire
  given-names: JJ
  email: jj@rstudio.com
- family-names: Xie
  given-names: Yihui
  email: xie@yihui.name
  orcid: https://orcid.org/0000-0003-0645-5666
- family-names: McPherson
  given-names: Jonathan
  email: jonathan@rstudio.com
- family-names: Luraschi
  given-names: Javier
  email: javier@rstudio.com
- family-names: Ushey
  given-names: Kevin
  email: kevin@rstudio.com
- family-names: Atkins
  given-names: Aron
  email: aron@rstudio.com
- family-names: Wickham
  given-names: Hadley
  email: hadley@rstudio.com
- family-names: Cheng
  given-names: Joe
  email: joe@rstudio.com
- family-names: Chang
  given-names: Winston
  email: winston@rstudio.com
- family-names: Iannone
  given-names: Richard
  email: rich@rstudio.com
  orcid: https://orcid.org/0000-0003-3925-190X
preferred-citation:
  type: manual
  title: 'rmarkdown: Dynamic Documents for R'
  authors:
  - family-names: Allaire
    given-names: JJ
  - family-names: Xie
    given-names: Yihui
  - family-names: McPherson
    given-names: Jonathan
  - family-names: Luraschi
    given-names: Javier
  - family-names: Ushey
    given-names: Kevin
  - family-names: Atkins
    given-names: Aron
  - family-names: Wickham
    given-names: Hadley
  - family-names: Cheng
    given-names: Joe
  - family-names: Chang
    given-names: Winston
  - family-names: Iannone
    given-names: Richard
  year: '2021'
  url: https://github.com/rstudio/rmarkdown
repository: https://CRAN.R-project.org/package=rmarkdown
repository-code: https://github.com/rstudio/rmarkdown
url: https://pkgs.rstudio.com/rmarkdown/
date-released: '2021-09-14'
contact:
- family-names: Xie
  given-names: Yihui
  email: xie@yihui.name
  orcid: https://orcid.org/0000-0003-0645-5666
keywords:
- literate-programming
- markdown
- pandoc
- r
- r-package
- rmarkdown
references:
- type: book
  title: 'R Markdown: The Definitive Guide'
  authors:
  - family-names: Xie
    given-names: Yihui
  - family-names: Allaire
    given-names: J.J.
  - family-names: Grolemund
    given-names: Garrett
  publisher:
    name: Chapman and Hall/CRC
  year: '2018'
  url: https://bookdown.org/yihui/rmarkdown
- type: book
  title: R Markdown Cookbook
  authors:
  - family-names: Xie
    given-names: Yihui
  - family-names: Dervieux
    given-names: Christophe
  - family-names: Riederer
    given-names: Emily
  publisher:
    name: Chapman and Hall/CRC
  year: '2020'
  url: https://bookdown.org/yihui/rmarkdown-cookbook

We can validate the result using cff_validate():


cff_validate(test)
#> 
#> cff_validate results-----
#> Congratulations! This cff object is valid

Check the docs and vignette(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.
cff_gha_update()

#> Installing update-citation-cff.yaml on './.github/workflows'
#> Adding .github to .Rbuildignore

See the example workflow file here.

Git pre-commit hook Experimental

You can also use a git pre-commit hook:

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.

  • citation: The development version (at the time of this writing) includes a new 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: Tool for converting among citation formats, including *.cff files. At the time of this writing only CFF v1.1.0 was supported (see #24).
  • codemeta/ codemetar 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. doi: 10.21105/joss.03900 (URL: https://doi.org/10.21105/joss.03900), <URL: https://doi.org/10.21105/joss.03900>.

A BibTeX entry for LaTeX users is

You can also use the citation provided by GitHub, that is generated from the information of a CITATION.cff created with cffr. See About CITATION files for more info.

References

Druskat, Stephan. 2021. “Making Software Citation Easi(er) - the Citation File Format and Its Integrations,” September. https://doi.org/10.5281/zenodo.5529914.

Druskat, Stephan, Jurriaan H. Spaaks, Neil Chue Hong, Robert Haines, James Baker, Spencer Bliven, Egon Willighagen, David Pérez-Suárez, and Alexander Konovalov. 2021. “Citation File Format,” August. https://doi.org/10.5281/zenodo.5171937.

Fenner, Martin. 2021. “We Need Your Feedback: Aligning the CodeMeta Vocabulary for Scientific Software with Schema.org.” https://doi.org/10.5438/a49j-x692.

Jones, Matthew B, Carl Boettiger, Abby Cabunoc Mayes, Arfon Smith, Peter Slaughter, Kyle Niemeyer, Yolanda Gil, et al. 2017. CodeMeta: An Exchange Schema for Software Metadata. KNB Data Repository. https://doi.org/10.5063/SCHEMA/CODEMETA-2.0.

Smith, Arfon. 2021. “Enhanced Support for Citations on GitHub.” https://github.blog/2021-08-19-enhanced-support-citations-github/.