How to use `describe_change`

Introduction

The describe_change function provides a straightforward way to describe numerical changes between two values (before and after). The function is flexible, allowing different ways to express the change, such as using percentages, ratios, or numbers, and can be customized through templates and phrasing.

This vignette demonstrates how to use the describe_change function in various scenarios, including basic usage, custom phrasing, and custom templates.

Basic Usage

To describe the change between two numeric values, you can call describe_change with the initial value (before), the new value (after), and specify the type of input and output units. For example:

# Describing a percentage decrease
describe_change(
  before = 1,
  after = 0.5,
  input_unit = "ratio",
  output_unit = "percent"
)
#> decreased by 50 percent

In this example, the input values are treated as ratios (e.g., 1 represents 100%, and 0.5 represents 50%), and the output is expressed as a percentage.

Including Values in the Description

If you want to include the initial (before) and new (after) values in the output, set the include_values argument to TRUE. This can be useful when you want to provide more context in your description.

# Including before and after values in the description
describe_change(
  before = 100,
  after = 120,
  input_unit = "number",
  output_unit = "number",
  include_values = TRUE
)
#> increased by 20, from 100 to 120

By setting include_values = TRUE, the output now includes the original values, offering more detailed information about the change.

Custom Phrasing

You can customize how the function expresses increases, decreases, or no changes by providing a direction_phrases argument. This argument allows you to specify your own phrasing for each case.

# Custom phrasing for increase and decrease
describe_change(
  before = 33,
  after = 66,
  input_unit = "percent",
  output_unit = "percent",
  direction_phrases = c(
    increase = "rose by",
    decrease = "fell by",
    none = "stagnated"
  )
)
#> rose by 100 percent

Here, we used "rose by" for increases and "fell by" for decreases instead of the default "increased by" and "decreased by".

Custom Template

The describe_change function supports custom templates via the template argument. You can include placeholders such as {direction}, {change}, and {unit} to dynamically insert values into the final description.

# Custom template for describing the change in people
describe_change(
  before = 10,
  after = 12,
  input_unit = "number",
  output_unit = "number",
  template = "{direction} {change} people"
)
#> increased by 2 people

The template argument gives you complete control over the output format, making the function adaptable to various use cases.

Handling Edge Cases

The function is designed to handle common edge cases, such as when the initial and new values are the same:

# No change in values
describe_change(
  before = 50,
  after = 50,
  input_unit = "number",
  output_unit = "number"
)
#> remained unchanged

In this case, the function returns a message indicating that there was no change.

Invalid Input/Output Unit Combinations

The describe_change function ensures that the combination of input_unit and output_unit is valid for the given values. For example, certain combinations require the before value to be non-zero. If an invalid combination is detected, an error is raised:

# Invalid combination where 'before' is zero and output unit is 'percent'
describe_change(
  before = 0,
  after = 10,
  input_unit = "number",
  output_unit = "percent"
)
#> Error in `describe_change()`:
#> ! 'before' cannot be zero for the given input/output unit combination.

This helps prevent issues like divide-by-zero errors, especially when working with percentages or ratios. The function will guide you toward valid input and output unit selections.

Conclusion

The describe_change function is a flexible tool for describing numerical changes. Whether you’re working with percentages, ratios, or raw numbers, this function provides clear, customizable descriptions of changes between two values.

The ability to modify templates and direction phrases makes the function adaptable for various contexts, from simple percentage changes to more complex descriptions that require including specific units or values.

For more advanced usage and customization, refer to the function’s documentation and examples.