How to use the volkeR package?

First, load the package, set the plot theme and get some data.

# Load the package
library(volker)

# Set the basic plot theme
theme_set(theme_vlkr())

# Load an example dataset ds from the package
ds <- volker::chatgpt

How to generate tables and plots?

Decide whether your data is categorical or metric and choose the appropriate function:

• tab_counts() shows frequency tables.
• plot_counts() generates simple and stacked bar charts.
• effect_counts() calculates test statistics for categorical data.
  
  
• tab_metrics() creates tables with distribution parameters.
• plot_metrics() visualises distributions in density plots, box plots or scatter plots.
• effect_metrics() calculates test statistics for metric data.

The column selection determines whether to analyse single variables, item lists or to compare and correlate multiple variables. Try it out!

# A single variable
tab_counts(ds, use_private)

# A list of variables
tab_counts(ds, c(use_private, use_work))

# Variables matched by a pattern
tab_counts(ds, starts_with("use_"))

# One metric variable
tab_metrics(ds, sd_age)

# Multiple metric items
tab_metrics(ds, starts_with("cg_adoption_"))

tab_counts(ds, adopter, sd_gender)

# Compare the means of one grouping variable  (including the confidence interval)
tab_metrics(ds, sd_age, sd_gender, ci = TRUE)

# Correlate two metric variables
tab_metrics(ds, sd_age, use_work, metric = TRUE, ci = TRUE)

ds |> 
  filter(sd_gender != "diverse") |> 
  plot_counts(adopter, sd_gender, prop="rows", numbers=c("p","n"))

ds |> 
  filter(sd_gender != "diverse") |> 
  effect_counts(adopter, sd_gender)

Automatically generate reports

---
title: "How to create reports?"
output: 
  volker::html_report
---

ds %>% 
  filter(sd_gender != "diverse") %>% 
  report_metrics(starts_with("cg_adoption_"), sd_gender, index=TRUE, box=TRUE, ci=TRUE)

#> ### Adoption types
#> 
#> ```{r echo=FALSE}
#> ds %>% 
#>   filter(sd_gender != "diverse") %>% 
#>   report_counts(adopter, sd_gender, prop="rows", title=FALSE, close=FALSE, box=TRUE, ci=TRUE)
#> ```
#>
#> ##### Method
#> Basis: Only male and female respondents.
#> 
#> #### {-}

Theming

Plot and table functions share a number of parameters that can be used to customize the outputs. Lookup the available parameters in the help of the specific function.

The theme_vlkr()-function lets you customise colors:

theme_set(theme_vlkr(
  base_fill = c("#F0983A","#3ABEF0","#95EF39","#E35FF5","#7A9B59"),
  base_gradient = c("#FAE2C4","#F0983A")
))

Custom labels

Labels used in plots and tables are stored in the comment attribute of the variable. You can inspect all labels using the codebook()-function:

codebook(ds)
#> # A tibble: 94 × 6
#>    item_name     item_group item_class item_label         value_name value_label
#>    <chr>         <chr>      <chr>      <chr>              <chr>      <chr>      
#>  1 case          case       numeric    case               <NA>       <NA>       
#>  2 sd_age        sd         numeric    Age                <NA>       <NA>       
#>  3 cg_activities cg         character  Activities with C… <NA>       <NA>       
#>  4 adopter       adopter    factor     Innovator type     I try new… I try new …
#>  5 adopter       adopter    factor     Innovator type     I try new… I try new …
#>  6 adopter       adopter    factor     Innovator type     I wait un… I wait unt…
#>  7 adopter       adopter    factor     Innovator type     I only us… I only use…
#>  8 adopter       adopter    factor     Innovator type     [no answe… [no answer]
#>  9 sd_gender     sd         factor     Gender             female     female     
#> 10 sd_gender     sd         factor     Gender             male       male       
#> # ℹ 84 more rows

You can set specific column labels by providing a named list to the items-parameter of labs_apply():

ds %>%
  labs_apply(
    items = list(
      "cg_adoption_advantage_01" = "Allgemeine Vorteile",
      "cg_adoption_advantage_02" = "Finanzielle Vorteile",
      "cg_adoption_advantage_03" = "Vorteile bei der Arbeit",
      "cg_adoption_advantage_04" = "Macht mehr Spaß"
    )
  ) %>% 
  tab_metrics(starts_with("cg_adoption_advantage_"))

2 missing case(s) omitted.

Labels for values inside a column can be adjusted by providing a named list to the values-parameter of labs_apply(). In addition, select the columns where value labels should be changed:

ds %>%
  labs_apply(
    cols=starts_with("cg_adoption"),  
    values = list(
      "1" = "Stimme überhaupt nicht zu",
      "2" = "Stimme nicht zu",
      "3" = "Unentschieden",
      "4" = "Stimme zu",
      "5" =  "Stimme voll und ganz zu"
    ) 
  ) %>% 
  plot_metrics(starts_with("cg_adoption"))

To conveniently manage all labels of a dataset, save the result of codebook() to an Excel file, change the labels manually in a copy of the Excel file, and finally call labs_apply() with your revised codebook.

library(readxl)
library(writexl)

# Save codebook to a file
codes <- codebook(ds)
write_xlsx(codes,"codebook.xlsx")

# Load and apply a codebook from a file
codes <- read_xlsx("codebook_revised.xlsx")
ds <- labs_apply(ds, codebook)

Be aware that some data operations such as mutate() from the tidyverse loose labels on their way. In this case, store the labels (in the codebook attribute of the data frame) before the operation and restore them afterwards:

ds %>%
  labs_store() %>%
  mutate(sd_age = 2024 - sd_age) %>% 
  labs_restore() %>% 
  
  tab_metrics(sd_age)

Index calculation for item batteries

You can calculate mean indexes from a bunch of items using idx_add(). A new column is created with the average value of all selected columns for each case.

Reliability and number of items are calculated with psych::alpha() and stored as column attribute named “psych.alpha”. The reliability values are printed by tab_metrics().

Add a single index

ds %>%
  idx_add(starts_with("cg_adoption_")) %>%
  tab_metrics(idx_cg_adoption)

4 missing case(s) omitted.

Compare the index values by group

ds %>%
  idx_add(starts_with("cg_adoption_")) %>%
  tab_metrics(idx_cg_adoption, adopter)

4 missing case(s) omitted.

Add multiple indizes and summarize them

ds %>%
  idx_add(starts_with("cg_adoption_")) %>%
  idx_add(starts_with("cg_adoption_advantage")) %>%
  idx_add(starts_with("cg_adoption_fearofuse")) %>%
  idx_add(starts_with("cg_adoption_social")) %>%
  tab_metrics(starts_with("idx_cg_adoption"))

4 missing case(s) omitted.

What’s behind the scenes?

The volker-package is based on standard methods for data handling and visualisation. You can produce all outputs with a handful of functions. The package just makes your code dry - don’t repeat yourself - and wraps often used snippets into a simple interface.

Basically, all table values are calculated two tidyverse functions:

• count() is used to produce counts
  
• skim() is used to produce metrics

To shape the data frames, two essential functions come into play:

• group_by() is used to calculate grouped outputs
• pivot_longer() brings multiple items into a format where the item name becomes a grouping variable.

Plots are generated by ggplot().

The package provides print- and knit-functions that pimp console and markdown output. To make this work, the cleaned data, produced plots, tables and markdown snippets gain new classes (vlkr_df, vlkr_plt, vlkr_tbl, vlkr_list, vlkr_rprt).