Skip to contents

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


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



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


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


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)


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


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


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


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'.


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


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


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


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

x2original x value to compare against y
y10original y value
delta8absolute difference between x & y
delta_p80% 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-8true difference between x & y
raw_delta_p-80true % 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-1the 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


# 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
  10, 8,
  trend_phrases = list(
    more = trend_terms(),
    higher = trend_terms("higher", "lower")
#> [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