Title: | 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. |
Authors: | Arnaud Gallou [aut, cre, cph] |
Maintainer: | Arnaud Gallou <[email protected]> |
License: | GPL (>= 3) |
Version: | 0.2.5.9000 |
Built: | 2024-11-18 03:23:37 UTC |
Source: | https://github.com/arnaudgallou/plume |
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.
credit_roles(oxford_spelling = TRUE)
credit_roles(oxford_spelling = TRUE)
oxford_spelling |
Should the suffix -ize/-ization be used? |
A named vector.
credit_roles()
credit_roles()
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
).
encyclopedists encyclopedists_fr
encyclopedists encyclopedists_fr
A tibble with 4 rows and 10 variables:
authors' given names
authors' family names
authors' email addresses
authors' phone numbers
authors' ORCID
authors' affiliations
authors that supervised the project
authors involved in the writing
special notes about authors
encyclopedists encyclopedists_fr
encyclopedists encyclopedists_fr
Wrapper around glue_collapse()
using
sep = ", "
and last = " and "
as default arguments.
enumerate(x, sep = ", ", last = " and ")
enumerate(x, sep = ", ", last = " and ")
x |
A character vector. |
sep |
Separator used to separate the terms. |
last |
Separator used to separate the last two items if |
A character string with the same class as x
.
aut <- Plume$new(encyclopedists) aut$get_author_list() |> enumerate()
aut <- Plume$new(encyclopedists) aut$get_author_list() |> enumerate()
Helper function to control the size and colour of the ORCID icon.
orcid(size = 16, bw = FALSE)
orcid(size = 16, bw = FALSE)
size |
Size (in pixels) of the icon. |
bw |
Should the black and white version of the icon be used? |
A plume icon.
aut <- Plume$new(encyclopedists, orcid_icon = orcid(bw = TRUE))
aut <- Plume$new(encyclopedists, orcid_icon = orcid(bw = TRUE))
This helper function allows you to generate an empty
tibble
that you can use as a template to supply
author data.
plm_template(minimal = TRUE, role_cols = credit_roles(), credit_roles = FALSE)
plm_template(minimal = TRUE, role_cols = credit_roles(), credit_roles = FALSE)
minimal |
If |
role_cols |
A vector of names defining role columns to create. If the vector contains key-value pairs, columns will be named after the keys. |
credit_roles |
It is now recommended to use |
An empty tibble.
plm_template() plm_template(role_cols = paste0("role_", 1:5))
plm_template() plm_template(role_cols = paste0("role_", 1:5))
Class that generates author lists and other author-related information as character strings.
plume::NameHandler
-> plume::PlumeHandler
-> plume::StatusSetter
-> plume::StatusSetterPlume
-> Plume
new()
Create a Plume
object.
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 )
data
A data frame containing author-related data.
names
A vector of key-value pairs specifying custom names to use, where keys are default names and values their respective replacements.
symbols
A list of key-value pairs defining the symbols to use to
link authors and their metadata. Valid keys are "affiliation"
,
"corresponding"
and "note"
. By default, uses digits for
affiliations, "*"
for corresponding authors and "†"
, "‡"
, "§"
,
"¶"
, "#"
, "**"
for notes. Set a key to NULL
to use numerals.
roles
A vector of key-value pairs defining roles where keys identify role columns and values describe the actual roles to use.
credit_roles
It is now recommended to use roles = credit_roles()
to use the
Contributor Roles Taxonomy.
initials_given_name
Should the initials of given names be used?
family_name_first
Should literal names show family names first?
interword_spacing
Should literal names use spacing? This parameter is only useful for people writing in languages that don't separate words with a space such as Chinese or Japanese.
orcid_icon
The ORCID icon, as defined by orcid()
, to be used.
by
A character string defining the default variable used to assign
specific metadata to authors in all set_*()
methods. By default, uses
authors' id.
A Plume
object.
get_author_list()
Get author list.
Plume$get_author_list(suffix = NULL, format = deprecated())
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.
A character vector.
get_affiliations()
Get authors' affiliations.
Plume$get_affiliations(superscript = TRUE, sep = "")
superscript
Should affiliation ids be superscripted?
sep
Separator used to separate affiliation ids and affiliations.
A character vector.
get_notes()
Get authors' notes.
Plume$get_notes(superscript = TRUE, sep = "")
superscript
Should note ids be superscripted?
sep
Separator used to separate note ids and notes.
A character vector.
get_orcids()
Get authors' ORCID.
Plume$get_orcids(compact = FALSE, icon = TRUE, sep = "")
compact
Should links only display the 16-digit identifier?
icon
Should the ORCID icon be shown?
sep
Separator used to separate authors and their respective ORCID.
A character vector.
get_contact_details()
Get the contact details of corresponding authors.
Plume$get_contact_details( format = "{details} ({name})", email = TRUE, phone = FALSE, fax = FALSE, url = FALSE, sep = ", " )
format
A glue
specification that uses the
variables name
and/or details
.
email, phone, fax, url
Arguments equal to TRUE
are evaluated and
passed to the variable details
. By default, only email
is set to
TRUE
.
sep
Separator used to separate details
items.
A character vector.
get_contributions()
Get authors' contributions.
Plume$get_contributions( roles_first = TRUE, by_author = FALSE, alphabetical_order = FALSE, dotted_initials = TRUE, literal_names = FALSE, divider = ": ", sep = ", ", sep_last = " and " )
roles_first
If TRUE
, displays roles first and authors second. If
FALSE
, roles follow authors.
by_author
Should roles be grouped by author?
alphabetical_order
Should authors be listed in alphabetical order? By default, lists authors in the order they are defined in the data.
dotted_initials
Should initials be dot-separated?
literal_names
Should literal names be used?
divider
Separator used to separate roles from authors.
sep
Separator used to separate roles or authors.
sep_last
Separator used to separate the last two roles or authors if more than one item is associated to a role or author.
A character vector.
clone()
The objects of this class are cloneable with this method.
Plume$clone(deep = FALSE)
deep
Whether to make a deep clone.
# 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 = " ")
# 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 = " ")
Class that pushes author metadata in YAML files or the YAML header of Quarto files.
plume::NameHandler
-> plume::PlumeHandler
-> plume::StatusSetter
-> plume::StatusSetterPlumeQuarto
-> PlumeQuarto
new()
Create a PlumeQuarto
object.
PlumeQuarto$new( data, file, names = NULL, roles = credit_roles(), credit_roles = FALSE, initials_given_name = FALSE, by = NULL )
data
A data frame containing author-related data.
file
A .qmd
, .yml
or .yaml
file to insert author data into.
names
A vector of key-value pairs specifying custom names to use, where keys are default names and values their respective replacements.
roles
A vector of key-value pairs defining roles where keys identify columns and values describe the actual roles to use.
credit_roles
It is now recommended to use roles = credit_roles()
to use the
Contributor Roles Taxonomy.
initials_given_name
Should the initials of given names be used?
by
A character string defining the default variable used to assign
specific metadata to authors in all set_*()
methods. By default, uses
authors' id.
A PlumeQuarto
object.
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.
PlumeQuarto$to_yaml()
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.
The input file
invisibly.
clone()
The objects of this class are cloneable with this method.
PlumeQuarto$clone(deep = FALSE)
deep
Whether to make a deep clone.
# 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)
# 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)
Modifier function used to generate logical sequences of characters.
sequential(x)
sequential(x)
x |
A character vector. |
A character vector with parent S3 class sequential
.
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)
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)
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.
set_default_names(..., .plume_quarto = FALSE)
set_default_names(..., .plume_quarto = FALSE)
... |
Key-value pairs where keys are default names and values their respective replacements. |
.plume_quarto |
Are you setting new names for |
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
.
A named list.
# 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)
# 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)