From R to CFF

Crosswalk

Diego Hernangómez

The goal of this vignette is to provide an explicit map between the metadata fields used by cffr and each one of the valid keys of the Citation File Format schema version 1.2.0.

Summary

We summarize here the fields that cffr can parse and the original source of information for each one of them. The details on each key are presented on the next section of the document. The assessment of fields are based on the Guide to Citation File Format schema version 1.2.0 (Druskat et al. 2021).

key source
abstract DESCRIPTION file
authors DESCRIPTION file
cff-version parameter on function
commit Not parsed by cffr
contact DESCRIPTION file
date-released DESCRIPTION file
doi CITATION file
identifiers DESCRIPTION/CITATION files
keywords DESCRIPTION file
license DESCRIPTION file
license-url Not parsed by cffr
message DESCRIPTION file
preferred-citation CITATION file
references DESCRIPTION/CITATION files
repository DESCRIPTION file
repository-artifact Not parsed by cffr
repository-code DESCRIPTION file
title DESCRIPTION file
type Fixed value: ‘software’
url DESCRIPTION file
version DESCRIPTION file

Details

abstract

This key is extracted from the “Description” field of the DESCRIPTION file.

Example


library(cffr)

# Create cffr for yaml

cff_obj <- cff_create("rmarkdown")

# Get DESCRIPTION of rmarkdown to check

pkg <- desc::desc(file.path(find.package("rmarkdown"), "DESCRIPTION"))

cat(cff_obj$abstract)
#> Convert R Markdown documents into a variety of formats.

cat(pkg$get("Description"))
#> Convert R Markdown documents into a variety of formats.

Back to summary.

authors

This key is parsed from the “Authors” or “Authors@R” field of the DESCRIPTION file. Only persons with the role “aut” or “cre” are considered.

Example


cff_obj <- cff_create("rmarkdown")
pkg <- desc::desc(file.path(find.package("rmarkdown"), "DESCRIPTION"))

cff_obj$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

authors <- pkg$get_authors()

authors[vapply(authors, function(x) {
  "aut" %in% x$role || "cre" %in% x$role
}, logical(1))]
#>  [1] "JJ Allaire <jj@rstudio.com> [aut]"                                                 
#>  [2] "Yihui Xie <xie@yihui.name> [aut, cre] (<https://orcid.org/0000-0003-0645-5666>)"   
#>  [3] "Jonathan McPherson <jonathan@rstudio.com> [aut]"                                   
#>  [4] "Javier Luraschi <javier@rstudio.com> [aut]"                                        
#>  [5] "Kevin Ushey <kevin@rstudio.com> [aut]"                                             
#>  [6] "Aron Atkins <aron@rstudio.com> [aut]"                                              
#>  [7] "Hadley Wickham <hadley@rstudio.com> [aut]"                                         
#>  [8] "Joe Cheng <joe@rstudio.com> [aut]"                                                 
#>  [9] "Winston Chang <winston@rstudio.com> [aut]"                                         
#> [10] "Richard Iannone <rich@rstudio.com> [aut] (<https://orcid.org/0000-0003-3925-190X>)"

Back to summary.

cff-version

This key can be set via the parameters of the cff_create()/cff_write() functions:

Example


cff_objv110 <- cff_create("jsonlite", cff_version = "v1.1.0")

cat(cff_objv110$`cff-version`)
#> v1.1.0

Back to summary.

commit

This key is not extracted from the metadata of the package. See the description on the Guide to CFF schema v1.2.0.

  • description: The commit hash or revision number of the software version.

  • usage:

    commit: 1ff847d81f29c45a3a1a5ce73d38e45c2f319bba
    
    commit: "Revision: 8612"

Back to summary.

contact

This key is parsed from the “Authors” or “Authors@R” field of the DESCRIPTION file. Only persons with the role “cre” (i.e, the maintainer(s)) are considered.

Example


cff_obj <- cff_create("rmarkdown")
pkg <- desc::desc(file.path(find.package("rmarkdown"), "DESCRIPTION"))

cff_obj$contact
#> - family-names: Xie
#>   given-names: Yihui
#>   email: xie@yihui.name
#>   orcid: https://orcid.org/0000-0003-0645-5666

pkg$get_author()
#> [1] "Yihui Xie <xie@yihui.name> [aut, cre] (<https://orcid.org/0000-0003-0645-5666>)"

Back to summary.

date-released

This key is parsed from the “Date” field or, if not present, from the “Date/Publication” field that is present on packages built on CRAN.

Example


# From an installed package

cff_obj <- cff_create("rmarkdown")
pkg <- desc::desc(file.path(find.package("rmarkdown"), "DESCRIPTION"))


cat(pkg$get("Date/Publication"))
#> 2022-08-24 19:50:02 UTC


cat(cff_obj$`date-released`)
#> 2022-08-24



# A DESCRIPTION file without a Date
nodate <- system.file("examples/DESCRIPTION_basic", package = "cffr")
tmp <- tempfile("DESCRIPTION")

# Create a temporary file
file.copy(nodate, tmp)
#> [1] TRUE


pkgnodate <- desc::desc(tmp)
cffnodate <- cff_create(tmp)

# Won't appear
cat(cffnodate$`date-released`)

pkgnodate
#> Type: Package
#> Package: basicdesc
#> Title: A Basic Description
#> Version: 0.1.6
#> Authors@R (parsed):
#>     * Marc Basic <marcbasic@gmail.com> [aut, cre, cph]
#> Description: A very basic description. Should parse without problems.
#> License: GPL-3
#> URL: https://github.com/basic/package, https://basic.github.io/package
#> BugReports: https://github.com/basic/package/issues
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 6.0.1.9000

# Adding a Date

desc::desc_set("Date", "1999-01-01", file = tmp)
#> Type: Package
#> Package: basicdesc
#> Title: A Basic Description
#> Version: 0.1.6
#> Date: 1999-01-01
#> Authors@R (parsed):
#>     * Marc Basic <marcbasic@gmail.com> [aut, cre, cph]
#> Description: A very basic description. Should parse without problems.
#> License: GPL-3
#> URL: https://github.com/basic/package, https://basic.github.io/package
#> BugReports: https://github.com/basic/package/issues
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 6.0.1.9000

cat(cff_create(tmp)$`date-released`)
#> 1999-01-01

Back to summary.

doi

This key is parsed from the “doi” field of the preferred-citation object.

Example


cff_doi <- cff_create("cffr")

cat(cff_doi$doi)
#> 10.21105/joss.03900

cat(cff_doi$`preferred-citation`$doi)
#> 10.21105/joss.03900

Back to summary.

identifiers

This key includes all the possible identifiers of the package:

Example

file <- system.file("examples/DESCRIPTION_many_urls", package = "cffr")

pkg <- desc::desc(file)

cat(pkg$get_urls())
#> https://github.com/test/package https://test.github.io/package/ https://r-forge.r-project.org/projects/test/ http://google.ru https://gitlab.com/r-packages/behaviorchange

cat(cff_create(file)$url)
#> https://test.github.io/package/

cat(cff_create(file)$`repository-code`)
#> https://github.com/test/package

cff_create(file)$identifiers
#> - type: url
#>   value: https://r-forge.r-project.org/projects/test/
#> - type: url
#>   value: http://google.ru
#> - type: url
#>   value: https://gitlab.com/r-packages/behaviorchange

Back to summary.

keywords

This key is extracted from the DESCRIPTION file. The keywords should appear in the DESCRIPTION as:

...
X-schema.org-keywords: keyword1, keyword2, keyword3

Example


# A DESCRIPTION file without keywords
nokeywords <- system.file("examples/DESCRIPTION_basic", package = "cffr")
tmp2 <- tempfile("DESCRIPTION")

# Create a temporary file
file.copy(nokeywords, tmp2)
#> [1] TRUE


pkgnokeywords <- desc::desc(tmp2)
cffnokeywords <- cff_create(tmp2)

# Won't appear
cat(cffnokeywords$keywords)

pkgnokeywords
#> Type: Package
#> Package: basicdesc
#> Title: A Basic Description
#> Version: 0.1.6
#> Authors@R (parsed):
#>     * Marc Basic <marcbasic@gmail.com> [aut, cre, cph]
#> Description: A very basic description. Should parse without problems.
#> License: GPL-3
#> URL: https://github.com/basic/package, https://basic.github.io/package
#> BugReports: https://github.com/basic/package/issues
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 6.0.1.9000

# Adding Keywords

desc::desc_set("X-schema.org-keywords", "keyword1, keyword2, keyword3",
  file = tmp2
)
#> Type: Package
#> Package: basicdesc
#> Title: A Basic Description
#> Version: 0.1.6
#> Authors@R (parsed):
#>     * Marc Basic <marcbasic@gmail.com> [aut, cre, cph]
#> Description: A very basic description. Should parse without problems.
#> License: GPL-3
#> URL: https://github.com/basic/package, https://basic.github.io/package
#> BugReports: https://github.com/basic/package/issues
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 6.0.1.9000
#> X-schema.org-keywords: keyword1, keyword2, keyword3

cat(cff_create(tmp2)$keywords)
#> keyword1 keyword2 keyword3

Additionally, if the source code of the package is hosted on GitHub, cffr can retrieve the topics of your repo via the GitHub API and include those topics as keywords. This option is controlled via the gh_keywords parameter:

Example


# Get cff object from jsonvalidate

jsonval <- cff_create("jsonvalidate")

# Keywords are retrieved from the GitHub repo

jsonval
#> cff-version: 1.2.0
#> message: 'To cite package "jsonvalidate" in publications use:'
#> type: software
#> license: MIT
#> title: 'jsonvalidate: Validate ''JSON'' Schema'
#> version: 1.3.2
#> abstract: Uses the node library 'is-my-json-valid' or 'ajv' to validate 'JSON' against
#>   a 'JSON' schema. Drafts 04, 06 and 07 of 'JSON' schema are supported.
#> authors:
#> - family-names: FitzJohn
#>   given-names: Rich
#>   email: rich.fitzjohn@gmail.com
#> - family-names: Ashton
#>   given-names: Rob
#> - family-names: Buus
#>   given-names: Mathias
#> - family-names: Poberezkin
#>   given-names: Evgeny
#> repository: https://CRAN.R-project.org/package=jsonvalidate
#> repository-code: https://github.com/ropensci/jsonvalidate
#> url: https://docs.ropensci.org/jsonvalidate/
#> date-released: '2021-11-03'
#> contact:
#> - family-names: FitzJohn
#>   given-names: Rich
#>   email: rich.fitzjohn@gmail.com
#> keywords:
#> - json
#> - json-validation
#> - jsonvalidate
#> - r
#> - r-package
#> - rstats
#> references:
#> - type: software
#>   title: V8
#>   abstract: 'V8: Embedded JavaScript and WebAssembly Engine for R'
#>   notes: Imports
#>   authors:
#>   - family-names: Ooms
#>     given-names: Jeroen
#>     email: jeroen@berkeley.edu
#>     orcid: https://orcid.org/0000-0002-4035-0289
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=V8
#> - type: software
#>   title: knitr
#>   abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
#>   notes: Suggests
#>   authors:
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: xie@yihui.name
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=knitr
#> - type: software
#>   title: jsonlite
#>   abstract: 'jsonlite: A Simple and Robust JSON Parser and Generator for R'
#>   notes: Suggests
#>   authors:
#>   - family-names: Ooms
#>     given-names: Jeroen
#>     email: jeroen@berkeley.edu
#>     orcid: https://orcid.org/0000-0002-4035-0289
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=jsonlite
#> - type: software
#>   title: rmarkdown
#>   abstract: 'rmarkdown: Dynamic Documents for R'
#>   notes: Suggests
#>   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
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=rmarkdown
#> - type: software
#>   title: testthat
#>   abstract: 'testthat: Unit Testing for R'
#>   notes: Suggests
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: hadley@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=testthat
#> - 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: lionel@rstudio.com
#>   - family-names: Müller
#>     given-names: Kirill
#>     email: krlmlr+r@mailbox.org
#>   - family-names: Ushey
#>     given-names: Kevin
#>     email: kevinushey@gmail.com
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: hadley@rstudio.com
#>   - family-names: Chang
#>     given-names: Winston
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=withr

# Check keywords
jsonval$keywords
#> [1] "json"            "json-validation" "jsonvalidate"   
#> [4] "r"               "r-package"       "rstats"

# The repo
jsonval$`repository-code`
#> [1] "https://github.com/ropensci/jsonvalidate"

Back to summary.

license

This key is extracted from the “License” field of the DESCRIPTION file.

Example


cff_obj <- cff_create("yaml")

cat(cff_obj$license)
#> BSD-3-Clause

pkg <- desc::desc(file.path(find.package("yaml"), "DESCRIPTION"))

cat(pkg$get("License"))
#> BSD_3_clause + file LICENSE

Back to summary.

license-url

This key is not extracted from the metadata of the package. See the description on the Guide to CFF schema v1.2.0.

  • description: The URL of the license text under which the software or dataset is licensed (only for non-standard licenses not included in the SPDX License List).
  • usage:

    yaml license-url: "https://obscure-licenses.com?id=1234"

Back to summary.

message

This key is extracted from the DESCRIPTION field, specifically as:

msg <- paste0(
  'To cite package "',
  "NAME_OF_THE_PACKAGE",
  '" in publications use:'
)

Example


cat(cff_create("jsonlite")$message)
#> To cite package "jsonlite" in publications use:

Back to summary.

preferred-citation

This key is extracted from the CITATION file. If several references are provided, it would select the first citation as the “preferred-citation” and the rest of them as references.

Example


cffobj <- cff_create("rmarkdown")

cffobj$`preferred-citation`
#> type: manual
#> title: 'rmarkdown: Dynamic Documents for R'
#> 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
#> year: '2022'
#> notes: R package version 2.16
#> url: https://github.com/rstudio/rmarkdown

citation("rmarkdown")[1]
#> 
#> JJ Allaire and Yihui Xie and Jonathan McPherson and
#> Javier Luraschi and Kevin Ushey and Aron Atkins and
#> Hadley Wickham and Joe Cheng and Winston Chang and
#> Richard Iannone (2022). rmarkdown: Dynamic Documents
#> for R. R package version 2.16. URL
#> https://rmarkdown.rstudio.com.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {rmarkdown: Dynamic Documents for R},
#>     author = {JJ Allaire and Yihui Xie and Jonathan McPherson and Javier Luraschi and Kevin Ushey and Aron Atkins and Hadley Wickham and Joe Cheng and Winston Chang and Richard Iannone},
#>     year = {2022},
#>     note = {R package version 2.16},
#>     url = {https://github.com/rstudio/rmarkdown},
#>   }

Back to summary.

references

This key is extracted from the CITATION file if several references are provided. The first citation is considered as the preferred-citation and the rest of them as “references”. It also extracts the package dependencies and adds those to this fields using citation(auto = TRUE) on each dependency.

Example


cffobj <- cff_create("rmarkdown")

cffobj$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: bslib
#>   abstract: 'bslib: Custom ''Bootstrap'' ''Sass'' Themes for ''shiny'' and ''rmarkdown'''
#>   notes: Imports
#>   authors:
#>   - family-names: Sievert
#>     given-names: Carson
#>     email: carson@rstudio.com
#>     orcid: https://orcid.org/0000-0002-4958-2844
#>   - family-names: Cheng
#>     given-names: Joe
#>     email: joe@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/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
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: xie@yihui.name
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=evaluate
#>   version: '>= 0.13'
#> - type: software
#>   title: htmltools
#>   abstract: 'htmltools: Tools for HTML'
#>   notes: Imports
#>   authors:
#>   - family-names: Cheng
#>     given-names: Joe
#>     email: joe@rstudio.com
#>   - family-names: Sievert
#>     given-names: Carson
#>     email: carson@rstudio.com
#>     orcid: https://orcid.org/0000-0002-4958-2844
#>   - family-names: Schloerke
#>     given-names: Barret
#>     email: barret@rstudio.com
#>     orcid: https://orcid.org/0000-0001-9986-114X
#>   - family-names: Chang
#>     given-names: Winston
#>     email: winston@rstudio.com
#>     orcid: https://orcid.org/0000-0002-1576-2126
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: yihui@rstudio.com
#>   - family-names: Allen
#>     given-names: Jeff
#>     email: jeff@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=htmltools
#>   version: '>= 0.5.1'
#> - type: software
#>   title: jquerylib
#>   abstract: 'jquerylib: Obtain ''jQuery'' as an HTML Dependency Object'
#>   notes: Imports
#>   authors:
#>   - family-names: Sievert
#>     given-names: Carson
#>     email: carson@rstudio.com
#>     orcid: https://orcid.org/0000-0002-4958-2844
#>   - family-names: Cheng
#>     given-names: Joe
#>     email: joe@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=jquerylib
#> - 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: jeroen@berkeley.edu
#>     orcid: https://orcid.org/0000-0002-4035-0289
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=jsonlite
#> - 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: xie@yihui.name
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=knitr
#>   version: '>= 1.22'
#> - 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: hadley@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=stringr
#>   version: '>= 1.2.0'
#> - 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: xie@yihui.name
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   year: '2022'
#>   url: https://CRAN.R-project.org/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
#>   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: xfun
#>   abstract: 'xfun: Supporting Functions for Packages Maintained by ''Yihui Xie'''
#>   notes: Imports
#>   authors:
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: xie@yihui.name
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=xfun
#>   version: '>= 0.30'
#> - type: software
#>   title: yaml
#>   abstract: 'yaml: Methods to Convert R Data to YAML and Back'
#>   notes: Imports
#>   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.
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=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: edd@debian.org
#>   - 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: dygraphs
#>   abstract: 'dygraphs: Interface to ''Dygraphs'' Interactive Time Series Charting
#>     Library'
#>   notes: Suggests
#>   authors:
#>   - family-names: Vanderkam
#>     given-names: Dan
#>   - family-names: Allaire
#>     given-names: JJ
#>   - family-names: Owen
#>     given-names: Jonathan
#>   - family-names: Gromer
#>     given-names: Daniel
#>   - family-names: Thieurmel
#>     given-names: Benoit
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=dygraphs
#> - 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: hadley@rstudio.com
#>   - family-names: Csárdi
#>     given-names: Gábor
#>     email: csardi.gabor@gmail.com
#>   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: aron@rstudio.com
#>   - family-names: McPherson
#>     given-names: Jonathan
#>     email: jonathan@rstudio.com
#>   - family-names: Allaire
#>     given-names: JJ
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=rsconnect
#> - type: software
#>   title: downlit
#>   abstract: 'downlit: Syntax Highlighting and Automatic Linking'
#>   notes: Suggests
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: hadley@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=downlit
#>   version: '>= 0.4.0'
#> - type: software
#>   title: katex
#>   abstract: 'katex: Rendering Math to HTML, ''MathML'', or R-Documentation Format'
#>   notes: Suggests
#>   authors:
#>   - family-names: Ooms
#>     given-names: Jeroen
#>     email: jeroen@berkeley.edu
#>     orcid: https://orcid.org/0000-0002-4035-0289
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=katex
#>   version: '>= 1.4.0'
#> - type: software
#>   title: sass
#>   abstract: 'sass: Syntactically Awesome Style Sheets (''Sass'')'
#>   notes: Suggests
#>   authors:
#>   - family-names: Cheng
#>     given-names: Joe
#>     email: joe@rstudio.com
#>   - family-names: Mastny
#>     given-names: Timothy
#>     email: tim.mastny@gmail.com
#>   - family-names: Iannone
#>     given-names: Richard
#>     email: rich@rstudio.com
#>     orcid: https://orcid.org/0000-0003-3925-190X
#>   - family-names: Schloerke
#>     given-names: Barret
#>     email: barret@rstudio.com
#>     orcid: https://orcid.org/0000-0001-9986-114X
#>   - family-names: Sievert
#>     given-names: Carson
#>     email: carson@rstudio.com
#>     orcid: https://orcid.org/0000-0002-4958-2844
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=sass
#>   version: '>= 0.4.0'
#> - type: software
#>   title: shiny
#>   abstract: 'shiny: Web Application Framework for R'
#>   notes: Suggests
#>   authors:
#>   - family-names: Chang
#>     given-names: Winston
#>     email: winston@rstudio.com
#>     orcid: https://orcid.org/0000-0002-1576-2126
#>   - family-names: Cheng
#>     given-names: Joe
#>     email: joe@rstudio.com
#>   - family-names: Allaire
#>     given-names: JJ
#>     email: jj@rstudio.com
#>   - family-names: Sievert
#>     given-names: Carson
#>     email: carson@rstudio.com
#>     orcid: https://orcid.org/0000-0002-4958-2844
#>   - family-names: Schloerke
#>     given-names: Barret
#>     email: barret@rstudio.com
#>     orcid: https://orcid.org/0000-0001-9986-114X
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: yihui@rstudio.com
#>   - family-names: Allen
#>     given-names: Jeff
#>     email: jeff@rstudio.com
#>   - family-names: McPherson
#>     given-names: Jonathan
#>     email: jonathan@rstudio.com
#>   - 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: hadley@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=testthat
#>   version: '>= 3.0.3'
#> - type: software
#>   title: tibble
#>   abstract: 'tibble: Simple Data Frames'
#>   notes: Suggests
#>   authors:
#>   - family-names: Müller
#>     given-names: Kirill
#>     email: krlmlr+r@mailbox.org
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: hadley@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=tibble
#> - type: software
#>   title: tufte
#>   abstract: 'tufte: Tufte''s Styles for R Markdown Documents'
#>   notes: Suggests
#>   authors:
#>   - family-names: Xie
#>     given-names: Yihui
#>     email: xie@yihui.name
#>     orcid: https://orcid.org/0000-0003-0645-5666
#>   - family-names: Allaire
#>     given-names: JJ
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=tufte
#> - type: software
#>   title: vctrs
#>   abstract: 'vctrs: Vector Helpers'
#>   notes: Suggests
#>   authors:
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: hadley@rstudio.com
#>   - family-names: Henry
#>     given-names: Lionel
#>     email: lionel@rstudio.com
#>   - family-names: Vaughan
#>     given-names: Davis
#>     email: davis@rstudio.com
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=vctrs
#> - 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: lionel@rstudio.com
#>   - family-names: Müller
#>     given-names: Kirill
#>     email: krlmlr+r@mailbox.org
#>   - family-names: Ushey
#>     given-names: Kevin
#>     email: kevinushey@gmail.com
#>   - family-names: Wickham
#>     given-names: Hadley
#>     email: hadley@rstudio.com
#>   - family-names: Chang
#>     given-names: Winston
#>   year: '2022'
#>   url: https://CRAN.R-project.org/package=withr
#>   version: '>= 2.4.2'

citation("rmarkdown")[-1]
#> 
#> Yihui Xie and J.J. Allaire and Garrett Grolemund
#> (2018). R Markdown: The Definitive Guide. Chapman and
#> Hall/CRC. ISBN 9781138359338. URL
#> https://bookdown.org/yihui/rmarkdown.
#> 
#> Yihui Xie and Christophe Dervieux and Emily Riederer
#> (2020). R Markdown Cookbook. Chapman and Hall/CRC.
#> ISBN 9780367563837. URL
#> https://bookdown.org/yihui/rmarkdown-cookbook.
#> 
#> To see these entries in BibTeX format, use
#> 'print(<citation>, bibtex=TRUE)', 'toBibtex(.)', or
#> set 'options(citation.bibtex.max=999)'.

Back to summary.

repository

This key is extracted from the “Repository” field of the DESCRIPTION file. Usually, this field is auto-populated when a package is hosted on a repo (like CRAN or the r-universe). For packages without this field on the DESCRIPTION (that is the typical case for an in-development package), cffr would try to search the package on any of the default repositories specified on options("repos").

In the case of Bioconductor packages, those are identified if a “biocViews” is present on the DESCRIPTION file.

If cffr detects that the package is available on CRAN, it would return the canonical url form of the package (i.e. https://CRAN.R-project.org/package=jsonlite).

Example


# Installed package

inst <- cff_create("jsonlite")

cat(inst$repository)
#> https://CRAN.R-project.org/package=jsonlite

# Demo file downloaded from the r-universe

runiv <- system.file("examples/DESCRIPTION_r_universe", package = "cffr")
runiv_cff <- cff_create(runiv)

cat(runiv_cff$repository)
#> https://ropensci.r-universe.dev

desc::desc(runiv)$get("Repository")
#>                        Repository 
#> "https://ropensci.r-universe.dev"

# For in development package

norepo <- system.file("examples/DESCRIPTION_basic", package = "cffr")

# No repo
norepo_cff <- cff_create(norepo)

cat(norepo_cff[["repository"]])

# Change the name to a known package on CRAN: ggplot2

tmp <- tempfile("DESCRIPTION")
file.copy(norepo, tmp)
#> [1] TRUE


# Change name
desc::desc_set("Package", "ggplot2", file = tmp)
#> Type: Package
#> Package: ggplot2
#> Title: A Basic Description
#> Version: 0.1.6
#> Authors@R (parsed):
#>     * Marc Basic <marcbasic@gmail.com> [aut, cre, cph]
#> Description: A very basic description. Should parse without problems.
#> License: GPL-3
#> URL: https://github.com/basic/package, https://basic.github.io/package
#> BugReports: https://github.com/basic/package/issues
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 6.0.1.9000

cat(cff_create(tmp)[["repository"]])
#> https://CRAN.R-project.org/package=ggplot2

# Show what happens if another repo is set

# Save original config
orig_options <- options()
getOption("repos")
#>     CRAN 
#> "@CRAN@"


# Set new repos
options(repos = c(
  tidyverse = "https://tidyverse.r-universe.dev",
  CRAN = "https://cloud.r-project.org"
))

# Load again the library
# Repos are evaluated on load
unloadNamespace("cffr")
library(cffr)


cat(cff_create(tmp)[["repository"]])
#> https://tidyverse.r-universe.dev/

# Now it is the tidyverse repo, due to our new config!

# Reset original config
options(orig_options)
getOption("repos")
#>     CRAN 
#> "@CRAN@"

Back to summary.

repository-artifact

This key is not extracted from the metadata of the package. See the description on the Guide to CFF schema v1.2.0.

  • description: The URL of the work in a build artifact/binary repository (when the work is software).

  • usage:

    repository-artifact: "https://search.maven.org/artifact/org.corpus-tools/cff-maven-plugin/0.4.0/maven-plugin"

Back to summary.

repository-code

This key is extracted from the “BugReports” or “URL” fields on the DESCRIPTION file. cffr tries to identify the url of the source on the following repositories:

Example


# Installed package on GitHub

cff_create("jsonlite")$`repository-code`
#> [1] "https://github.com/jeroen/jsonlite"



# GitLab

gitlab <- system.file("examples/DESCRIPTION_gitlab", package = "cffr")

cat(cff_create(gitlab)$`repository-code`)
#> https://gitlab.com/ninijay/methoden


# Check

desc::desc(gitlab)
#> Type: Package
#> Package: codemetar
#> Title: Generate 'CodeMeta' Metadata for R Packages
#> Version: 0.1.6
#> Authors@R (parsed):
#>     * Carl Boettiger <cboettig@gmail.com> [aut, cre, cph] (<https://orcid.org/0000-0002-1642-628X>)
#>     * Anna Krystalli [rev, ctb] (<https://orcid.org/0000-0002-2378-4915>)
#>     * Toph Allen [rev] (<https://orcid.org/0000-0003-4580-091X>)
#>     * Maëlle Salmon [ctb, aut] (<https://orcid.org/0000-0002-2815-0399>)
#>     * rOpenSci [fnd] (https://ropensci.org/)
#>     * Katrin Leinweber [ctb]
#>     * Noam Ross [ctb]
#>     * Arfon Smith [ctb]
#> Description: The 'Codemeta' Project defines a 'JSON-LD' format for
#>     describing software metadata, as detailed at
#>     <https://codemeta.github.io>. This package provides utilities to
#>     generate, parse, and modify 'codemeta.json' files automatically for R
#>     packages, as well as tools and examples for working with
#>     'codemeta.json' 'JSON-LD' more generally.
#> License: GPL-3
#> URL: https://gitlab.com/ninijay/methoden,
#>     https://ropensci.github.io/codemetar
#> BugReports: https://gitlab.com/ninijay/methoden/-/issues
#> Depends:
#>     R (>= 3.0.0)
#> Imports:
#>     crul,
#>     desc,
#>     devtools,
#>     gh,
#>     git2r,
#>     jsonld,
#>     jsonlite (>= 1.3),
#>     memoise,
#>     methods,
#>     purrr,
#>     readr,
#>     sessioninfo,
#>     stats,
#>     stringi,
#>     stringr,
#>     tibble,
#>     usethis,
#>     whisker
#> Suggests:
#>     covr,
#>     dplyr (>= 0.7.0),
#>     jsonvalidate,
#>     knitr,
#>     magrittr,
#>     printr,
#>     rmarkdown,
#>     testthat,
#>     xml2
#> VignetteBuilder:
#>     knitr
#> Encoding: UTF-8
#> LazyData: true
#> RoxygenNote: 6.0.1.9000
#> X-schema.org-isPartOf: https://ropensci.org
#> X-schema.org-keywords: metadata, codemeta, ropensci, citation, credit,
#>     linked-data

Back to summary.

title

This key is extracted from the “Description” field of the DESCRIPTION file.

title <- paste0(
  "NAME_OF_THE_PACKAGE",
  ": ",
  "TITLE_OF_THE_PACKAGE"
)

Example


# Installed package

cat(cff_create("testthat")$title)
#> testthat: Unit Testing for R

Back to summary.

type

Fixed value equal to “software”. The other possible value is “dataset”. See the description on the Guide to CFF schema v1.2.0.

Back to summary.

url

This key is extracted from the “BugReports” or “URL” fields on the DESCRIPTION file. It corresponds to the first url that is different to repository-code.

Example


# Many urls
manyurls <- system.file("examples/DESCRIPTION_many_urls", package = "cffr")

cat(cff_create(manyurls)$url)
#> https://test.github.io/package/

# Check

desc::desc(manyurls)
#> Type: Package
#> Package: manyurls
#> Title: A lot of urls
#> Version: 0.1.6
#> Authors@R (parsed):
#>     * Marc Basic <marcbasic@gmail.com> [aut, cre, cph]
#> Description: This package has many urls. Specifically, 1 Bug Reports and 6
#>     URLs. Expected is to have 1 repository-code, 1 url and 3 URLs, since
#>     there is 1 duplicate and 1 invalid url.
#> License: GPL-3
#> URL: https://github.com/test/package, https://test.github.io/package/,
#>     https://r-forge.r-project.org/projects/test/, http://google.ru,
#>     https://gitlab.com/r-packages/behaviorchange, this.is.not.an.url
#> BugReports: https://github.com/test/package/issues
#> Encoding: UTF-8

Back to summary.

version

This key is extracted from the “Version” field on the DESCRIPTION file.


# Should be (>= 3.0.0)
cat(cff_create("testthat")$version)
#> 3.1.4

Back to summary.

References

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.