Type:	Package
Title:	A Simple Author Handler for Scientific Writing
Version:	0.3.0
Description:	Handles and formats author information in scientific writing in 'R Markdown' and 'Quarto'. 'plume' provides easy-to-use and flexible tools for inserting author data in 'YAML' as well as generating author and contribution lists (among others) as strings from tabular data.
License:	GPL (≥ 3)
URL:	https://arnaudgallou.github.io/plume/, https://github.com/arnaudgallou/plume
BugReports:	https://github.com/arnaudgallou/plume/issues
Depends:	R (≥ 4.1.0)
Imports:	dplyr (≥ 1.0.0), glue (≥ 1.3.2), jsonlite (≥ 1.6.0), knitr (≥ 1.40), lifecycle (≥ 1.0.3), purrr (≥ 1.0.0), R6, readr (≥ 1.0.0), rlang (≥ 1.0.0), stringr, tibble (≥ 3.0.0), tidyr (≥ 1.1.0), tidyselect (≥ 1.0.0), vctrs (≥ 0.3.0), yaml (≥ 2.3.8)
Suggests:	covr, fontawesome, gt, rmarkdown, testthat, waldo (≥ 0.3.0), withr
VignetteBuilder:	knitr
Config/Needs/website:	arnaudgallou/cygne
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-GB
LazyData:	true
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-09-27 10:11:31 UTC; arnaudgallou
Author:	Arnaud Gallou [aut, cre, cph]
Maintainer:	Arnaud Gallou <arangacas@gmail.com>
Repository:	CRAN
Date/Publication:	2025-09-27 10:20:02 UTC

plume: A Simple Author Handler for Scientific Writing

Description

Handles and formats author information in scientific writing in 'R Markdown' and 'Quarto'. 'plume' provides easy-to-use and flexible tools for inserting author data in 'YAML' as well as generating author and contribution lists (among others) as strings from tabular data.

Author(s)

Maintainer: Arnaud Gallou arangacas@gmail.com (ORCID) [copyright holder]

See Also

Useful links:

• https://arnaudgallou.github.io/plume/

• https://github.com/arnaudgallou/plume

• Report bugs at https://github.com/arnaudgallou/plume/issues

Generate author information within a document

Description

Plume provides several methods to generate author information directly within an R Markdown or Quarto document. This is a convenient solution when you don't need preformatted reports.

In some cases, Plume gives you greater control over the formatting of author information, as it supports features not available in PlumeQuarto.

Notes

new_plume() is an alias for Plume$new().

Super classes

plume::NameHandler -> plume::PlumeHandler -> plume::StatusSetter -> plume::StatusSetterPlume -> Plume

Methods

Public methods

• Plume$new()

• Plume$get_author_list()

• Plume$get_affiliations()

• Plume$get_notes()

• Plume$get_orcids()

• Plume$get_contact_details()

• Plume$get_contributions()

• Plume$clone()

Method new()

Create a Plume object.

Usage

Plume$new(
  data,
  names = NULL,
  roles = credit_roles(),
  symbols = plm_symbols(),
  credit_roles = FALSE,
  initials_given_name = FALSE,
  dotted_initials = TRUE,
  family_name_first = FALSE,
  distinct_initials = FALSE,
  interword_spacing = TRUE,
  orcid_icon = icn_orcid(),
  by = NULL
)

Arguments

Returns

A Plume object.

Method get_author_list()

Get the list of authors.

Usage

Plume$get_author_list(suffix = NULL, format = deprecated())

Arguments

Details

suffix lets you choose which symbol categories to suffix authors with, using the following keys:

• a for affiliations

• c for corresponding authors

• n for notes

• o for ORCID icons (only supported in R Markdown)

The order of the keys determines the order of symbol types. For example, "ac" shows affiliation ids first and corresponding author mark second, when "ca" shows corresponding author mark first and affiliation ids second. Use "," to separate and "^" to superscript symbols.

Set to NULL or "" to list authors without suffixes.

Returns

A character vector.

Method get_affiliations()

Get authors' affiliations.

Usage

Plume$get_affiliations(superscript = TRUE, sep = "")

Arguments

Returns

A character vector.

Method get_notes()

Get authors' notes.

Usage

Plume$get_notes(superscript = TRUE, sep = "")

Arguments

Returns

A character vector.

Method get_orcids()

Get authors' ORCID.

Usage

Plume$get_orcids(compact = FALSE, icon = TRUE, sep = "")

Arguments

Returns

A character vector.

Method get_contact_details()

Get the contact details of corresponding authors.

Usage

Plume$get_contact_details(
  template = "{details} ({name})",
  email = TRUE,
  phone = FALSE,
  fax = FALSE,
  url = FALSE,
  sep = ", ",
  format = deprecated()
)

Arguments

Returns

A character vector.

Method get_contributions()

Get authors' contributions.

Usage

Plume$get_contributions(
  roles_first = TRUE,
  by_author = FALSE,
  alphabetical_order = FALSE,
  literal_names = FALSE,
  divider = ": ",
  sep = ", ",
  sep_last = " and ",
  dotted_initials = deprecated()
)

Arguments

Returns

A character vector.

Method clone()

The objects of this class are cloneable with this method.

Usage

Plume$clone(deep = FALSE)

Arguments

Examples

# Create a Plume instance
aut <- Plume$new(encyclopedists)

# Set the desired corresponding authors, using
# authors' id by default
aut$set_corresponding_authors(1, 4)

# Listing authors, followed by affiliation ids
# and the corresponding author mark:
aut$get_author_list("^a,c^")

# Or maybe with the corresponding author mark
# coming before affiliation ids:
aut$get_author_list("^c,a^")

# Getting more author metadata
aut$get_affiliations()

aut$get_contributions()

# Use `symbols` to change the default symbols.
# E.g. to use letters as affiliation ids:
aut <- Plume$new(
  encyclopedists,
  symbols = plm_symbols(affiliation = letters)
)

aut$get_author_list("^a^")

aut$get_affiliations()

# It is also possible to output contributions in the
# active voice
aut <- Plume$new(
  encyclopedists,
  roles = c(
    supervision = "supervised the project",
    writing = "contributed to the Encyclopédie"
  )
)
aut$get_contributions(roles_first = FALSE, divider = " ")

PlumeHandler class

Description

Internal class processing and shaping tabular data into a plume object.

Super class

plume::NameHandler -> PlumeHandler

Methods

Public methods

• PlumeHandler$new()

• PlumeHandler$print()

• PlumeHandler$data()

• PlumeHandler$get_plume()

• PlumeHandler$roles()

• PlumeHandler$get_roles()

• PlumeHandler$clone()

Method new()

Usage

PlumeHandler$new(
  data,
  names,
  roles,
  credit_roles,
  initials_given_name,
  dotted_initials,
  family_name_first = FALSE,
  distinct_initials = FALSE,
  interword_spacing = TRUE
)

Method print()

Usage

PlumeHandler$print()

Method data()

Get the data of a plume object.

Usage

PlumeHandler$data()

Returns

A tibble.

Method get_plume()

Please use ⁠$data()⁠ instead.

Usage

PlumeHandler$get_plume()

Returns

A tibble.

Method roles()

Get the roles used in a plume object.

Usage

PlumeHandler$roles()

Returns

A character vector.

Method get_roles()

Please use ⁠$roles()⁠ instead.

Usage

PlumeHandler$get_roles()

Returns

A character vector.

Method clone()

The objects of this class are cloneable with this method.

Usage

PlumeHandler$clone(deep = FALSE)

Arguments

Add or update author data in YAML for Quarto

Description

PlumeQuarto allows you to add or update author data in YAML files or the YAML header of Quarto documents. The generated YAML complies with Quarto's author and affiliations schemas. Use this class when working with journal templates.

Notes

new_plume_quarto() is an alias for PlumeQuarto$new().

Super classes

plume::NameHandler -> plume::PlumeHandler -> plume::StatusSetter -> plume::StatusSetterPlumeQuarto -> PlumeQuarto

Methods

Public methods

• PlumeQuarto$new()

• PlumeQuarto$to_yaml()

• PlumeQuarto$clone()

Method new()

Create a PlumeQuarto object.

Usage

PlumeQuarto$new(
  data,
  file,
  names = NULL,
  roles = credit_roles(),
  credit_roles = FALSE,
  initials_given_name = FALSE,
  dotted_initials = TRUE,
  by = NULL
)

Arguments

Returns

A PlumeQuarto object.

Method to_yaml()

Add or update author data in the input file.

Usage

PlumeQuarto$to_yaml()

Returns

The input file, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

PlumeQuarto$clone(deep = FALSE)

Arguments

Examples

# Create a simple temporary YAML file containing a title
tmp_file <- tempfile(fileext = ".yml")
readr::write_lines("title: Encyclopédie", tmp_file)

# View the temporary file
cat(readr::read_file(tmp_file))

# Create a PlumeQuarto instance using the temporary file
# we've just created
aut <- PlumeQuarto$new(
  encyclopedists,
  file = tmp_file
)

# And add author data to the YAML file
aut$to_yaml()

cat(readr::read_file(tmp_file))

# Running the method again with new data updates the YAML
# accordingly
aut <- PlumeQuarto$new(
  dplyr::slice(encyclopedists, 2),
  file = tmp_file
)
aut$to_yaml()

cat(readr::read_file(tmp_file))

# Clean up
unlink(tmp_file)

StatusSetter class

Description

Internal class that manages authors' status.

Super classes

plume::NameHandler -> plume::PlumeHandler -> StatusSetter

Methods

Public methods

• StatusSetter$new()

• StatusSetter$set_corresponding_authors()

• StatusSetter$clone()

Method new()

Usage

StatusSetter$new(..., by)

Method set_corresponding_authors()

Set corresponding authors.

Usage

StatusSetter$set_corresponding_authors(..., .by = NULL, by = deprecated())

Arguments

Returns

The class instance.

Method clone()

The objects of this class are cloneable with this method.

Usage

StatusSetter$clone(deep = FALSE)

Arguments

StatusSetterPlume class

Description

Internal class extending StatusSetter for Plume.

Super classes

plume::NameHandler -> plume::PlumeHandler -> plume::StatusSetter -> StatusSetterPlume

Methods

Public methods

• StatusSetterPlume$set_main_contributors()

• StatusSetterPlume$clone()

Method set_main_contributors()

Force one or more contributors' names to appear first in the contribution list.

Usage

StatusSetterPlume$set_main_contributors(..., .roles = NULL, .by = NULL)

Arguments

Returns

The class instance.

Method clone()

The objects of this class are cloneable with this method.

Usage

StatusSetterPlume$clone(deep = FALSE)

Arguments

StatusSetterPlumeQuarto class

Description

Internal class extending StatusSetter for PlumeQuarto.

Super classes

plume::NameHandler -> plume::PlumeHandler -> plume::StatusSetter -> StatusSetterPlumeQuarto

Methods

Public methods

• StatusSetterPlumeQuarto$set_cofirst_authors()

• StatusSetterPlumeQuarto$set_equal_contributor()

• StatusSetterPlumeQuarto$set_deceased()

• StatusSetterPlumeQuarto$clone()

Method set_cofirst_authors()

Set co-first authors.

Usage

StatusSetterPlumeQuarto$set_cofirst_authors(..., .by = NULL)

Arguments

Returns

The class instance.

Method set_equal_contributor()

This method has been deprecated in favour of set_cofirst_authors().

Usage

StatusSetterPlumeQuarto$set_equal_contributor(
  ...,
  .by = NULL,
  by = deprecated()
)

Arguments

Returns

The class instance.

Method set_deceased()

Set deceased authors.

Usage

StatusSetterPlumeQuarto$set_deceased(..., .by = NULL, by = deprecated())

Arguments

Returns

The class instance.

Method clone()

The objects of this class are cloneable with this method.

Usage

StatusSetterPlumeQuarto$clone(deep = FALSE)

Arguments

Print vector elements on distinct lines

Description

Thin wrapper around cat() to display vector elements on distinct lines when rendering an R Markdown or Quarto document.

Usage

as_lines(...)

Arguments

Value

NULL, invisibly.

Examples

aut <- Plume$new(encyclopedists)
as_lines(aut$get_affiliations())

CRediT roles

Description

Helper function returning the 14 contributor roles of the Contributor Roles Taxonomy (CRediT). This function is the default argument of the roles and role_cols parameters in plume classes and plm_template(), respectively.

Usage

credit_roles(oxford_spelling = TRUE)

Arguments

Value

A named vector.

Examples

credit_roles()

Famous encyclopedists

Description

Data on four notable authors of the Encyclopédie (originally "Encyclopédie, ou dictionnaire raisonné des sciences, des arts et des métiers") published in France in the second half of the 18th century. The dataset is available in English (encyclopedists) and French (encyclopedists_fr).

Usage

encyclopedists

encyclopedists_fr

Format

A tibble with 4 rows and 10 variables:

given_name,prénom

authors' given names

family_name,nom

authors' family names

email,courriel

authors' email addresses

phone,téléphone

authors' phone numbers

orcid

authors' ORCID

affiliation_1,affiliation_2

authors' affiliations

supervision

authors that supervised the project

writing,rédaction

authors involved in the writing

note

special notes about authors

Examples

encyclopedists

encyclopedists_fr

Enumerate vector elements

Description

Wrapper around glue_collapse() using sep = ", " and last = " and " as default arguments.

Usage

enumerate(x, sep = ", ", last = " and ")

Arguments

Value

A character string with the same class as x.

Examples

aut <- Plume$new(encyclopedists)
enumerate(aut$get_author_list())

Select all authors or exclude some from a selection

Description

Selection helpers to use in conjonction with status setter methods (i.e. methods that assign a status to authors with either TRUE or FALSE):

• everyone() select all authors.

• everyone_but() this function was deprecated as I believe it is not necessary since not more than a couple of authors should normally be given a particular status.

Usage

everyone()

everyone_but(...)

Arguments

Examples

aut <- Plume$new(encyclopedists)

aut$set_corresponding_authors(everyone())
dplyr::select(aut$data(), 1:3, corresponding)

Create an ORCID icon

Description

Create an ORCID icon for use with the Plume class. This is only supported in R Markdown.

Usage

icn_orcid(size = 16, bw = FALSE)

Arguments

Value

A plume icon, i.e. an object with S3 class plm_icon.

Examples

aut <- Plume$new(encyclopedists, orcid_icon = icn_orcid(bw = TRUE))

ORCID icon

Description

Please use icn_orcid() instead.

Usage

orcid(size = 16, bw = FALSE)

Arguments

Value

A plume icon.

Set symbols for Plume

Description

Set the symbols used in a Plume object.

Usage

plm_symbols(
  affiliation = NULL,
  corresponding = "*",
  note = c("†", "‡", "§", "¶", "#", "**")
)

Arguments

Value

A named list.

Examples

aut <- Plume$new(
  encyclopedists,
  symbols = plm_symbols(affiliation = letters)
)
aut$get_author_list("^a^")

Create a table template for plume classes

Description

Create an empty tibble that can be used as a template to supply author data.

Usage

plm_template(minimal = TRUE, role_cols = credit_roles(), credit_roles = FALSE)

Arguments

Value

An empty tibble.

Examples

plm_template()

plm_template(role_cols = paste0("role_", 1:5))

Control the sequencing behaviour of character vectors

Description

Modifier function used to generate logical sequences of characters.

Usage

sequential(x)

Arguments

Value

A character vector with parent S3 class sequential.

Examples

aut <- Plume$new(
  tibble::tibble(
    given_name = "X",
    family_name = "Y",
    affiliation = 1:60
  ),
  symbols = plm_symbols(affiliation = sequential(letters))
)

aut$get_affiliations(sep = ": ", superscript = FALSE)

Set new default names to a plume subclass

Description

This function allows you to set new default names to a plume subclass, for example to set default names to a language other than English.

Usage

set_default_names(..., .plume_quarto = FALSE)

Arguments

Details

See vignette("plume") for the list of available names.

Value

A named list.

Examples

# Extending `Plume` with default names in French
PlumeFr <- R6::R6Class(
  classname = "PlumeFr",
  inherit = Plume,
  private = list(
    names = set_default_names(
      initials = "initiales",
      literal_name = "nom_complet",
      corresponding = "correspondant",
      given_name = "prénom",
      family_name = "nom",
      email = "courriel",
      phone = "téléphone"
    )
  )
)

PlumeFr$new(encyclopedists_fr)