diff --git a/NEWS.md b/NEWS.md index 1dc7115..69748e1 100644 --- a/NEWS.md +++ b/NEWS.md @@ -15,8 +15,13 @@ quarto. When file is NULL (new default), instead of writing a file, the function returns a string with the CRediT Author Statement. It works well with inline code in rmarkdown and quarto documents: `r cras_write(cras_table, markdown = TRUE)` (#2) +- `cras_write` includes a new argument `drop_authors`, if set to `FALSE`, the authors without contributions are not removed from the statement. ## Minor improvements and fixes + - The roles are created using the function roles_get() instead of hard coded. - The former allows to check if authors’ roles are up-to-date comparing with [CRediT] (https://credit.niso.org/) +- Improvements on the documentation of all functions +- In `cras_write`, the default of `markdown` argument is `TRUE`. +- Added some checks to `template_read` to ensure that the format is correct. diff --git a/R/cras_write.R b/R/cras_write.R index 5f9e47e..3669c1b 100644 --- a/R/cras_write.R +++ b/R/cras_write.R @@ -1,16 +1,25 @@ #' Write CRediT author statement +#' @description +#' The function transforms the information in the template +#' (from \code{template_create}) to a raw string following the CRediT authors +#' statement format of "author1: contributions author2: contributions ..." #' @param cras_table A data.frame created using \code{create_template()} -#' @param file The text file to be created. If NULL (default), the statement is returned as a string instead -#' of written to a file. +#' @param file The text file to be created. If NULL (default), the statement is +#' returned as a string instead of written to a file. +#' @param drop_authors If TRUE (default) the authors without contributions are +#' removed from the statement. If FALSE, they are kept without contributions +#' assigned. #' @param overwrite If TRUE, the file is overwritten. Otherwise, a error is #' triggered. -#' @param markdown If TRUE, the authors are surrounded by ** to make them bold -#' in markdown. -#' @param quiet If TRUE, authors without contributions are silently dropped out. +#' @param markdown If TRUE (default), the authors are surrounded by ** to make +#' them bold in markdown. +#' @param quiet If TRUE and \code{drop_authors} is also TRUE, authors without +#' contributions are silently dropped out. #' If FALSE, a warning is triggered in case any authors is dropped out. #' @return A text file with the CRediT authors statement or, if file is NULL -#' (default), a string with the statement that can be used in a Rmarkdown or -#' quarto document using inline code: \code{`r cras_write(cras_table, markdown = TRUE)`} +#' (default), a character vector of length 1 with the statement that can be +#' used in a Rmarkdown or quarto document using inline code: +#' \code{`r cras_write(cras_table, markdown = TRUE)`} #' @examples #' # Generate a template and populate it (randomwly for this example) #' cras_table <- template_create(authors = c("Josep Maria", "Jane Doe")) @@ -30,18 +39,26 @@ cras_write <- function(cras_table, file = NULL, + drop_authors = TRUE, overwrite = FALSE, - markdown = FALSE, + markdown = TRUE, quiet = FALSE){ - cras_table <- drop_authors(cras_table, quiet = quiet) + if(drop_authors) + cras_table <- drop_authors(cras_table, quiet = quiet) cras <- character() for (i in seq_len(nrow(cras_table))){ if (markdown) cras <- paste0(cras,"**") - cras <- paste0(cras, cras_table$Authors[[i]], ":") + cras <- paste0(cras, cras_table$Authors[[i]]) + if (rowSums(cras_table[i, -1]) > 0){ + cras <- paste0(cras, ":") + }# else if (i < nrow(cras_table)) { + # cras <- paste0(cras, " ") + # } + if (markdown) cras <- paste0(cras,"**") cras <- paste0(cras, " ") diff --git a/R/template_create.R b/R/template_create.R index 427865e..1304ff6 100644 --- a/R/template_create.R +++ b/R/template_create.R @@ -1,13 +1,19 @@ -#' Create a template to fill the CRediTas author statement +#' Create a template to fill the CRediT author statement. +#' (\url{https://credit.niso.org}). The template is a table where the authors +#' are the rows and the columns are the roles. #' @param authors A character vector with all the authors to be included in the -#' statement +#' statement. #' @param roles A character vector with the roles to be included in the #' statement. If NULL, it uses all the roles defined in the CRediT author -#' statement +#' statement. #' @param file If a path is provided, the template is saved as a csv for excel -#' @returns A dataframe with a row for each authors and a column for each role, +#' @returns A dataframe with a row for each author and a column for each role, #' filled with zeros. -#' @details The dataframe can be exported to a csv to be edited manually. +#' @details The dataframe can be edited in R or, if file is provided, it is +#' exported to a csv to be edited manually in your preferred csv editor. The +#' csv is created to be compatible with Microsoft Excel, since it is the most +#' popular spreadsheet software among scientists. Therefore, it is separated +#' by semicolon. #' @examples #' template_create(authors = c("Josep Maria", "Jane Doe")) #' @export diff --git a/R/template_read.R b/R/template_read.R index a055ba2..6428845 100644 --- a/R/template_read.R +++ b/R/template_read.R @@ -15,5 +15,21 @@ #' @importFrom utils write.csv2 read.csv2 template_read <- function(file){ + cras_table <- read.csv2(file, check.names = FALSE) + + if(!("Authors" %in% names(cras_table))) + stop("A column named `Authors` is missing") + + if(nrow(cras_table) < 1) + stop("The cras_table has zero rows") + + if(!is.character(cras_table$Authors)) + warning("Authors column is not of type character") + + if(!all(vapply(cras_table[-1], is.numeric, FALSE))) + warning("Roles are not numeric, it can lead to unexpected behaviour") + + return(cras_table) + } diff --git a/README.Rmd b/README.Rmd index a209d93..52f2510 100644 --- a/README.Rmd +++ b/README.Rmd @@ -40,7 +40,10 @@ library(CRediTas) template_create(authors = c("Alexander Humboldt", "Carl Ritter"), file = tempfile()) -cras_table <- template_create(authors = c("Friedrich Ratzel", "Pau Vidal de la Blache", "Élisée Reclus")) +cras_table <- template_create(authors = c("Friedrich Ratzel", + "Pau Vidal de la Blache", + "Pau Vila", + "Élisée Reclus")) knitr::kable(cras_table) ``` @@ -55,21 +58,22 @@ Once the `cras_table` is populated, for instance: ```{r populate_random, echo=FALSE} -cras_table[, 2:ncol(cras_table)] <- sample(0:1, size=3*14, replace = TRUE, prob = c(0.6, 0.4)) +cras_table[-3, -1] <- sample(0:1, size=3*14, replace = TRUE, prob = c(0.6, 0.4)) knitr::kable(cras_table) ``` -A text file can be generated following the CRediT author statement format. +A text file can be generated following the CRediT author statement format. Since `drop = TRUE` by default, the authors without contribution are removed from the statement, Pau Vila in this case. ```{r} textfile <- tempfile() -cras_write(cras_table, textfile, markdown = TRUE) +cras_write(cras_table, textfile, markdown = TRUE, quiet = TRUE) ``` If you open the text file, you will find this: -`r cras_write(cras_table, markdown = TRUE)` +`r cras_write(cras_table, markdown = TRUE, quiet = TRUE)` + diff --git a/README.md b/README.md index edb62eb..a150871 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,10 @@ library(CRediTas) template_create(authors = c("Alexander Humboldt", "Carl Ritter"), file = tempfile()) -cras_table <- template_create(authors = c("Friedrich Ratzel", "Pau Vidal de la Blache", "Élisée Reclus")) +cras_table <- template_create(authors = c("Friedrich Ratzel", + "Pau Vidal de la Blache", + "Pau Vila", + "Élisée Reclus")) knitr::kable(cras_table) ``` @@ -52,6 +55,7 @@ knitr::kable(cras_table) |:-----------------------|------------------:|------------:|---------:|-----------:|----------------:|--------------:|----------:|--------------:|-------------------------:|---------------------------:|--------------:|------------:|-----------------------:|--------------------:| | Friedrich Ratzel | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | | Pau Vidal de la Blache | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | +| Pau Vila | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | | Élisée Reclus | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | As you can see, the table is empty. So you must provide the information @@ -66,24 +70,26 @@ Once the `cras_table` is populated, for instance: | Authors | Conceptualization | Methodology | Software | Validation | Formal Analysis | Investigation | Resources | Data curation | Writing - original draft | Writing - review & editing | Visualization | Supervision | Project administration | Funding acquisition | |:-----------------------|------------------:|------------:|---------:|-----------:|----------------:|--------------:|----------:|--------------:|-------------------------:|---------------------------:|--------------:|------------:|-----------------------:|--------------------:| -| Friedrich Ratzel | 0 | 0 | 0 | 1 | 1 | 0 | 1 | 0 | 1 | 1 | 0 | 1 | 1 | 0 | -| Pau Vidal de la Blache | 1 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | -| Élisée Reclus | 1 | 0 | 1 | 0 | 1 | 0 | 0 | 1 | 1 | 1 | 0 | 0 | 0 | 0 | +| Friedrich Ratzel | 0 | 0 | 1 | 1 | 0 | 0 | 0 | 1 | 1 | 1 | 1 | 0 | 0 | 1 | +| Pau Vidal de la Blache | 0 | 0 | 1 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 1 | +| Pau Vila | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | +| Élisée Reclus | 0 | 0 | 0 | 0 | 1 | 0 | 1 | 0 | 1 | 0 | 0 | 1 | 1 | 1 | A text file can be generated following the CRediT author statement -format. +format. Since `drop = TRUE` by default, the authors without contribution +are removed from the statement, Pau Vila in this case. ``` r textfile <- tempfile() -cras_write(cras_table, textfile, markdown = TRUE) +cras_write(cras_table, textfile, markdown = TRUE, quiet = TRUE) ``` If you open the text file, you will find this: -**Friedrich Ratzel:** Validation, Formal Analysis, Resources, Writing - -original draft, Writing - review & editing, Supervision, Project -administration **Pau Vidal de la Blache:** Conceptualization, -Investigation, Supervision **Élisée Reclus:** Conceptualization, -Software, Formal Analysis, Data curation, Writing - original draft, -Writing - review & editing +**Friedrich Ratzel:** Software, Validation, Data curation, Writing - +original draft, Writing - review & editing, Visualization, Funding +acquisition **Pau Vidal de la Blache:** Software, Validation, +Visualization, Funding acquisition **Élisée Reclus:** Formal Analysis, +Resources, Writing - original draft, Supervision, Project +administration, Funding acquisition diff --git a/docs/articles/get_started.html b/docs/articles/get_started.html index 5c29539..28583ca 100644 --- a/docs/articles/get_started.html +++ b/docs/articles/get_started.html @@ -94,7 +94,7 @@

Installationremotes::install_github("jospueyo/CRediTas")
-

Example +

Create a template

The workflow is meant to work with three basic functions. First, we create a template table. It can be created as a data.frame @@ -209,9 +209,13 @@

Example 
 
-template_create(authors = c("Danaerys Targaryen", "John Snow"),
-                roles = c("Free slaves", "Kill white walkers", "Ride dragons")) |> 
-                  knitr::kable()
+cras_got <- template_create(authors = c("Danaerys Targaryen", "Kingslayer", "John Snow"), + roles = c("Free slaves", "Kill white walkers", "Ride dragons")) + +# add contribution roles +cras_got[-2, -1] <- 1 + +knitr::kable(cras_got)

@@ -222,23 +226,37 @@

Example

- - - + + + - + + + + + + +
Authors
Danaerys Targaryen000111
John SnowKingslayer 0 0 0
John Snow111
+ +
+

Read a template +

If you wrote the template to a file, then you can read it back to R as follows:

 
 cras_table <- template_read(path_to_your_csv_file)
+
+
+

Generate the CRediT author statement +

Once the cras_table is populated, for instance:

@@ -278,9 +296,12 @@

Example

+ + + @@ -288,39 +309,36 @@

Example1

- - - - + - - + + - + + - @@ -337,16 +355,31 @@

Example cras_write(cras_table, textfile, markdown = TRUE)

If you open the text file, you will find this:

-

Friedrich Ratzel: Conceptualization, Methodology, -Formal Analysis, Resources, Data curation Pau Vidal de la -Blache: Methodology, Software, Validation, Resources, Data -curation, Writing - original draft, Writing - review & editing, -Supervision, Funding acquisition Élisée Reclus: -Methodology, Writing - original draft

+

Friedrich Ratzel: Methodology, Software, Validation, +Investigation, Data curation, Writing - review & editing, +Visualization, Funding acquisition Pau Vidal de la +Blache: Methodology, Software, Formal Analysis, Investigation, +Writing - original draft, Writing - review & editing, Project +administration Élisée Reclus: Methodology, Software

Moreover, if you are writing your paper in RMarkdown or quarto, you can insert the CRediT author statement directly in the text using an inline chunk `r cras_write(cras_table, file = NULL, markdown = TRUE)`.

+
+

Do not drop authors without contributions +

+

In some cases, one or several authors did not contribute to any +specific role. The drop arguments determines if they must +be removed from the statement. If drop = TRUE (default), +the authors are removed. Otherwise, they are kept without contributions +as below.

+
+
+cras_write(cras_got, drop = FALSE, markdown = TRUE)
+

Danaerys Targaryen: Free slaves, Kill white walkers, +Ride dragons Kingslayer John Snow: +Free slaves, Kill white walkers, Ride dragons

+

Friedrich Ratzel01 1 1 01 0 1 00 000001
Pau Vidal de la Blache 0 1 110 0 1 100 1 1 01 0 10
Élisée Reclus 0 11 0 0 0 0 0 01 0 0 0
@@ -117,12 +120,12 @@

ExampleMethodology

- + - - + + @@ -164,6 +167,23 @@

Example0

+ + + + + + + + + + + + + + + + + @@ -210,12 +230,12 @@

ExampleMethodology

- + - - + + @@ -224,64 +244,81 @@

Example

- - + + + + + - - - - - + - + + - - + + + + + + + + + + + + + + + + + + +
Software ValidationFormal analysisFormal Analysis Investigation Resources Data curationWriting - Original DraftWriting - Review & EditingWriting - original draftWriting - review & editing Visualization Supervision Project administration
Pau Vila00000000000000
Élisée Reclus 0 0Software ValidationFormal analysisFormal Analysis Investigation Resources Data curationWriting - Original DraftWriting - Review & EditingWriting - original draftWriting - review & editing Visualization Supervision Project administration
Friedrich Ratzel1100000 0 1 1 01 0 10 1 1 10
Pau Vidal de la Blache 001 10 1 0 0 01 0 010 0 0 1
Élisée Reclus1Pau Vila00000 0 0 0 0 0 0000
Élisée Reclus0 1 0 1 1 0 01001 011
-

A text file can be generated following the CRediT author statement format.

+

A text file can be generated following the CRediT author statement format. Since drop = TRUE by default, the authors without contribution are removed from the statement, Pau Vila in this case.

 textfile <- tempfile()
 
-cras_write(cras_table, textfile, markdown = TRUE)
+cras_write(cras_table, textfile, markdown = TRUE, quiet = TRUE)

If you open the text file, you will find this:

-

Friedrich Ratzel: Conceptualization, Methodology, Validation, Formal analysis, Resources, Writing - Original Draft, Visualization, Supervision, Project administration Pau Vidal de la Blache: Software, Validation, Formal analysis, Writing - Original Draft, Funding acquisition Élisée Reclus: Conceptualization, Data curation, Writing - Review & Editing, Visualization

+

Friedrich Ratzel: Resources, Data curation, Visualization, Supervision, Project administration, Funding acquisition Pau Vidal de la Blache: Methodology, Validation, Writing - review & editing, Funding acquisition Élisée Reclus: Methodology, Validation, Formal Analysis, Data curation, Visualization, Project administration, Funding acquisition