cff_class {cffr}R Documentation

The cff class

Description

The cff class

cffr implements a S3 object with class cff, that it is used to represent the information of a CITATION.cff file in R.

Under the hood, a cff object is simply a named list to which we added additional methods, most notably print and as_cff(). 

a_named_list <- list(
  first = "I", second = "am", third = "a", fourth = "list",
  fifth = "with", sixth = "names", "none" = NULL
)

# As cff
a_cff_object <- as_cff(a_named_list)

class(a_cff_object)
#> [1] "cff"

a_cff_object
#> first: I
#> second: am
#> third: a
#> fourth: list
#> fifth: with
#> sixth: names

is.list(a_cff_object)
#> [1] TRUE

as_cff() not only converts a list to cff but also removes items (known as keys in CFF terminology) that are NULL or NA.

Sub-classes

cffr implements two special sub-classes of cff, with the aim of representing two special types of objects defined in the CFF Schema:

These two sub-classes does not provide full valid cff objects, but adapts information to the schema required by CFF: 

# Using the utils::person() function

## Array
two_persons <- as_cff_person(
  c(
    person("A", "person", comment = c(ORCID = "0000-0000-0000-0000")),
    person("An entity", email = "fake@gmail.com")
  )
)

two_persons
#> - family-names: person
#>   given-names: A
#>   orcid: https://orcid.org/0000-0000-0000-0000
#> - name: An entity
#>   email: fake@gmail.com

class(two_persons)
#> [1] "cff_pers_lst" "cff"

# Single element

two_persons[[1]]
#> family-names: person
#> given-names: A
#> orcid: https://orcid.org/0000-0000-0000-0000

class(two_persons[[1]])
#> [1] "cff_pers" "cff"

# Array of references

cit <- c(citation(), citation("yaml"))

ref_list <- as_cff(cit)

ref_list
#> - type: manual
#>   title: 'R: A Language and Environment for Statistical Computing'
#>   authors:
#>   - name: R Core Team
#>   institution:
#>     name: R Foundation for Statistical Computing
#>     address: Vienna, Austria
#>   year: '2024'
#>   url: https://www.R-project.org/
#> - type: manual
#>   title: 'yaml: Methods to Convert R Data to YAML and Back'
#>   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'
#>   notes: R package version 2.3.9
#>   url: https://github.com/vubiostat/r-yaml/

class(ref_list)
#> [1] "cff_ref_lst" "cff"

# Single element

ref_list[[1]]
#> type: manual
#> title: 'R: A Language and Environment for Statistical Computing'
#> authors:
#> - name: R Core Team
#> institution:
#>   name: R Foundation for Statistical Computing
#>   address: Vienna, Austria
#> year: '2024'
#> url: https://www.R-project.org/

class(ref_list[[1]])
#> [1] "cff_ref" "cff"

Valid cff objects

Creating a cff object does not ensure its validity according to the CFF Schema: 

class(a_cff_object)
#> [1] "cff"

cff_validate(a_cff_object)
#> == Validating cff ==============================================================
#> x Oops! This <cff> has the following errors:
#> * cff.authors: is required
#> * cff["cff-version"]: is required
#> * cff.message: is required
#> * cff.title: is required

cff_validate() gives minimal messages of what's wrong with our cff and (invisibly) returns the result of the validation (TRUE/FALSE).

We can use cff_modify() to add more keys: 

cff_valid <- cff_modify(a_cff_object,
  authors = as_cff_person("{James and James}"),
  cff_version = "1.2.0",
  message = "Hi there",
  title = "My title"
)


# Remove invalid keys
cff_valid <- as_cff(cff_valid[names(cff_valid) %in% cff_schema_keys()])

cff_valid
#> authors:
#> - name: James and James
#> cff-version: 1.2.0
#> message: Hi there
#> title: My title

cff_validate(cff_valid)
#> == Validating cff ==============================================================
#> v Congratulations! This <cff> is valid

Base methods provided by cffr

cffr version 1.0.0 provides additional S3 Methods for common coercing functions of the base and utils package.

as.data.frame()
minimal_cff <- cff()

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

as_df <- as.data.frame(minimal_cff)

class(as_df)
#> [1] "data.frame"

t(as_df)
#>                         [,1]                                                            
#> cff_version             "1.2.0"                                                         
#> message                 "If you use this software, please cite it using these metadata."
#> title                   "My Research Software"                                          
#> authors.00.family_names "Doe"                                                           
#> authors.00.given_names  "John"
c()
new_keys <- c("date-released" = "2020-01-31", abstract = "Minimal example")

c(minimal_cff, new_keys)
#> 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
#> date-released: '2020-01-31'
#> abstract: Minimal example
as.list()
as.list(minimal_cff)
#> $`cff-version`
#> [1] "1.2.0"
#> 
#> $message
#> [1] "If you use this software, please cite it using these metadata."
#> 
#> $title
#> [1] "My Research Software"
#> 
#> $authors
#> $authors[[1]]
#> $authors[[1]]$`family-names`
#> [1] "Doe"
#> 
#> $authors[[1]]$`given-names`
#> [1] "John"
as.person()

Only for cff_pers_lst and cff_pers objects: 

as.person(two_persons)
#> [1] "A person (<https://orcid.org/0000-0000-0000-0000>)"
#> [2] "An entity <fake@gmail.com>"
toBibtex()
# For cff
toBibtex(minimal_cff)
#> @Misc{doe,
#>   title = {My Research Software},
#>   author = {John Doe},
#> }

# cff_ref, cff_ref_lst
toBibtex(cit)
#> @Manual{,
#>   title = {R: A Language and Environment for Statistical Computing},
#>   author = {{R Core Team}},
#>   organization = {R Foundation for Statistical Computing},
#>   address = {Vienna, Austria},
#>   year = {2024},
#>   url = {https://www.R-project.org/},
#> }
#> 
#> @Manual{,
#>   title = {yaml: Methods to Convert R Data to YAML and Back},
#>   author = {Shawn P Garbett and Jeremy Stephens and Kirill Simonov and Yihui Xie and Zhuoer Dong and Hadley Wickham and Jeffrey Horner and {reikoch} and Will Beasley and Brendan O'Connor and Gregory R. Warnes and Michael Quinn and Zhian N. Kamvar and Charlie Gao},
#>   year = {2024},
#>   note = {R package version 2.3.9},
#>   url = {https://github.com/vubiostat/r-yaml/},
#> }

# cff_pers, cff_pers_lst
toBibtex(two_persons)
#> [1] "person, A and {An entity}"

References

See Also

Coercing between R classes with S3 Methods: as_bibentry(), as_cff(), as_cff_person()

[Package cffr version 1.1.0 Index]