A function to create "talking points" that describes the difference between two values.

compare_values(
x,
y,
orig_values = "{x} vs. {y}",
plural_phrases = NULL,
n_decimal = 1,
round_all = TRUE,
multiplier = 1,
check_rounding = TRUE
)

## Arguments

x

a numeric value to compare to the reference value of 'y'

y

a numeric value to act as a control for the 'x' value

trend_phrases

list of values to use for when x is more than y or x is less than y. You can pass it just trend_terms (the default) and call the result with "...{trend}..." or pass is a named list (see examples)

orig_values

a string using glue syntax. example: ({x} vs {y})

plural_phrases

named list of values to use when difference (delta) is singular (delta = 1) or plural (delta != 1)

n_decimal

numeric value to limit the number of decimal places in the returned values.

round_all

logical value to indicate if all values should be rounded. When FALSE, the values will return with no modification. When TRUE (default) all values will be round to the length specified by 'n_decimal'.

multiplier

number indicating the scaling factor. When multiplier = 1 (default), 0.25 will return 0.25. When multiplier = 100, 0.25 will return 25.

check_rounding

when TRUE (default) inputs will be checked to confirm if a difference of zero may be due to rounding. Ex: 0.16 and 0.24 with 'n_decimal = 1' will both return 0.2. Because this will show no difference, a message will be displayed

## Value

compare_values() returns a list object that can be used with glue syntax

## Details

Given compare_values(x = 8, y = 10) the following items will be returned in the list:

 item value description x 2 original x value to compare against y y 10 original y value delta 8 absolute difference between x & y delta_p 80 % difference between x & y article_delta "an 8" delta with the article included article_delta_p "an 80" delta_p with the article included raw_delta -8 true difference between x & y raw_delta_p -80 true % difference between x & y article_raw_delta "a -8" raw_delta with the article article_raw_delta_p "a -80" raw_delta_p with the article sign -1 the direction, 1 (increase), -1 (decrease), or 0 (no change) orig_values "2 vs. 10" shorthand for {x} vs {y} trend "decrease" influenced by the values in trend_phrases argument

headline(), trend_terms(), plural_phrasing() and view_list()

## Examples

# the values can be manually entered

compare_values(10, 8) |> head(2)
#> $x #> [1] 10 #> #>$y
#> [1] 8
#>
# percent difference (10-8)/8
compare_values(10, 8)$delta_p #> [1] 25 # trend_phrases returns an object called trend if nothing is passed compare_values(10, 8)$trend
#> [1] "increase"

# or if one argument is passed using trend_terms()
compare_values(10, 8, trend_phrases = trend_terms(more = "higher"))$trend #> [1] "higher" # if a named list is used, the objects are called by their names compare_values( 10, 8, trend_phrases = list( more = trend_terms(), higher = trend_terms("higher", "lower") ) )$higher
#> [1] "higher"

# a phrase about the comparison can be edited by providing glue syntax
# 'c' = the 'compare' value, 'r' = 'reference'
compare_values(10, 8, orig_values = "{x} to {y} people")$orig_values #> 10 to 8 people # you can also adjust the rounding, although the default is 1 compare_values(0.1234, 0.4321)$orig_values
#> 0.1 vs. 0.4
compare_values(0.1234, 0.4321, n_decimal = 3)$orig_values #> 0.123 vs. 0.432 # or add a multiplier compare_values(0.1234, 0.4321, multiplier = 100)$orig_values
#> 12.3 vs. 43.2