Type:	Package
Title:	A Simple Author Handler for Scientific Writing
Version:	0.2.5
Description:	Handles and formats author information in scientific writing in 'R Markdown' and 'Quarto'. 'plume' provides easy-to-use and flexible tools for injecting author metadata in 'YAML' headers 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:	2024-09-02 19:34:12 UTC; arnaudgallou
Author:	Arnaud Gallou [aut, cre, cph]
Maintainer:	Arnaud Gallou <arangacas@gmail.com>
Repository:	CRAN
Date/Publication:	2024-09-02 21:40: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 injecting author metadata in 'YAML' headers 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

Plume class

Description

Class that generates author lists and other author-related information as character strings.

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,
  symbols = NULL,
  roles = credit_roles(),
  credit_roles = FALSE,
  initials_given_name = FALSE,
  family_name_first = FALSE,
  interword_spacing = TRUE,
  orcid_icon = orcid(),
  by = NULL
)

Arguments

Returns

A Plume object.

Method get_author_list()

Get author list.

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 ORCIDs

The order of the keys determines the order of symbol types. E.g. "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. Use NULL or an empty string to list author names 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(
  format = "{details} ({name})",
  email = TRUE,
  phone = FALSE,
  fax = FALSE,
  url = FALSE,
  sep = ", "
)

Arguments

Returns

A character vector.

Method get_contributions()

Get authors' contributions.

Usage

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

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)

# Getting authors suffixed 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 = list(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$get_plume()

• PlumeHandler$get_roles()

• PlumeHandler$clone()

Method new()

Usage

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

Method print()

Usage

PlumeHandler$print()

Method get_plume()

Usage

PlumeHandler$get_plume()

Method get_roles()

Usage

PlumeHandler$get_roles()

Method clone()

The objects of this class are cloneable with this method.

Usage

PlumeHandler$clone(deep = FALSE)

Arguments

PlumeQuarto class

Description

Class that pushes author metadata in YAML files or the YAML header of Quarto files.

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,
  by = NULL
)

Arguments

Returns

A PlumeQuarto object.

Method to_yaml()

Push or update author information in a YAML file or YAML header. The generated YAML complies with Quarto's author and affiliations schemas.

Usage

PlumeQuarto$to_yaml()

Details

If missing, to_yaml() inserts author information into the desired file. Otherwise, the function replaces old author and affiliations values with the ones provided in the input data.

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 file with a YAML header
# containing a title
tmp_file <- tempfile(fileext = ".qmd")
readr::write_lines("---\ntitle: Encyclopédie\n---", tmp_file)

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

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

# And push author data to the YAML header
aut$to_yaml()

cat(readr::read_file(tmp_file))

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

cat(readr::read_file(tmp_file))

# Clean up the temporary file
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, 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)

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)

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, by = deprecated())

Arguments

Returns

The class instance.

Method set_deceased()

Set deceased authors.

Usage

StatusSetterPlumeQuarto$set_deceased(..., .by, 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

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 famous 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 data set 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)
aut$get_author_list() |> enumerate()

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())
aut$get_plume() |> dplyr::select(1:3, corresponding)

ORCID icon

Description

Helper function to control the size and colour of the ORCID icon.

Usage

orcid(size = 16, bw = FALSE)

Arguments

Value

A plume icon.

Examples

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

Create a table template for plume classes

Description

This helper function allows you to generate an empty tibble that you can use 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 = list(affiliation = sequential(letters))
)

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

Set new default names to a plume subclass

Description

This helper function allows you to set new default names to a plume subclass, e.g. to set default names to a language other than English.

Usage

set_default_names(..., .plume_quarto = FALSE)

Arguments

Details

Available names are:

id, initials, literal_name, corresponding, contributor_rank, given_name, family_name, email, phone, fax, url, affiliation, role, note, orcid.

Using .plume_quarto = TRUE adds deceased, equal_contributor, number, dropping_particle and acknowledgements.

Value

A named list.

Examples

# Extending `Plume` with default names in French
PlumeFr <- R6::R6Class(
  classname = "PlumeFr",
  inherit = Plume,
  private = list(
    plume_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)