close #6 Functions

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.

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

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

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

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

README.md

@@ -44,14 +44,18 @@ 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)
 ```
 
 | 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 |          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