Manipulating citations with cffr

cffr is designed for R package developers. Its main goal is to create a CITATION.cff file using metadata from the following files:

  • Your DESCRIPTION file.
  • Citation information from inst/CITATION, when available.

What is a CITATION.cff file?

A CITATION.cff file follows the Citation File Format (CFF) (Druskat et al. 2021) (v1.2.0). It contains human- and machine-readable citation metadata for software and datasets. Developers can include it in a repository to explain how to cite their software.

This format is increasingly used in the software citation ecosystem. GitHub, Zenodo and Zotero support this citation format (Druskat 2021).

GitHub support is of special interest:

GitHub citation support announcement
Nat Friedman (@natfriedman) July 27, 2021

See GitHub’s guide to CITATION files for more information.

Creating a CITATION.cff file for your R package

Creating a CITATION.cff file with cffr is straightforward. You only need to run cff_write():

library(cffr)

cff_write()

# Done.

Under the hood, cff_write() performs these tasks:

  • Extracts the metadata using cff_create().
  • Optionally modifies it with cff_modify().
  • Writes a CITATION.cff file.
  • Validates the result using cff_validate().

You now have a complete CITATION.cff file for your R package.

Modifying your CITATION.cff file

You can customize a cff object using cff_modify(), the package’s coercion methods and the keys argument.

For demonstration, we create a cff object using cff() and then add or modify its contents.

Adding new keys

newobject <- cff()

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 from 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"                 "identifiers"         "abstract"           
#> [10] "authors"             "preferred-citation"  "repository"         
#> [13] "repository-artifact" "repository-code"     "commit"             
#> [16] "url"                 "date-released"       "contact"            
#> [19] "keywords"            "references"          "license-url"

In this case, we add url, version and repository. We also overwrite the title key by passing these arguments to cff_modify():

modobject <- cff_modify(
  newobject,
  url = "https://ropensci.org/",
  version = "0.0.1",
  repository = "https://github.com/ropensci/cffr",
  # If the key is already present, it is overridden.
  title = "Modifying a 'cff' object"
)

modobject
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> authors:
#> - family-names: Doe
#>   given-names: John
#> url: https://ropensci.org/
#> version: 0.0.1
#> repository: https://github.com/ropensci/cffr

# Validate against the schema.

cff_validate(modobject)
#> ══ Validating CFF ══════════════════════════════════════════════════════════════
#> ✔ This <cff> object is valid.

Persons and references

as_cff_person() converts person objects and as_cff() converts bibentry objects to metadata that follows the Citation File Format schema.

Following the previous example, we first add a new author. To do that, we need to extract the current package authors and append the converted 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 = "[email protected]",
  comment = c(
    alias = "Chiquito de la Calzada",
    city = "Malaga",
    country = "ES",
    ORCID = "0000-0000-0000-0001"
  )
)

chiquito
#> [1] "Gregorio Sánchez Fernández <[email protected]> (alias: Chiquito de la Calzada, city: Malaga, country: ES, ORCID: <https://orcid.org/0000-0000-0000-0001>)"

# Convert to `cff`.
chiquito_cff <- as_cff_person(chiquito)
chiquito_cff
#> - family-names: Sánchez Fernández
#>   given-names: Gregorio
#>   email: [email protected]
#>   alias: Chiquito de la Calzada
#>   city: Malaga
#>   country: ES
#>   orcid: https://orcid.org/0000-0000-0000-0001

# Append to previous authors.

newauthors <- c(modobject$authors, chiquito_cff)
newauthors
#> - family-names: Doe
#>   given-names: John
#> - family-names: Sánchez Fernández
#>   given-names: Gregorio
#>   email: [email protected]
#>   alias: Chiquito de la Calzada
#>   city: Malaga
#>   country: ES
#>   orcid: https://orcid.org/0000-0000-0000-0001

newauthorobject <- cff_modify(modobject, 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
#> authors:
#> - family-names: Doe
#>   given-names: John
#> - family-names: Sánchez Fernández
#>   given-names: Gregorio
#>   email: [email protected]
#>   alias: Chiquito de la Calzada
#>   city: Malaga
#>   country: ES
#>   orcid: https://orcid.org/0000-0000-0000-0001
#> url: https://ropensci.org/
#> version: 0.0.1
#> repository: https://github.com/ropensci/cffr

cff_validate(newauthorobject)
#> ══ Validating CFF ══════════════════════════════════════════════════════════════
#> ✔ This <cff> object is valid.

Next, we add references to the cff object. This example adds two references, one created with bibentry() and another with citation():

# 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"

# Automatic coercion from another **R** package.
base_r <- citation("base")

bib <- bibentry(
  "Book",
  title = "This is a book",
  author = "Lisa Lee",
  year = 1980,
  publisher = "McGraw Hill",
  volume = 2
)

refs <- c(base_r, bib)

refs
#> R Core Team (2026). _R: A Language and Environment for Statistical
#> Computing_. R Foundation for Statistical Computing, Vienna, Austria.
#> doi:10.32614/R.manuals <https://doi.org/10.32614/R.manuals>.
#> <https://www.R-project.org/>.
#> 
#> Lee L (1980). _This is a book_, volume 2. McGraw Hill.

# Convert to `cff`.

refs_cff <- as_cff(refs)

refs_cff
#> - type: manual
#>   title: 'R: A Language and Environment for Statistical Computing'
#>   authors:
#>   - name: R Core Team
#>     website: https://ror.org/02zz1nj61
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     website: https://ror.org/05qewa988
#>     address: Vienna, Austria
#>   year: '2026'
#>   doi: 10.32614/R.manuals
#>   url: https://www.R-project.org/
#> - type: book
#>   title: This is a book
#>   authors:
#>   - family-names: Lee
#>     given-names: Lisa
#>   year: '1980'
#>   publisher:
#>     name: McGraw Hill
#>   volume: '2'

As with the person example, we modify the cff object:

finalobject <- cff_modify(newauthorobject, references = refs_cff)

finalobject
#> cff-version: 1.2.0
#> message: If you use this software, please cite it using these metadata.
#> title: Modifying a 'cff' object
#> authors:
#> - family-names: Doe
#>   given-names: John
#> - family-names: Sánchez Fernández
#>   given-names: Gregorio
#>   email: [email protected]
#>   alias: Chiquito de la Calzada
#>   city: Malaga
#>   country: ES
#>   orcid: https://orcid.org/0000-0000-0000-0001
#> url: https://ropensci.org/
#> version: 0.0.1
#> repository: https://github.com/ropensci/cffr
#> references:
#> - type: manual
#>   title: 'R: A Language and Environment for Statistical Computing'
#>   authors:
#>   - name: R Core Team
#>     website: https://ror.org/02zz1nj61
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     website: https://ror.org/05qewa988
#>     address: Vienna, Austria
#>   year: '2026'
#>   doi: 10.32614/R.manuals
#>   url: https://www.R-project.org/
#> - 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 ══════════════════════════════════════════════════════════════
#> ✔ This <cff> object is valid.

Write the modified CITATION.cff file

The result can be written with cff_write():

# Create a temporary output file.
tmp <- tempfile(fileext = ".cff")

see_res <- cff_write(finalobject, outfile = tmp)
#> ✔ '/tmp/Rtmp1ouD9D/fileca934283fad.cff' generated.
#> ══ Validating CFF ══════════════════════════════════════════════════════════════
#> ✔ '/tmp/Rtmp1ouD9D/fileca934283fad.cff' is valid.

cat(readLines(tmp), sep = "\n")
#> # ------------------------------------------------
#> # CITATION.cff file created with {cffr} R package
#> # See also: https://docs.ropensci.org/cffr/
#> # ------------------------------------------------
#>  
#> 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: [email protected]
#>   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
#>     website: https://ror.org/02zz1nj61
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     website: https://ror.org/05qewa988
#>     address: Vienna, Austria
#>   year: '2026'
#>   doi: 10.32614/R.manuals
#>   url: https://www.R-project.org/
#> - type: book
#>   title: This is a book
#>   authors:
#>   - family-names: Lee
#>     given-names: Lisa
#>   year: '1980'
#>   publisher:
#>     name: McGraw Hill
#>   volume: '2'

Finally, we can read the created CITATION.cff file using cff_read():

reading <- cff_read(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: [email protected]
#>   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
#>     website: https://ror.org/02zz1nj61
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     website: https://ror.org/05qewa988
#>     address: Vienna, Austria
#>   year: '2026'
#>   doi: 10.32614/R.manuals
#>   url: https://www.R-project.org/
#> - 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 argument, so the workflow can be simplified to:

allkeys <- list(
  "url" = "https://ropensci.org/",
  "version" = "0.0.1",
  "repository" = "https://github.com/ropensci/cffr",
  # If the key is already present, it is overridden.
  title = "Modifying a 'cff' object",
  authors = newauthors,
  references = refs_cff
)

tmp2 <- tempfile(fileext = ".cff")

res <- cff_write(cff(), outfile = tmp2, keys = allkeys)
#> ✔ '/tmp/Rtmp1ouD9D/fileca9345ee6fe.cff' generated.
#> ══ Validating CFF ══════════════════════════════════════════════════════════════
#> ✔ '/tmp/Rtmp1ouD9D/fileca9345ee6fe.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: [email protected]
#>   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
#>     website: https://ror.org/02zz1nj61
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     website: https://ror.org/05qewa988
#>     address: Vienna, Austria
#>   year: '2026'
#>   doi: 10.32614/R.manuals
#>   url: https://www.R-project.org/
#> - type: book
#>   title: This is a book
#>   authors:
#>   - family-names: Lee
#>     given-names: Lisa
#>   year: '1980'
#>   publisher:
#>     name: McGraw Hill
#>   volume: '2'

References

Druskat, Stephan. 2021. Making Software Citation Easi(er) - The Citation File Format and Its Integrations. Version 1. Zenodo. https://doi.org/10.5281/zenodo.5529914.
Druskat, Stephan, Jurriaan H. Spaaks, Neil Chue Hong, et al. 2021. Citation File Format. Version 1.2.0. Zenodo. https://doi.org/10.5281/zenodo.5171937.