seq_disperse: Sequence generation with dispersion at decimal level

Description

seq_disperse() creates a sequence around a given number. It goes a specified number of steps up and down from it. Step size depends on the number's decimal places. For example, 7.93 will be surrounded by values like 7.91, 7.92, and 7.94, 7.95, etc.

seq_disperse_df() is a variant that creates a data frame. Further columns can be added as in tibble::tibble(). Regular arguments are the same as in seq_disperse(), but with a dot before each.

Usage

seq_disperse(
  from,
  by = NULL,
  dispersion = 1:5,
  offset_from = 0L,
  out_min = "auto",
  out_max = NULL,
  string_output = TRUE,
  include_reported = TRUE,
  track_diff_var = FALSE,
  track_var_change = deprecated()
)
seq_disperse_df(
  .from,
  .by = NULL,
  ...,
  .dispersion = 1:5,
  .offset_from = 0L,
  .out_min = "auto",
  .out_max = NULL,
  .string_output = TRUE,
  .include_reported = TRUE,
  .track_diff_var = FALSE,
  .track_var_change = FALSE
)

Value

seq_disperse() returns a string vector by default (string_output = TRUE) and a numeric vector otherwise.
seq_disperse_df() returns a tibble (data frame). The sequence is stored in the x column. x is string by default (.string_output = TRUE), numeric otherwise. Other columns might have been added via the dots (...).

Arguments

from, .from: Numeric (or string coercible to numeric). Starting point of the sequence.
by, .by: Numeric. Step size of the sequence. If not set, inferred automatically. Default is NULL.
dispersion, .dispersion: Numeric. Vector that determines the steps up and down, starting at from (or .from, respectively) and proceeding on the level of its last decimal place. Default is 1:5, i.e., five steps up and down.
offset_from, .offset_from: Integer. If set to a non-zero number, the starting point will be offset by that many units on the level of the last decimal digit. Default is 0.
out_min, .out_min, out_max, .out_max: If specified, output will be restricted so that it's not below out_min or above out_max. Defaults are "auto" for out_min, i.e., a minimum of one decimal unit above zero; and NULL for out_max, i.e., no maximum.
string_output, .string_output: Logical or string. If TRUE (the default), the output is a string vector. Decimal places are then padded with zeros to match from's number of decimal places. "auto" works like TRUE if and only if from (.from) is a string.
include_reported, .include_reported: Logical. Should from (.from) itself be part of the sequence built around it? Default is TRUE for the sake of continuity, but this can be misleading if the focus is on the dispersed values, as opposed to the input.
track_diff_var, .track_diff_var: Logical. In seq_disperse(), ignore this argument. In seq_disperse_df(), default is TRUE, which creates the "diff_var" output column.
track_var_change, .track_var_change: Renamed to track_diff_var / .track_diff_var.
...: Further columns, added as in tibble::tibble(). Only in seq_disperse_df().

Details

Unlike seq_endpoint() and friends, the present functions don't necessarily return continuous or even regular sequences. The greater flexibility is due to the dispersion (.dispersion) argument, which takes any numeric vector. By default, however, the output sequence is regular and continuous.

Underlying this difference is the fact that seq_disperse() and seq_disperse_df() do not wrap around base::seq(), although they are otherwise similar to seq_endpoint() and friends.

Examples

Run this code

# Basic usage:
seq_disperse(from = 4.02)

# If trailing zeros don't matter,
# the output can be numeric:
seq_disperse(from = 4.02, string_output = FALSE)

# Control steps up and down with
# `dispersion` (default is `1:5`):
seq_disperse(from = 4.02, dispersion = 1:10)

# Sequences might be discontinuous...
disp1 <- seq(from = 2, to = 10, by = 2)
seq_disperse(from = 4.02, dispersion = disp1)

# ...or even irregular:
disp2 <- c(2, 3, 7)
seq_disperse(from = 4.02, dispersion = disp2)

# The data fame variant supports further
# columns added as in `tibble::tibble()`:
seq_disperse_df(.from = 4.02, n = 45)