1% File src/library/utils/man/person.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2020 R Core Team 4% Distributed under GPL 2 or later 5 6\name{person} 7\title{Persons} 8\alias{person} 9\alias{as.person} 10\alias{as.person.default} 11\alias{[.person} 12\alias{$.person} 13\alias{as.character.person} 14\alias{c.person} 15\alias{format.person} 16\alias{print.person} 17\alias{toBibtex.person} 18\alias{personList} 19\alias{as.personList} 20\alias{as.personList.person} 21\alias{as.personList.default} 22\description{ 23 A class and utility methods for holding information about persons 24 like name and email address. 25} 26\usage{ 27person(given = NULL, family = NULL, middle = NULL, 28 email = NULL, role = NULL, comment = NULL, 29 first = NULL, last = NULL) 30\method{as.person}{default}(x) 31\method{format}{person}(x, 32 include = c("given", "family", "email", "role", "comment"), 33 braces = list(given = "", family = "", email = c("<", ">"), 34 role = c("[", "]"), comment = c("(", ")")), 35 collapse = list(given = " ", family = " ", email = ", ", 36 role = ", ", comment = ", "), 37 ..., 38 style = c("text", "R") 39 ) 40} 41\arguments{ 42 \item{given}{a character vector with the \emph{given} names, 43 or a list thereof.} 44 \item{family}{a character string with the \emph{family} name, 45 or a list thereof.} 46 \item{middle}{a character string with the collapsed middle name(s). 47 Deprecated, see \bold{Details}.} 48 \item{email}{a character string (or vector) giving an e-mail address 49 (each), 50 or a list thereof.} 51 \item{role}{a character vector specifying the role(s) of the person 52 (see \bold{Details}), 53 or a list thereof.} 54 \item{comment}{a character string (or vector) providing comments, 55 or a list thereof.} 56 \item{first}{a character string giving the first name. 57 Deprecated, see \bold{Details}.} 58 \item{last}{a character string giving the last name. 59 Deprecated, see \bold{Details}.} 60 \item{x}{a character string for the \code{as.person} default method; 61 an object of class \code{"person"} otherwise.} 62 \item{include}{a character vector giving the fields to be included 63 when formatting.} 64 \item{braces}{a list of characters (see \bold{Details}).} 65 \item{collapse}{a list of characters (see \bold{Details}).} 66 \item{\dots}{currently not used.} 67 \item{style}{a character string specifying the print style, with 68 \code{"R"} yielding formatting as R code.} 69} 70\value{ 71 \code{person()} and \code{as.person()} return objects of class 72 \code{"person"}. 73} 74\details{ 75 Objects of class \code{"person"} can hold information about an 76 arbitrary positive number of persons. These can be obtained by one 77 call to \code{person()} with list arguments, or by first creating 78 objects representing single persons and combining these via 79 \code{c()}. 80 81 The \code{format()} method collapses information about persons into 82 character vectors (one string for each person): the fields in 83 \code{include} are selected, each collapsed to a string using the 84 respective element of \code{collapse} and subsequently 85 \dQuote{embraced} using the respective element of \code{braces}, and 86 finally collapsed into one string separated by white space. If 87 \code{braces} and/or \code{collapse} do not specify characters for all 88 fields, the defaults shown in the usage are imputed. 89 If \code{collapse} is \code{FALSE} or \code{NA} the corresponding 90 field is not collapsed but only the first element is used. 91 The \code{print()} method calls the \code{format()} method and prints 92 the result, the \code{toBibtex()} method creates a suitable BibTeX 93 representation. 94 95 Person objects can be subscripted by fields (using \code{$}) or by 96 position (using \code{[}). 97 98 \code{as.person()} is a generic function. Its default method tries to 99 reverse the default person formatting, and can also handle formatted 100 person entries collapsed by comma or \code{"and"} (with appropriate 101 white space). 102 103 Personal names are rather tricky, e.g., 104 \url{https://en.wikipedia.org/wiki/Personal_name}. 105 106 The current implementation (starting from R 2.12.0) of the 107 \code{"person"} class uses the notions of \emph{given} (including 108 middle names) and \emph{family} names, as specified by \code{given} 109 and \code{family} respectively. Earlier versions used a scheme based 110 on first, middle and last names, as appropriate for most of Western 111 culture where the given name precedes the family name, but not 112 universal, as some other cultures place it after the family name, or 113 use no family name. To smooth the transition to the new scheme, 114 arguments \code{first}, \code{middle} and \code{last} are still 115 supported, but their use is deprecated and they must not be given in 116 combination with the corresponding new style arguments. For persons 117 which are not natural persons (e.g., institutions, companies, etc.) it 118 is appropriate to use \code{given} (but not \code{family}) for the 119 name, e.g., \code{person("R Core Team", role = "aut")}. 120 121 The new scheme also adds the possibility of specifying \emph{roles} 122 based on a subset of the MARC Code List for Relators 123 (\url{https://www.loc.gov/marc/relators/relaterm.html}). 124 When giving the roles of persons in the context of authoring \R 125 packages, the following usage is suggested. 126 \describe{ 127 \item{\code{"aut"}}{(Author) Use for full authors who have made 128 substantial contributions to the package and should show up in the 129 package citation.} 130 \item{\code{"com"}}{(Compiler) Use for persons who collected code 131 (potentially in other languages) but did not make further 132 substantial contributions to the package.} 133 \item{\code{"cph"}}{(Copyright holder) Use for all copyright 134 holders. This is a legal concept so should use the legal name of 135 an institution or corporate body.} 136 \item{\code{"cre"}}{(Creator) Use for the package maintainer.} 137 \item{\code{"ctb"}}{(Contributor) Use for authors who have made 138 smaller contributions (such as code patches etc.) but should not 139 show up in the package citation.} 140 \item{\code{"ctr"}}{(Contractor) Use for authors who have been 141 contracted to write (parts of) the package and hence do not own 142 intellectual property.} 143 \item{\code{"dtc"}}{(Data contributor) Use for persons who 144 contributed data sets for the package.} 145 \item{\code{"fnd"}}{(Funder) Use for persons or organizations that 146 furnished financial support for the development of the package.} 147 \item{\code{"rev"}}{(Reviewer) Use for persons or organizations 148 responsible for reviewing (parts of) the package.} 149 \item{\code{"ths"}}{(Thesis advisor) If the package is part of a 150 thesis, use for the thesis advisor.} 151 \item{\code{"trl"}}{(Translator) If the R code is a translation from 152 another language (typically S), use for the translator to R.} 153 } 154 155 In the old scheme, person objects were used for single persons, and a 156 separate \code{"personList"} class with corresponding creator 157 \code{personList()} for collections of these. The new scheme employs 158 a single class for information about an arbitrary positive number of 159 persons, eliminating the need for the \code{personList} mechanism. 160 161 The \code{comment} field can be used for \dQuote{arbitrary} additional 162 information about persons. Elements named \code{"ORCID"} will be 163 taken to give ORCID identifiers (see \url{https://orcid.org/} for more 164 information), and be displayed as the corresponding URIs by the 165 \code{print()} and \code{format()} methods (see \bold{Examples} 166 below). 167 168} 169\seealso{ 170 \code{\link{citation}} 171} 172\keyword{misc} 173\examples{ 174## Create a person object directly ... 175p1 <- person("Karl", "Pearson", email = "pearson@stats.heaven") 176 177## ... or convert a string. 178p2 <- as.person("Ronald Aylmer Fisher") 179 180## Combining and subsetting. 181p <- c(p1, p2) 182p[1] 183p[-1] 184 185## Extracting fields. 186p$family 187p$email 188p[1]$email 189 190## Specifying package authors, example from "boot": 191## AC is the first author [aut] who wrote the S original. 192## BR is the second author [aut], who translated the code to R [trl], 193## and maintains the package [cre]. 194b <- c(person("Angelo", "Canty", role = "aut", comment = 195 "S original, <http://statwww.epfl.ch/davison/BMA/library.html>"), 196 person(c("Brian", "D."), "Ripley", role = c("aut", "trl", "cre"), 197 comment = "R port", email = "ripley@stats.ox.ac.uk") 198 ) 199b 200 201## Formatting. 202format(b) 203format(b, include = c("family", "given", "role"), 204 braces = list(family = c("", ","), role = c("(Role(s): ", ")"))) 205 206## Conversion to BibTeX author field. 207paste(format(b, include = c("given", "family")), collapse = " and ") 208toBibtex(b) 209 210## ORCID identifiers. 211(p3 <- person("Achim", "Zeileis", 212 comment = c(ORCID = "0000-0003-0918-3766"))) 213} 214