person {utils} | R Documentation |
Persons
Description
A class and utility methods for holding information about persons like name and email address.
Usage
person(given = NULL, family = NULL, middle = NULL,
email = NULL, role = NULL, comment = NULL,
first = NULL, last = NULL)
as.person(x)
## 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", "md")
)
## S3 method for class 'person'
toBibtex(object, escape = FALSE, ...)
Arguments
given |
a character vector with the given names, or a list thereof. |
family |
a character string with the family name, or a list thereof. |
middle |
a character string with the collapsed middle name(s). Deprecated, see Details. |
email |
a character string (or vector) giving an e-mail address (each), or a list thereof. |
role |
a character vector specifying the role(s) of the person (see Details), or a list thereof. |
comment |
a character string (or vector) providing comments, or a list thereof. |
first |
a character string giving the first name. Deprecated, see Details. |
last |
a character string giving the last name. Deprecated, see Details. |
x |
an object for the |
include |
a character vector giving the fields to be included when formatting. |
braces |
a list of characters (see Details). |
collapse |
a list of characters (see Details). |
... |
currently not used. |
style |
a character string specifying the print style, with
|
object |
an R object inhering from class |
escape |
a logical indicating whether non-ASCII characters should be translated to LaTeX escape sequences. |
Details
Objects of class "person"
can hold information about an
arbitrary positive number of persons. These can be obtained by one
call to person()
with list arguments, or by first creating
objects representing single persons and combining these via
c()
.
The format()
method collapses information about persons into
character vectors (one string for each person): the fields in
include
are selected, each collapsed to a string using the
respective element of collapse
and subsequently
“embraced” using the respective element of braces
, and
finally collapsed into one string separated by white space. If
braces
and/or collapse
do not specify characters for all
fields, the defaults shown in the usage are imputed.
If collapse
is FALSE
or NA
the corresponding
field is not collapsed but only the first element is used.
The print()
method calls the format()
method and prints
the result, the toBibtex()
method creates a suitable BibTeX
representation.
Person objects can be subscripted by fields (using $
) or by
position (using [
).
as.person()
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 "and"
(with appropriate
white space).
Personal names are rather tricky, e.g., https://en.wikipedia.org/wiki/Personal_name.
The current implementation (starting from R 2.12.0) of the
"person"
class uses the notions of given (including
middle names) and family names, as specified by given
and family
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 first
, middle
and last
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 given
(but not family
) for the
name, e.g., person("R Core Team", role = "aut")
.
The new scheme also adds the possibility of specifying roles based on a subset of the MARC Code List for Relators (https://www.loc.gov/marc/relators/relaterm.html). When giving the roles of persons in the context of authoring R packages, the following usage is suggested.
"aut"
(Author) Use for full authors who have made substantial contributions to the package and should show up in the package citation.
"com"
(Compiler) Use for persons who collected code (potentially in other languages) but did not make further substantial contributions to the package.
"cph"
(Copyright holder) Use for all copyright holders. This is a legal concept so should use the legal name of an institution or corporate body. Note that authors which are ‘natural persons’ are by default copyright holders and so do not need to be given this role.
"cre"
(Creator) Use for the package maintainer.
"ctb"
(Contributor) Use for authors who have made smaller contributions (such as code patches etc.) but should not show up in the package citation.
"ctr"
(Contractor) Use for authors who have been contracted to write (parts of) the package and hence do not own intellectual property.
"dtc"
(Data contributor) Use for persons who contributed data sets for the package.
"fnd"
(Funder) Use for persons or organizations that furnished financial support for the development of the package.
"rev"
(Reviewer) Use for persons or organizations responsible for reviewing (parts of) the package.
"ths"
(Thesis advisor) If the package is part of a thesis, use for the thesis advisor.
"trl"
(Translator) If the R code is a translation from another language (typically S), use for the translator to R.
In the old scheme, person objects were used for single persons, and a
separate "personList"
class with corresponding creator
personList()
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 personList
mechanism.
The comment
field can be used for “arbitrary” additional
information about persons. Elements named "ORCID"
will be
taken to give ORCID identifiers (see https://orcid.org/ for more
information), and be displayed as the corresponding URIs by the
print()
and format()
methods (see Examples
below).
Where more than one entity is given a "cph"
role, the
comment
field should be used to delimit who owns the copyright
to what parts of the package.
Value
person()
and as.person()
return objects of class
"person"
.
See Also
Examples
## 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")))