Generate Citation File Format ('cff').
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 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 (Boettiger and Salmon 2021a) / codemetar (Boettiger and Salmon 2021b) 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 2024-08-11 there are at least 296 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:
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
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.27'
identifiers:
- type: doi
value: 10.32614/CRAN.package.rmarkdown
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: Dervieux
given-names: Christophe
email: [email protected]
orcid: https://orcid.org/0000-0003-4474-2498
- family-names: McPherson
given-names: Jonathan
email: [email protected]
- family-names: Luraschi
given-names: Javier
- 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: Dervieux
given-names: Christophe
email: [email protected]
orcid: https://orcid.org/0000-0003-4474-2498
- family-names: McPherson
given-names: Jonathan
email: [email protected]
- family-names: Luraschi
given-names: Javier
- 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: '2024'
notes: R package version 2.27
url: https://github.com/rstudio/rmarkdown
repository: https://CRAN.R-project.org/package=rmarkdown
repository-code: https://github.com/rstudio/rmarkdown
commit: '2.27'
url: https://pkgs.rstudio.com/rmarkdown/
date-released: '2024-05-17'
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'
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'
isbn: '9780367563837'
url: https://bookdown.org/yihui/rmarkdown-cookbook
- type: software
title: 'R: A Language and Environment for Statistical Computing'
notes: Depends
url: https://www.R-project.org/
authors:
- name: R Core Team
institution:
name: R Foundation for Statistical Computing
address: Vienna, Austria
year: '2024'
version: '>= 3.0'
- type: software
title: bslib
abstract: 'bslib: Custom ''Bootstrap'' ''Sass'' Themes for ''shiny'' and ''rmarkdown'''
notes: Imports
url: https://rstudio.github.io/bslib/
repository: https://CRAN.R-project.org/package=bslib
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]
- family-names: Aden-Buie
given-names: Garrick
email: [email protected]
orcid: https://orcid.org/0000-0002-7111-0077
year: '2024'
doi: 10.32614/CRAN.package.bslib
version: '>= 0.2.5.1'
- type: software
title: evaluate
abstract: 'evaluate: Parsing and Evaluation Tools that Provide More Details than
the Default'
notes: Imports
url: https://github.com/r-lib/evaluate
repository: https://CRAN.R-project.org/package=evaluate
authors:
- family-names: Wickham
given-names: Hadley
email: [email protected]
- family-names: Xie
given-names: Yihui
orcid: https://orcid.org/0000-0003-0645-5666
year: '2024'
doi: 10.32614/CRAN.package.evaluate
version: '>= 0.13'
- type: software
title: fontawesome
abstract: 'fontawesome: Easily Work with ''Font Awesome'' Icons'
notes: Imports
url: https://rstudio.github.io/fontawesome/
repository: https://CRAN.R-project.org/package=fontawesome
authors:
- family-names: Iannone
given-names: Richard
email: [email protected]
orcid: https://orcid.org/0000-0003-3925-190X
year: '2024'
doi: 10.32614/CRAN.package.fontawesome
version: '>= 0.5.0'
- type: software
title: htmltools
abstract: 'htmltools: Tools for HTML'
notes: Imports
url: https://rstudio.github.io/htmltools/
repository: https://CRAN.R-project.org/package=htmltools
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
year: '2024'
doi: 10.32614/CRAN.package.htmltools
version: '>= 0.5.1'
- type: software
title: jquerylib
abstract: 'jquerylib: Obtain ''jQuery'' as an HTML Dependency Object'
notes: Imports
repository: https://CRAN.R-project.org/package=jquerylib
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: '2024'
doi: 10.32614/CRAN.package.jquerylib
- type: software
title: jsonlite
abstract: 'jsonlite: A Simple and Robust JSON Parser and Generator for R'
notes: Imports
url: https://jeroen.r-universe.dev/jsonlite
repository: https://CRAN.R-project.org/package=jsonlite
authors:
- family-names: Ooms
given-names: Jeroen
email: [email protected]
orcid: https://orcid.org/0000-0002-4035-0289
year: '2024'
doi: 10.32614/CRAN.package.jsonlite
- type: software
title: knitr
abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
notes: Imports
url: https://yihui.org/knitr/
repository: https://CRAN.R-project.org/package=knitr
authors:
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
year: '2024'
doi: 10.32614/CRAN.package.knitr
version: '>= 1.43'
- type: software
title: methods
abstract: 'R: A Language and Environment for Statistical Computing'
notes: Imports
authors:
- name: R Core Team
institution:
name: R Foundation for Statistical Computing
address: Vienna, Austria
year: '2024'
- type: software
title: tinytex
abstract: 'tinytex: Helper Functions to Install and Maintain TeX Live, and Compile
LaTeX Documents'
notes: Imports
url: https://github.com/rstudio/tinytex
repository: https://CRAN.R-project.org/package=tinytex
authors:
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
year: '2024'
doi: 10.32614/CRAN.package.tinytex
version: '>= 0.31'
- type: software
title: tools
abstract: 'R: A Language and Environment for Statistical Computing'
notes: Imports
authors:
- name: R Core Team
institution:
name: R Foundation for Statistical Computing
address: Vienna, Austria
year: '2024'
- type: software
title: utils
abstract: 'R: A Language and Environment for Statistical Computing'
notes: Imports
authors:
- name: R Core Team
institution:
name: R Foundation for Statistical Computing
address: Vienna, Austria
year: '2024'
- type: software
title: xfun
abstract: 'xfun: Supporting Functions for Packages Maintained by ''Yihui Xie'''
notes: Imports
url: https://github.com/yihui/xfun
repository: https://CRAN.R-project.org/package=xfun
authors:
- family-names: Xie
given-names: Yihui
email: [email protected]
orcid: https://orcid.org/0000-0003-0645-5666
year: '2024'
doi: 10.32614/CRAN.package.xfun
version: '>= 0.36'
- type: software
title: yaml
abstract: 'yaml: Methods to Convert R Data to YAML and Back'
notes: Imports
url: https://github.com/vubiostat/r-yaml/
repository: https://CRAN.R-project.org/package=yaml
authors:
- family-names: Garbett
given-names: Shawn P
- 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.
- family-names: Quinn
given-names: Michael
- family-names: Kamvar
given-names: Zhian N.
- family-names: Gao
given-names: Charlie
year: '2024'
doi: 10.32614/CRAN.package.yaml
version: '>= 2.1.19'
- type: software
title: digest
abstract: 'digest: Create Compact Hash Digests of R Objects'
notes: Suggests
url: https://dirk.eddelbuettel.com/code/digest.html
repository: https://CRAN.R-project.org/package=digest
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: Queljoe
given-names: Matthew
name-particle: de
- family-names: Suruceanu
given-names: Ion
- family-names: Denney
given-names: Bill
- family-names: Schumacher
given-names: Dirk
- family-names: Chang
given-names: Winston
- family-names: Attali
given-names: Dean
- family-names: Chirico.
given-names: Michael
year: '2024'
doi: 10.32614/CRAN.package.digest
- type: software
title: fs
abstract: 'fs: Cross-Platform File System Operations Based on ''libuv'''
notes: Suggests
url: https://fs.r-lib.org
repository: https://CRAN.R-project.org/package=fs
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: '2024'
doi: 10.32614/CRAN.package.fs
- type: software
title: downlit
abstract: 'downlit: Syntax Highlighting and Automatic Linking'
notes: Suggests
url: https://downlit.r-lib.org/
repository: https://CRAN.R-project.org/package=downlit
authors:
- family-names: Wickham
given-names: Hadley
email: [email protected]
year: '2024'
doi: 10.32614/CRAN.package.downlit
version: '>= 0.4.0'
- type: software
title: sass
abstract: 'sass: Syntactically Awesome Style Sheets (''Sass'')'
notes: Suggests
url: https://rstudio.github.io/sass/
repository: https://CRAN.R-project.org/package=sass
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: '2024'
doi: 10.32614/CRAN.package.sass
version: '>= 0.4.0'
- type: software
title: shiny
abstract: 'shiny: Web Application Framework for R'
notes: Suggests
url: https://shiny.posit.co/
repository: https://CRAN.R-project.org/package=shiny
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
- family-names: McPherson
given-names: Jonathan
email: [email protected]
- family-names: Dipert
given-names: Alan
- family-names: Borges
given-names: Barbara
year: '2024'
doi: 10.32614/CRAN.package.shiny
version: '>= 1.6.0'
- type: software
title: testthat
abstract: 'testthat: Unit Testing for R'
notes: Suggests
url: https://testthat.r-lib.org
repository: https://CRAN.R-project.org/package=testthat
authors:
- family-names: Wickham
given-names: Hadley
email: [email protected]
year: '2024'
doi: 10.32614/CRAN.package.testthat
version: '>= 3.0.3'
- type: software
title: tibble
abstract: 'tibble: Simple Data Frames'
notes: Suggests
url: https://tibble.tidyverse.org/
repository: https://CRAN.R-project.org/package=tibble
authors:
- family-names: Müller
given-names: Kirill
email: [email protected]
orcid: https://orcid.org/0000-0002-1416-3412
- family-names: Wickham
given-names: Hadley
email: [email protected]
year: '2024'
doi: 10.32614/CRAN.package.tibble
- type: software
title: vctrs
abstract: 'vctrs: Vector Helpers'
notes: Suggests
url: https://vctrs.r-lib.org/
repository: https://CRAN.R-project.org/package=vctrs
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: '2024'
doi: 10.32614/CRAN.package.vctrs
- type: software
title: withr
abstract: 'withr: Run Code ''With'' Temporarily Modified Global State'
notes: Suggests
url: https://withr.r-lib.org
repository: https://CRAN.R-project.org/package=withr
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: '2024'
doi: 10.32614/CRAN.package.withr
version: '>= 2.4.2'
- type: software
title: xml2
abstract: 'xml2: Parse XML'
notes: Suggests
url: https://xml2.r-lib.org/
repository: https://CRAN.R-project.org/package=xml2
authors:
- family-names: Wickham
given-names: Hadley
email: [email protected]
- family-names: Hester
given-names: Jim
- family-names: Ooms
given-names: Jeroen
year: '2024'
doi: 10.32614/CRAN.package.xml2
We can validate the result using cff_validate()
:
cff_validate(test)
#> ══ Validating cff ══════════════════════════════════════════════════════════════
#> ✔ Congratulations! This <cff> 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.
Learn more
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
Related packages
- citation (Dietrich and Leoncio 2022) includes a function
r2cff
that creates aCITATION.cff
file (v1.1.0) using the information of yourDESCRIPTION
file. It also provide minimal validity checks. - handlr (Chamberlain 2022): Tool for converting among citation formats, including
*.cff
files. - codemeta (Boettiger and Salmon 2021a) / codemetar (Boettiger and Salmon 2021b) 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, https://doi.org/10.21105/joss.03900
A BibTeX entry for LaTeX users is:
@article{hernangomez2021,
title = {{cffr}: Generate Citation File Format Metadata for {R} Packages},
author = {Diego Hernangómez},
year = 2021,
journal = {Journal of Open Source Software},
publisher = {The Open Journal},
volume = 6,
number = 67,
pages = 3900,
doi = {10.21105/joss.03900},
url = {https://doi.org/10.21105/joss.03900}
}
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
Boettiger, Carl, and Maëlle Salmon. 2021a. codemeta: A Smaller codemetar Package. https://CRAN.R-project.org/package=codemeta.
———. 2021b. codemetar: Generate ’CodeMeta’ Metadata for R Packages.
Chamberlain, Scott. 2022. handlr: Convert Among Citation Formats.
Dietrich, Jan Philipp, and Waldir Leoncio. 2022. citation: Software Citation Tools.
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/news-insights/company-news/enhanced-support-citations-github/.