Skip to contents

Define a Hierarchical Variable Format

Source: R/varformat_new.R
new_format.Rd

Allows the creation of hierarchical variable formats with optional "total" and "other" categories.

Usage

new_format(
  ...,
  name = NULL,
  var = NULL,
  add_total = FALSE,
  add_total_overlapping = FALSE,
  total_subset_label = "davon",
  add_other = FALSE,
  add_other_na = FALSE,
  code_then_label = TRUE
)

Arguments

...

One or more variable format entries, which can be:

  • Character string representing parent of collectively exhaustive subsets (must be followed by a list with subsets).

  • Two-sided formula specifying code ~ label or label ~ code. The following shorthand codes are allowed:

    • 7 for . == 7

    • c(7, 9) for . %in% c(7, 9)

    • 7:9 for . %in% 7:9

  • List representing subsets of the previous entry, with an attribute subset containing logical values exhaustive and disjoint.

name

Name for the resulting variable format as character string. If name = NULL (default) and var is provided, a name is generated from var. Either name or var must be provided.

var

Variable name to replace the shorthand . in formulas. Either name or var must be provided.

add_total

Logical or character. Adds a row with the total for disjoint subsets at the top. TRUE generates a row named "Total"; a string provides a custom label. FALSE (default) adds no row. Mutually exclusive with add_total_overlapping.

add_total_overlapping

Logical or character. Adds a row with the total for overlapping subsets at the top. TRUE generates a row named "Total"; a string provides a custom label. FALSE (default) adds no row. Mutually exclusive with add_total.

total_subset_label

Character. Label to be used for subsets of total added by add_total or add_total_overlapping.

add_other

Logical or character. Adds a row at the bottom containing all values not covered by existing codes and not is.na(var). Requires var to be set. TRUE generates a row named "Other (non-NA values of var)"; a string provides a custom label. FALSE (default) adds no row. Mutually exclusive with add_other_na.

add_other_na

Logical or character. Adds a row at the bottom containing all values not covered by existing codes (including NA). TRUE generates a row named "Other"; a string provides a custom label. FALSE (default) adds no row. Mutually exclusive with add_other.

code_then_label

Logical, default TRUE. Determines whether the formulas in ... are interpreted as code ~ label (TRUE) or label ~ code (FALSE).

Value

An object of class procr_varformat, which is a list with two elements:

  • formula: the name as a symbol.

  • data: a list containing a data frame named name, with structure as documented in new_varformat_data_row()

Details

  • All parameters must be explicitly named. Not naming a parameter will throw an error. This allows future changes to the parameters and their order without breaking existing code.

  • For add_total, the total is calculated not as the sum of all items, but rather as a set union - i.e. all other conditions are combined using | (logical OR). This is slightly less computationally efficient, but works neatly with overlapping subsets.

  • The parameter add_other/add_other_na is processed before add_total. As a consequence, a computed total will always include "Other" values.

  • This function works similarly to variable preparation and format specification in SAS. However, it additionally allows the specification of hierarchies between individual items.

See also

new_format_asis(), total_format()

Examples

new_format(var = Sepal.Length,
           "short",
           ss_all(. < 5 ~ "< 5",
                  5 ~ "5"),
           "long",
           ss_all(. > 5 & . <= 6 ~ "5 - 6",
                  . > 6 & . <= 6 ~ "6 - 7"),
           add_total = TRUE,
           add_other = TRUE)
#> Sepal.Length                               code                                 
#> ╲╴Total                                    Sepal.Length < 5 | Sepal.Length %... 
#>    ├╴short                                 Sepal.Length < 5 | Sepal.Length %... 
#>    │  ├╴< 5                                Sepal.Length < 5                     
#>    │  └╴5                                  Sepal.Length %in% 5                  
#>    ├╴long                                  Sepal.Length > 5 & Sepal.Length <... 
#>    │  ├╴5 - 6                              Sepal.Length > 5 & Sepal.Length <= 6 
#>    │  └╴6 - 7                              Sepal.Length > 6 & Sepal.Length <= 6 
#>    └╴Other (non-NA values of Sepal.Length) !(Sepal.Length < 5 | Sepal.Length... 
#>