qol - Quality of Life

Description

This package brings some quality of life concepts and functions inspired by 'SAS' to 'R'. The main goal is to make descriptive evaluations easier, so one can create bigger and more complex outputs in less time with less code. Introducing format containers with multilabels, a more powerful summarise, which is capable to output every possible combination of the provided grouping variables in one go, tabulation functions which can create any table in different styles and other more readable functions.

In addition it offers an error handling which often catches errors and just let's your code flow, even if there are small errors. You always get an understandable message which helps you to get rid of the problem.

The package builds on the incredibly fast data.table and collapse packages for maximum speed and on the wonderful openxlsx2 package for maximum style.

Imports

data.table, collapse, openxlsx2

Minimal R Version

4.1.0 or higher

Functions

Creating formats: discrete_format(), interval_format()

Summarisation and tabulation: summarise_plus(), frequencies(), crosstabs(), any_table(), export_with_style(), combine_into_workbook()

Creating a custom table style: excel_output_style(), modify_output_style(), number_format_style(), modify_number_formats()

Recoding: recode(), recode_multi()

Selecting: keep(), dropp(), inverse(), vars_between()

Joining: multi_join()

Transposing: transpose_plus()

Sorting: sort_plus()

If-statement: if.(), else_if.(), else.()

Monitoring: monitor_start(), monitor_end(), monitor_next(), monitor_plot()

Renaming: rename_pattern(), add_extension(), remove_stat_extension(), replace_except()

Retaining: running_number(), mark_case(), retain_value(), retain_sum(), retain_variables()

Generate dummy data: dummy_data()

Conversion: args_to_char(), dots_to_char(), get_origin_as_char() convert_numeric(), convert_factor()

Loading: libname(), set()

Reporting: content_report()

Small helpers: setcolorder_by_pattern(), drop_type_vars(), fuse_variables(), get_excel_range(), get_integer_length()

Split data frame: split_by

Error handling: resolve_intersection(), part_of_df(), remove_doubled_values(), check_weight()

Global options: set_style_options(), reset_style_options(), get_style_options(), close_file(), set_variable_labels(), get_variable_labels(), set_stat_labels(), get_stat_labels(), set_print(), get_print(), set_monitor(), get_monitor(), set_na.rm(), get_na.rm(), set_output(), get_output(), set_titles(), get_titles(), set_footnotes(), get_footnotes()

Other: build_master(), build_rstheme()

Snippets

snippet splus
    summarise_plus(class      = c(var1, var2, ...),
                   values     = c(var1, var2, ...),
                   statistics = c("pct_group", "sum", "sum_wgt", "freq"),
                   weight     = weight_var,
                   formats    = list(var = format., ...),
                   nesting    = "deepest")

snippet if.
         if.(condition, var = value) |>
    else_if.(condition, var = value) |>
    else.   (           var = value)

snippet freq
    frequencies(variables = c(var1, var2, ...),
                weight    = weight_var,
                formats   = list(var = "format.", ...),
                titles    = c(),
                footnotes = c())

snippet cross
    crosstabs(rows       = row_var,
              columns    = col_var,
              statistics = c("sum", "pct_row", "pct_column", "pct_total", "freq"),
              weight    = weight_var,
              formats   = list(var = format., ...),
              titles    = c(),
              footnotes = c())

snippet any
    any_table(rows        = c("var1 + var2 + ...", "var1"),
              columns     = c("var3", "var3 + var4 + ..."),
              values      = c("value_var1", "value_var2"),
              statistics  = c("sum", "pct_group", "pct_value", "freq"),
              pct_group   = c("var1", "var2"),
              pct_value   = list(new_var = "numerator / denominator"),
              weight    = weight_var,
              formats     = list(var = format., ...),
              titles      = c(),
              footnotes   = c(),
              var_labels  = list("var1" = "My label", ...),
              stat_labels = list("pct" = "
              box         = "")

Author(s)

Tim Siebenmorgen

See Also

Useful links:

• https://github.com/s3rdia/qol

• https://s3rdia.github.io/qol/

Add Extensions to Variable Names

Description

Renames variables in a data frame by adding the desired extensions to the original names. This can be useful if you want to use pre summarised data with any_table(), which needs the value variables to have the statistic extensions.

Usage

add_extension(data_frame, from, extensions, reuse = "none")

Arguments

Value

Returns a data frame with extended variable names.

Examples

# Example data frame
my_data <- dummy_data(10)

# Add extensions to variable names
new_names1 <- my_data |> add_extension(5, c("sum", "pct"))
new_names2 <- my_data |> add_extension(5, c("sum", "pct"), reuse = "last")
new_names3 <- my_data |> add_extension(5, c("sum", "pct"), reuse = "alternate")

Add Empty Variables In A Given Range

Description

Add empty variables to a data frame in the provided range. Basically does in a data frame, what paste0("age", 1:10) does for a vector.

Usage

add_variable_range(data_frame, var_range)

Arguments

Value

Returns a data frame with added variables.

Examples

# Example data frames
my_data <- dummy_data(100)

# Add variable range
my_data <- my_data |> add_variable_range(status1:status12)

Compute Any Possible Table

Description

any_table() produces any possible descriptive table in 'Excel' format. Any number of variables can be nested and crossed. The output is an individually styled 'Excel' table, which also receives named ranges, making it easier to read the data back in.

Usage

any_table(
  data_frame,
  rows,
  columns = "",
  values,
  statistics = c("sum"),
  pct_group = c(),
  pct_value = list(),
  formats = list(),
  by = c(),
  weight = NULL,
  order_by = "stats",
  titles = .qol_options[["titles"]],
  footnotes = .qol_options[["footnotes"]],
  var_labels = .qol_options[["var_labels"]],
  stat_labels = .qol_options[["stat_labels"]],
  box = "",
  workbook = NULL,
  style = .qol_options[["excel_style"]],
  output = .qol_options[["output"]],
  na.rm = .qol_options[["na.rm"]],
  print = .qol_options[["print"]],
  monitor = .qol_options[["monitor"]]
)

Arguments

Details

any_table() is based on the 'SAS' procedure Proc Tabulate, which provides efficient and readable ways to perform complex tabulations.

With this function you can combine any number of variables in any possible way, all at once. You just define which variables or variable combinations should end up in the table rows and columns with a simple syntax. Listing variables in a vector like c("var1", "var2", "var3",...) means to put variables below (in case of the row variables) or besides (in case of the column variables) each other. Nesting variables is as easy as putting a plus sign between them, e.g. c("var1 + var2", "var2" + "var3" + "var4", etc.). And of course you can combine both versions.

The real highlight is, that this function not only creates all the desired variable combinations and exports them to an 'Excel' file, it prints a fully custom styled table to a workbook. Setting up a custom, reusable style is as easy as setting up options like: provide a color for the table header, set the font size for the row header, should borders be drawn for the table cells yes/no, and so on. Merging doubled header texts, happens automatically.

With this function you basically can fully concentrate on designing a table, instead of thinking hard about how to calculate where to put a border or to even manually prepare a designed workbook.

Value

Returns a list with the data table containing the results for the table, the formatted 'Excel' workbook and the meta information needed for styling the final table.

See Also

Creating a custom table style: excel_output_style(), modify_output_style(), number_format_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Creating formats: discrete_format() and interval_format().

Functions that can handle formats and styles: frequencies(), crosstabs().

Additional functions that can handle styles: export_with_style()

Additional functions that can handle formats: summarise_plus(), recode(), recode_multi(), transpose_plus(), sort_plus()

Examples

# Example data frame
my_data <- dummy_data(1000)
my_data[["person"]] <- 1

# Formats
age. <- discrete_format(
    "Total"          = 0:100,
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:64,
    "65 and older"   = 65:100)

sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

education. <- discrete_format(
    "Total"            = c("low", "middle", "high"),
    "low education"    = "low",
    "middle education" = "middle",
    "high education"   = "high")

state. <- discrete_format(
    "Germany"                       = 1:16,
    "Schleswig-Holstein"            = 1,
    "Hamburg"                       = 2,
    "Lower Saxony"                  = 3,
    "Bremen"                        = 4,
    "North Rhine-Westphalia"        = 5,
    "Hesse"                         = 6,
    "Rhineland-Palatinate"          = 7,
    "Baden-Württemberg"             = 8,
    "Bavaria"                       = 9,
    "Saarland"                      = 10,
    "West"                          = 1:10,
    "Berlin"                        = 11,
    "Brandenburg"                   = 12,
    "Mecklenburg-Western Pomerania" = 13,
    "Saxony"                        = 14,
    "Saxony-Anhalt"                 = 15,
    "Thuringia"                     = 16,
    "East"                          = 11:16)

# Define style
set_style_options(column_widths = c(2, 15, 15, 15, 9))

# Define titles and footnotes. If you want to add hyperlinks you can do so by
# adding "link:" followed by the hyperlink to the main text.
set_titles("This is title number 1 link: https://cran.r-project.org/",
           "This is title number 2",
           "This is title number 3")

set_footnotes("This is footnote number 1",
              "This is footnote number 2",
              "This is footnote number 3 link: https://cran.r-project.org/")

# Output complex tables with different percentages
my_data |> any_table(rows       = c("sex + age", "sex", "age"),
                     columns    = c("year", "education + year"),
                     values     = weight,
                     statistics = c("sum", "pct_group"),
                     pct_group  = c("sex", "age", "education", "year"),
                     formats    = list(sex = sex., age = age.,
                                       education = education.),
                     na.rm      = TRUE)

# If you want to get a clearer vision of what the result table looks like, in terms
# of the row and column categories, you can write the code like this, to make out
# the variable crossings and see the order.
my_data |> any_table(columns = c(            "year", "education + year"),
                     rows    = c("sex + age",
                                 "sex",
                                 "age"),
                     values     = weight,
                     statistics = c("sum", "pct_group"),
                     pct_group  = c("sex", "age", "education", "year"),
                     formats    = list(sex = sex., age = age.,
                                       education = education.),
                     na.rm      = TRUE)

# Percentages based on value variables instead of categories
my_data |> any_table(rows       = c("age + year"),
                     columns    = c("sex"),
                     values     = c(probability, person),
                     statistics = c("pct_value", "sum", "freq"),
                     pct_value  = list(rate = "probability / person"),
                     weight     = weight,
                     formats    = list(sex = sex., age = age.),
                     na.rm      = TRUE)

# Customize the visual appearance by adding variable and statistic labels. Both
# can also be set as a global option, if labels should be reused over multiple
# tables.
# Note: You don't have to describe every element. Sometimes a table can be more
# readable with less text. To completely remove a variable label just put in an
# empty text "" as label.
my_data |> any_table(rows        = c("age + year"),
                     columns     = c("sex"),
                     values      = weight,
                     statistics  = c("sum", "pct_group"),
                     order_by    = "interleaved",
                     formats     = list(sex = sex., age = age.),
                     var_labels  = list(age = "Age categories",
                                        sex = "", weight = ""),
                     stat_labels = list(pct = "%"),
                     na.rm       = TRUE)

# Individual styling can also be passed directly
my_style <- excel_output_style(header_back_color = "0077B6",
                               font              = "Times New Roman")

my_data |> any_table(rows       = c("age + year"),
                     columns    = c("sex"),
                     values     = c(probability, person),
                     statistics = c("pct_value", "sum", "freq"),
                     pct_value  = list(rate = "probability / person"),
                     weight     = weight,
                     formats    = list(sex = sex., age = age.),
                     style      = my_style,
                     na.rm      = TRUE)

# Pass on workbook to create more sheets in the same file
my_style <- my_style |> modify_output_style(sheet_name = "age_sex")

result_list <- my_data |>
           any_table(rows       = c("age"),
                     columns    = c("sex"),
                     values     = weight,
                     statistics = c("sum"),
                     formats    = list(sex = sex., age = age.),
                     na.rm      = TRUE,
                     print      = FALSE)

my_style <- my_style |> modify_output_style(sheet_name = "edu_year")

my_data |> any_table(workbook   = result_list[["workbook"]],
                     rows       = c("education"),
                     columns    = c("year"),
                     values     = weight,
                     statistics = c("pct_group"),
                     formats    = list(education = education.),
                     na.rm      = TRUE)

# Output multiple complex tables by expressions of another variable.
# If you specify the sheet name as "by" in the output style, the sheet
# names are named by the variable expressions of the by-variable. Otherwise
# the given sheet named gets a running number.
my_style <- my_style |> modify_output_style(sheet_name = "by")

my_data |> any_table(rows       = c("sex", "age"),
                     columns    = c("education + year"),
                     values     = weight,
                     by         = state,
                     statistics = c("sum", "pct_group"),
                     pct_group  = c("education"),
                     formats    = list(sex = sex., age = age., state = state.,
                                       education = education.),
                     na.rm      = TRUE)

# To save a table as xlsx file you have to set the path and filename in the
# style element
# Example files paths
table_file <- tempfile(fileext = ".xlsx")

# Note: Normally you would directly input the path ("C:/MyPath/") and name ("MyFile.xlsx").
set_style_options(save_path  = dirname(table_file),
                  file       = basename(table_file),
                  sheet_name = "MyTable")

my_data |> any_table(rows       = "sex",
                     columns    = "year",
                     values     = weight,
                     formats    = list(sex = sex.))

# Manual cleanup for example
unlink(table_file)

# Global options are permanently active until the current R session is closed.
# There are also functions to reset the values manually.
reset_style_options()
reset_qol_options()
close_file()

Build a Master Script From Folder

Description

build_master() reads a given folder structure, which contains scripts, and builds a master script as a markdown file.

Usage

build_master(
  dir,
  master_name = "Master",
  author = "",
  with_structure = TRUE,
  with_run_all = TRUE,
  with_run_folder = TRUE
)

Arguments

Details

The function works with folder structures that look like this:

root/

 subfolder1/

     script1.R

     script2.R

     ....R

 subfolder2/

     script3.R

     script4.R

     ....R

 .../

     ....R

Value

Returns the script as character vector and saves it as markdown file.

Examples

# Example export file paths
# NOTE: These tempfiles are only for the examples. In reality you just call the
# main function and put in your desired path and name directly.
temp_file <- tempfile(fileext = ".rstheme")
file_name <- basename(tools::file_path_sans_ext(temp_file))

# Example master
build_master(dir         = dirname(temp_file),
             master_name = file_name)

# Manual cleanup for example
unlink(temp_file)

Build a Theme From Scratch

Description

Build your own theme by just setting up the colors for the different parts of RStudio. A theme file will be exported which can be added by going to:

Tools -> Global Options -> Appearance -> Add

Usage

build_rstheme(
  file_path,
  theme_name = "qol_green",
  dark_theme = TRUE,
  editor_background = "#062625",
  editor_headline = "#3B3B3B",
  editor_font = "#C3B79D",
  toolbar = "#2E2E2E",
  tab = "#3B3B3B",
  selected_tab = "#062625",
  line_number = "#C3B79D",
  print_margin = "#3B3B3B",
  cursor = "#CCCCCC",
  selection = "#1B436E",
  smart_highlight = "#3686dc",
  bracket_highlight = "#595959",
  active_line = "#202324",
  whitespace = "#CCCCCC",
  debug_line = "#F18889",
  scrollbar = "#3B3B3B",
  scrollbar_hover = "#595959",
  scrollbar_active = "#BFBFBF",
  class_name = "#BEDD1A",
  keyword = "#FFC90E",
  language_constant = "#FFC90E",
  function_name = "#C3B79D",
  numeric = "#C93F3F",
  string = "#63C2C9",
  regex = "#E8E6E3",
  variable = "#E8E6E3",
  comment = "#32CD32",
  symbol = "#C3B79D",
  console_code = "#C3B79D",
  markdown_code = "#083332"
)

Arguments

Details

In the 'SAS Enterprise Guide' the user is able to not only choose a given theme, but to also pick the colors for the different parts of the editor by themselves. Everyone has a different taste of what colors look pleasing to the eyes, so you should be able to choose them by yourself.

Value

Saves a complete theme file.

Examples

# Example export file paths
# NOTE: These tempfiles are only for the examples. In reality you just call the
# main function and put in your desired path and name directly.
temp_file <- tempfile(fileext = ".rstheme")
file_name <- basename(tools::file_path_sans_ext(temp_file))

# Example theme
build_rstheme(file_path         = dirname(temp_file),
              theme_name        = file_name,
              editor_background = "#417291",
              editor_headline   = "#602BCA",
              editor_font       = "#C75C48")

# Manual cleanup for example
unlink(temp_file)

Combine Multiple Tables Into One Workbook

Description

Combines any number of tables created with any_table() into one workbook and styles them according to their meta information.

Usage

combine_into_workbook(
  ...,
  file = NULL,
  output = "excel",
  print = TRUE,
  monitor = FALSE
)

Arguments

Value

A fully styled workbook containing the provided tables.

Examples

# Example data frame
my_data <- dummy_data(1000)
my_data[["person"]] <- 1

# Formats
age. <- discrete_format(
    "Total"          = 0:100,
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:64,
    "65 and older"   = 65:100)

sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

education. <- discrete_format(
    "Total"            = c("low", "middle", "high"),
    "low education"    = "low",
    "middle education" = "middle",
    "high education"   = "high")

# Define style
my_style <- excel_output_style(column_widths = c(2, 15, 15, 15, 9))

# Define titles and footnotes. If you want to add hyperlinks you can do so by
# adding "link:" followed by the hyperlink to the main text.
titles <- c("This is title number 1 link: https://cran.r-project.org/",
            "This is title number 2",
            "This is title number 3")
footnotes <- c("This is footnote number 1",
               "This is footnote number 2",
               "This is footnote number 3 link: https://cran.r-project.org/")

# Catch the output and additionally use the options:
# pint = FALSE and output = "excel_nostyle".
# This skips the styling and output part, so that the function runs faster.
# The styling is done later on.
my_style <- my_style |> modify_output_style(sheet_name = "big table")

tab1 <- my_data |> any_table(rows       = c("sex + age", "sex", "age"),
                             columns    = c("year", "education + year"),
                             values     = weight,
                             statistics = c("sum", "pct_group"),
                             pct_group  = c("sex", "age", "education", "year"),
                             formats    = list(sex = sex., age = age.,
                                               education = education.),
                             style      = my_style,
                             na.rm      = TRUE,
                             print      = FALSE,
                             output     = "excel_nostyle")

my_style <- my_style |> modify_output_style(sheet_name = "age_sex")

tab2 <- my_data |> any_table(rows       = c("age"),
                             columns    = c("sex"),
                             values     = weight,
                             statistics = c("sum"),
                             formats    = list(sex = sex., age = age.),
                             style      = my_style,
                             na.rm      = TRUE,
                             print      = FALSE,
                             output     = "excel_nostyle")

my_style <- my_style |> modify_output_style(sheet_name = "edu_year")

tab3 <- my_data |> any_table(rows       = c("education"),
                             columns    = c("year"),
                             values     = weight,
                             statistics = c("pct_group"),
                             formats    = list(education = education.),
                             style      = my_style,
                             na.rm      = TRUE,
                             print      = FALSE,
                             output     = "excel_nostyle")

# Every of the above tabs is a list, which contains the data table, an unstyled
# workbook and the meta information needed for the individual styling. These
# tabs can be input into the following function, which reads the meta information,
# styles each table individually and combines them as separate sheets into a single workbook.
combine_into_workbook(tab1, tab2, tab3)

Get Detailed Summary About A Data Frame

Description

Prints a summary of a data frames contents, including details such as variable names, types, unique values, missings and min/max values. It also tells you the number of observations and variables present in the data frame, memory usage and the number of duplicate observations.

Usage

content_report(data_frame, output = "console", monitor = FALSE)

Arguments

Details

content_report() is based on the 'SAS' procedure Proc Contents, which provides a summary of global information one one hand like number of observations and variables among many others and on the other hand shows per variable information like type and length.

'R' doesn't store the same information in a data frame like 'SAS', but there are many useful information to get a quick overview of a data frame. With this function you don't need to look at each variable individually. You can simply run it over a data frame and get values for: number of unique values, missing values (absolute and relative), min and max value as well as the top value.

Value

Returns a list containing the global information as well as a data table containing the per variable information.

Examples

# Example data frame
my_data <- dummy_data(100)

content_report(my_data)

Convert Function Arguments to Character Vector

Description

args_to_char(): Converts any argument passed as a single character or symbol as well as character vectors or vector of symbols back as character vector.

dots_to_char(): When you define a function and want the user to be able to pass variable names without the need to have them stored in a vector c() or list() beforehand and without putting the names into quotation marks, you can convert this variable list passed as ... into a character vector.

Note: If the user passes a list of characters it is returned as given.

get_origin_as_char() is a wrapper that allows to retrieve the original contents of the provided variable, whether called directly or nested in multiple function calls, as a character vector.

Usage

args_to_char(argument)

dots_to_char(...)

get_origin_as_char(original, substituted)

Arguments

Value

Returns a character vector.

Examples

# Example function with function parameter
print_vnames <- function(parameter){
    var_names <- args_to_char(substitute(parameter))
    print(var_names)
}

print_vnames(age)
print_vnames("age")
print_vnames(c(age, sex, income, weight))
print_vnames(c("age", "sex", "income", "weight"))

# You can also pass in a character vector, if you have stored variable names elsewhere
var_names <- c("age", "sex", "income", "weight")
print_vnames(var_names)

# If you plan to use the function within other functions, better use get_origin_as_char()
print_vnames <- function(parameter){
    var_names <- get_origin_as_char(parameter, substitute(parameter))
    print(var_names)
}

another_function <- function(parameter){
    print_vnames(parameter)
}

another_function("age")
another_function(c("age", "sex", "income", "weight"))

# Example function with ellipsis
print_vnames <- function(...){
    var_names <- dots_to_char(...)
    print(var_names)
}

print_vnames(age)
print_vnames("age")
print_vnames(age, sex, income, weight)
print_vnames("age", "sex", "income", "weight")

# You can also pass in a character vector, if you have stored variable names elsewhere
var_names <- c("age", "sex", "income", "weight")
print_vnames(var_names)

Convert Variables

Description

convert_numeric() converts all given variables to numeric if possible. If a variable contains none numerical values (not including NAs), the variable will not be converted.

convert_factor() converts all given variables to factor.

Usage

convert_numeric(data_frame, variables)

convert_factor(data_frame, variables)

Arguments

Value

convert_numeric() returns the same data frame with converted variables where possible.

convert_factor() returns the same data frame with converted variables.

Examples

# Convert variables in a data frame to numeric where possible
test_df <- data.frame(var_a = c(1, 2, 3, NA, 4, 5),
                      var_b = c(1, 2, "Hello", NA, 4, 5))

convert_df <- test_df |> convert_numeric(c("var_a", "var_b"))

# Convert variables in a data frame to factor
test_df <- data.frame(var_a = c(1, 2, 3, 4, 5),
                      var_b = c("e", "c", "a", "d", "b"))

convert_df <- test_df |> convert_factor("var_b")

Display Cross Table of Two Variables

Description

crosstabs() produces a cross table of two variables. Statistics can be weighted sums, unweighted frequencies or different percentages.

Usage

crosstabs(
  data_frame,
  rows,
  columns,
  show_total = TRUE,
  statistics = c("sum"),
  formats = c(),
  by = c(),
  weight = NULL,
  titles = .qol_options[["titles"]],
  footnotes = .qol_options[["footnotes"]],
  style = .qol_options[["excel_style"]],
  output = .qol_options[["output"]],
  na.rm = .qol_options[["na.rm"]],
  print = .qol_options[["print"]],
  monitor = .qol_options[["monitor"]]
)

Arguments

Details

crosstabs() is based on the 'SAS' procedure Proc Freq, which provides efficient and readable ways to perform cross tabulations.

To create a cross table you only need to provide a variable for the rows and columns. Nothing special about this. The real power comes into play, when you output your tables as a fully styled 'Excel' workbook. Setting up a custom, reusable style is as easy as setting up options like: provide a color for the table header, set the font size for the row header, should borders be drawn for the table cells yes/no, and so on.

You can not only output sums and frequencies, but also different percentages, all set up in separate, evenly designed tables. For just a quick overview, rather than fully designed tables, you can also just output the tables in ASCII style format.

Value

Returns a data tables containing the results for the cross table.

See Also

Creating a custom table style: excel_output_style(), modify_output_style(), number_format_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Creating formats: discrete_format() and interval_format().

Functions that can handle formats and styles: frequencies(), any_table().

Additional functions that can handle styles: export_with_style()

Additional functions that can handle formats: summarise_plus(), recode(), recode_multi(), transpose_plus(), sort_plus()

Examples

# Example data frame
my_data <- dummy_data(1000)

# Define titles and footnotes. If you want to add hyperlinks you can do so by
# adding "link:" followed by the hyperlink to the main text.
set_titles("This is title number 1 link: https://cran.r-project.org/",
           "This is title number 2",
           "This is title number 3")

set_footnotes("This is footnote number 1",
              "This is footnote number 2",
              "This is footnote number 3 link: https://cran.r-project.org/")

# Output cross tables
my_data |> crosstabs(age, sex)
my_data |> crosstabs(age, sex,
                     weight = "weight")

# Also works with characters
my_data |> crosstabs("age", "sex")
my_data |> crosstabs("age", "sex",
                     weight = "weight")

# Applying formats
age. <- discrete_format(
    "Total"          = 0:100,
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:64,
    "65 and older"   = 65:100)

sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

my_data |> crosstabs(age, sex,
                     formats   = list(age = age., sex = sex.))

# Split cross table by expressions of another variable
my_data |> crosstabs(age, sex, by = education)

# Compute different stats
my_data |> crosstabs(age, sex,
                     statistics = c("sum", "freq", "pct_row", "pct_column", "pct_total"))

# Get a list with two data tables for further usage
result_list <- my_data |> crosstabs(age, sex,
                                    formats = list(age = age., sex = sex.))

# Output in text file
my_data |> crosstabs(age, sex, output = "text")

# Output to Excel
my_data |> crosstabs(age, sex, output = "excel")

# Individual styling can also be passed directly
my_style <- excel_output_style(header_back_color = "0077B6",
                               font              = "Times New Roman")

my_data |> crosstabs(age, sex, output = "excel", style = my_style)

# To save a table as xlsx file you have to set the path and filename in the
# style element
# Example files paths
table_file <- tempfile(fileext = ".xlsx")

# Note: Normally you would directly input the path ("C:/MyPath/") and name ("MyFile.xlsx").
set_style_options(save_path  = dirname(table_file),
                  file       = basename(table_file),
                  sheet_name = "MyTable")

my_data |> crosstabs(age, sex, output = "excel")

# Manual cleanup for example
unlink(table_file)

# Global options are permanently active until the current R session is closed.
# There are also functions to reset the values manually.
reset_style_options()
reset_qol_options()
close_file()

Drop automatically generated Variables

Description

If summarise_plus() is used with the nested options "all" or "single", three variables are automatically generated: TYPE, TYPE_NR and DEPTH. With this functions these variables are dropped.

Usage

drop_type_vars(data_frame)

Arguments

Value

Returns a data frame without the variables TYPE, TYPE_NR and DEPTH.

Examples

# Example format
sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

# Example data frame
my_data <- dummy_data(1000)

# Call function
all_possible <- my_data |>
    summarise_plus(class      = c(year, sex),
                   values     = c(income, probability),
                   statistics = c("sum", "mean", "freq"),
                   formats    = list(sex = "sex."),
                   weight     = weight,
                   nesting    = "all",
                   na.rm      = TRUE) |>
    drop_type_vars()

Dummy Data

Description

The dummy data frame contains a few randomly generated variables like year, sex, age, income and weight to test out functionalities. It can be generated with the desired number of observations.

Usage

dummy_data(no_obs, monitor = .qol_options[["monitor"]])

Arguments

Value

Returns a dummy data table.

Examples

my_data <- dummy_data(1000)

Error Handling

Description

resolve_intersection(): Compares if two vectors have intersecting values. If TRUE, removes the intersection values from the base vector

part_of_df(): Check if variable names are part of a data frame. If not, remove them from the given vector.

remove_doubled_values(): Remove values from a vector that appear more than once.

check_weight(): Check if a weight variable was provided. If TRUE, check whether it can be used else add a temporary weight variable.

Usage

resolve_intersection(base, vector_to_check, check_only = FALSE)

part_of_df(data_frame, var_names, check_only = FALSE)

remove_doubled_values(var_names)

check_weight(data_frame, var_names)

Arguments

Value

Returns a vector or list.

Examples

# Resolve intersection between two vectors
vec1 <- c("a", "b", "c", "d")
vec2 <- c("e", "f", "a", "g")

vec1 <- resolve_intersection(vec1, vec2)

# Check if variables are part of a data frame
my_data   <- dummy_data(100)
var_names <- c("year", "state", "age", "test")

var_names <- my_data |> part_of_df(var_names)

# Remove doubled values
var_names <- c("year", "state", "state", "age")

var_names <- remove_doubled_values(var_names)

# Check the provided weight variable
var_names <- my_data |> check_weight("weight")

Style for 'Excel' Table Outputs

Description

Set different options which define the visual output of 'Excel' tables produced by frequencies(), crosstabs() and any_table().

Usage

excel_output_style(
  save_path = NULL,
  file = NULL,
  sheet_name = "Table",
  font = "Arial",
  column_widths = "auto",
  row_heights = "auto",
  title_heights = NULL,
  header_heights = NULL,
  table_heights = NULL,
  footnote_heights = NULL,
  start_row = 2,
  start_column = 2,
  freeze_col_header = FALSE,
  freeze_row_header = FALSE,
  filters = TRUE,
  grid_lines = TRUE,
  header_back_color = "FFFFFF",
  header_font_color = "000000",
  header_font_size = 10,
  header_font_bold = TRUE,
  header_alignment = "center",
  header_wrap = "1",
  header_indent = 0,
  header_borders = TRUE,
  header_border_color = "000000",
  cat_col_back_color = "FFFFFF",
  cat_col_font_color = "000000",
  cat_col_font_size = 10,
  cat_col_font_bold = FALSE,
  cat_col_alignment = "left",
  cat_col_wrap = "1",
  cat_col_indent = 1,
  cat_col_borders = TRUE,
  cat_col_border_color = "000000",
  table_back_color = "FFFFFF",
  table_font_color = "000000",
  table_font_size = 10,
  table_font_bold = FALSE,
  table_alignment = "right",
  table_indent = 1,
  table_borders = FALSE,
  table_border_color = "000000",
  as_heatmap = FALSE,
  heatmap_low_color = "F8696B",
  heatmap_middle_color = "FFFFFF",
  heatmap_high_color = "63BE7B",
  box_back_color = "FFFFFF",
  box_font_color = "000000",
  box_font_size = 10,
  box_font_bold = TRUE,
  box_alignment = "center",
  box_wrap = "1",
  box_indent = 0,
  box_borders = TRUE,
  box_border_color = "000000",
  number_formats = number_format_style(),
  title_font_color = "000000",
  title_font_size = 10,
  title_font_bold = TRUE,
  title_alignment = "left",
  footnote_font_color = "000000",
  footnote_font_size = 8,
  footnote_font_bold = FALSE,
  footnote_alignment = "left",
  na_symbol = "."
)

Arguments

Details

excel_output_style() is based on the Output Delivery System (ODS) in 'SAS', which provides efficient and readable ways to set up different table styles.

With the output style you have full control over the table design. There is no need to think about calculating the right place to input a background color or a border of a certain type and how to do this in a loop for multiple cells. Just input colors, borders, font styles, etc. for the different table parts and everything else is handled by the functions capable of using styles.

The concept basically is: design over complex calculations.

Value

Returns a list of named style options.

See Also

Creating a custom table style: modify_output_style(), number_format_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Functions that can handle styles: frequencies(), crosstabs(), any_table(), export_with_style()

Examples

# For default values
excel_style <- excel_output_style()

# Set specific options, the rest will be set to default values
excel_style <- excel_output_style(font       = "Calibri",
                                  sheet_name = "My_Output")

# For cells with no background color pass an empty string
excel_style <- excel_output_style(table_back_color = "")

Export Data Frame With Style

Description

export_with_style() prints a data frame as an individually styled 'Excel' table. Titles, footnotes and labels for variable names can optionally be added.

Usage

export_with_style(
  data_frame,
  titles = .qol_options[["titles"]],
  footnotes = .qol_options[["footnotes"]],
  var_labels = .qol_options[["var_labels"]],
  workbook = NULL,
  style = .qol_options[["excel_style"]],
  output = .qol_options[["output"]],
  print = .qol_options[["print"]],
  monitor = .qol_options[["monitor"]]
)

Arguments

Details

export_with_style() is based on the 'SAS' procedure Proc Print, which outputs the data frame as is into a styled table.

Value

Returns a formatted 'Excel' workbook.

See Also

Creating a custom table style: excel_output_style(), modify_output_style(), number_format_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Functions that can handle styles: frequencies(), crosstabs(), any_table().

Examples

# Example data frame
my_data <- dummy_data(1000)

# Define style
set_style_options(column_widths = c(2, 15, 15, 15, 9))

# Define titles and footnotes. If you want to add hyperlinks you can do so by
# adding "link:" followed by the hyperlink to the main text.
set_titles("This is title number 1 link: https://cran.r-project.org/",
           "This is title number 2",
           "This is title number 3")

set_footnotes("This is footnote number 1",
              "This is footnote number 2",
              "This is footnote number 3 link: https://cran.r-project.org/")

# Print styled data frame
my_data |> export_with_style()

# Retrieve formatted workbook for further usage
wb <- my_data |> export_with_style()

# To save a table as xlsx file you have to set the path and filename in the
# style element
# Example files paths
table_file <- tempfile(fileext = ".xlsx")

# Note: Normally you would directly input the path ("C:/MyPath/") and name ("MyFile.xlsx").
set_style_options(save_path  = dirname(table_file),
                  file       = basename(table_file),
                  sheet_name = "MyTable")

my_data |> export_with_style()

# Manual cleanup for example
unlink(table_file)

# Global options are permanently active until the current R session is closed.
# There are also functions to reset the values manually.
reset_style_options()
reset_qol_options()
close_file()

Set First Data Frame Row As Variable Names

Description

Sets the first row of a data frame as variable names and deletes it. In case of NA, numeric values or empty characters in the first row, the old names are kept.

Usage

first_row_as_names(data_frame)

Arguments

Value

Returns a data frame with renamed variables.

Examples

# Example data frame
my_data <- data.frame(
              var1 = c("id", 1, 2, 3),
              var2 = c(NA, "a", "b", "c"),
              var3 = c("value", 1, 2, 3),
              var4 = c("", "a", "b", "c"),
              var5 = c(1, 2, 3, 4))

my_data <- my_data |> first_row_as_names()

Create Format Container

Description

Create a format container which stores discrete or interval values with corresponding labels that can be applied by using summarise_plus().

Create a format container independent from any data frame. Define which values should be recoded into which new categories, if the format is applied to a variable in a data frame. It is possible to assign a single value to multiple new categories to create a multilabel. It is recommended to let format names end with a dot to make them stand out.

Usage

discrete_format(...)

interval_format(...)

Arguments

Details

The concept of having formats as molds or stencils to put the data through, is inspired by 'SAS' formats. In 'SAS' formats are defined with the procedure Proc Formats, which is adapted with discrete_format() and interval_format(). Here you can define, which values should be transferred into which result categories. This is completely detached from the data your working with.

The great thing about this is, that one can not only label and recode values, but one can also define so called multilabels. Meaning, one original value can be transferred into multiple result categories.

A cell in a data frame can only hold one distinct value, which is normally a good thing. But let's say you want to convert single ages into age categories. The age "3" for example could go into the category "under 6", but also in "under 12", "under 18" and "total". Normally you would compute additional variables, which hold the different categorizations, or you could also double up the observations for each category. Both ways would just bloat up the data frame and cost additional memory, particularly if you work with big data sets.

With these format containers, you just keep a small reference of original values and result categories. Formats and data find their way together only just before computing the results, meaning the original data frame can be passed into a function capable of handling formats (see below), without any data transformation beforehand. You just tell the function which format should be applied to which variable. That's it. The function handles the rest and outputs all the desired categories.

This method is very memory efficient, readable and user friendly for creating larger and more complex outputs at the same time.

Value

Returns a data table which contains the values/value ranges with the corresponding labels

See Also

Functions that can handle formats: summarise_plus(), frequencies(), crosstabs(), any_table(), recode_multi(), transpose_plus(), sort_plus().

Examples

age. <- discrete_format(
    "Total"          = 0:100,
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:64,
    "65 and older"   = 65:100)

sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

education. <- discrete_format(
    "Total"            = c("low", "middle", "high"),
    "low education"    = "low",
    "middle education" = "middle",
    "high education"   = "high")

income. <- interval_format(
    "Total"              = 0:99999,
    "below 500"          = 0:499,
    "500 to under 1000"  = 500:999,
    "1000 to under 2000" = 1000:1999,
    "2000 and more"      = 2000:99999)

state. <- discrete_format(
    "Germany"                       = 1:16,
    "Schleswig-Holstein"            = 1,
    "Hamburg"                       = 2,
    "Lower Saxony"                  = 3,
    "Bremen"                        = 4,
    "North Rhine-Westphalia"        = 5,
    "Hesse"                         = 6,
    "Rhineland-Palatinate"          = 7,
    "Baden-Württemberg"             = 8,
    "Bavaria"                       = 9,
    "Saarland"                      = 10,
    "West"                          = 1:10,
    "Berlin"                        = 11,
    "Brandenburg"                   = 12,
    "Mecklenburg-Western Pomerania" = 13,
    "Saxony"                        = 14,
    "Saxony-Anhalt"                 = 15,
    "Thuringia"                     = 16,
    "East"                          = 11:16)

# With discrete formats you can specify the keyword "other" to
# catch any other value not covered by the explicitly specified values.
age. <- discrete_format(
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = "other")

# With interval formats you can also use the keywords "low" and "high" to
# catch everything from the lowest to the highest values, in case one doesn't
# know exactly what the lowest and highest values are.
income. <- interval_format(
    "Total"              = c("low", "high"),
    "below 500"          = c("low", 499),
    "500 to under 1000"  = 500:999,
    "1000 to under 2000" = 1000:1999,
    "2000 and more"      = c(2000, "high"))

Display Frequency Tables of Single Variables

Description

frequencies() produces two kinds of tables for a quick overview of single variables. The first table is for a broader overview and contains mean, sd, min, max, freq and missings. The second table is the actual frequency table which shows the weighted sums, percentages and unweighted frequencies per expression.

Usage

frequencies(
  data_frame,
  variables,
  formats = c(),
  by = c(),
  weight = NULL,
  titles = .qol_options[["titles"]],
  footnotes = .qol_options[["footnotes"]],
  style = .qol_options[["excel_style"]],
  output = .qol_options[["output"]],
  na.rm = .qol_options[["na.rm"]],
  print = .qol_options[["print"]],
  monitor = .qol_options[["monitor"]]
)

Arguments

Details

frequencies() is based on the 'SAS' procedure Proc Freq, which provides efficient and readable ways to output frequency tables.

To create a frequency table you only need to provide a single variable. Nothing special about this. The real power comes into play, when you output your tables as a fully styled 'Excel' workbook. Setting up a custom, reusable style is as easy as setting up options like: provide a color for the table header, set the font size for the row header, should borders be drawn for the table cells yes/no, and so on.

You also can provide multiple single variables to generate multiple, evenly designed tables, all at once. For just a quick overview, rather than fully designed tables, you can also just output the tables in ASCII style format.

Value

Returns a list of two data tables containing the results for the frequency tables.

See Also

Creating a custom table style: excel_output_style(), modify_output_style(), number_format_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Creating formats: discrete_format() and interval_format().

Functions that can handle formats and styles: crosstabs(), any_table().

Additional functions that can handle styles: export_with_style()

Additional functions that can handle formats: summarise_plus(), recode(), recode_multi(), transpose_plus(), sort_plus()

Examples

# Example data frame
my_data <- dummy_data(1000)

# Define titles and footnotes. If you want to add hyperlinks you can do so by
# adding "link:" followed by the hyperlink to the main text.
set_titles("This is title number 1 link: https://cran.r-project.org/",
           "This is title number 2",
           "This is title number 3")

set_footnotes("This is footnote number 1",
              "This is footnote number 2",
              "This is footnote number 3 link: https://cran.r-project.org/")

# Output frequencies tables
my_data |> frequencies(sex)
my_data |> frequencies(c(age, education),
                       weight = weight)

# Also works with characters
my_data |> frequencies("sex")
my_data |> frequencies(c("age", "education"),
                       weight = "weight")

# Applying
sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

my_data |> frequencies(sex,
                       formats   = (sex = sex.))

# Split frequencies by expressions of another variable
my_data |> frequencies(sex, by = education)

# Get a list with two data tables for further usage
result_list <- my_data |> frequencies(sex, formats = (sex = sex.))

# Output in text file
my_data |> frequencies(sex, output = "text")

# Output to Excel
my_data |> frequencies(sex, output = "excel")

# Individual styling can also be passed directly
my_style <- excel_output_style(header_back_color = "0077B6",
                               font              = "Times New Roman")

my_data |> frequencies(sex, output = "excel", style = my_style)

# To save a table as xlsx file you have to set the path and filename in the
# style element
# Example files paths
table_file <- tempfile(fileext = ".xlsx")

# Note: Normally you would directly input the path ("C:/MyPath/") and name ("MyFile.xlsx").
set_style_options(save_path  = dirname(table_file),
                  file       = basename(table_file),
                  sheet_name = "MyTable")

my_data |> frequencies(sex, output = "excel")

# Manual cleanup for example
unlink(table_file)

# Global options are permanently active until the current R session is closed.
# There are also functions to reset the values manually.
reset_style_options()
reset_qol_options()
close_file()

Fuse Multiple Variables

Description

When you have a situation where you have multiple variables with different NA values that happen to be in different places (where one variable has a value the other is NA and vice versa) you can fuse these together to a single variable.

Usage

fuse_variables(
  data_frame,
  new_variable_name,
  variables_to_fuse,
  drop_original_vars = TRUE
)

Arguments

Value

Returns a data frame without the variables TYPE, TYPE_NR and DEPTH.

Examples

# Example format
sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

# Example data frame
my_data <- dummy_data(1000)

# Call function
all_possible <- my_data |>
    summarise_plus(class      = c(year, sex),
                   values     = c(income, probability),
                   statistics = c("sum", "mean", "freq"),
                   formats    = list(sex = "sex."),
                   weight     = weight,
                   nesting    = "all",
                   na.rm      = TRUE)

all_possible <- all_possible[DEPTH <= 1] |>
    fuse_variables("fusion", c("year", "sex"))

# NOTE: You can generally use this function to fuse variables. What is done in
#       multiple steps above can be achieved by just using nested = "single" in
#       summarise_plus.
single <- my_data |>
    summarise_plus(class      = c(year, sex),
                   values     = c(income, probability),
                   statistics = c("sum", "mean", "freq"),
                   formats    = list(sex = "sex."),
                   weight     = weight,
                   nesting    = "single",
                   na.rm      = TRUE)

Converts Numbers into 'Excel' Ranges

Description

Converts a column number into the according letter to form a cell reference like it is used in 'Excel' (e.g "A1"). Also can compute a range from cell to cell (e.g. "A1:BY22").

Usage

get_excel_range(
  row = NULL,
  column = NULL,
  from_row = NULL,
  from_column = NULL,
  to_row = NULL,
  to_column = NULL
)

Arguments

Value

Returns a character with an 'Excel' range.

Examples

single_cell <- get_excel_range(row = 1, column = 6)
range       <- get_excel_range(from_row = 1, from_column = 6,
                                 to_row = 5,   to_column = 35)

Get Integer Length

Description

Get the number of digits of an integer variable.

Usage

get_integer_length(variable)

Arguments

Value

Returns a vector with the number of digits places.

Examples

# Example data frame
my_data <- dummy_data(100)

my_data[["age_length"]] <- get_integer_length(my_data[["age"]])

If - Else if - Else Statements

Description

These functions make if statements more readable. Especially if an if block becomes bigger it can be hard to read with multiple nested if_else statements. With these new functions if blocks can be written like in other languages with a clear and simpler structure. In addition not only for one variable can a new value be assigned, but for multiple.

if.() always creates a new variable if the given variable name is not part of the given data frame. If there already is a variable with the given name, the existing values will be overwritten if the condition is TRUE.

If no new variable is provided, if.() will select observations by the given condition instead.

else_if.() only acts if there already is a variable with the given name. Only NA values will get new values if condition is TRUE. The existing values will not be overwritten.

else.() only acts if there already is a variable with the given name. Sets every remaining NA in given variable to the given value.

Usage

if.(data_frame, condition, ...)

else_if.(data_frame, condition, ...)

else.(data_frame, ...)

Arguments

Value

Returns a data frame with conditionally computed variables. If assigned values are of different types a character variable will be returned.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Call function
new_df <- my_data |>
         if.(age < 18,             age_group = "under 18") |>
    else_if.(age >= 18 & age < 65, age_group = "18 to under 65") |>
    else.   (                      age_group = "65 and older")

# Or with multiple variables
new_df <- my_data |>
         if.(age < 18,             age_group = "under 18"      , age_num = 1L) |>
    else_if.(age >= 18 & age < 65, age_group = "18 to under 65", age_num = 2L) |>
    else.   (                      age_group = "65 and older",   age_num = 3L)

# NOTE: As in other languages the following if blocks won't produce the same result.
#       if.() will overwrite existing values, while else_if.() will not.
state_df <- my_data |>
         if.(state == 1, state_a = "State 1") |>
    else_if.(state < 11, state_a = "West") |>
    else.   (            state_a = "East")

state_df <- state_df |>
      if.(state == 1, state_b = "State 1") |>
      if.(state < 11, state_b = "West") |>
    else.(            state_b = "East")

# Select observations by condition instead of generating new variable
subset_df <- my_data |> if.(sex == 1)

High Level Import From And Export To CSV And XLSX

Description

import_data(): A wrapper for data.table::fread() and openxlsx2::wb_to_df(), providing basic import functionality with minimal code.

export_data(): A wrapper for data.table::fwrite() and openxlsx2::wb_save(), providing basic export functionality with minimal code.

Usage

import_data(
  infile,
  sheet = 1,
  region = NULL,
  separator = "auto",
  decimal = "auto",
  var_names = TRUE
)

export_data(
  data_frame,
  outfile,
  separator = ";",
  decimal = ",",
  var_names = TRUE
)

Arguments

Details

import_data() and export_data() are based on the 'SAS' procedures Proc Import and Proc Export, which provide a very straight forward syntax. While 'SAS' can import many different formats with these procedures, these 'R' versions concentrate on importing CSV and XLSX files.

The main goal here is to just provide as few as possible parameters to tackle most of the imports and exports. These error handling also tries to let an import and export happen, even though a parameter wasn't provided in the correct way.

Value

Returns a data frame.

See Also

Functions that can export with style: frequencies(), crosstabs(), any_table(), export_with_style().

Creating a custom table style: excel_output_style(), modify_output_style(), number_format_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Examples

# Example files
csv_file  <- system.file("extdata", "qol_example_data.csv",  package = "qol")
xlsx_file <- system.file("extdata", "qol_example_data.xlsx", package = "qol")

# Import: Provide full file path
my_csv  <- import_data(csv_file)
my_xlsx <- import_data(xlsx_file)

# Import specific regions
range_import <- import_data(xlsx_file, region = "B4:H32")
name_import  <- import_data(xlsx_file, region = "test_region")

# Import from another sheet
sheet_import <- import_data(xlsx_file, sheet = "Sheet 2")

# Example data frame
my_data <- dummy_data(100)

# Example export file paths
export_csv  <- tempfile(fileext = ".csv")
export_xlsx <- tempfile(fileext = ".xlsx")

# Export: Provide full file path
my_data |> export_data(export_csv)
my_data |> export_data(export_xlsx)

# Manual cleanup for example
unlink(c(export_csv, export_xlsx))

Get Variable Names Which Are Not Part Of The Given Vector

Description

If you have stored variable names inside a character vector, this function gives you the inverse variable name vector.

Usage

inverse(data_frame, var_names)

Arguments

Value

Returns the inverse vector of variable names compared to the given vector.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Get variable names
var_names <- c("year", "age", "sex")
other_names <- my_data |> inverse(var_names)

# Can also be used to just get all variable names
all_names <- my_data |> inverse()

Keep and Drop Variables Inside a Data Frame

Description

keep() enables you to put in a vector of variable names which then are kept inside the given data frame. All other variables are dropped.

dropp() enables you to put in a vector of variable names which then are dropped from the given data frame. All other variables are kept.

Usage

keep(data_frame, ..., order_vars = FALSE)

dropp(data_frame, ...)

Arguments

Value

Returns a reduced data table.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Call function
new_dt1 <- my_data |> keep(year, age, sex)
new_dt2 <- my_data |> keep(weight, income, education, sex, order_vars = TRUE)
new_dt3 <- my_data |> dropp(year, age, sex)

# Also works with characters
new_dt4 <- my_data |> keep("year", "age", "sex")
new_dt5 <- my_data |> dropp("year", "age", "sex")

# Or variable names stored as a character vector
var_names <- c("age", "sex", "income", "weight")

new_dt6 <- my_data |> keep(var_names)
new_dt7 <- my_data |> dropp(var_names)

# You can also keep or drop a range of variables
new_dt8 <- my_data |> keep(year, state:income)
new_dt9 <- my_data |> dropp(year, state:income)

# You can also use the colon as a placeholder for any text
start1 <- my_data |> keep("s:") # Variable names start with "s"
start2 <- my_data |> dropp("s:")

end1 <- my_data |> keep(":id") # Variable names end with "id"
end2 <- my_data |> dropp(":id")

contain1 <- my_data |> keep(":on:") # Variable names which contain "on"
contain2 <- my_data |> dropp(":on:")

Check If Path Exists And Retrieve Files

Description

libname() checks if a given path exists and writes a message in the console accordingly. Optional all files from the given path can be retrieved as a named character vector.

Usage

libname(path, get_files = FALSE)

Arguments

Value

Returns the given file path or a named character vector containing file paths.

Examples

my_path   <- libname("C:/My_Path/")
file_list <- libname("C:/My_Path/", get_files = TRUE)

Modify Number Formats Used by any_table()

Description

Modify previously created number formats with number_format_style().

Usage

modify_number_formats(formats_to_modify, ...)

Arguments

Details

modify_number_formats() is based on 'SAS' number formats and the Output Delivery System (ODS), which provides efficient and readable ways to set up different table styles.

With the number format style you have full control over formatting numbers according to the different statistics. There is no need to think about calculating the right place to input the number formats and how to do this in a loop for multiple cells. Just input the different number formats and decimals for the different statistics and everything else is handled by the functions capable of using number styles.

The concept basically is: design over complex calculations.

Value

Returns a modified list of number format options.

See Also

Creating a custom table style: excel_output_style(), modify_output_style(), number_format_style().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Functions that can handle styles: frequencies(), crosstabs(), any_table(), export_with_style().

Examples

# For default values
format_list <- number_format_style(pct_excel    = "0.00000000",
                                   pct_decimals = 8)

# Set specific options, the rest will be kept as is
format_list <- format_list |> modify_number_formats(sum_excel = "#,###,##0.000")

# IMPORTANT: Don't forget to add individual formats to an excel style, otherwise
# they won't come into affect.
excel_style <- excel_output_style(number_formats = format_list)

Modify Style for 'Excel' Table Outputs

Description

Modify a previously created style with excel_output_style().

Usage

modify_output_style(style_to_modify, ...)

Arguments

Details

modify_output_style() is based on the Output Delivery System (ODS) in 'SAS', which provides efficient and readable ways to set up different table styles.

With the output style you have full control over the table design. There is no need to think about calculating the right place to input a background color or a border of a certain type and how to do this in a loop for multiple cells. Just input colors, borders, font styles, etc. for the different table parts and everything else is handled by the functions capable of using styles.

The concept basically is: design over complex calculations.

Value

Returns a modified list of named style options.

See Also

Creating a custom table style: excel_output_style(), number_format_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Functions that can handle styles: frequencies(), crosstabs(), any_table(), export_with_style()

Examples

# For default values
excel_style <- excel_output_style()

# Set specific options, the rest will be kept as is
excel_style <- excel_style |> modify_output_style(sheet_name      = "Sheet",
                                                  title_font_bold = FALSE)

# For cells with no background color pass an empty string
excel_style <- excel_style |> modify_output_style(table_back_color = "")

Monitor Time Consumption

Description

The monitor functions offer a simple way to keep track of timings and visualize them in charts. If used throughout a longer syntax it is useful to identify bottlenecks or just get a better feeling which passages take more time than others.

monitor_start() starts a new timing and adds this as an observation to the monitoring data table. Pass NULL as monitor_df if you call the function for the first time to create a new monitoring data table.

monitor_end() ends the current timing and calculates corresponding delta.

monitor_next() ends the current timing and calculates corresponding delta. In addition directly starts a new timing for a new section.

monitor_plot() outputs two charts to visualize the saved delta times.

Usage

monitor_start(monitor_df, section, group = "Total")

monitor_end(monitor_df)

monitor_next(monitor_df, section, group = "Total")

monitor_plot(monitor_df, by = "section", draw_plot = TRUE)

Arguments

Value

Returns a small data table with section-, group-names and corresponding delta times.

Examples

# Example data frame
monitor_df <- NULL |> monitor_start("Generate data frame", "Preparation")

my_data <- dummy_data(1000)

# Formats
monitor_df <- monitor_df |> monitor_next("Create formats", "Preparation")

age. <- discrete_format(
    "Total"          = 0:100,
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:65,
    "65 and older"   = 65:100)

sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

# Evaluations
monitor_df <- monitor_df |> monitor_next("Nested summarise", "Summarise")

all_nested <- my_data |>
    summarise_plus(class      = c(year, sex, age),
                   values     = income,
                   statistics = c("sum", "pct_group", "pct_total", "sum_wgt", "freq"),
                   formats    = list(sex = "sex.", age = "age."),
                   weight     = weight,
                   nesting    = "deepest",
                   na.rm      = TRUE)

monitor_df <- monitor_df |> monitor_next("All summarise", "Summarise")

all_possible <- my_data |>
    summarise_plus(class      = c(year, sex, age),
                   values     = c(probability),
                   statistics = c("sum", "p1", "p99", "min", "max", "freq", "freq_g0"),
                   formats    = list(sex    = "sex.",
                                     age    = "age."),
                   weight     = weight,
                   nesting    = "all",
                   na.rm      = TRUE)

monitor_df <- monitor_df |> monitor_end()

# For detailed plot
monitor_df |> monitor_plot()

# For summarised plot
monitor_df |> monitor_plot(by = "group")

# NOTE: The more complex functions in this package have a detailed monitoring
#       integrated which can be viewed by setting the argument 'monitor' to TRUE.

Join Multiple Data Frames In One Go

Description

Join two or more data frames together in one operation. multi_join() can handle multiple different join methods and can join on differently named variables.

Usage

multi_join(
  data_frames,
  on,
  how = "left",
  keep_indicators = FALSE,
  monitor = .qol_options[["monitor"]]
)

Arguments

Details

multi_join() is based on the 'SAS' Data-Step function Merge. Merge is capable of joining multiple data sets together at once, with a very basic syntax.

Provide the dataset names, the variables, on which they should be joined and after a full join is complete, the user can decide which parts of the joins should remain in the final dataset.

multi_join() tries to keep the simplicity, while giving the user the power, to do more joins at the same time. Additionally to what Merge can do, this function also makes use of the Proc SQL possibility to join datasets on different variable names.

Value

Returns a single data frame with joined variables from all given data frames.

Examples

# Example data frames
df1 <- data.frame(key = c(1, 1, 1, 2, 2, 2),
                  a   = c("a", "a", "a", "a", "a", "a"))

df2 <- data.frame(key = c(2, 3),
                  b   = c("b", "b"))

# See all different joins in action
join_methods <- c("left", "right", "inner", "full", "outer", "left_inner", "right_inner")
joined_data  <- list()

for (method in seq_along(join_methods)){
    joined_data[[method]] <- multi_join(list(df1, df2),
                                        on  = "key",
                                        how = join_methods[[method]])
}

# Left join on more than one key
df1b <- data.frame(key1 = c(1, 1, 1, 2, 2, 2),
                   key2 = c("a", "a", "a", "a", "a", "a"),
                   a    = c("a", "a", "a", "a", "a", "a"))

df2b <- data.frame(key1 = c(2, 3),
                   key2 = c("a", "a"),
                   b    = c("b", "b"))

left_joined <- multi_join(list(df1b, df2b), on = c("key1", "key2"))

# Join more than two data frames
df3 <- data.frame(key = c(1, 2),
                  c   = c("c", "c"))

multiple_joined <- multi_join(list(df1, df2, df3), on = "key")

# You can also use different methods for each join
multiple_joined2 <- multi_join(list(df1, df3, df2),
                               on  = "key",
                               how = c("left", "right"))

# Joining on different variable names
df1c <- data.frame(key1 = c(1, 1, 1, 2, 2, 2),
                   key2 = c("a", "a", "a", "a", "a", "a"),
                   a    = c("a", "a", "a", "a", "a", "a"))

df2c <- data.frame(var1 = c(2, 3),
                   var2 = c("a", "a"),
                   b    = c("b", "b"))

df3c <- data.frame(any  = c(1, 2),
                   name = c("a", "a"),
                   c    = c("c", "c"))

multiple_joined3 <- multi_join(list(df1c, df2c, df3c),
                               on = list(df1c = c("key1", "key2"),
                                         df2c = c("var1", "var2"),
                                         df3c = c("any", "name")))

Number Formats Used by any_table()

Description

Set individual number formats for the different statistics in tables produced with any_table().

Usage

number_format_style(
  pct_excel = "0.0",
  freq_excel = "#,###,##0",
  freq.g0_excel = "#,###,##0",
  sum_excel = "#,###,##0",
  sum.wgt_excel = "#,###,##0",
  mean_excel = "#,###,##0",
  median_excel = "#,###,##0",
  mode_excel = "#,###,##0",
  min_excel = "#,###,##0",
  max_excel = "#,###,##0",
  sd_excel = "#,###,##0.000",
  variance_excel = "#,###,##0.000",
  first_excel = "#,###,##0",
  last_excel = "#,###,##0",
  p_excel = "#,###,##0",
  missing_excel = "#,###,##0",
  pct_decimals = 1,
  freq_decimals = 0,
  freq.g0_decimals = 0,
  sum_decimals = 3,
  sum.wgt_decimals = 3,
  mean_decimals = 2,
  median_decimals = 2,
  mode_decimals = 2,
  min_decimals = 2,
  max_decimals = 2,
  sd_decimals = 3,
  variance_decimals = 3,
  first_decimals = 0,
  last_decimals = 0,
  p_decimals = 2,
  missing_decimals = 0
)

Arguments

Details

number_format_style() is based on 'SAS' number formats and the Output Delivery System (ODS), which provides efficient and readable ways to set up different table styles.

With the number format style you have full control over formatting numbers according to the different statistics. There is no need to think about calculating the right place to input the number formats and how to do this in a loop for multiple cells. Just input the different number formats and decimals for the different statistics and everything else is handled by the functions capable of using number styles.

The concept basically is: design over complex calculations.

Value

Returns a list of named number format options.

See Also

Creating a custom table style: excel_output_style(), modify_output_style(), modify_number_formats().

Global style options: set_style_options(), set_variable_labels(), set_stat_labels().

Functions that can handle styles: frequencies(), crosstabs(), any_table(), export_with_style()

Examples

# For default values
format_list <- number_format_style()

# Set specific options, the rest will be set to default values
format_list <- number_format_style(pct_excel    = "0.00000000",
                                   pct_decimals = 8)

# IMPORTANT: Don't forget to add individual formats to an excel style, otherwise
# they won't come into affect.
excel_style <- excel_output_style(number_formats = format_list)

Go To GitHub NEWS Page

Description

Opens browser and goes to the Github NEWS page

Usage

qol_news()

Value

URL.

Set Global Print Option

Description

set_print(): Set the print option globally for the tabulation and export to Excel functions.

get_print(): Get the globally stored print option.

set_monitor(): Set the monitor option globally for the heavier functions which are able to show how they work internally.

get_monitor(): Get the globally stored monitor option.

set_na.rm(): Set the na.rm option globally for each function which can remove NA values.

get_na.rm(): Get the globally stored na.rm option.

set_output(): Set the output option globally for each function that can output results to "console", "text", "excel" or "excel_nostyle".

get_output(): Get the globally stored output option.

set_titles(): Set the titles globally for each function that can print titles above the output table.

get_titles(): Get the globally stored titles.

set_footnotes(): Set the footnotes globally for each function that can print footnotes above the output table.

get_footnotes(): Get the globally stored footnotes.

Usage

set_print(...)

get_print()

set_monitor(...)

get_monitor()

set_na.rm(...)

get_na.rm()

set_output(...)

get_output()

set_titles(...)

get_titles()

set_footnotes(...)

get_footnotes()

Arguments

Value

set_print(): Changed global print option.

get_print(): TRUE or FALSE.

set_monitor(): Changed global monitor option.

get_monitor(): TRUE or FALSE.

set_na.rm(): Changed global na.rm option.

get_na.rm(): TRUE or FALSE.

set_output(): Changed global output option.

get_output(): Current output option as character.

set_titles(): Changed global titles.

get_titles(): Current titles as character.

set_footnotes(): Changed global footnotes.

get_footnotes(): Current footnotes as character.

Examples

set_print(FALSE)
set_print(TRUE)

get_print()

set_monitor(TRUE)
set_monitor(FALSE)

get_monitor()

set_na.rm(TRUE)
set_na.rm(FALSE)

get_na.rm()

set_output("excel")

get_output()

set_titles("This is title number 1 link: https://cran.r-project.org/",
           "This is title number 2",
           "This is title number 3")

get_titles()

set_footnotes("This is title number 1 link: https://cran.r-project.org/",
           "This is title number 2",
           "This is title number 3")

get_footnotes()

Recode New Variables With Formats

Description

Instead of writing multiple if-clauses to recode values into a new variable, you can use formats to recode a variable into a new one.

Usage

recode(data_frame, new_var, ...)

recode_multi(data_frame, ...)

Arguments

Details

recode() is based on the 'SAS' function put(), which provides an efficient and readable way, to generate new variables with the help of formats.

When creating a format you can basically write code like you think: This new category consists of these original values. And after that you just apply these new categories to the original values to create a new variable. No need for multiple if_else statements.

Value

Returns a data frame with the newly recoded variable.

See Also

Creating formats: discrete_format() and interval_format().

Functions that also make use of formats: frequencies(), crosstabs(), any_table().

Examples

# Example formats
age. <- discrete_format(
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:64,
    "65 and older"   = 65:100)

# Example data frame
my_data <- dummy_data(1000)

# Call function
my_data <- my_data |> recode("age_group1", age = age.)

# Formats can also be passed as characters
my_data <- my_data |> recode("age_group2", age = "age.")

# Multilabel recode
sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

income. <- interval_format(
    "Total"              = 0:99999,
    "below 500"          = 0:499,
    "500 to under 1000"  = 500:999,
    "1000 to under 2000" = 1000:1999,
    "2000 and more"      = 2000:99999)

multi_data <- my_data |> recode_multi(sex = sex., income = income.)

Replace Statistic From Variable Names

Description

Remove the statistic name from variable names, so that they get back their old names without extension.

Usage

remove_stat_extension(data_frame, statistics)

Arguments

Value

Returns a data frame with renamed variables.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Summarise data
all_nested <- my_data |>
    summarise_plus(class      = c(year, sex),
                   values     = c(weight, income),
                   statistics = c("sum", "pct_group", "pct_total", "sum_wgt", "freq"),
                   weight     = weight,
                   nesting    = "deepest",
                   na.rm      = TRUE)

# Remove statistic extension
new_names <- all_nested |> remove_stat_extension("sum")

Rename One Or More Variables

Description

Can rename one or more existing variable names into the corresponding new variable names in one go.

Usage

rename_multi(data_frame, ...)

Arguments

Value

Returns a data_frame with renamed variables.

Examples

# Example data frame
my_data <- dummy_data(10)

# Rename multiple variables at once
new_names_df <- my_data |> rename_multi("sex"   = "var1",
                                        "age"   = "var2",
                                        "state" = "var3")

Replace Patterns Inside Variable Names

Description

Replace a certain pattern inside a variable name with a new one. This can be used if there are multiple different variable names which have a pattern in common (e.g. all end in "_sum" but start different), so that there don't have to be multiple rename variable calls.

Usage

rename_pattern(data_frame, old_pattern, new_pattern)

Arguments

Value

Returns a data frame with renamed variables.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Summarise data
all_nested <- my_data |>
    summarise_plus(class      = c(year, sex),
                   values     = c(weight, income),
                   statistics = c("sum", "pct_group", "pct_total", "sum_wgt", "freq"),
                   weight     = weight,
                   nesting    = "deepest",
                   na.rm      = TRUE)

# Rename variables by repacing patterns
new_names <- all_nested |>
    rename_pattern("pct", "percent") |>
    rename_pattern("_sum", "")

Replace Patterns While Protecting Exceptions

Description

Replaces a provided pattern with another, while protecting exceptions. Exceptions can contain the given pattern, but won't be changed during replacement.

Usage

replace_except(vector, pattern, replacement, exceptions = NULL)

Arguments

Value

Returns a vector with replaced pattern.

Examples

# Vector, where underscores should be replaced
underscores <- c("my_variable", "var_with_underscores", "var_sum", "var_pct_total")

# Extensions, where underscores shouldn't be replaced
extensions <- c("_sum", "_pct_group", "_pct_total", "_pct_value", "_pct", "_freq_g0",
                "_freq", "_mean", "_median", "_mode", "_min", "_max", "_first",
                "_last", "_p1", "_p2", "_p3", "_p4", "_p5", "_p6", "_p7", "_p8", "_p9",
                "sum_wgt", "_sd", "_variance", "_missing")

# Replace
new_vector <- underscores |> replace_except("_", ".", extensions)

Different Facets of Retain

Description

These retain functions all have one thing in common: transferring a value from one case to the next. What they make out of this functionality can be quiet different. Therefor there is a function for each different use case.

running_number() computes running numbers in a data frame. Without specifying a by variable results in the row number. With by variable computes the running number within each group of expressions.

mark_case() sets a flag for the first or last case within the provided by group.

retain_value() retains the first value for all cases of the same group and saves it into a new variable.

retain_sum() retains the summarised values for all cases of the same group and saves it into a new variable.

retain_variables() orders the provided variables to the front or back of the data frame. If a variable is not part of the data frame it will be added with all NA values at the desired position.

Usage

running_number(data_frame, var_name = "run_nr", by = NULL)

mark_case(data_frame, var_name = "first", by = NULL, first = TRUE)

retain_value(data_frame, values, var_name = "retain_value", by = NULL)

retain_sum(data_frame, values, var_name = "retain_sum", by = NULL)

retain_variables(data_frame, ..., order_last = FALSE)

Arguments

Details

The functions listed here are based on the 'SAS' function retain. On a very basic level retain can do two things, depending on the position in the 'SAS' code: It can either sort variables column wise or it can - since it works row wise - remember a value from one row to the next. The functions here concentrate on the second part.

Remembering a value from a previous observation offers multiple use cases. E.g. always adding +1 to the previous case creates a running number. Or if an observation knows the value of the previous one, it can check whether it is of the same value or another, e.g. to mark first or last cases within a group.

In it's simplest form it can remember a value from the first observation and transfer it to all other observations.

All of these functions work on the whole data frame as well as on groups, e.g. to transfer a value from the first person in a household to all other persons of the same household.ame retain

Value

running_number(): Returns the data frame with a new variable containing a running number.

mark_case(): Returns the data frame with a new variable marking first or last cases.

retain_value(): Return the data frame with a new variable containing a retained value.

retain_sum(): Return the data frame with a new variable containing a retained sum.

retain_sum(): Return the data frame with a new variable containing a retained sum.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Get row numbers
my_data <- my_data |> running_number()
my_data <- my_data |> running_number("row_number")

# Running number per variable expression
my_data <- my_data |> running_number(by = year)

# Mark first and last cases
my_data <- my_data |>
    mark_case(by = household_id) |>
    mark_case(var_name = "last", by = household_id, first = FALSE)

# Retain first value inside a group
my_data <- my_data |>
    retain_value(var_name = c("household_weight", "household_icome"),
                 value    = c(weight, income),
                 by       = c(state, household_id))

# Retain sum inside a group
my_data <- my_data |>
    retain_sum(var_name = c("weight_hh_sum", "icome_hh_sum"),
               values    = c(weight, income),
               by       = c(state, household_id))

# Retain columns inside data frame, which orders them to the front
my_data <- my_data |> retain_variables(age, sex, income)

# Retain columns inside data frame, but order them to the end.
# Variable ranges can also be used.
my_data <- my_data |> retain_variables(age:income, order_last = TRUE)

# Retain columns inside data frame and add new variables with all NA values
my_data <- my_data |> retain_variables(age, sex, income, status1:status5)

Stack Multiple Data Frames

Description

Stacks multiple data frames and matches column names.

Usage

set(..., id = FALSE, compress = NULL, guessing_rows = 100)

Arguments

Value

Returns a stacked data frame.

Examples

# Example data frames
my_data1 <- dummy_data(100)
my_data2 <- dummy_data(100)
my_data3 <- dummy_data(100)
my_data4 <- dummy_data(100)
my_data5 <- dummy_data(100)

# Stack data frames
stacked_df <- set(my_data1,
                  my_data2,
                  my_data3,
                  my_data4,
                  my_data5)

Order Columns by Variable Name Patterns

Description

Order variables in a data frame based on a pattern rather than whole variable names. E.g. grab every variable that contains "sum" in it's name and order them together so that they appear next to each other.

Usage

setcolorder_by_pattern(data_frame, pattern)

Arguments

Value

Returns a reordered data frame with the ordered variables at the end.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Summarise data
all_nested <- my_data |>
    summarise_plus(class      = c(year, sex),
                   values     = c(weight, income),
                   statistics = c("sum", "pct_group", "pct_total", "sum_wgt", "freq"),
                   weight     = weight,
                   nesting    = "deepest",
                   na.rm      = TRUE)

# Set a different column order
new_order <- all_nested |> setcolorder_by_pattern(c("pct", "freq", "sum"))

Sort Data Frame Rows With Some Additions

Description

Sort data frame rows by the provided variables. sort_plus() is also able to preserve the current order of certain variables and only sort other variables within this order. As another option one can sort a variable with the help of formats, which can be used to e.g. sort a character variable in another than alphabetical order without creating a temporary variable just for sorting.

Usage

sort_plus(
  data_frame,
  by,
  preserve = NULL,
  order = "ascending",
  formats = c(),
  na.last = TRUE
)

Arguments

Details

sort_plus() is just very loosely based on the 'SAS' procedure Proc Sort. It tries to keep the simplicity, but with some added features.

Value

Returns a sorted data table.

See Also

Creating formats: discrete_format() and interval_format().

Functions that also make use of formats: frequencies(), crosstabs(), any_table(), recode(), recode_multi(), transpose_plus().

Examples

# Example formats
education. <- discrete_format(
    "1" = "low",
    "2" = "middle",
    "3" = "high")

# Example data frame
my_data <- dummy_data(1000)

# Simple sorting
sort_df1 <- my_data |> sort_plus(by = c(state, sex, age))
sort_df2 <- my_data |> sort_plus(by    = c(state, sex, age),
                                 order = c("ascending", "descending"))

# Character variables will normally be sorted alphabetically. With the help
# of a format this variable can be sorted in a completely different way.
sort_df3 <- my_data |> sort_plus(by      = education,
                                 formats = list(education = education.))

# Preserve the order of the character variable, otherwise it couldn't stay in
# it's current order.
sort_df4 <- sort_df3 |> sort_plus(by       = age,
                                  preserve = education)

Split Data Frame By Variable Expressions Or Condition

Description

Split up a data frame based on variable expressions or on conditions to receive multiple smaller data frames. Both possibilities can be used at the same time.

Usage

split_by(
  data_frame,
  ...,
  formats = list(),
  inverse = FALSE,
  monitor = .qol_options[["monitor"]]
)

Arguments

Details

split_by() is based on the explicit Output from 'SAS'. With the Output function one can - among other things - explicitly tell 'SAS' which observation to output into which data set. Which enables the user to output one observation into one or multiple data sets.

Instead of subsetting the same data frame multiple times manually, you can subset it multiple times at once with this function.

Value

Returns a list of data frames split by variable expressions and/or conditions. The lists names are the variable expressions or conditions.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Split by variable expressions
split_var_df <- my_data |> split_by(sex)

# Split by conditions
split_cond_df <- my_data |> split_by(sex == 1 & age <  18,
                                     sex == 2 & age >= 18)

# Split by condition with inverse group
split_inv_df <- my_data |> split_by(sex == 1, inverse = TRUE)

# Split by variables and conditions
split_combi_df <- my_data |> split_by(state, education,
                                      sex == 1, age < 18)

# Split by variable expressions using formats
state. <- discrete_format(
    "Germany"                       = 1:16,
    "Schleswig-Holstein"            = 1,
    "Hamburg"                       = 2,
    "Lower Saxony"                  = 3,
    "Bremen"                        = 4,
    "North Rhine-Westphalia"        = 5,
    "Hesse"                         = 6,
    "Rhineland-Palatinate"          = 7,
    "Baden-Württemberg"             = 8,
    "Bavaria"                       = 9,
    "Saarland"                      = 10,
    "West"                          = 1:10,
    "Berlin"                        = 11,
    "Brandenburg"                   = 12,
    "Mecklenburg-Western Pomerania" = 13,
    "Saxony"                        = 14,
    "Saxony-Anhalt"                 = 15,
    "Thuringia"                     = 16,
    "East"                          = 11:16)

split_format_df <- my_data |> split_by(state,
                                       formats = list(state = state.))

Set Global Styling Options For Excel Workbooks

Description

Modify Styling options for Excel workbooks. Available parameters can be seen in excel_output_style() or number_format_style().

set_style_options() sets the styling options for Excel workbooks globally.These options are used by all tabulation and output functions, which are capable of exporting styled outputs.

reset_style_options() resets global style options to the default parameters.

get_style_options() prints out the currently set global styling options.

close_file() is a simple, more readable wrapper for setting file parameter to NULL.

set_variable_labels(): Can set variable labels globally so that they don't have to be provided in every output function separately.

get_variable_labels(): Get the globally stored variable labels.

set_stat_labels(): Can set statistic labels globally so that they don't have to be provided in every output function separately.

get_stat_labels(): Get the globally stored statistic labels.

reset_qol_options() resets global options to the default parameters.

Usage

set_style_options(...)

reset_style_options()

get_style_options()

close_file()

set_variable_labels(...)

get_variable_labels()

set_stat_labels(...)

get_stat_labels()

reset_qol_options()

Arguments

Value

set_style_options(): Returns modified global styling options.

reset_style_options(): Returns default global styling options.

get_style_options(): List of global styling options.

close_file(): List of global styling options with file = NULL.

set_variable_labels(): List of variable labels.

get_variable_labels(): List of variable labels.

set_stat_labels(): List of statistic labels.

get_stat_labels(): List of statistic labels.

reset_qol_options(): Returns default global options.

See Also

Functions that use global styling optionss: any_table(), frequencies(), crosstabs().

Functions that also use global variable labels: export_with_style().

Functions that use global variable and statistic labels: any_table(), frequencies(), crosstabs().

Functions that also use global variable labels: export_with_style().

Examples

set_style_options(save_path    = "C:/My Projects/",
                  sum_decimals = 8)

reset_style_options()

get_style_options()

close_file()

set_variable_labels(age_gr = "Group of ages",
                    status = "Current status")

get_variable_labels()

set_stat_labels(pct  = "%",
                freq = "Count")

get_stat_labels()

reset_qol_options()

Fast And Powerful Yet Simple To Use Summarise

Description

summarise_plus() creates a new aggregated data table with the desired grouping. It can output only the deepest nested combination of the grouping variables (default) or you can also output every possible combination of the grouping variables at once, with just one small change. Besides the normal summary functions like sum, mean or median, you can also calculate their respective weighted version by just setting a weight variable.

Usage

summarise_plus(
  data_frame,
  class = NULL,
  values,
  statistics = c("sum", "freq"),
  formats = list(),
  types = "",
  weight = NULL,
  nesting = "deepest",
  merge_back = FALSE,
  na.rm = .qol_options[["na.rm"]],
  monitor = .qol_options[["monitor"]],
  notes = TRUE
)

Arguments

Details

summarise_plus() is based on the 'SAS' procedure Proc Summary, which provides efficient and readable ways to perform complex aggregations.

Normally you would compute new categorical variables beforehand - probably even in different forms, if you wanted to have different categorizations - and bloat up the data set. After all this recoding footwork you could finally use multiple summaries to compute all the stats you need to then put them back together. With this function this is no more necessary.

In summarise_plus() you put in the original data frame and let the recoding happen via format containers. This is very efficient, since new variables and categories are only created just before the summarise happens.

Additionally you can specify whether you only want to produce the all nested version of all group variables or whether you want to produce every possible combination in one go. All with a single option.

The function is optimized to always take the fastest route, depending on the options specified.

Value

Returns a summarised data table.

See Also

Creating formats: discrete_format() and interval_format().

Functions that also make use of formats: frequencies(), crosstabs(), any_table(), recode(), recode_multi(), transpose_plus(), sort_plus().

Examples

# Example formats
age. <- discrete_format(
    "Total"          = 0:100,
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:64,
    "65 and older"   = 65:100)

sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

income. <- interval_format(
    "Total"              = 0:99999,
    "below 500"          = 0:499,
    "500 to under 1000"  = 500:999,
    "1000 to under 2000" = 1000:1999,
    "2000 and more"      = 2000:99999)

# Example data frame
my_data <- dummy_data(1000)

# Call function
all_nested <- my_data |>
    summarise_plus(class      = c(year, sex, age),
                   values     = income,
                   statistics = c("sum", "pct_group", "pct_total", "sum_wgt", "freq"),
                   formats    = list(sex = sex., age = age.),
                   weight     = weight,
                   nesting    = "deepest",
                   na.rm      = TRUE)

all_possible <- my_data |>
    summarise_plus(class      = c(year, sex, age, income),
                   values     = c(probability),
                   statistics = c("sum", "p1", "p99", "min", "max", "freq", "freq_g0"),
                   formats    = list(sex    = sex.,
                                     age    = age.,
                                     income = income.),
                   weight     = weight,
                   nesting    = "all",
                   na.rm      = TRUE)

# Formats can also be passed as characters
single <- my_data |>
    summarise_plus(class      = c(year, age, sex),
                   values     = weight,
                   statistics = c("sum", "mean"),
                   formats    = list(sex = "sex.", age = "age."),
                   nesting    = "single")

merge_back <- my_data |>
    summarise_plus(class      = c(year, age, sex),
                   values     = weight,
                   statistics = c("sum", "mean"),
                   nesting    = "deepest",
                   merge_back = TRUE)

certain_types <- my_data |>
    summarise_plus(class      = c(year, sex, age),
                   values     = c(probability),
                   statistics = c("sum", "mean", "freq"),
                   formats    = list(sex = sex.,
                                     age = age.),
                   types      = c("year", "year + age", "age + sex"),
                   weight     = weight,
                   nesting    = "all",
                   na.rm      = TRUE)

Fast And Powerful Yet Simple To Use Transpose

Description

transpose_plus() is able to reshape a data frame from long to wide and from wide to long. In the long to wide transposition variables can be nested or placed side by side. With the wide to long transposition it is also possible to transpose multiple variables at once.

Additionally transpose_plus() is able to weight results before transposing them from long to wide.

The function also makes use of formats, which means you don't need to create variables storing the new variable names before transposition. You can just use formats to name the new variables and with multilabels you can even generate new variable expressions at the same time.

Usage

transpose_plus(
  data_frame,
  preserve = NULL,
  pivot,
  values = NULL,
  formats = c(),
  weight = NULL,
  na.rm = .qol_options[["na.rm"]],
  monitor = .qol_options[["monitor"]]
)

Arguments

Details

transpose_plus() is just very loosely based on the 'SAS' procedure Proc Transpose, and the possibilities of a Data-Step transposition using loops.

The transposition methods 'SAS' has to offer are actually fairly weak. Which is weird because all tools are there to have another powerful function. So transpose_plus() tries to create the function 'SAS' should have.

The function is able to interpret which transposition direction the user wants by just looking at what the user provided with the function parameters. For a long to wide transposition it is natural to just provide variables to transpose. While it is also just natural to provide new variable names when transposing from wide to long. That alone reduces the number of parameters the user has to enter to perform a simple transposition.

The real magic happens when formats come into play. With their help you can not only name new variables or their expressions, but you can also generate completely new expressions with no effort, just with the help of multilabels.

Value

Returns a transposed data table.

See Also

Creating formats: discrete_format() and interval_format().

Functions that also make use of formats: frequencies(), crosstabs(), any_table(), recode(), recode_multi(), sort_plus().

Examples

# Example formats
age. <- discrete_format(
    "Total"          = 0:100,
    "under 18"       = 0:17,
    "18 to under 25" = 18:24,
    "25 to under 55" = 25:54,
    "55 to under 65" = 55:64,
    "65 and older"   = 65:100)

sex. <- discrete_format(
    "Total"  = 1:2,
    "Male"   = 1,
    "Female" = 2)

sex2. <- discrete_format(
    "Total"  = c("Male", "Female"),
    "Male"   = "Male",
    "Female" = "Female")

income. <- interval_format(
    "Total"              = 0:99999,
    "below 500"          = 0:499,
    "500 to under 1000"  = 500:999,
    "1000 to under 2000" = 1000:1999,
    "2000 and more"      = 2000:99999)

# Example data frame
my_data <- dummy_data(1000)

# Transpose from long to wide and use a multilabel to generate additional categories
long_to_wide <- my_data |>
    transpose_plus(preserve = c(year, age),
                   pivot    = c("sex", "education"),
                   values   = income,
                   formats  = list(sex = sex., age = age.),
                   weight   = weight,
                   na.rm    = TRUE)

# Transpose back from wide to long
wide_to_long <- long_to_wide |>
    transpose_plus(preserve = c(year, age),
                   pivot    = list(sex       = c("Total", "Male", "Female"),
                                   education = c("low", "middle", "high")))

# Nesting variables in long to wide transposition
nested <- my_data |>
    transpose_plus(preserve = c(year, age),
                   pivot    = "sex + education",
                   values   = income,
                   formats  = list(sex = sex., age = age.),
                   weight   = weight,
                   na.rm    = TRUE)

# Or both, nested and un-nested, at the same time
both <- my_data |>
    transpose_plus(preserve = c(year, age),
                   pivot    = c("sex + education", "sex", "education"),
                   values   = income,
                   formats  = list(sex = sex., age = age.),
                   weight   = weight,
                   na.rm    = TRUE)

Get All Variable Names Between Two Variables

Description

Get all the variable names inside a data frame between two variables (including the provided ones) as a character vector

Usage

vars_between(data_frame, from, to)

Arguments

Value

Returns a character vector of variable names.

Examples

# Example data frame
my_data <- dummy_data(1000)

# Get variable names
var_names <- my_data |> vars_between(state, income)

# Get variable names in reverse order
vars_reverse <- my_data |> vars_between(income, state)

# If you only provide "from" or "to" you get all variable names from a point to
# the end or from the beginning to a given point.
vars_from <- my_data |> vars_between(state)
vars_to   <- my_data |> vars_between(to = state)

# Or just get all variable names
vars_all <- my_data |> vars_between()