---
title: "Categorical variables"
description: > 
  Learn the workflow for loading and analysing data collected during the
  elicitation of categorical variables.
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Categorical variables}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set( #nolint
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(elicitr)
```

Many of the concepts introduced in `vignette("continuous_variables")` are also applicable to categorical variables, and the name of the functions are the same but have the prefix `cat` instead of `cont`. However, there are some differences in the workflow for loading and analysing data collected during the elicitation of categorical variables. This vignette will guide you through the process of loading and analysing categorical data.

## Datasets

There are three datasets included in the package for demonstration purposes: `?topic_1`, `?topic_2`,  and `?topic_3`:

```{r topic1}
topic_1
```

```{r topic2}
topic_2
```

```{r topic3}
topic_3
```

In each dataset the first column contains the name of the expert, the second the options considered and the third the categories of the categorical variable. The fourth column contains the expert's confidence, and the fifth the expert's estimate. Expert estimates for each option should represent probabilities or percentages, and should thus sum up to 1 or 100. Both are accepted and data scaled to 1 will be automatically rescaled to 100.

## Load data

We start by creating the `?elic_cat` object with the function `cat_start()`. As for the continuous variables, this objects stores the metadata of the elicitation process:

```{r cat-start}
my_categories <- c("category_1", "category_2", "category_3",
                   "category_4", "category_5")
my_options <- c("option_1", "option_2", "option_3", "option_4")
my_topics <- c("topic_1", "topic_2", "topic_3")
my_elicitation <- cat_start(categories = my_categories,
                            options = my_options,
                            experts = 6,
                            topics = my_topics)
my_elicitation
```

This elicitation process is for a categorical variables with 5 categories estimated for four options and three topics by six experts.

As we did for continuous variables, we can load the data with the function `cat_add_data()`:

```{r cat-add-data}
my_elicitation <- cat_add_data(my_elicitation,
                               data_source = topic_1,
                               topic = "topic_1") |>
  cat_add_data(data_source = topic_2, topic = "topic_2") |>
  cat_add_data(data_source = topic_3, topic = "topic_3")
```

As mentioned before, estimates can also sum up to 100.

```{r cat-add-data-percent}
topic_1_percent <- dplyr::mutate(topic_1,
                                 estimate = estimate * 100)

my_elicitation <- cat_add_data(my_elicitation,
                               data_source = topic_1_percent,
                               topic = "topic_1")
```

Expert anonymisation is automatic but optional. If expert names are not to be anonymised, the argument `anonymise` can be set to `FALSE` in the `cat_add_data()` function.

```{r add-data-no-anon}
my_elicitation <- cat_add_data(my_elicitation,
                               data_source = topic_1,
                               topic = "topic_1",
                               anonymise = FALSE)
```

Again, metadata are used to validate the data. If the data is not consistent with the metadata, an error message will be displayed. For example, if we try to load data with a category not defined in the metadata:

```{r error, error=TRUE}
malformed_data <- topic_1
malformed_data[1, 3] <- "category_6"
cat_add_data(my_elicitation,
             data_source = malformed_data,
             topic = "topic_1")
```

## Get data

Data can be retrieved from the `elic_cat` object with the `cat_get_data()` function:

```{r get-data}
cat_get_data(my_elicitation, topic = "topic_1")
```

Notice that the name of the expert is not anonymised in this case and assigned to the column `id`. 

Data can also be retrieved only for given options:

```{r get-data-var1}
cat_get_data(my_elicitation, topic = "topic_2", option = "option_1")
```

Here, the data is anonymised, following what was specified when loading the data.

## Data analysis

Contrary to continuous variables, there is not yet a function for plotting the raw data. However, we can plot the distribution of the sampled data.

### Sample data

Data can be sampled using the function `cat_sample_data()` (see the variable documentation for the explanation of the sampling methods). Two sampling methods are available, which sample data from a Dirichlet distribution using the expert estimates as parameters. When only one estimate is provided, i.e. 100 % for one category, the method assigns 100 % to all votes for this category.

* The unweighted method: This method samples data based on the expert estimates without accounting for their confidence.

* The weighted method: This method samples data based on the expert estimates accounting for their confidence. The confidence is used to weight the number of votes assigned to each expert. 

Here we sample 100 values for each expert in each option (all options in topic_1 are sampled).
Each expert are basically given 100 votes.

```{r sample unweighted}
samp <- cat_sample_data(my_elicitation,
                        method = "unweighted",
                        topic = "topic_1",
                        n_votes = 100)
samp
```

Here we sample 100 values for each expert in each option (all options in topic_1 are sampled).
Each expert gets a portion of the total number of vote based on their self-expressed confidence level.

```{r sample weighted}
samp <- cat_sample_data(my_elicitation,
                        method = "unweighted",
                        topic = "topic_1",
                        n_votes = 100)
samp
```

Data can be sampled using the function `cat_sample_data()` (see the variable documentation for the explanation of the sampling methods). Here we sample 100 values for each expert in each option:

```{r sample}
samp <- cat_sample_data(my_elicitation,
                        method = "unweighted",
                        topic = "topic_1",
                        n_votes = 100)
samp
```

Sampled data can be summarised for any option:

```{r sample-summary}
summary(samp, option = "option_1")
```

And plotted as violin plot:

```{r plot-all}
#| fig.alt: >
#|   Violin plot of the sampled data for all options.
plot(samp)
```

Or as beeswarm plot, which can be adapted as needed:

```{r cat-plot-beeswarm}
#| fig.alt: >
#|  Beeswarm plot of the sampled data for all options.
#|  Each point represents a sampled value.
plot(samp, type = "beeswarm")
```

```{r cat-plot-beeswarm-wrap}
#| fig.alt: >
#|  Beeswarm plot of the sampled data for all options.
#|  Each point represents a sampled value.
plot(samp, type = "beeswarm",
     beeswarm_cex = 0.9, beeswarm_corral = "wrap")
```

We can also plot the distribution for a specific option:

```{r plot-option2}
#| fig.alt: >
#|  Violin plot of the sampled data for option 2.
plot(samp, option = "option_2")
```