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.
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.
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.
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-01-16 there are at least 80 repos on GitHub using cffr. Check them out here.
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")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 validHowever, 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: [email protected]
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
- family-names: McPherson
given-names: Jonathan
email: [email protected]
- family-names: Luraschi
given-names: Javier
email: [email protected]
- family-names: Ushey
given-names: Kevin
email: [email protected]
- family-names: Atkins
given-names: Aron
email: [email protected]
- family-names: Wickham
given-names: Hadley
email: [email protected]
- family-names: Cheng
given-names: Joe
email: [email protected]
- family-names: Chang
given-names: Winston
email: [email protected]
- family-names: Iannone
given-names: Richard
email: [email protected]
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
email: [email protected]
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
- family-names: McPherson
given-names: Jonathan
email: [email protected]
- family-names: Luraschi
given-names: Javier
email: [email protected]
- family-names: Ushey
given-names: Kevin
email: [email protected]
- family-names: Atkins
given-names: Aron
email: [email protected]
- family-names: Wickham
given-names: Hadley
email: [email protected]
- family-names: Cheng
given-names: Joe
email: [email protected]
- family-names: Chang
given-names: Winston
email: [email protected]
- family-names: Iannone
given-names: Richard
email: [email protected]
orcid: https://orcid.org/0000-0003-3925-190X
year: '2021'
notes: R package version 2.11
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: [email protected]
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
address: Boca Raton, Florida
year: '2018'
notes: ISBN 9781138359338
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
address: Boca Raton, Florida
year: '2020'
notes: ISBN 9780367563837
url: https://bookdown.org/yihui/rmarkdown-cookbook
- type: software
title: 'R: A Language and Environment for Statistical Computing'
notes: Depends
authors:
- name: R Core Team
location:
name: Vienna, Austria
year: '2022'
url: https://www.R-project.org/
institution:
name: R Foundation for Statistical Computing
version: '>= 3.0'
- type: software
title: tools
abstract: 'R: A Language and Environment for Statistical Computing'
notes: Imports
authors:
- name: R Core Team
location:
name: Vienna, Austria
year: '2022'
url: https://www.R-project.org/
institution:
name: R Foundation for Statistical Computing
- type: software
title: utils
abstract: 'R: A Language and Environment for Statistical Computing'
notes: Imports
authors:
- name: R Core Team
location:
name: Vienna, Austria
year: '2022'
url: https://www.R-project.org/
institution:
name: R Foundation for Statistical Computing
- type: software
title: knitr
abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
notes: Imports
authors:
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
year: '2022'
url: https://CRAN.R-project.org/package=knitr
version: '>= 1.22'
- type: software
title: yaml
abstract: 'yaml: Methods to Convert R Data to YAML and Back'
notes: Imports
authors:
- family-names: Stephens
given-names: Jeremy
- family-names: Simonov
given-names: Kirill
- family-names: Xie
given-names: Yihui
- family-names: Dong
given-names: Zhuoer
- family-names: Wickham
given-names: Hadley
- family-names: Horner
given-names: Jeffrey
- name: reikoch
- family-names: Beasley
given-names: Will
- family-names: O'Connor
given-names: Brendan
- family-names: Warnes
given-names: Gregory R.
year: '2022'
url: https://CRAN.R-project.org/package=yaml
version: '>= 2.1.19'
- type: software
title: htmltools
abstract: 'htmltools: Tools for HTML'
notes: Imports
authors:
- family-names: Cheng
given-names: Joe
email: [email protected]
- family-names: Sievert
given-names: Carson
email: [email protected]
orcid: https://orcid.org/0000-0002-4958-2844
- family-names: Schloerke
given-names: Barret
email: [email protected]
orcid: https://orcid.org/0000-0001-9986-114X
- family-names: Chang
given-names: Winston
email: [email protected]
orcid: https://orcid.org/0000-0002-1576-2126
- family-names: Xie
given-names: Yihui
email: [email protected]
- family-names: Allen
given-names: Jeff
email: [email protected]
year: '2022'
url: https://CRAN.R-project.org/package=htmltools
version: '>= 0.3.5'
- type: software
title: evaluate
abstract: 'evaluate: Parsing and Evaluation Tools that Provide More Details than
the Default'
notes: Imports
authors:
- family-names: Wickham
given-names: Hadley
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
year: '2022'
url: https://CRAN.R-project.org/package=evaluate
version: '>= 0.13'
- type: software
title: jsonlite
abstract: 'jsonlite: A Simple and Robust JSON Parser and Generator for R'
notes: Imports
authors:
- family-names: Ooms
given-names: Jeroen
email: [email protected]
orcid: https://orcid.org/0000-0002-4035-0289
year: '2022'
url: https://CRAN.R-project.org/package=jsonlite
- type: software
title: tinytex
abstract: 'tinytex: Helper Functions to Install and Maintain TeX Live, and Compile
LaTeX Documents'
notes: Imports
authors:
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
year: '2022'
url: https://CRAN.R-project.org/package=tinytex
version: '>= 0.31'
- type: software
title: xfun
abstract: 'xfun: Supporting Functions for Packages Maintained by ''Yihui Xie'''
notes: Imports
authors:
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
year: '2022'
url: https://CRAN.R-project.org/package=xfun
version: '>= 0.21'
- type: software
title: jquerylib
abstract: 'jquerylib: Obtain ''jQuery'' as an HTML Dependency Object'
notes: Imports
authors:
- family-names: Sievert
given-names: Carson
email: [email protected]
orcid: https://orcid.org/0000-0002-4958-2844
- family-names: Cheng
given-names: Joe
email: [email protected]
year: '2022'
url: https://CRAN.R-project.org/package=jquerylib
- type: software
title: methods
abstract: 'R: A Language and Environment for Statistical Computing'
notes: Imports
authors:
- name: R Core Team
location:
name: Vienna, Austria
year: '2022'
url: https://www.R-project.org/
institution:
name: R Foundation for Statistical Computing
- type: software
title: stringr
abstract: 'stringr: Simple, Consistent Wrappers for Common String Operations'
notes: Imports
authors:
- family-names: Wickham
given-names: Hadley
email: [email protected]
year: '2022'
url: https://CRAN.R-project.org/package=stringr
version: '>= 1.2.0'
- type: software
title: shiny
abstract: 'shiny: Web Application Framework for R'
notes: Suggests
authors:
- family-names: Chang
given-names: Winston
email: [email protected]
orcid: https://orcid.org/0000-0002-1576-2126
- family-names: Cheng
given-names: Joe
email: [email protected]
- family-names: Allaire
given-names: JJ
email: [email protected]
- family-names: Sievert
given-names: Carson
email: [email protected]
orcid: https://orcid.org/0000-0002-4958-2844
- family-names: Schloerke
given-names: Barret
email: [email protected]
orcid: https://orcid.org/0000-0001-9986-114X
- family-names: Xie
given-names: Yihui
email: [email protected]
- family-names: Allen
given-names: Jeff
email: [email protected]
- family-names: McPherson
given-names: Jonathan
email: [email protected]
- family-names: Dipert
given-names: Alan
- family-names: Borges
given-names: Barbara
year: '2022'
url: https://CRAN.R-project.org/package=shiny
version: '>= 1.6.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'
url: https://CRAN.R-project.org/package=testthat
version: '>= 3.0.0'
- 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'
url: https://CRAN.R-project.org/package=digest
- 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://CRAN.R-project.org/package=vctrs
- 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'
url: https://CRAN.R-project.org/package=tibble
- 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'
url: https://CRAN.R-project.org/package=fs
- type: software
title: rsconnect
abstract: 'rsconnect: Deployment Interface for R Markdown Documents and Shiny Applications'
notes: Suggests
authors:
- family-names: Atkins
given-names: Aron
email: [email protected]
- family-names: McPherson
given-names: Jonathan
email: [email protected]
- family-names: Allaire
given-names: JJ
year: '2022'
url: https://CRAN.R-project.org/package=rsconnect
- 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'
url: https://CRAN.R-project.org/package=withr
version: '>= 2.4.2'
- type: software
title: bslib
abstract: 'bslib: Custom ''Bootstrap'' ''Sass'' Themes for ''shiny'' and ''rmarkdown'''
notes: Suggests
authors:
- family-names: Sievert
given-names: Carson
email: [email protected]
orcid: https://orcid.org/0000-0002-4958-2844
- family-names: Cheng
given-names: Joe
email: [email protected]
year: '2022'
url: https://CRAN.R-project.org/package=bslib
version: '>= 0.2.5.1'
- 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'
url: https://CRAN.R-project.org/package=sass
version: '>= 0.4.0'
We can validate the result using cff_validate():
cff_validate(test)
#>
#> cff_validate results-----
#> Congratulations! This cff object is validCheck the docs
and vignette("cffr", package = "cffr") to learn how to work with cff
objects.
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 .RbuildignoreSee the example workflow file here.
You can also use a git pre-commit hook:
The
pre-commithook 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.
Check the following articles to learn more about cffr:
- cffr: Create a CITATION.cff File for your R Package
- How I Test cffr on (about) 2,000 Packages using GitHub Actions and R-universe
- citation: The
development version (at the time of this writing) includes a new
function
r2cffthat creates aCITATION.cfffile (v1.1.0) using the information of yourDESCRIPTIONfile. It also provide minimal validity checks. - handlr: Tool for
converting among citation formats, including
*.cfffiles. At the time of this writing only CFF v1.1.0 was supported (see #24). - codemeta/
codemetar provides
similar solutions for creating
codemeta.jsonfile, another format for storing and sharing software metadata.
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
@Article{hernangomez2021,
doi = {10.21105/joss.03900},
url = {https://doi.org/10.21105/joss.03900},
year = {2021},
publisher = {The Open Journal},
volume = {6},
number = {67},
pages = {3900},
author = {Diego Hernangómez},
title = {cffr: Generate Citation File Format Metadata for R Packages},
journal = {Journal of Open Source Software},
}
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.
Druskat, Stephan. 2021. “Making Software Citation Easi(er) - The Citation File Format and Its Integrations.” 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.” 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/.
