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)

### 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).

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

### Value

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

### See Also

`bibentry`

### Examples

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

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

[Package utils version 3.4.2 Index]