utils (version 3.6.0)

citation: Citing R and R Packages in Publications

Description

How to cite R and R packages in publications.

Usage

citation(package = "base", lib.loc = NULL, auto = NULL)
readCitationFile(file, meta = NULL)

Arguments

package

a character string with the name of a single package. An error occurs if more than one package name is given.

lib.loc

a character vector with path names of R libraries, or the directory containing the source for package, or NULL. The default value of NULL corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries.

auto

a logical indicating whether the default citation auto-generated from the package DESCRIPTION metadata should be used or not, or NULL (default), indicating that a CITATION file is used if it exists, or an object of class "packageDescription" with package metadata (see below).

file

a file name.

meta

a list of package metadata as obtained by packageDescription, or NULL (the default).

Value

An object of class "citation", inheriting from class "bibentry"; see there, notably for the print and format methods.

Details

The R core development team and the very active community of package authors have invested a lot of time and effort in creating R as it is today. Please give credit where credit is due and cite R and R packages when you use them for data analysis.

Execute function citation() for information on how to cite the base R system in publications. If the name of a non-base package is given, the function either returns the information contained in the CITATION file of the package (using readCitationFile with meta equal to packageDescription(package, lib.loc)) or auto-generates citation information from the DESCRIPTION file.

In R >= 2.14.0, one can use a Authors@R field in DESCRIPTION to provide (R code giving) a person object with a refined, machine-readable description of the package “authors” (in particular specifying their precise roles). Only those with an author role will be included in the auto-generated citation.

If only one reference is given, the print method for the object returned by citation() shows both a text version and a BibTeX entry for it, if a package has more than one reference then only the text versions are shown. The BibTeX versions can be obtained using function toBibtex() (see the examples below).

The CITATION file of an R package should be placed in the inst subdirectory of the package source. The file is an R source file and may contain arbitrary R commands including conditionals and computations. Function readCitationFile() is used by citation() to extract the information in CITATION files. The file is source()ed by the R parser in a temporary environment and all resulting bibliographic objects (specifically, of class "bibentry") are collected.

Traditionally, the CITATION file contained zero or more calls to citHeader, then one or more calls to citEntry, and finally zero or more calls to citFooter, where in fact citHeader and citFooter are simply wrappers to paste, with their … argument passed on to paste as is. The "bibentry" class makes for improved representation and manipulation of bibliographic information (in fact, the old mechanism is implemented using the new one), and one can write CITATION files using the unified bibentry interface.

One can include an auto-generated package citation in the CITATION file via citation(auto = meta).

readCitationFile makes use of the Encoding element (if any) of meta to determine the encoding of the file.

See Also

bibentry

Examples

# NOT RUN {
## the basic R reference
citation()

## references for a package -- might not have these installed
if(nchar(system.file(package = "lattice"))) citation("lattice")
if(nchar(system.file(package = "foreign"))) citation("foreign")

## extract the bibtex entry from the return value
x <- citation()
toBibtex(x)

# }
# NOT RUN {
## A citation with more than one bibentry:
cm <- tryCatch(citation("mgcv"),
               error = function(e) {
                 warning("Recommended package 'mgcv' is not installed properly")
                 stop(e$message) })
cm # short entries (2-3 lines each)
print(cm, bibtex = TRUE) # each showing its bibtex code
# }
# NOT RUN {
<!-- %dont -->
# }