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