Package 'plume'

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())

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()

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

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())

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))

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^")

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))

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 = " ")

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)

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)

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)