| citation {utils} | R Documentation |
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)
citHeader(...)
citFooter(...)
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 |
auto |
a logical indicating whether the default citation
auto-generated from the package ‘DESCRIPTION’ metadata should
be used or not, or |
file |
a file name. |
meta |
a list of package metadata as obtained by
|
... |
character strings (which will be |
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.
Packages can use an ‘Authors@R’ field in their
‘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 the object returned by citation() contains only one reference,
the associated print method 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. This threshold is controlled by
options("citation.bibtex.max").
The BibTeX versions can also 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, inheriting from "bibentry") are
collected.
These are typically produced by one or more bibentry()
calls, optionally preceded by a citHeader() and followed
by a citFooter() call.
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.
Value
An object of class "citation", inheriting from class
"bibentry"; see there, notably for the
print and format methods.
citHeader and citFooter return an empty
"bibentry" storing “outer” header/footer text
for the package citation.
See Also
Examples
## the basic R reference
citation()
## extract the BibTeX entry from the return value
x <- citation()
toBibtex(x)
## references for a package
citation("lattice")
citation("lattice", auto = TRUE) # request the Manual-type reference
citation("foreign")
## a CITATION file with more than one bibentry:
file.show(system.file("CITATION", package="mgcv"))
cm <- citation("mgcv")
cm # header, text references, plus "reminder" about getting BibTeX
print(cm, bibtex = TRUE) # each showing its bibtex code
## a CITATION file including citation(auto = meta)
file.show(system.file("CITATION", package="nlme"))
citation("nlme")