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:
— Nat Friedman (@natfriedman) July 27, 2021
See Enhanced support for citations on GitHub (Smith 2021) for more info.
Related projects
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()
.
As per 2022-06-09 there are at least 139 repos on GitHub using cffr. Check them out here.
Installation
Install cffr from CRAN:
install.packages("cffr")
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
-version: 1.2.0
cff: 'To cite package "rmarkdown" in publications use:'
message: software
type: GPL-3.0-only
license: 'rmarkdown: Dynamic Documents for R'
title: '2.14'
version: Convert R Markdown documents into a variety of formats.
abstract:
authors- family-names: Allaire
-names: JJ
given: jj@rstudio.com
email- family-names: Xie
-names: Yihui
given: xie@yihui.name
email: https://orcid.org/0000-0003-0645-5666
orcid- family-names: McPherson
-names: Jonathan
given: jonathan@rstudio.com
email- family-names: Luraschi
-names: Javier
given: javier@rstudio.com
email- family-names: Ushey
-names: Kevin
given: kevin@rstudio.com
email- family-names: Atkins
-names: Aron
given: aron@rstudio.com
email- family-names: Wickham
-names: Hadley
given: hadley@rstudio.com
email- family-names: Cheng
-names: Joe
given: joe@rstudio.com
email- family-names: Chang
-names: Winston
given: winston@rstudio.com
email- family-names: Iannone
-names: Richard
given: rich@rstudio.com
email: https://orcid.org/0000-0003-3925-190X
orcid-citation:
preferred: manual
type: 'rmarkdown: Dynamic Documents for R'
title:
authors- family-names: Allaire
-names: JJ
given: jj@rstudio.com
email- family-names: Xie
-names: Yihui
given: xie@yihui.name
email: https://orcid.org/0000-0003-0645-5666
orcid- family-names: McPherson
-names: Jonathan
given: jonathan@rstudio.com
email- family-names: Luraschi
-names: Javier
given: javier@rstudio.com
email- family-names: Ushey
-names: Kevin
given: kevin@rstudio.com
email- family-names: Atkins
-names: Aron
given: aron@rstudio.com
email- family-names: Wickham
-names: Hadley
given: hadley@rstudio.com
email- family-names: Cheng
-names: Joe
given: joe@rstudio.com
email- family-names: Chang
-names: Winston
given: winston@rstudio.com
email- family-names: Iannone
-names: Richard
given: rich@rstudio.com
email: https://orcid.org/0000-0003-3925-190X
orcid: '2022'
year: R package version 2.14
notes: https://github.com/rstudio/rmarkdown
url: https://CRAN.R-project.org/package=rmarkdown
repository-code: https://github.com/rstudio/rmarkdown
repository: https://pkgs.rstudio.com/rmarkdown/
url-released: '2022-04-25'
date:
contact- family-names: Xie
-names: Yihui
given: xie@yihui.name
email: https://orcid.org/0000-0003-0645-5666
orcid:
keywords- literate-programming
- markdown
- pandoc
- r
- r-package
- rmarkdown
:
references- type: book
: 'R Markdown: The Definitive Guide'
title:
authors- family-names: Xie
-names: Yihui
given- family-names: Allaire
-names: J.J.
given- family-names: Grolemund
-names: Garrett
given:
publisher: Chapman and Hall/CRC
name: Boca Raton, Florida
address: '2018'
year: ISBN 9781138359338
notes: https://bookdown.org/yihui/rmarkdown
url- type: book
: R Markdown Cookbook
title:
authors- family-names: Xie
-names: Yihui
given- family-names: Dervieux
-names: Christophe
given- family-names: Riederer
-names: Emily
given:
publisher: Chapman and Hall/CRC
name: Boca Raton, Florida
address: '2020'
year: ISBN 9780367563837
notes: https://bookdown.org/yihui/rmarkdown-cookbook
url- type: software
: 'R: A Language and Environment for Statistical Computing'
title: Depends
notes:
authors- name: R Core Team
:
location: Vienna, Austria
name: '2022'
year: https://www.R-project.org/
url:
institution: R Foundation for Statistical Computing
name: '>= 3.0'
version- type: software
: bslib
title: 'bslib: Custom ''Bootstrap'' ''Sass'' Themes for ''shiny'' and ''rmarkdown'''
abstract: Imports
notes:
authors- family-names: Sievert
-names: Carson
given: carson@rstudio.com
email: https://orcid.org/0000-0002-4958-2844
orcid- family-names: Cheng
-names: Joe
given: joe@rstudio.com
email: '2022'
year: '>= 0.2.5.1'
version- type: software
: evaluate
title: 'evaluate: Parsing and Evaluation Tools that Provide More Details than
abstract the Default'
: Imports
notes:
authors- family-names: Wickham
-names: Hadley
given- family-names: Xie
-names: Yihui
given: xie@yihui.name
email: https://orcid.org/0000-0003-0645-5666
orcid: '2022'
year: https://github.com/r-lib/evaluate
url: '>= 0.13'
version- type: software
: htmltools
title: 'htmltools: Tools for HTML'
abstract: Imports
notes:
authors- family-names: Cheng
-names: Joe
given: joe@rstudio.com
email- family-names: Sievert
-names: Carson
given: carson@rstudio.com
email: https://orcid.org/0000-0002-4958-2844
orcid- family-names: Schloerke
-names: Barret
given: barret@rstudio.com
email: https://orcid.org/0000-0001-9986-114X
orcid- family-names: Chang
-names: Winston
given: winston@rstudio.com
email: https://orcid.org/0000-0002-1576-2126
orcid- family-names: Xie
-names: Yihui
given: yihui@rstudio.com
email- family-names: Allen
-names: Jeff
given: jeff@rstudio.com
email: '2022'
year: https://github.com/rstudio/htmltools
url: '>= 0.3.5'
version- type: software
: jquerylib
title: 'jquerylib: Obtain ''jQuery'' as an HTML Dependency Object'
abstract: Imports
notes:
authors- family-names: Sievert
-names: Carson
given: carson@rstudio.com
email: https://orcid.org/0000-0002-4958-2844
orcid- family-names: Cheng
-names: Joe
given: joe@rstudio.com
email: '2022'
year- type: software
: jsonlite
title: 'jsonlite: A Simple and Robust JSON Parser and Generator for R'
abstract: Imports
notes:
authors- family-names: Ooms
-names: Jeroen
given: jeroen@berkeley.edu
email: https://orcid.org/0000-0002-4035-0289
orcid: '2022'
year- type: software
: knitr
title: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
abstract: Imports
notes:
authors- family-names: Xie
-names: Yihui
given: xie@yihui.name
email: https://orcid.org/0000-0003-0645-5666
orcid: '2022'
year: https://yihui.org/knitr/
url: '>= 1.22'
version- type: software
: methods
title: 'R: A Language and Environment for Statistical Computing'
abstract: Imports
notes:
authors- name: R Core Team
:
location: Vienna, Austria
name: '2022'
year: https://www.R-project.org/
url:
institution: R Foundation for Statistical Computing
name- type: software
: stringr
title: 'stringr: Simple, Consistent Wrappers for Common String Operations'
abstract: Imports
notes:
authors- family-names: Wickham
-names: Hadley
given: hadley@rstudio.com
email: '2022'
year: '>= 1.2.0'
version- type: software
: tinytex
title: 'tinytex: Helper Functions to Install and Maintain TeX Live, and Compile
abstract LaTeX Documents'
: Imports
notes:
authors- family-names: Xie
-names: Yihui
given: xie@yihui.name
email: https://orcid.org/0000-0003-0645-5666
orcid: '2022'
year: https://github.com/rstudio/tinytex
url: '>= 0.31'
version- type: software
: tools
title: 'R: A Language and Environment for Statistical Computing'
abstract: Imports
notes:
authors- name: R Core Team
:
location: Vienna, Austria
name: '2022'
year: https://www.R-project.org/
url:
institution: R Foundation for Statistical Computing
name- type: software
: utils
title: 'R: A Language and Environment for Statistical Computing'
abstract: Imports
notes:
authors- name: R Core Team
:
location: Vienna, Austria
name: '2022'
year: https://www.R-project.org/
url:
institution: R Foundation for Statistical Computing
name- type: software
: xfun
title: 'xfun: Supporting Functions for Packages Maintained by ''Yihui Xie'''
abstract: Imports
notes:
authors- family-names: Xie
-names: Yihui
given: xie@yihui.name
email: https://orcid.org/0000-0003-0645-5666
orcid: '2022'
year: https://github.com/yihui/xfun
url: '>= 0.30'
version- type: software
: yaml
title: 'yaml: Methods to Convert R Data to YAML and Back'
abstract: Imports
notes:
authors- family-names: Garbett
-names: Shawn P
given- family-names: Stephens
-names: Jeremy
given- family-names: Simonov
-names: Kirill
given- family-names: Xie
-names: Yihui
given- family-names: Dong
-names: Zhuoer
given- family-names: Wickham
-names: Hadley
given- family-names: Horner
-names: Jeffrey
given- name: reikoch
- family-names: Beasley
-names: Will
given- family-names: O'Connor
given-names: Brendan
- family-names: Warnes
given-names: Gregory R.
- family-names: Quinn
given-names: Michael
- family-names: Kamvar
given-names: Zhian N.
year: '2022'
url: https://github.com/vubiostat/r-yaml/
version: '>= 2.1.19'
- type: software
title: digest
abstract: 'digest: Create Compact Hash Digests of R Objects'
notes: Suggests
authors:
- family-names: Lucas
given-names: Dirk Eddelbuettel with contributions by Antoine
email: [email protected]
- family-names: Tuszynski
given-names: Jarek
- family-names: Bengtsson
given-names: Henrik
- family-names: Urbanek
given-names: Simon
- family-names: Frasca
given-names: Mario
- family-names: Lewis
given-names: Bryan
- family-names: Stokely
given-names: Murray
- family-names: Muehleisen
given-names: Hannes
- family-names: Murdoch
given-names: Duncan
- family-names: Hester
given-names: Jim
- family-names: Wu
given-names: Wush
- family-names: Kou
given-names: Qiang
- family-names: Onkelinx
given-names: Thierry
- family-names: Lang
given-names: Michel
- family-names: Simko
given-names: Viliam
- family-names: Hornik
given-names: Kurt
- family-names: Neal
given-names: Radford
- family-names: Bell
given-names: Kendon
- family-names: de Queljoe
given-names: Matthew
- family-names: Suruceanu
given-names: Ion
- family-names: Denney
given-names: Bill
- family-names: Schumacher
given-names: Dirk
- family-names: Chang.
given-names: and Winston
year: '2022'
- type: software
title: fs
abstract: 'fs: Cross-Platform File System Operations Based on ''libuv'''
notes: Suggests
authors:
- family-names: Hester
given-names: Jim
- family-names: Wickham
given-names: Hadley
email: [email protected]
- family-names: Csárdi
given-names: Gábor
email: [email protected]
year: '2022'
- type: software
title: sass
abstract: 'sass: Syntactically Awesome Style Sheets (''Sass'')'
notes: Suggests
authors:
- family-names: Cheng
given-names: Joe
email: [email protected]
- family-names: Mastny
given-names: Timothy
email: [email protected]
- family-names: Iannone
given-names: Richard
email: [email protected]
orcid: https://orcid.org/0000-0003-3925-190X
- family-names: Schloerke
given-names: Barret
email: [email protected]
orcid: https://orcid.org/0000-0001-9986-114X
- family-names: Sievert
given-names: Carson
email: [email protected]
orcid: https://orcid.org/0000-0002-4958-2844
year: '2022'
version: '>= 0.4.0'
- type: software
title: testthat
abstract: 'testthat: Unit Testing for R'
notes: Suggests
authors:
- family-names: Wickham
given-names: Hadley
email: [email protected]
year: '2022'
version: '>= 3.0.3'
- type: software
title: tibble
abstract: 'tibble: Simple Data Frames'
notes: Suggests
authors:
- family-names: Müller
given-names: Kirill
email: [email protected]
- family-names: Wickham
given-names: Hadley
email: [email protected]
year: '2022'
- type: software
title: vctrs
abstract: 'vctrs: Vector Helpers'
notes: Suggests
authors:
- family-names: Wickham
given-names: Hadley
email: [email protected]
- family-names: Henry
given-names: Lionel
email: [email protected]
- family-names: Vaughan
given-names: Davis
email: [email protected]
year: '2022'
url: https://vctrs.r-lib.org/
- type: software
title: withr
abstract: 'withr: Run Code ''With'' Temporarily Modified Global State'
notes: Suggests
authors:
- family-names: Hester
given-names: Jim
- family-names: Henry
given-names: Lionel
email: [email protected]
- family-names: Müller
given-names: Kirill
email: [email protected]
- family-names: Ushey
given-names: Kevin
email: [email protected]
- family-names: Wickham
given-names: Hadley
email: [email protected]
- family-names: Chang
given-names: Winston
year: '2022'
version: '>= 2.4.2'
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("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.
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
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 withgit 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.
Related packages
-
citation: The development version (at the time of this writing) includes a new function
r2cff
that creates aCITATION.cff
file (v1.1.0) using the information of yourDESCRIPTION
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 https://doi.org/10.21105/joss.03900, https://doi.org/10.21105/joss.03900.
A BibTeX entry for LaTeX users is
@Article{hernangomez2021,
= {10.21105/joss.03900},
doi = {https://doi.org/10.21105/joss.03900},
url = {2021},
year = {The Open Journal},
publisher = {6},
volume = {67},
number = {3900},
pages = {Diego Hernangómez},
author = {cffr: Generate Citation File Format Metadata for R Packages},
title = {Journal of Open Source Software},
journal }
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.