The goal of the plume package is to make the handling and formatting of author data for scientific writing in R Markdown and Quarto easy and painless.
We’ll use the datasets encyclopedists and
encyclopedists_fr to explore the different functionalities
of the package. These datasets contain information about four notable
authors of the “Encyclopédie”, published in France in the 18th century.
encyclopedists_fr is the French translation of
encyclopedists and will be used to illustrate how to handle
custom variable names. Both datasets are documented in
?encyclopedists.
encyclopedists
#> # A tibble: 4 × 10
#> given_name family_name email phone orcid supervision writing note
#> <chr> <chr> <chr> <chr> <chr> <dbl> <dbl> <chr>
#> 1 Denis Diderot dider… +1234 0000… 1 1 born…
#> 2 Jean-Jacques Rousseau rouss… <NA> 0000… NA 1 <NA>
#> 3 François-Marie Arouet aroue… <NA> <NA> NA 1 also…
#> 4 Jean Le Rond d'Alembert alemb… <NA> 0000… 1 1 born…
#> # ℹ 2 more variables: affiliation_1 <chr>, affiliation_2 <chr>plume provides two R6 classes: Plume and
PlumeQuarto. You can create a plume object with
Plume$new() or PlumeQuarto$new().
Alternatively, you can use their alias new_plume() and
new_plume_quarto(). plume classes take a data frame or
tibble as input data. The input data must have at least two columns, one
for given names and another for family names.
Plume$new(encyclopedists)
#> # A tibble: 4 × 11
#> id given_name family_name literal_name initials orcid email phone note
#> <int> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 1 Denis Diderot Denis Dider… D.D. 0000… dide… +1234 born…
#> 2 2 Jean-Jacques Rousseau Jean-Jacque… J.-J.R. 0000… rous… <NA> <NA>
#> 3 3 François-Marie Arouet François-Ma… F.-M.A. <NA> arou… <NA> also…
#> 4 4 Jean Le Rond d'… Jean Le Ron… J.L.R.d… 0000… alem… <NA> born…
#> # ℹ 2 more variables: affiliation <list>, role <list>The default variables handled by plume classes are organised into six categories:
Primaries: variables required to create a plume object.
| Name | Plume | PlumeQuarto |
|---|---|---|
| given_name | ||
| family_name |
Secondaries: optional variables that can be provided in the input data.
| Name | Plume | PlumeQuarto |
|---|---|---|
| orcid | ||
| phone | ||
| fax | ||
| url | ||
| number | ||
| dropping_particle | ||
| acknowledgements |
Nestables: optional variables that can be provided
in the input data to pass multiple independent values to authors.
Nestable variables must start with the same prefix. For example,
affiliation_1, affiliation_2, …,
affiliation_n to pass several affiliations to authors.
| Name | Plume | PlumeQuarto |
|---|---|---|
| affiliation | ||
| note | ||
| degree |
Roles: optional user-defined variables describing
authors’ roles (see Defining roles and
contributors for details). By default, uses CRediT roles as defined
by credit_roles().
Internals: variables created internally. These variables don’t need to be provided in the input data and are ignored if supplied. You shouldn’t worry much about these variables unless you want to customise names or extend plume classes with new default names.
| Name | Plume | PlumeQuarto |
|---|---|---|
| id | ||
| initials | ||
| literal_name | ||
| corresponding | ||
| role | ||
| contributor_rank | ||
| deceased | ||
| equal_contributor |
Meta: PlumeQuarto-specific variables
used to pass extra information that doesn’t fit in other categories.
Meta columns must start with the prefix meta- and are
followed by a custom name (e.g. meta-custom_name). You
should only use these variables to pass data that are template specific.
See Quarto’s arbitrary-metadata
section for details.
plume lets you use custom variable names. Simply provide the
names parameter a named vector when instantiating a plume
class, where keys are default names and values their respective
replacements.
Plume$new(
encyclopedists_fr,
names = c(
given_name = "prénom",
family_name = "nom",
literal_name = "nom_complet",
email = "courriel",
initials = "initiales"
)
)
#> # A tibble: 4 × 10
#> id prénom nom nom_complet initiales orcid courriel role note
#> <int> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 1 Denis Diderot Denis Dide… D.D. 0000… diderot… Supe… né e…
#> 2 2 Jean-Jacques Rousseau Jean-Jacqu… J.-J.R. 0000… roussea… <NA> <NA>
#> 3 3 François-Marie Arouet François-M… F.-M.A. <NA> arouet@… <NA> dit …
#> 4 4 Jean Le Rond… Jean Le Ro… J.L.R.d'… 0000… alember… Supe… né e…
#> # ℹ 1 more variable: affiliation <list>You can add roles by creating specific role columns in the input data
and indicating contributors with the number 1:
#> # A tibble: 4 × 4
#> given_name family_name supervision writing
#> <chr> <chr> <dbl> <dbl>
#> 1 Denis Diderot 1 1
#> 2 Jean-Jacques Rousseau NA 1
#> 3 François-Marie Arouet NA 1
#> 4 Jean Le Rond d'Alembert 1 1plume uses the Contributor Roles
Taxonomy (CRediT) by default, assuming the input data contains the
appropriate columns (see credit_roles() for details). You
can specify your own roles via the roles parameter when
creating a plume object. The roles parameter takes a vector
of key-value pairs where keys identify role columns and values define
the actual roles to use.
PlumeQuarto allows you to add or update author data
directly into YAML files or the YAML header of .qmd
documents.
Consider the following YAML file:
title: EncyclopédieYou can add author data to the file using the to_yaml()
method:
title: Encyclopédie
author:
- id: aut1
name:
given: Denis
family: Diderot
email: diderot@encyclopediste.fr
phone: '+1234'
orcid: 0000-0000-0000-0001
note: born in 1713 in Langres
roles:
- Supervision
- Writing - original draft
affiliations:
- ref: aff1
- id: aut2
name:
given: Jean
family: Le Rond d'Alembert
email: alembert@encyclopediste.fr
orcid: 0000-0000-0000-0003
note: born in 1717 in Paris
roles:
- Supervision
- Writing - original draft
affiliations:
- ref: aff1
- ref: aff2
affiliations:
- id: aff1
name: Université de Paris
- id: aff2
name: Collège des Quatre-NationsAuthors are listed in the order they’re defined in the input data.
If the YAML or Quarto file already has an author and
affiliations keys, to_yaml() replaces old
values with new ones.
title: Encyclopédie
author:
- name:
given: Jean-Jacques
family: Rousseau
email: rousseau@encyclopediste.fr
orcid: 0000-0000-0000-0002
roles:
- Writing - original draft
affiliations:
- ref: aff1
affiliations:
- id: aff1
name: Lycée Louis-le-GrandDefault symbols are:
#> List of 3
#> $ affiliation : NULL
#> $ corresponding: chr "*"
#> $ note : chr [1:6] "†" "‡" "§" "¶" "#" "**"You can change symbols when creating a plume object using the
parameter symbols.
Use NULL to display numerals:
aut <- Plume$new(
encyclopedists,
symbols = plm_symbols(affiliation = letters, note = NULL)
)
aut$get_author_list("^a,n^")
#> Denis Diderot^a,1^
#> Jean-Jacques Rousseau^b^
#> François-Marie Arouet^b,2^
#> Jean Le Rond d'Alembert^a,c,3^Use NULL as much as possible for symbols using numerous
unique items (typically affiliations). If you have to use a character
vector for a given category that has more unique items than vector
elements, you can control the sequencing behaviour using the
sequential() modifier, as shown below:
By default, plume repeats elements when all elements in a vector are
consumed. Using sequential() allows you to display a
logical sequence of characters
(e.g. a, b, c, ..., z, aa, ab, ac, ..., az, ba, bb, bc, ...).
To output author data as markdown content, use the chunk option
results: asis in combination with cat():
Inline chunks output values “as is” by default and can be used as follows:
`r aut$get_author_list()`