---
title: "Utility functions"
output: rmarkdown::html_vignette
vignette: >

  %\VignetteIndexEntry{05_utility_functions}

  %\VignetteIndexEntry{utilityFunctions}

  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

options(rmarkdown.html_vignette.check_title = FALSE)
```

In this vignette we will present the **column retrieval** and **unite** functionalities which provide useful tools to work with *visOmopResults* functions and managing `<summarised_result>` objects.

# Column retrieval functions

Column retrieval functions are designed to simplify the extraction of specific columns or variables within name-level columns from `<summarised_result>` objects. In this section, we will review the different column functions and provide a use-case example.

### Variables in name-level columns

The following functions are useful for identifying variables stored in name-level pairs:

- `groupColumns()`

- `strataColumns()`

- `additionalColumns()`

For example, let's see which strata are included in a mock `<summarised_result>`:

```{r}
# Set-up
library(visOmopResults)
library(dplyr)

# Create a mock summarized result
result <- mockSummarisedResult()
head(result)

# Get strata columns
strataColumns(result)
```

This function returns the strata columns that would be generated if `result` were split by strata.

### Settings

The settingsColumns() function returns which settings are linked to a `<summarised_result>`:

```{r}
# Display settings tibble
settings(result)

# Get which settings are present using `settingsColumns()`
settingsColumns(result)
```

### Tidy columns

The `tidyColumns()` function provides the columns that the <summarised_result> will have in its tidy format:
```{r}
# Show tidy result:
tidy(result) |> head()

# Get the tidy columns with `tidyColumns()`
tidyColumns(result)
```
### Use-case

These functionalities can be used in table and plot functions. For instance, let’s plot the number of subjects in each cohort and strata from our mock result. 

We’ll first filter the result to focus on the variable of interest, and then use `barPlot()` (see vignette on plots for more information on how to use plotting functions).

```{r}
result <- result |>
  filter(variable_name == "number subjects")

barPlot(
  result = result, 
  x = groupColumns(result), 
  y = "count", 
  facet = strataColumns(result), 
  colour = groupColumns(result)
)
```



# Unite functions

The unite functions serve as the complementary tools to the split functions (see vignette on tidying `<summarised_result>`), allowing you to generate name-level pair columns from targeted columns within a `<dataframe>`.

There are three `unite` functions that allow to create group, strata, and additional name-level columns from specified sets of columns:

- `uniteAdditional()`

- `uniteGroup()`

- `uniteStrata()`

For example, to create group_name and group_level columns from a tibble, you can use:

```{r}
# Create and show mock data
data <- tibble(
  denominator_cohort_name = c("general_population", "older_than_60", "younger_than_60"),
  outcome_cohort_name = c("stroke", "stroke", "stroke")
)
head(data)

# Unite into group name-level columns
data |>
  uniteGroup(cols = c("denominator_cohort_name", "outcome_cohort_name"))
```

This functions can be helpful when creating your own `<summarised_result>`.