compare_values {headliner}

Compare two values and get talking points

Description

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

Usage

compare_values(
  x,
  y,
  trend_phrases = headliner::trend_terms(),
  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

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

Value

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

See Also

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

Examples

# the values can be manually entered

compare_values(10, 8) |> head(2)
# percent difference (10-8)/8
compare_values(10, 8)$delta_p

# trend_phrases returns an object called trend if nothing is passed
compare_values(10, 8)$trend

# or if one argument is passed using trend_terms()
compare_values(10, 8, trend_phrases = trend_terms(more = "higher"))$trend

# 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

# 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

# you can also adjust the rounding, although the default is 1
compare_values(0.1234, 0.4321)$orig_values
compare_values(0.1234, 0.4321, n_decimal = 3)$orig_values
# or add a multiplier
compare_values(0.1234, 0.4321, multiplier = 100)$orig_values