EVOLUTION-MANAGER
Edit File: citation.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Citing R and R Packages in Publications</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for citation {utils}"><tr><td>citation {utils}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Citing R and R Packages in Publications</h2> <h3>Description</h3> <p>How to cite <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> and <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> packages in publications. </p> <h3>Usage</h3> <pre> citation(package = "base", lib.loc = NULL, auto = NULL) readCitationFile(file, meta = NULL) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>package</code></td> <td> <p>a character string with the name of a single package. An error occurs if more than one package name is given.</p> </td></tr> <tr valign="top"><td><code>lib.loc</code></td> <td> <p>a character vector with path names of <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> libraries, or the directory containing the source for <code>package</code>, or <code>NULL</code>. The default value of <code>NULL</code> corresponds to all libraries currently known. If the default is used, the loaded packages are searched before the libraries.</p> </td></tr> <tr valign="top"><td><code>auto</code></td> <td> <p>a logical indicating whether the default citation auto-generated from the package ‘<span class="file">DESCRIPTION</span>’ metadata should be used or not, or <code>NULL</code> (default), indicating that a ‘<span class="file">CITATION</span>’ file is used if it exists, or an object of class <code>"<a href="packageDescription.html">packageDescription</a>"</code> with package metadata (see below).</p> </td></tr> <tr valign="top"><td><code>file</code></td> <td> <p>a file name.</p> </td></tr> <tr valign="top"><td><code>meta</code></td> <td> <p>a list of package metadata as obtained by <code><a href="packageDescription.html">packageDescription</a></code>, or <code>NULL</code> (the default).</p> </td></tr> </table> <h3>Details</h3> <p>The <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> core development team and the very active community of package authors have invested a lot of time and effort in creating <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> as it is today. Please give credit where credit is due and cite <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> and <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> packages when you use them for data analysis. </p> <p>Execute function <code>citation()</code> 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 ‘<span class="file">CITATION</span>’ file of the package (using <code>readCitationFile</code> with <code>meta</code> equal to <code>packageDescription(package, lib.loc)</code>) or auto-generates citation information from the ‘<span class="file">DESCRIPTION</span>’ file. </p> <p>In <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> >= 2.14.0, one can use a <span class="samp">Authors@R</span> field in ‘<span class="file">DESCRIPTION</span>’ to provide (<span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> code giving) a <code><a href="person.html">person</a></code> 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. </p> <p>If only one reference is given, the print method for the object returned by <code>citation()</code> 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 <code>toBibtex()</code> (see the examples below). </p> <p>The ‘<span class="file">CITATION</span>’ file of an R package should be placed in the ‘<span class="file">inst</span>’ subdirectory of the package source. The file is an R source file and may contain arbitrary R commands including conditionals and computations. Function <code>readCitationFile()</code> is used by <code>citation()</code> to extract the information in ‘<span class="file">CITATION</span>’ files. The file is <code>source()</code>ed by the R parser in a temporary environment and all resulting bibliographic objects (specifically, of class <code>"<a href="bibentry.html">bibentry</a>"</code>) are collected. </p> <p>Traditionally, the ‘<span class="file">CITATION</span>’ file contained zero or more calls to <code>citHeader</code>, then one or more calls to <code><a href="citEntry.html">citEntry</a></code>, and finally zero or more calls to <code>citFooter</code>, where in fact <code>citHeader</code> and <code>citFooter</code> are simply wrappers to <code><a href="../../base/html/paste.html">paste</a></code>, with their <code>...</code> argument passed on to <code><a href="../../base/html/paste.html">paste</a></code> as is. The <code>"<a href="bibentry.html">bibentry</a>"</code> 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 ‘<span class="file">CITATION</span>’ files using the unified <code><a href="bibentry.html">bibentry</a></code> interface. </p> <p>One can include an auto-generated package citation in the ‘<span class="file">CITATION</span>’ file via <code>citation(auto = meta)</code>. </p> <p><code>readCitationFile</code> makes use of the <code>Encoding</code> element (if any) of <code>meta</code> to determine the encoding of the file. </p> <h3>Value</h3> <p>An object of class <code>"citation"</code>, inheriting from class <code>"<a href="bibentry.html">bibentry</a>"</code>; see there, notably for the <code><a href="../../base/html/print.html">print</a></code> and <code><a href="../../base/html/format.html">format</a></code> methods. </p> <h3>See Also</h3> <p><code><a href="bibentry.html">bibentry</a></code> </p> <h3>Examples</h3> <pre> ## 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 </pre> <hr /><div style="text-align: center;">[Package <em>utils</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>