Chapter 1 Introduction

This chapter explains the code behind the calculation system implemented in R using the R6 package. The system is designed to handle various types of calculations, manipulations, and filters on data frames. It includes the definition of the calculation and instat_calculation classes and several methods for performing and managing calculations.

1.1 Calculation Class

The calculation class is an R6 class designed to represent a calculation. It includes methods for initializing, adding sub-calculations, and cloning.

1.1.1 Initialization

The initialize method sets up a new calculation object with various parameters.

calculation <- R6::R6Class("calculation",
                           public = list(
                             initialize = function(function_name = "", parameters = list(), calculated_from = c(), is_recalculable = TRUE,
                                                   sub_calculations = list(), type = "", filter_conditions = list(), filters = list(), name = "") {
                               self$function_name = function_name
                               self$parameters = parameters
                               self$calculated_from = calculated_from
                               self$is_recalculable = is_recalculable
                               self$sub_calculations = sub_calculations
                               self$type = type
                               self$name = name
                               self$filter_conditions = filter_conditions
                               self$filters = filters
                             },
                             function_name = "",
                             parameters = list(), 
                             calculated_from = c(),
                             is_recalculable = TRUE,
                             sub_calculations = list(),
                             filter_conditions = list(),
                             filters = list(),
                             name = "",
                             type = ""
                           )
)

1.1.1.1 Parameters

  • function_name: The name of the function to perform the calculation.
  • parameters: A list of parameters required for the calculation.
  • calculated_from: A vector specifying the source columns for the calculation.
  • is_recalculable: A logical value indicating whether the calculation can be recalculated.
  • sub_calculations: A list of sub-calculations.
  • type: The type of calculation (e.g., “summary”, “filter”).
  • filter_conditions: Conditions for filtering data.
  • filters: Applied filters.
  • name: The name of the calculation.

1.1.2 Methods

1.1.2.1 add_sub_calculation

Adds a sub-calculation to the current calculation.

calculation$set("public", "add_sub_calculation", function(sub_calculation, name) {
  self$sub_calculations[[name]] <- sub_calculation
})

1.1.2.2 data_clone

Clones the calculation object.

calculation$set("public", "data_clone", function() {
  ret <- calculation$new(function_name = self$function_name, parameters = self$parameters, 
                         calculated_from = self$calculated_from, is_recalculable = self$is_recalculable,
                         sub_calculations = self$sub_calculations, type = self$type, 
                         filter_conditions = self$filter_conditions, filters = self$filters,
                         name = self$name)
  return(ret)
})

1.2 Instat Calculation Class

The instat_calculation class extends the calculation class to handle more complex calculations and manage dependencies.

1.2.1 Initialization

The initialize method sets up a new instat_calculation object.

instat_calculation <- R6::R6Class("instat_calculation",
                                  public = list(
                                    initialize = function(function_exp = "", type = "", name = "", result_name = "", result_data_frame = "", manipulations = list(),
                                                          sub_calculations = list(), calculated_from = list(), save = 0, before = FALSE, adjacent_column = "") {
                                      if((type == "calculation" || type == "summary") && missing(result_name)) stop("result_name must be provided for calculation and summary types")
                                      if(type == "combination" && save > 0) {
                                        warning("combination types do not have a main calculation which can be saved. save_output will be stored as FALSE")
                                        save <- 0
                                      }
                                      self$function_exp <- function_exp
                                      self$type <- type
                                      self$name <- name
                                      self$result_name <- result_name
                                      self$result_data_frame <- result_data_frame
                                      self$manipulations <- manipulations
                                      self$sub_calculations <- sub_calculations
                                      self$calculated_from <- calculated_from
                                      self$save <- save
                                      self$before <- before
                                      self$adjacent_column <- adjacent_column
                                    },
                                    name = "",
                                    result_name = "",
                                    result_data_frame = "",
                                    type = "",
                                    manipulations = list(),
                                    sub_calculations = list(),
                                    function_exp = "",
                                    calculated_from = list(),
                                    save = 0,
                                    before = FALSE,
                                    adjacent_column = ""
                                  )
)

1.2.2 Methods

1.2.2.1 data_clone

Clones the instat_calculation object.

instat_calculation$set("public", "data_clone", function(...) {
  ret <- instat_calculation$new(function_exp = self$function_exp, type = self$type,
                                name = self$name, result_name = self$result_name, 
                                manipulations = lapply(self$manipulations, function(x) x$data_clone()), 
                                sub_calculations = lapply(self$sub_calculations, function(x) x$data_clone()),
                                calculated_from = self$calculated_from, save = self$save)
  return(ret)
})

1.3 Applying Calculations

1.3.1 DataBook Methods

1.3.1.1 apply_calculation

Applies a calculation to a data frame.

DataBook$set("public", "apply_calculation", function(calc) {
  if(calc$type == "summary") {
    out <- self$get_data_objects(calc[["parameters"]][["data_name"]])$calculate_summary(calc = calc, ... = calc[["parameters"]][["..."]])
    if(calc[["parameters"]][["store_results"]]) self$append_summaries_to_data_object(out, calc[["parameters"]][["data_name"]], calc[["parameters"]][["columns_to_summarise"]], calc[["parameters"]][["summaries"]], calc[["parameters"]][["factors"]], calc[["parameters"]][["summary_name"]], calc)
    if(calc[["parameters"]][["return_output"]]) return(out)
    else return(NULL)
  }
})

1.3.1.2 save_calculation

Saves a calculation to a data frame.

DataBook$set("public", "save_calculation", function(end_data_frame, calc) {
  self$get_data_objects(end_data_frame)$save_calculation(calc)
})

1.3.2 DataSheet Methods

1.3.2.1 save_calculation

Saves a calculation in the DataSheet.

DataSheet$set("public", "save_calculation", function(calc) {
  if(calc$name == "") calc$name <- next_default_item("calc", names(private$calculations))
  if(calc$name %in% names(private$calculations)) warning("There is already a calculation called ", calc$name, ". It will be replaced.")
  private$calculations[[calc$name]] <- calc
  return(calc$name)
})

1.4 Example Usage

# Create a new calculation
calc <- calculation$new(function_name = "mean", parameters = list(x = 1:10), calculated_from = c("column1"))

# Add a sub-calculation
sub_calc <- calculation$new(function_name = "sum", parameters = list(x = 1:10), calculated_from = c("column2"))
calc$add_sub_calculation(sub_calc, "sub1")

# Clone the calculation
calc_clone <- calc$data_clone()

# Apply a calculation
data_book <- DataBook$new()
result <- data_book$apply_calculation(calc)

# Save a calculation
data_sheet <- DataSheet$new()
data_sheet$save_calculation(calc)

1.5 Conclusion

This documentation provides a detailed overview of the calculation system, including class definitions, methods, and example usage. This system allows for flexible and complex calculations on data frames, supporting various types of manipulations and filters.