# plume [![CRAN status](https://www.r-pkg.org/badges/version/plume)](https://CRAN.R-project.org/package=plume) [![R-CMD-check](https://github.com/arnaudgallou/plume/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/arnaudgallou/plume/actions/workflows/R-CMD-check.yaml) [![Codecov test coverage](https://codecov.io/gh/arnaudgallou/plume/graph/badge.svg)](https://app.codecov.io/gh/arnaudgallou/plume) ## Overview plume provides tools for handling and generating author-related information for scientific writing in R Markdown and Quarto. The package implements two R6 classes: - `PlumeQuarto`: class that allows you to add or update author metadata in YAML files or the YAML header of Quarto documents. The generated YAML complies with Quarto’s [author and affiliations schemas](https://quarto.org/docs/journals/authors.html). This is the class to use when working with journal templates. - `Plume`: class that generates author lists and other author-related information as character vectors. This is a simple and convenient solution when you don’t need preformatted documents. ## Installation Install plume from CRAN with: ``` r install.packages("plume") ``` Alternatively, you can install the development version of plume from GitHub with: ``` r # install.packages("pak") pak::pak("arnaudgallou/plume") ``` ## Usage The minimal required data to work with plume classes is a dataset containing given and family names but you would normally want to provide more information such as email addresses, ORCIDs, affiliations, etc. ``` r library(plume) encyclopedists #> # A tibble: 4 × 10 #> given_name family_name email phone orcid supervision writing note #> #> 1 Denis Diderot dider… +1234 0000… 1 1 born… #> 2 Jean-Jacques Rousseau rouss… 0000… NA 1 #> 3 François-Marie Arouet aroue… NA 1 also… #> 4 Jean Le Rond d'Alembert alemb… 0000… 1 1 born… #> # ℹ 2 more variables: affiliation_1 , affiliation_2 Plume$new(encyclopedists) #> # A tibble: 4 × 11 #> id given_name family_name literal_name initials orcid email phone note #> #> 1 1 Denis Diderot Denis Dider… D.D. 0000… dide… +1234 born… #> 2 2 Jean-Jacques Rousseau Jean-Jacque… J.-J.R. 0000… rous… #> 3 3 François-Marie Arouet François-Ma… F.-M.A. arou… also… #> 4 4 Jean Le Rond d'… Jean Le Ron… J.L.R.d… 0000… alem… born… #> # ℹ 2 more variables: affiliation , role ``` `PlumeQuarto` lets you insert author data into YAML files or the YAML header of any `.qmd` document using the `to_yaml()` method. Consider the following example: --- title: Encyclopédie --- Qui scribit bis legit ``` r aut <- PlumeQuarto$new( encyclopedists, file = "example.qmd" ) aut$set_corresponding_authors(1, 4) aut$to_yaml() ``` --- 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 attributes: corresponding: true roles: - Supervision - Writing - original draft affiliations: - ref: aff1 - id: aut2 name: given: Jean-Jacques family: Rousseau email: rousseau@encyclopediste.fr orcid: 0000-0000-0000-0002 attributes: corresponding: false roles: - Writing - original draft affiliations: - ref: aff2 - id: aut3 name: given: François-Marie family: Arouet email: arouet@encyclopediste.fr note: also known as Voltaire attributes: corresponding: false roles: - Writing - original draft affiliations: - ref: aff2 - id: aut4 name: given: Jean family: Le Rond d'Alembert email: alembert@encyclopediste.fr orcid: 0000-0000-0000-0003 note: born in 1717 in Paris attributes: corresponding: true roles: - Supervision - Writing - original draft affiliations: - ref: aff1 - ref: aff3 affiliations: - id: aff1 name: Université de Paris - id: aff2 name: Lycée Louis-le-Grand - id: aff3 name: Collège des Quatre-Nations --- Qui scribit bis legit Alternatively, you can generate author information as character vectors using `Plume`: ``` r aut <- Plume$new(encyclopedists) aut$set_corresponding_authors(diderot, .by = "family_name") aut$get_author_list(suffix = "^a,^cn") #> Denis Diderot^1,^\*† #> Jean-Jacques Rousseau^2^ #> François-Marie Arouet^2^‡ #> Jean Le Rond d'Alembert^1,3^§ aut$get_contact_details() #> diderot@encyclopediste.fr (Denis Diderot) aut$get_affiliations() #> ^1^Université de Paris #> ^2^Lycée Louis-le-Grand #> ^3^Collège des Quatre-Nations aut$get_notes() #> ^†^born in 1713 in Langres #> ^‡^also known as Voltaire #> ^§^born in 1717 in Paris aut$get_contributions() #> Supervision: D.D. and J.L.R.d'A. #> Writing - original draft: D.D., J.-J.R., F.-M.A. and J.L.R.d'A. aut2 <- Plume$new( encyclopedists, roles = c( supervision = "supervised the project", writing = "contributed to the Encyclopédie" ), symbols = plm_symbols(affiliation = letters) ) aut2$get_author_list("^a^") #> Denis Diderot^a^ #> Jean-Jacques Rousseau^b^ #> François-Marie Arouet^b^ #> Jean Le Rond d'Alembert^a,c^ aut2$get_contributions(roles_first = FALSE, divider = " ") #> D.D. and J.L.R.d'A. supervised the project #> D.D., J.-J.R., F.-M.A. and J.L.R.d'A. contributed to the Encyclopédie ``` ## Acknowledgements Thanks to: - [Richard J. Telford](https://github.com/richardjtelford) for his advice that helped me conceive this package. - [Maëlle Salmon](https://github.com/maelle) and [Gábor Csárdi](https://github.com/gaborcsardi) for their help when I was stuck with unit tests, roxygen2 or pkgdown.