---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{get_started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# CRediTas
The goal of CRediTas is to facilitate the tedious job of creating [CRediT authors statements](https://credit.niso.org/) for scientific publications.
## Installation
You can install the development version of CRediTas from [r-universe](https://r-universe.dev/) with:
``` r
install.packages("CRediTas", repos = "https://ropensci.r-universe.dev")
```
Or you can install de long term release version from [CRAN](https://cran.r-project.org/web/packages/CRediTas/index.html) as usual:
``` r
install.packages("CRediTas")
```
## 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` and being populated in R.
```{r create_template}
library(CRediTas)
cras_table <- template_create(authors = c("Friedrich Ratzel",
"Pau Vidal de la Blache",
"Élisée Reclus"))
knitr::kable(cras_table)
```
As you can see, the table is empty. So you must provide the information of who did what. To do this, you can use the `fix` function to edit directly in R:
```{r fix, eval=FALSE}
fix(cras_table)
```
Alternatively, you can write the template as a csv file and then populate it in your preferred csv editor.
```{r write_csv, eval=FALSE}
template_create(authors = c("Friedrich Ratzel",
"Pau Vidal de la Blache",
"Élisée Reclus"),
file = path_to_your_csv_file)
```
Additionally, you can also define the roles to be included in the template. If `roles` is no specified, the roles recommended by the CRediT system are all included:
```{r define_roles}
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)
```
## Read a template
If you wrote the template to a file, then you can read it back to R as follows:
```{r template_read, eval=FALSE}
cras_table <- template_read(path_to_your_csv_file)
```
## Generate the CRediT author statement
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))
knitr::kable(cras_table)
```
A text file can be generated following the CRediT author statement format.
```{r}
textfile <- tempfile()
cras_write(cras_table, textfile, markdown = TRUE)
```
If you open the text file, you will find this:
`r readLines(textfile)`
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, 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.
```{r, eval = FALSE}
cras_write(cras_got, drop = FALSE, markdown = TRUE)
```
`r cras_write(cras_got, drop = FALSE, markdown = TRUE)`