cffr is a tool whose target audience are R package developers. The main goal of cffr is to create a CITATION.cff
file using the metadata information of the following files:
- Your
DESCRIPTION
file. - If available, the citation information located in
inst/CITATION
.
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 Customize your repository/About CITATION files for more info.
Creating a CITATION.cff
file for my R package
With cffr creating a CITATION.cff
file is quite straightforward. You just need to run cff_write()
:
Under the hood, cff_write()
performs the following tasks:
- It extracts the metadata using
cff_create()
. - Writes a
CITATION.cff
file usingyaml::write_yaml()
. - Validates the result using
cff_validate()
.
Congratulations! Now you have a full CITATION.cff
file for your R package.
Modifying your CITATION.cff
file
You can easily customize the cff
object (a custom class of cffr) using the parsers provided in the package, as well as making use of the keys
parameter.
We would create a cff
object using cff()
(for example purposes only) and we would add or modify contents of it.
Adding new fields
newobject <- cff_create(cff())
# For modifying your auto-generated object, run this line instead:
# newoobject <- cff_create()
newobject
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: My Research Software
#> authors:
#> - family-names: Doe
#> given-names: John
The valid keys of the Citation File Format schema version 1.2.0 can be displayed with cff_schema_keys()
:
cff_schema_keys()
#> [1] "cff-version" "message" "type"
#> [4] "license" "title" "version"
#> [7] "doi" "abstract" "authors"
#> [10] "preferred-citation" "repository" "repository-artifact"
#> [13] "repository-code" "url" "date-released"
#> [16] "contact" "keywords" "references"
#> [19] "commit" "identifiers" "license-url"
In this case, we are going to add url
, version
and repository
. We would also overwrite the title
key. We just need to create a list and pass it to the keys
argument of cff_create()
:
newkeys <- list(
"url" = "https://ropensci.org/",
"version" = "0.0.1",
"repository" = "https://github.com/ropensci/cffr",
# If the field is already present, it would be overridden
title = "Modifying a 'cff' object"
)
modobject <- cff_create(newobject, keys = newkeys)
modobject
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> version: 0.0.1
#> authors:
#> - family-names: Doe
#> given-names: John
#> repository: https://github.com/ropensci/cffr
#> url: https://ropensci.org/
# Validate against the schema
cff_validate(modobject)
#> ══ Validating cff ══════════════════════════════════════════════════════════════
#> ✔ Congratulations! This <cff> is valid
Parsing persons and citations
cffr provides two functions that parse person
objects and bibentry
objects (See ?person
and ?bibentry
). These objects are included in the utils package and are a core part of the metadata of any R package.
Following the previous example, we are going to add a new author first. For doing that, we need first to extract the current author of the package and append the parsed person:
# Valid person keys
cff_schema_definitions_person()
#> [1] "address" "affiliation" "alias" "city"
#> [5] "country" "email" "family-names" "fax"
#> [9] "given-names" "name-particle" "name-suffix" "orcid"
#> [13] "post-code" "region" "tel" "website"
# Create the person
chiquito <- person("Gregorio",
"Sánchez Fernández",
email = "fake@email2.com",
comment = c(
alias = "Chiquito de la Calzada",
city = "Malaga",
country = "ES",
ORCID = "0000-0000-0000-0001"
)
)
chiquito
#> [1] "Gregorio Sánchez Fernández <fake@email2.com> (Chiquito de la Calzada, Malaga, ES, <https://orcid.org/0000-0000-0000-0001>)"
# Parse it
chiquito_parsed <- cff_parse_person(chiquito)
chiquito_parsed
#> family-names: Sánchez Fernández
#> given-names: Gregorio
#> email: fake@email2.com
#> alias: Chiquito de la Calzada
#> city: Malaga
#> country: ES
#> orcid: https://orcid.org/0000-0000-0000-0001
# Append to previous authors
# Needs to be append as a list
newauthors <- c(modobject$authors, list(chiquito_parsed))
newauthors
#> - family-names: Doe
#> given-names: John
#> - family-names: Sánchez Fernández
#> given-names: Gregorio
#> email: fake@email2.com
#> alias: Chiquito de la Calzada
#> city: Malaga
#> country: ES
#> orcid: https://orcid.org/0000-0000-0000-0001
newauthorobject <- cff_create(modobject, keys = list(authors = newauthors))
newauthorobject
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> version: 0.0.1
#> authors:
#> - family-names: Doe
#> given-names: John
#> - family-names: Sánchez Fernández
#> given-names: Gregorio
#> email: fake@email2.com
#> alias: Chiquito de la Calzada
#> city: Malaga
#> country: ES
#> orcid: https://orcid.org/0000-0000-0000-0001
#> repository: https://github.com/ropensci/cffr
#> url: https://ropensci.org/
cff_validate(newauthorobject)
#> ══ Validating cff ══════════════════════════════════════════════════════════════
#> ✔ Congratulations! This <cff> is valid
Now, we may want to add references
to our data. cffr supports two types of references:
- References created with
bibentry()
- References extracted from packages using
citation()
On the following example, we would add two references, one of each type:
# Valid reference keys
cff_schema_definitions_refs()
#> [1] "abbreviation" "abstract" "authors"
#> [4] "collection-doi" "collection-title" "collection-type"
#> [7] "commit" "conference" "contact"
#> [10] "copyright" "data-type" "database-provider"
#> [13] "database" "date-accessed" "date-downloaded"
#> [16] "date-published" "date-released" "department"
#> [19] "doi" "edition" "editors"
#> [22] "editors-series" "end" "entry"
#> [25] "filename" "format" "identifiers"
#> [28] "institution" "isbn" "issn"
#> [31] "issue" "issue-date" "issue-title"
#> [34] "journal" "keywords" "languages"
#> [37] "license" "license-url" "loc-end"
#> [40] "loc-start" "location" "medium"
#> [43] "month" "nihmsid" "notes"
#> [46] "number" "number-volumes" "pages"
#> [49] "patent-states" "pmcid" "publisher"
#> [52] "recipients" "repository" "repository-artifact"
#> [55] "repository-code" "scope" "section"
#> [58] "senders" "start" "status"
#> [61] "term" "thesis-type" "title"
#> [64] "translators" "type" "url"
#> [67] "version" "volume" "volume-title"
#> [70] "year" "year-original"
# Auto parsed from another R package
base_r <- cff_parse_citation(citation("base"))
base_r
#> type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#> location:
#> name: Vienna, Austria
#> year: '2023'
#> url: https://www.R-project.org/
#> institution:
#> name: R Foundation for Statistical Computing
# Create with bibentry
bib <- bibentry("Book",
title = "This is a book",
author = "Lisa Lee",
year = 1980,
publisher = "McGraw Hill",
volume = 2
)
bib
#> Lee L (1980). _This is a book_, volume 2. McGraw Hill.
# Now parse it
bookparsed <- cff_parse_citation(bib)
bookparsed
#> type: book
#> title: This is a book
#> authors:
#> - family-names: Lee
#> given-names: Lisa
#> year: '1980'
#> publisher:
#> name: McGraw Hill
#> volume: '2'
Now the process is similar to the example with person
: we append both references (as lists) and add them to our object:
refkeys <- list(references = c(list(base_r), list(bookparsed)))
refkeys
#> $references
#> $references[[1]]
#> type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#> location:
#> name: Vienna, Austria
#> year: '2023'
#> url: https://www.R-project.org/
#> institution:
#> name: R Foundation for Statistical Computing
#>
#> $references[[2]]
#> type: book
#> title: This is a book
#> authors:
#> - family-names: Lee
#> given-names: Lisa
#> year: '1980'
#> publisher:
#> name: McGraw Hill
#> volume: '2'
finalobject <- cff_create(newauthorobject, keys = refkeys)
finalobject
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> version: 0.0.1
#> authors:
#> - family-names: Doe
#> given-names: John
#> - family-names: Sánchez Fernández
#> given-names: Gregorio
#> email: fake@email2.com
#> alias: Chiquito de la Calzada
#> city: Malaga
#> country: ES
#> orcid: https://orcid.org/0000-0000-0000-0001
#> repository: https://github.com/ropensci/cffr
#> url: https://ropensci.org/
#> references:
#> - type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#> location:
#> name: Vienna, Austria
#> year: '2023'
#> url: https://www.R-project.org/
#> institution:
#> name: R Foundation for Statistical Computing
#> - type: book
#> title: This is a book
#> authors:
#> - family-names: Lee
#> given-names: Lisa
#> year: '1980'
#> publisher:
#> name: McGraw Hill
#> volume: '2'
cff_validate(finalobject)
#> ══ Validating cff ══════════════════════════════════════════════════════════════
#> ✔ Congratulations! This <cff> is valid
Create your modified CITATION.cff
file
The results can be written with cff_write()
:
# For example
tmp <- tempfile(fileext = ".cff")
see_res <- cff_write(finalobject, outfile = tmp)
#> ✔ /tmp/Rtmpcia9Ym/file7fb1912179a.cff generated
#> ══ Validating cff ══════════════════════════════════════════════════════════════
#> ✔ Congratulations! /tmp/Rtmpcia9Ym/file7fb1912179a.cff is valid
see_res
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> version: 0.0.1
#> authors:
#> - family-names: Doe
#> given-names: John
#> - family-names: Sánchez Fernández
#> given-names: Gregorio
#> email: fake@email2.com
#> alias: Chiquito de la Calzada
#> city: Malaga
#> country: ES
#> orcid: https://orcid.org/0000-0000-0000-0001
#> repository: https://github.com/ropensci/cffr
#> url: https://ropensci.org/
#> references:
#> - type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#> location:
#> name: Vienna, Austria
#> year: '2023'
#> url: https://www.R-project.org/
#> institution:
#> name: R Foundation for Statistical Computing
#> - type: book
#> title: This is a book
#> authors:
#> - family-names: Lee
#> given-names: Lisa
#> year: '1980'
#> publisher:
#> name: McGraw Hill
#> volume: '2'
And finally we can read our created CITATION.cff
file using cff()
:
reading <- cff(tmp)
reading
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> version: 0.0.1
#> authors:
#> - family-names: Doe
#> given-names: John
#> - family-names: Sánchez Fernández
#> given-names: Gregorio
#> email: fake@email2.com
#> alias: Chiquito de la Calzada
#> city: Malaga
#> country: ES
#> orcid: https://orcid.org/0000-0000-0000-0001
#> repository: https://github.com/ropensci/cffr
#> url: https://ropensci.org/
#> references:
#> - type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#> location:
#> name: Vienna, Austria
#> year: '2023'
#> url: https://www.R-project.org/
#> institution:
#> name: R Foundation for Statistical Computing
#> - type: book
#> title: This is a book
#> authors:
#> - family-names: Lee
#> given-names: Lisa
#> year: '1980'
#> publisher:
#> name: McGraw Hill
#> volume: '2'
Note that cff_write()
also has the keys
param, so the workflow can be simplified as:
allkeys <- list(
"url" = "https://ropensci.org/",
"version" = "0.0.1",
"repository" = "https://github.com/user/repo",
# If the field is already present, it would be overridden
title = "Modifying a 'cff' object",
authors = newauthors,
references = c(list(base_r), list(bookparsed))
)
tmp2 <- tempfile(fileext = ".cff")
res <- cff_write(cff(), outfile = tmp2, keys = allkeys)
#> ✔ /tmp/Rtmpcia9Ym/file7fb7035a092.cff generated
#> ══ Validating cff ══════════════════════════════════════════════════════════════
#> ✔ Congratulations! /tmp/Rtmpcia9Ym/file7fb7035a092.cff is valid
res
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> version: 0.0.1
#> authors:
#> - family-names: Doe
#> given-names: John
#> - family-names: Sánchez Fernández
#> given-names: Gregorio
#> email: fake@email2.com
#> alias: Chiquito de la Calzada
#> city: Malaga
#> country: ES
#> orcid: https://orcid.org/0000-0000-0000-0001
#> repository: https://github.com/user/repo
#> url: https://ropensci.org/
#> references:
#> - type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#> location:
#> name: Vienna, Austria
#> year: '2023'
#> url: https://www.R-project.org/
#> institution:
#> name: R Foundation for Statistical Computing
#> - type: book
#> title: This is a book
#> authors:
#> - family-names: Lee
#> given-names: Lisa
#> year: '1980'
#> publisher:
#> name: McGraw Hill
#> volume: '2'