EVOLUTION-MANAGER
Edit File: person.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: Persons</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 person {utils}"><tr><td>person {utils}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Persons</h2> <h3>Description</h3> <p>A class and utility methods for holding information about persons like name and email address. </p> <h3>Usage</h3> <pre> person(given = NULL, family = NULL, middle = NULL, email = NULL, role = NULL, comment = NULL, first = NULL, last = NULL) ## Default S3 method: as.person(x) ## S3 method for class 'person' format(x, include = c("given", "family", "email", "role", "comment"), braces = list(given = "", family = "", email = c("<", ">"), role = c("[", "]"), comment = c("(", ")")), collapse = list(given = " ", family = " ", email = ", ", role = ", ", comment = ", "), ..., style = c("text", "R") ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>given</code></td> <td> <p>a character vector with the <em>given</em> names, or a list thereof.</p> </td></tr> <tr valign="top"><td><code>family</code></td> <td> <p>a character string with the <em>family</em> name, or a list thereof.</p> </td></tr> <tr valign="top"><td><code>middle</code></td> <td> <p>a character string with the collapsed middle name(s). Deprecated, see <b>Details</b>.</p> </td></tr> <tr valign="top"><td><code>email</code></td> <td> <p>a character string (or vector) giving an e-mail address (each), or a list thereof.</p> </td></tr> <tr valign="top"><td><code>role</code></td> <td> <p>a character vector specifying the role(s) of the person (see <b>Details</b>), or a list thereof.</p> </td></tr> <tr valign="top"><td><code>comment</code></td> <td> <p>a character string (or vector) providing comments, or a list thereof.</p> </td></tr> <tr valign="top"><td><code>first</code></td> <td> <p>a character string giving the first name. Deprecated, see <b>Details</b>.</p> </td></tr> <tr valign="top"><td><code>last</code></td> <td> <p>a character string giving the last name. Deprecated, see <b>Details</b>.</p> </td></tr> <tr valign="top"><td><code>x</code></td> <td> <p>a character string for the <code>as.person</code> default method; an object of class <code>"person"</code> otherwise.</p> </td></tr> <tr valign="top"><td><code>include</code></td> <td> <p>a character vector giving the fields to be included when formatting.</p> </td></tr> <tr valign="top"><td><code>braces</code></td> <td> <p>a list of characters (see <b>Details</b>).</p> </td></tr> <tr valign="top"><td><code>collapse</code></td> <td> <p>a list of characters (see <b>Details</b>).</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>currently not used.</p> </td></tr> <tr valign="top"><td><code>style</code></td> <td> <p>a character string specifying the print style, with <code>"R"</code> yielding formatting as R code.</p> </td></tr> </table> <h3>Details</h3> <p>Objects of class <code>"person"</code> can hold information about an arbitrary positive number of persons. These can be obtained by one call to <code>person()</code> with list arguments, or by first creating objects representing single persons and combining these via <code>c()</code>. </p> <p>The <code>format()</code> method collapses information about persons into character vectors (one string for each person): the fields in <code>include</code> are selected, each collapsed to a string using the respective element of <code>collapse</code> and subsequently “embraced” using the respective element of <code>braces</code>, and finally collapsed into one string separated by white space. If <code>braces</code> and/or <code>collapse</code> do not specify characters for all fields, the defaults shown in the usage are imputed. If <code>collapse</code> is <code>FALSE</code> or <code>NA</code> the corresponding field is not collapsed but only the first element is used. The <code>print()</code> method calls the <code>format()</code> method and prints the result, the <code>toBibtex()</code> method creates a suitable BibTeX representation. </p> <p>Person objects can be subscripted by fields (using <code>$</code>) or by position (using <code>[</code>). </p> <p><code>as.person()</code> is a generic function. Its default method tries to reverse the default person formatting, and can also handle formatted person entries collapsed by comma or <code>"and"</code> (with appropriate white space). </p> <p>Personal names are rather tricky, e.g., <a href="https://en.wikipedia.org/wiki/Personal_name">https://en.wikipedia.org/wiki/Personal_name</a>. </p> <p>The current implementation (starting from R 2.12.0) of the <code>"person"</code> class uses the notions of <em>given</em> (including middle names) and <em>family</em> names, as specified by <code>given</code> and <code>family</code> respectively. Earlier versions used a scheme based on first, middle and last names, as appropriate for most of Western culture where the given name precedes the family name, but not universal, as some other cultures place it after the family name, or use no family name. To smooth the transition to the new scheme, arguments <code>first</code>, <code>middle</code> and <code>last</code> are still supported, but their use is deprecated and they must not be given in combination with the corresponding new style arguments. For persons which are not natural persons (e.g., institutions, companies, etc.) it is appropriate to use <code>given</code> (but not <code>family</code>) for the name, e.g., <code>person("R Core Team", role = "aut")</code>. </p> <p>The new scheme also adds the possibility of specifying <em>roles</em> based on a subset of the MARC Code List for Relators (<a href="https://www.loc.gov/marc/relators/relaterm.html">https://www.loc.gov/marc/relators/relaterm.html</a>). When giving the roles of persons in the context of authoring <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> packages, the following usage is suggested. </p> <dl> <dt><code>"aut"</code></dt><dd><p>(Author) Use for full authors who have made substantial contributions to the package and should show up in the package citation.</p> </dd> <dt><code>"com"</code></dt><dd><p>(Compiler) Use for persons who collected code (potentially in other languages) but did not make further substantial contributions to the package.</p> </dd> <dt><code>"cph"</code></dt><dd><p>(Copyright holder) Use for all copyright holders.</p> </dd> <dt><code>"cre"</code></dt><dd><p>(Creator) Use for the package maintainer.</p> </dd> <dt><code>"ctb"</code></dt><dd><p>(Contributor) Use for authors who have made smaller contributions (such as code patches etc.) but should not show up in the package citation.</p> </dd> <dt><code>"ctr"</code></dt><dd><p>(Contractor) Use for authors who have been contracted to write (parts of) the package and hence do not own intellectual property.</p> </dd> <dt><code>"dtc"</code></dt><dd><p>(Data contributor) Use for persons who contributed data sets for the package.</p> </dd> <dt><code>"fnd"</code></dt><dd><p>(Funder) Use for persons or organizations that furnished financial support for the development of the package.</p> </dd> <dt><code>"rev"</code></dt><dd><p>(Reviewer) Use for persons or organizations responsible for reviewing (parts of) the package.</p> </dd> <dt><code>"ths"</code></dt><dd><p>(Thesis advisor) If the package is part of a thesis, use for the thesis advisor.</p> </dd> <dt><code>"trl"</code></dt><dd><p>(Translator) If the R code is a translation from another language (typically S), use for the translator to R.</p> </dd> </dl> <p>In the old scheme, person objects were used for single persons, and a separate <code>"personList"</code> class with corresponding creator <code>personList()</code> for collections of these. The new scheme employs a single class for information about an arbitrary positive number of persons, eliminating the need for the <code>personList</code> mechanism. </p> <p>The <code>comment</code> field can be used for “arbitrary” additional information about persons. Elements named <code>"ORCID"</code> will be taken to give ORCID identifiers (see <a href="https://orcid.org/">https://orcid.org/</a> for more information), and be displayed as the corresponding URIs by the <code>print()</code> and <code>format()</code> methods (see <b>Examples</b> below). </p> <h3>Value</h3> <p><code>person()</code> and <code>as.person()</code> return objects of class <code>"person"</code>. </p> <h3>See Also</h3> <p><code><a href="citation.html">citation</a></code> </p> <h3>Examples</h3> <pre> ## Create a person object directly ... p1 <- person("Karl", "Pearson", email = "pearson@stats.heaven") ## ... or convert a string. p2 <- as.person("Ronald Aylmer Fisher") ## Combining and subsetting. p <- c(p1, p2) p[1] p[-1] ## Extracting fields. p$family p$email p[1]$email ## Specifying package authors, example from "boot": ## AC is the first author [aut] who wrote the S original. ## BR is the second author [aut], who translated the code to R [trl], ## and maintains the package [cre]. b <- c(person("Angelo", "Canty", role = "aut", comment = "S original, <http://statwww.epfl.ch/davison/BMA/library.html>"), person(c("Brian", "D."), "Ripley", role = c("aut", "trl", "cre"), comment = "R port", email = "ripley@stats.ox.ac.uk") ) b ## Formatting. format(b) format(b, include = c("family", "given", "role"), braces = list(family = c("", ","), role = c("(Role(s): ", ")"))) ## Conversion to BibTeX author field. paste(format(b, include = c("given", "family")), collapse = " and ") toBibtex(b) ## ORCID identifiers. (p3 <- person("Achim", "Zeileis", comment = c(ORCID = "0000-0003-0918-3766"))) </pre> <hr /><div style="text-align: center;">[Package <em>utils</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>