Package 'qol'

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

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)

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 = NULL,
  pct_group = c(),
  pct_value = list(),
  pct_block = c(),
  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_miss = .qol_options[["print_miss"]],
  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().

Other global options: set_titles(), set_footnotes(), set_print(), set_monitor(), set_na.rm(), set_print(), set_print_miss(), set_output().

Combine Excel workbooks: combine_into_workbook().

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

# NOTE: Some of the examples use the parameter 'output = "excel_nostyle"' to
#       make them run faster so that more examples can be provided. Take out
#       the parameter to get the fully styled excel table.
#       The global option for printing the output is also set to FALSE for
#       the same reason. When running the examples manually, don't run this
#       option here.
set_print(FALSE)

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

# NOTE: "!" in front of an expression makes the expression available for
#       calculations but prevents it from beeing printed out.
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. Linking to another
# cell works with "cell:". To link to a file use "file:" an pass the full file
# path afterwards.
set_titles("This is title number 1",
           "This is title number 2 link: https://cran.r-project.org/",
           "This is title number 3 cell: W22",
           "This is title number 4 file: C:/MyFolder/MyFile.txt")

set_footnotes("This is footnote number 1",
              "This is footnote number 2 file: C:/MyFolder/MyFile.txt",
              "This is footnote number 3 cell: W22",
              "This is footnote number 4 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,
                     pct_group = c("row_pct", "col_pct"),
                     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,
#                      pct_group = c("sex", "age"),
#                      formats   = list(sex = sex., age = age.,
#                                       education = education.),
#                      output    = "excel_nostyle",
#                      na.rm     = TRUE)

# Percentages based on value variables instead of categories
my_data |> any_table(rows       = c("age + year"),
                     columns    = "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.),
                     output    = "excel_nostyle",
                     na.rm      = TRUE)

# Percentages based on a formatted variable expression
my_data |> any_table(rows       = c("age + year"),
                     columns    = "sex",
                     values     = c(probability, person),
                     pct_value  = list(sex = "Total", age = "Total"),
                     weight     = weight,
                     formats    = list(sex = sex., age = age.),
                     output    = "excel_nostyle",
                     na.rm      = TRUE)

# Percentages based on variable combination blocks
# NOTE: age + (year education) becomes "age + year" and "age + education"
#       and will be sorted together. Also works in columns.
my_data |> any_table(rows       = c("sex + (age education)"),
                     columns    = "year",
                     values     = weight,
                     pct_block  = c("rows", "columns"),
                     formats    = list(sex = sex., age = age.,
                                       education = education.),
                     output     = "excel_nostyle",
                     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.#'
set_titles("This is title number 1",
           "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")

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

# In case you have a good amount of tables, you want to combine in a single workbook,
# you can also catch the outputs and combine them afterwards in one go.
# NOTE: This section is commented out to just show the principle. Otherwise the
#       example code would run for too long.
# set_style_options(sheet_name = "sheet1")
# tab1 <- my_data |> any_table(..., print = FALSE, output = "excel_nostyle")
#
# set_style_options(sheet_name = "sheet2")
# tab2 <- my_data |> any_table(..., print = FALSE, output = "excel_nostyle")
#
# set_style_options(sheet_name = "sheet3")
# tab3 <- my_data |> any_table(..., 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 file = "C:/My_folder/My_workbook.xlsx")

# The result list from above also carries the transformed data frame if
# needed for further usage
any_table_df <- result_list[["table"]]

# 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    = "education",
                     values     = weight,
                     by         = state,
                     statistics = c("sum", "pct_group"),
                     pct_group  = "education",
                     formats    = list(sex = sex., age = age., state = state.,
                                       education = education.),
                     output     = "excel_nostyle",
                     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()

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,
  with_monitor = FALSE
)

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)

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)

Description

code_statistics() reads in a folder or entire folder structure, grabs all 'R' script files and scans the contents for different patterns. It then outputs a small report which shows of which parts the code consists.

Usage

code_statistics(paths, recursive = FALSE, output_per = "overall")

Arguments

Value

Returns the results as a data frame.

Examples

# Run this function on a directory, actually containing R script files
# to see some results.
code_statistics(tempdir())

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
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 cell: W22",
           "This is title number 3 file: C:/MyFolder/MyFile.docx",
           "This is title number 4")
set_footnotes("This is footnote number 1 cell: W22",
              "This is footnote number 2 file: C:/MyFolder/MyFile.docx",
              "This is footnote number 3 link: https://cran.r-project.org/",
              "This is footnote number 4")

# Catch the output and additionally use the options:
# print = FALSE and output = "excel_nostyle".
# This skips the styling and output part, so that the function runs faster.
# The styling is done later on.
set_print(FALSE)
set_output("excel_nostyle")
set_style_options(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.),
                             na.rm      = TRUE)

set_style_options(sheet_name = "age_sex")

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

set_style_options(sheet_name = "edu_year")

tab3 <- my_data |> any_table(rows       = "education",
                             columns    = "year",
                             values     = weight,
                             statistics = "pct_group",
                             formats    = list(education = education.),
                             na.rm      = TRUE)

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

# Reset the global options afterwards
set_print(TRUE)
set_output("excel")

Description

Compute new variables without having to write the name of the data frame multiple times. It can handle all kinds of operations like simple value assignment or calculations, but also can make use of other functions.

In addition it can be used in a conditional do_if() block.

Usage

compute.(data_frame, ..., monitor = .qol_options[["monitor"]])

Arguments

Details

The loop you can use within compute.() is based on the 'SAS' do-over-loop. This type of loop iterates over every vector that appears in the loop in parallel. Means that in the first iteration all the first vector elements are used, in the second iteration all second elements of every vector, and so on. With this loop you don't have the need to construct an outer loop, but can directly pass in different vectors and let the function handle the loop inside.

Value

Returns a data frame with newly computed variables.

See Also

The following functions can make use of the do_if() filter variables:

Conditions: if.(), else_if.(), else.()

Filter Data Frame: where.()

Create new Variables: compute.()

Examples

# Example data frame
my_data <- dummy_data(1000)

# Simple assignment
assign_df <- my_data |> compute.(new_var1 = 1,
                                new_var2 = "Hello")

# Simple calculation
sum_df <- my_data |> compute.(new_sum = age + sex)

# Using functions
mean_df <- my_data |> compute.(new_mean = collapse::fmean(age))

# Using qol functions
qol_df <- my_data |> compute.(row_sum = row_calculation("sum", state, age, sex))

# Use compute.() as a do-over-loop. In this kind of loop all vectors will be
# advanced one iteration at a time in parallel.
new_vars <- c("var1", "var2", "var3")
money    <- c("income", "expenses", "balance")
multi    <- c(1, 2, 3)

do_over_df <- my_data |> compute.(new_vars = money * multi)

# You can also do all at once
all_df <- my_data |> compute.(new_var1 = 1,
                             new_var2 = "Hello",
                             new_sum  = age + sex,
                             new_mean = mean(age),
                             row_sum  = row_calculation("sum", state, age, sex),
                             new_vars = multi * money)

# compute.() can be used in a do_if() situation and is aware of overarching
# conditions.
age_west. <- discrete_format("under 18"     = 0:17,
                             "18 and older" = 18:100)

age_east. <- discrete_format("under 65"     = 0:64,
                             "65 and older" = 65:100)

do_if_df <- my_data |>
    do_if(state < 11) |>
        compute.(region    = "West",
                 age_group = recode.(age = age_west.)) |>
    else_do() |>
        compute.(region    = "East",
                 age_group = recode.(age = age_east.)) |>
    end_do()

Description

Concatenate multiple variables inside a data frame into a new variable. An automatic or individual padding can be applied. The padding character can be chosen freely.

The function can also be used to give a single variable a padding.

Usage

concat(
  data_frame,
  ...,
  separator = NULL,
  padding_char = NULL,
  padding_length = NULL,
  padding_right = FALSE
)

Arguments

Value

Returns a character vector.

See Also

Other character manipulating functions: sub_string(), remove_blanks()

Examples

# Example data frame
my_data <- dummy_data(100)

# Concatenate variables as provided
my_data[["id1"]] <- my_data |> concat(household_id, state, age)

# Concatenate variables with leading zeros. Each variable will
# receive an individual padding length according to their
# longest value.
my_data[["id2"]] <- my_data |> concat(household_id, state, age,
                                      padding_char = "0")

# Concatenate variables with individual character and lengths.
my_data[["id2"]] <- my_data |> concat(household_id, state, age,
                                      padding_char   = "_",
                                      padding_length = c(5, 3, 4))

# Padding a single variable in place
my_data[["state"]] <- my_data |> concat(state, padding_char = "0")

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)

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)

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

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 = "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_miss = .qol_options[["print_miss"]],
  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().

Other global options: set_titles(), set_footnotes(), set_print(), set_monitor(), set_na.rm(), set_print(), set_print_miss(), set_output().

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.
set_titles("This is title number 1",
           "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")

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

# Also works with characters
my_data |> crosstabs("state", "sex")
my_data |> crosstabs("state", "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(state, sex, by = education)

# Compute different stats
my_data |> crosstabs(state, 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(state, sex, output = "text")

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

# If you want to add hyperlinksto titles and footnotes you can do so by
# adding "link:" followed by the hyperlink to the main text. Linking to another
# cell works with "cell:". To link to a file use "file:" an pass the full file
# path afterwards.
set_titles("This is title number 1",
           "This is title number 2 link: https://cran.r-project.org/",
           "This is title number 3 cell: W22",
           "This is title number 4 file: C:/MyFolder/MyFile.txt")

set_footnotes("This is footnote number 1",
              "This is footnote number 2 file: C:/MyFolder/MyFile.txt",
              "This is footnote number 3 cell: W22",
              "This is footnote number 4 link: https://cran.r-project.org/")

# 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,
                     formats = list(age = age., sex = sex.))

# 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").
#       With the set_style_options you can also set a table style globally.
set_style_options(save_path  = dirname(table_file),
                  file       = basename(table_file),
                  sheet_name = "MyTable")

my_data |> crosstabs(state, 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()

Description

Creates a filter variable based on the given condition. This variable can be accessed by if.(), else_if.(), else.(), where.() and compute.(), enabling these functions to work with an overarching condition. This function can also be used to nest multiple overarching conditions.

else_do(): Checks for existing filter variables and reverses the condition of the last filter variable.

end_do(): Drops the last filter variable.

end_all_do(): Drops all filter variables.

Usage

do_if(data_frame, condition)

else_do(data_frame)

end_do(data_frame)

end_all_do(data_frame)

Arguments

Value

Returns a data frame with a new filter variable.

See Also

The following functions can make use of the do_if() filter variables:

Conditions: if.(), else_if.(), else.()

Filter Data Frame: where.()

Create new Variables: compute.()

Examples

# Example data frame
my_data <- dummy_data(1000)

# Create a simple do-if-block
do_if_df <- my_data |>
    do_if(state < 11) |>
          if.(age < 18, new_var = 1) |>
        else.(          new_var = 2) |>
    else_do() |>
          if.(age < 18, new_var = 3) |>
        else.(          new_var = 4) |>
    end_do()

# do_if() can also be nested
do_if_df <- my_data |>
    do_if(state < 11) |>
        do_if(sex == 1) |>
              if.(age < 18, new_var = 1) |>
            else.(          new_var = 2) |>
        else_do() |>
              if.(age < 18, new_var = 3) |>
            else.(          new_var = 4) |>
        end_do() |>
    else_do() |>
        do_if(sex == 1) |>
              if.(age < 18, new_var = 5) |>
            else.(          new_var = 6) |>
        else_do() |>
              if.(age < 18, new_var = 7) |>
            else.(          new_var = 8) |>
        end_do() |>
    end_do()

# NOTE: Close the do-if-blocks with end_do() to remove the temporary logical
#       filter variables.

# Probably a logical filter variable is exactly what you want. In this case
# just run do_if() without closing the block.
logic_filter_df <- my_data |> do_if(state < 11)

Description

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

• TYPE (character): The active grouping combination for the row (e.g., "year+sex"), or "total" for the grand total.

• TYPE_NR (integer): A unique sequential identifier assigned to each distinct grouping combination (TYPE).

• DEPTH (integer): The number of active grouping variables in the row's combination (e.g., 0 for "total", 1 for single variables, etc.).

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

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 = 25000,
  insert_na = TRUE,
  monitor = .qol_options[["monitor"]]
)

Arguments

Value

Returns a dummy data table.

Examples

my_data <- dummy_data(1000)

Description

Checks for duplicate variable names in a data frame, e.g. AGE, age and Age.

Counts the number of duplicated variables in a data frame. If a variable appears three times, e.g. AGE, age and Age, the variable count will be one.

Usage

get_duplicate_var_names(data_frame)

get_duplicate_var_count(data_frame)

Arguments

Value

get_duplicate_var_names(): Returns a vector of duplicate variable names.

get_duplicate_var_count(): Returns the count of duplicated variables as a numeric value.

Examples

# Example data frame
my_data <- data.frame(age    = 1,
                      AGE    = 2,
                      Age    = 3,
                      sex    = 1)

dup_var_names <- my_data |> get_duplicate_var_names()

dup_var_count <- my_data |> get_duplicate_var_count()

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

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,
  subheader_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,
  by_as_subheaders = FALSE,
  background_color = "",
  header_back_color = "FFFFFF",
  header_font_color = "000000",
  header_font_size = 10,
  header_font_bold = TRUE,
  header_alignment = "center",
  header_stat_merging = "block",
  header_wrap = "1",
  header_indent = 0,
  header_borders = TRUE,
  header_border_color = "000000",
  subheader_back_color = "FFFFFF",
  subheader_font_color = "000000",
  subheader_font_size = 10,
  subheader_font_bold = TRUE,
  subheader_alignment = "center",
  subheader_wrap = "1",
  subheader_indent = 0,
  subheader_borders = TRUE,
  subheader_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 = "")

Description

Generates a data frame which contains all nested combinations of the provided format labels.

Usage

expand_formats(..., names = NULL)

Arguments

Value

Returns a data frames with all format label combinations.

Examples

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

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)

# Expand formats
expand_df <- expand_formats(sex., age.,
                            names = c("sex", "age"))

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 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().

Other global options: set_titles(), set_footnotes(), set_print(), set_monitor(), set_na.rm(), set_print(), set_print_miss(), set_output().

Combine Excel workbooks: combine_into_workbook().

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

Examples

# Example data frame
my_data <- dummy_data(100)

# 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. Linking to another
# cell works with "cell:". To link to a file use "file:" an pass the full file
# path afterwards.
set_titles("This is title number 1",
           "This is title number 2 link: https://cran.r-project.org/",
           "This is title number 3 cell: W22",
           "This is title number 4 file: C:/MyFolder/MyFile.txt")

set_footnotes("This is footnote number 1",
              "This is footnote number 2 file: C:/MyFolder/MyFile.txt",
              "This is footnote number 3 cell: W22",
              "This is footnote number 4 link: https://cran.r-project.org/")

# Print styled data frame
my_data |> export_with_style()

# Retrieve formatted workbook, original table and meta information for further usage
export_list <- 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").
#       With the set_style_options you can also set a table style globally.
set_style_options(save_path  = dirname(table_file),
                  file       = basename(table_file),
                  sheet_name = "MyTable")

my_data |> export_with_style()

# In case you have a good amount of tables, you want to combine in a single
# workbook, you can also catch the outputs and combine them afterwards in one go.
set_style_options(sheet_name = "sheet1")
tab1 <- my_data |> export_with_style(print = FALSE)

set_titles(NULL)
set_style_options(sheet_name = "sheet2")
tab2 <- my_data |> export_with_style(print = FALSE)

set_footnotes(NULL)
set_style_options(sheet_name = "sheet3")
tab3 <- my_data |> export_with_style(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)
combine_into_workbook(tab1, tab2, tab3, file = table_file)

# 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()

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

Description

Remove objects by name or type to free up memory. Uses the base rm() function but provides more flexible ways to remove objects.

Usage

free_memory(names = NULL, types = NULL, envir = .GlobalEnv)

Arguments

Details

free_memory() is based on the 'SAS' function Proc Datasets. Among other things this procedure is able to remove datasets from memory. But not only by writing out the full file name, it is capable of looking for datasets starting with, ending with or containing a certain text. Additionally certain object types can be removed.

Value

Returns removed objects.

Examples

# Example data frames
my_data1 <- dummy_data(10)
my_data2 <- dummy_data(10)
data     <- dummy_data(10)
file     <- dummy_data(10)

# Free memory by name
free_memory("my_:")
free_memory(c("data", "file"))

# Free by type
my_data1 <- dummy_data(10)
my_data2 <- dummy_data(10)
data     <- dummy_data(10)
file     <- dummy_data(10)

free_memory(type = "data.frame")

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,
  means = FALSE,
  titles = .qol_options[["titles"]],
  footnotes = .qol_options[["footnotes"]],
  style = .qol_options[["excel_style"]],
  output = .qol_options[["output"]],
  na.rm = .qol_options[["na.rm"]],
  print_miss = .qol_options[["print_miss"]],
  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().

Other global options: set_titles(), set_footnotes(), set_print(), set_monitor(), set_na.rm(), set_print(), set_print_miss(), set_output().

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.
set_titles("This is title number 1",
           "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")

# 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 = list(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 = list(sex = sex.))

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

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

# If you want to add hyperlinksto titles and footnotes you can do so by
# adding "link:" followed by the hyperlink to the main text. Linking to another
# cell works with "cell:". To link to a file use "file:" an pass the full file
# path afterwards.
set_titles("This is title number 1",
           "This is title number 2 link: https://cran.r-project.org/",
           "This is title number 3 cell: W22",
           "This is title number 4 file: C:/MyFolder/MyFile.txt")

set_footnotes("This is footnote number 1",
              "This is footnote number 2 file: C:/MyFolder/MyFile.txt",
              "This is footnote number 3 cell: W22",
              "This is footnote number 4 link: https://cran.r-project.org/")

# 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").
#       With the set_style_options you can also set a table style globally.
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()

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)

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)

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"]])

Description

hex_to_256(): Generate a 256-color 6x6x6 color cube.

hex_to_ansi(): Applies hex color and font weight to a text as ansi codes.

Usage

hex_to_256(hex_color)

hex_to_ansi(text, hex_color = NULL, bold = FALSE)

Arguments

Value

hex_to_256(): Returns 6x6x6 color cube.

hex_to_ansi(): Returns formatted text.

Examples

color_cube <- hex_to_ansi("#32CD32")

formatted_text <- hex_to_ansi("This is a text to test the coloring",
                              hex_color = "#32CD32", bold = TRUE)

Description

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

import_multi(): Runs multiple imports on all provided files. Is able to import all sheets from xlsx files.

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

export_multi(): Runs multiple exports on a list of data frames. Is able to export to a single xlsx file with multiple sheets.

Usage

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

import_multi(
  file_list,
  sheet = "all",
  region = NULL,
  separator = "auto",
  decimal = "auto",
  var_names = TRUE
)

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

export_multi(
  file_list,
  out_path,
  into_sheets = TRUE,
  separator = NULL,
  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, TXT 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.

Multi functions: Returns a list of data frames.

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.csv",   package = "qol")
txt_file  <- system.file("extdata", "qol_example_data_txt.txt",   package = "qol")
xlsx_file <- system.file("extdata", "qol_example_data_xlsx.xlsx", package = "qol")

# Import: Provide full file path
my_csv  <- import_data(csv_file)
my_csv  <- import_data(txt_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")

# Import multiple files at once
all_files <- import_multi(c(csv_file, txt_file, xlsx_file))

# Example data frame
my_data <- dummy_data(100)

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

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

# Example data frame list
my_list <- list(first      = dummy_data(10),
                second.txt = dummy_data(10))

# Export multiple data frames into one xlsx file
# with multiple sheets
export_multi(my_list, tempdir())

# Export multiple data frames into multiple xlsx files
export_multi(my_list, tempdir(), into_sheets = FALSE)

# Export multiple data frames into multiple csv/txt files
export_multi(my_list, tempdir(), separator = ";")

# Manual cleanup for example
file1 <- file.path(tempdir(), "my_list.xlsx")
file2 <- file.path(tempdir(), "first.xlsx")
file3 <- file.path(tempdir(), "second.xlsx")
file4 <- file.path(tempdir(), "first.csv")
file5 <- file.path(tempdir(), "second.txt")

unlink(c(export_csv, export_xlsx,
         file1, file2, file3, file4, file5))

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

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, extensions = NULL, recursive = 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)

Description

Variables written with a leading "&" inside a text will be resolved into the character or numeric expression the corresponding object is holding.

Usage

macro(text)

apply_macro(character_vector)

Arguments

Details

Macro variables in 'SAS' can be set up with %Let and can act as global accessible variables. This in itself is nothing special to 'R' because basically every object created outside a function is a global variable.

To use these global objects within a text one has to use e.g. paste0("The current year is: ", year). With the macro function one can write it like this: macro("The current year is &year").

So where is the benefit? If implemented within a function, a parameter like "title" or "footnote" in the tabulation functions, can resolve these variables without the need of another function. You can just pass the character expression "The current year is &year" and the implementation inside the function resolves the macro variable directly in place.

Value

macro(): Returns a character.

apply_macro(): Returns a character vector.

See Also

Functions that can make use of macro variables: any_table(), frequencies(), crosstabs(), export_with_style(), summarise_plus()

Within the tabulation functions titles, footnotes, var_labels and stat_labels can resolve macros. Additionally they can be used in the any_table() rows and columns parameter and in the summarise_plus() types parameter.

Examples

# Resolving macro variable in single character
year <- 2026

text <- macro("The current year is &year")

# You can also combine multiple macro variables
some_variable <- "current"
current2026   <- "The current year is"

text_combi <- macro("&&some_variable&year &year")

# Resolving macro variable in character vector
char_vector <- c("The current year is &year",
                 "The &some_variable year is &year",
                 "&&some_variable&year &year")

text_vector <- apply_macro(char_vector)

Description

get_message_stack(): Retrieves the current message stack as list or data frame.

set_no_print(): FALSE by default. If set to TRUE the messages will be formatted and returned but not printed to the console. Can e.g. be used in unit test situations.

set_no_color(): TRUE by default. Suppresses the color codes so that messages can be printed clean.

print_stack_as_messages(): Prints the message stack as actual messages (only not suppressed messages). Can be used to trigger expect_message, expect_warning or expect_error in unit tests.

convert_square_brackets(): Convert different curly bracket patterns into ansi formatting or passes the context of vectors into the text.

Usage

get_message_stack(as_data_frame = FALSE)

set_no_print(value = FALSE)

set_no_color(value = TRUE)

print_stack_as_messages(type = NULL)

convert_square_brackets(text, ...)

Arguments

Details

The message types in which you can enter custom texts, are capable of using different styling operators. These are:

• Insert list of elements: [vector_name]

• Adding conditional words, if list of elements has more than one element: [?word]

• Adding conditional singular/plural, depending on list of element length: [?singular/plural]

• Bold, italic and underline: [b]some text[/b], [i]some text[/i], [u]some text[/u]

• Coloring parts of the message: [#FF00FF some text]

Value

get_message_stack(): Returns a list of messages or a data frame.

set_no_print(): Returns the global no_print option.

set_no_color(): Returns the global no_color option.

print_stack_as_messages(): Returns NULL.

convert_square_brackets(): Returns formatted text.

See Also

Main printing functions: print_message(), print_headline(), print_start_message(), print_closing(), print_step(), set_up_custom_message()

Description

Printing styled messages for different occasions. There are notifications, warnings, errors, function call headlines, progress and function closing messages. Or just a neutral one.

Usage

print_message(
  type,
  text,
  ...,
  always_print = FALSE,
  utf8 = .qol_messages[["format"]][["utf8"]],
  no_color = .qol_messages[["no_color"]]
)

print_headline(
  text,
  ...,
  line_char = "=",
  max_width = getOption("width"),
  always_print = FALSE,
  utf8 = .qol_messages[["format"]][["utf8"]],
  no_color = .qol_messages[["no_color"]]
)

print_start_message(
  current_time = Sys.time(),
  caller_color = "#63C2C9",
  always_print = FALSE,
  suppress = FALSE,
  utf8 = .qol_messages[["format"]][["utf8"]],
  no_color = .qol_messages[["no_color"]]
)

print_closing(
  time_threshold = 2,
  start_time = .qol_messages[["start_time"]],
  caller_color = "#63C2C9",
  always_print = FALSE,
  suppress = FALSE,
  utf8 = .qol_messages[["format"]][["utf8"]],
  no_color = .qol_messages[["no_color"]]
)

print_step(
  type,
  text,
  ...,
  in_place = FALSE,
  always_print = FALSE,
  utf8 = .qol_messages[["format"]][["utf8"]],
  no_color = .qol_messages[["no_color"]]
)

set_up_custom_message(
  type = "UNICORN",
  color = "#FF00FF",
  ansi_icon = NULL,
  text_icon = "^",
  ansi_wait_icon = NULL,
  text_wait_icon = "?",
  indent = 1,
  text_bold = FALSE,
  text_italic = FALSE,
  text_underline = FALSE,
  text_color = NULL,
  time_color = "#6B6B6B"
)

Arguments

Details

The message types in which you can enter custom texts, are capable of using different styling operators. These are:

• Insert list of elements: [vector_name]

• Adding conditional words, if list of elements has more than one element: [?word]

• Adding conditional singular/plural, depending on list of element length: [?singular/plural]

• Bold, italic and underline: [b]some text[/b], [i]some text[/i], [u]some text[/u]

• Coloring parts of the message: [#FF00FF some text]

Value

Return text without styling or total running time.

set_up_custom_message(): Returns the global list of custom messages.

See Also

Also have a look at the small helpers: get_message_stack(), set_no_print(), set_no_color(), print_stack_as_messages(), convert_square_brackets()

Examples

# Example messages
print_message("NOTE", c("Just a quick note that you can also insert e.g.[? a / ]variable",
                        "name[?s] like this: [listing].",
                        "Depending on the number of variables you can also alter the text."),
             listing = c("age", "state", "NUTS3"))

print_message("WARNING", "Just a quick [#FF00FF colored warning]!")

print_message("ERROR", "Or a [b]bold[/b], [i]italic[/i] and [u]underlined[/u] error.")

print_message("NEUTRAL", c("You can also just output [u]plain text[/u] if you like and use",
                           "[#FFFF00 [b]all the different[/b] [i]formatting options.[/i]]"))

# Different headlines
print_headline("This is a headline")

print_headline("[#00FFFF This is a different headline] with some color",
               line_char = "-")

print_headline("[b]This is a very small[/b] and bold headline",
               line_char = ".",
               max_width = 60)

# Messages with time stamps
test_func <- function(){
    print_start_message()
    print_step("GREY", "Probably not so important")
    print_step("MAJOR", "This is a major step...")
    print_step("MINOR", "Sub step1")
    print_step("MINOR", "Sub step2")
    print_step("MINOR", "Sub step3")
    print_step("MAJOR", "[b]Finishing... [/b][#00FFFF with some color again!]")
    print_closing()
}

test_func()

# See what is going on in the message stack
message_stack <- get_message_stack()

# Print messages on the same line instead of below each other
in_place_steps <- function(){
    print_start_message()

    print_step("MAJOR", "Let's get started...")

    for (i in seq_len(10)){
        print_step("Minor", "This is in place step [i] of 10", i = i, in_place = TRUE)
        Sys.sleep(0.25)
    }

    print_step("MAJOR", "Loop has ended")

    print_closing()
}

in_place_steps()

# Set up a custom message
set_up_custom_message(type           = "HOTDOG",
                      color          = "#B27A01",
                      ansi_icon      = "\U0001f32d",
                      text_icon      = "IOI",
                      ansi_wait_icon = "\U00023f1",
                      text_wait_icon = "/",
                      indent         = 1)

hotdog_print <- function(){
    print_start_message()
    print_message("HOTDOG", c("This is the first hotdog message! Hurray!",
                              "And it is also multiline in this version."))
    print_step("HOTDOG", "Or use as single line message with time stamps.")
    Sys.sleep(0.5)
    print_step("HOTDOG", "Or use as single line message with time stamps.")
    Sys.sleep(0.5)
    print_step("HOTDOG", "Or use as single line message with time stamps.")
    Sys.sleep(0.5)
    print_closing()
}

hotdog_print()

# See new message in the message stack
hotdog_stack <- get_message_stack()

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)

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 = "")

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