differs_from_previous: Find values in a vector that differ from the previous value

In LudvigOlsen/R-splitters: Creating Groups from Data

Find values in a vector that differ from the previous value

Description

\Sexpr[results=rd, stage=render]{lifecycle::badge("maturing")}

Finds values, or indices of values, that differ from the previous value by some threshold(s).

Operates with both a positive and a negative threshold. Depending on `direction`, it checks if the difference to the previous value is:

• greater than or equal to the positive threshold.

• less than or equal to the negative threshold.

Usage

differs_from_previous(
  data,
  col = NULL,
  threshold = NULL,
  direction = "both",
  return_index = FALSE,
  include_first = FALSE,
  handle_na = "ignore",
  factor_conversion_warning = TRUE
)

Arguments

data	data.frame or vector. N.B. If checking a factor, it is converted to a character vector. This means that factors can only be used when `threshold` is NULL. Conversion will generate a warning, which can be turned off by setting `factor_conversion_warning` to FALSE. N.B. If `data` is a grouped data.frame, the function is applied group-wise and the output is a list of vectors. The names are based on the group indices (see dplyr::group_indices()).
col	Name of column to find values that differ in. Used when `data` is data.frame. (Character)
threshold	Threshold to check difference to previous value to. NULL, numeric scalar or numeric vector with length 2. NULL Checks if the value is different from the previous value. Ignores `direction`. N.B. Works for both numeric and character vectors. Numeric scalar Positive number. Negative threshold is the negated number. N.B. Only works for numeric vectors. Numeric vector with length 2 Given as c(negative threshold, positive threshold). Negative threshold must be a negative number and positive threshold must be a positive number. N.B. Only works for numeric vectors.
direction	both, positive or negative. (character) both Checks whether the difference to the previous value is greater than or equal to the positive threshold. less than or equal to the negative threshold. positive Checks whether the difference to the previous value is greater than or equal to the positive threshold. negative Checks whether the difference to the previous value is less than or equal to the negative threshold.
return_index	Return indices of values that differ. (Logical)
include_first	Whether to include the first element of the vector in the output. (Logical)
handle_na	How to handle NAs in the column. "ignore" Removes the NAs before finding the differing values, ensuring that the first value after an NA will be correctly identified as new, if it differs from the value before the NA(s). "as_element" Treats all NAs as the string "NA". This means, that threshold must be NULL when using this method. Numeric scalar A numeric value to replace NAs with.
factor_conversion_warning	Whether to throw a warning when converting a factor to a character. (Logical)

Value

vector with either the differing values or the indices of the differing values.

N.B. If `data` is a grouped data.frame, the output is a list of vectors with the differing values. The names are based on the group indices (see dplyr::group_indices()).

Author(s)

Ludvig Renbo Olsen, [e-mail]

See Also

Other l_starts tools: find_missing_starts(), find_starts(), group(), group_factor()

Examples

# Attach packages
library(groupdata2)

# Create a data frame
df <- data.frame(
  "a" = factor(c("a", "a", "b", "b", "c", "c")),
  "n" = c(1, 3, 6, 2, 2, 4)
)

# Get differing values in column 'a' with no threshold.
# This will simply check, if it is different to the previous value or not.
differs_from_previous(df, col = "a")

# Get indices of differing values in column 'a' with no threshold.
differs_from_previous(df, col = "a", return_index = TRUE)

# Get values, that are 2 or more greater than the previous value
differs_from_previous(df, col = "n", threshold = 2, direction = "positive")

# Get values, that are 4 or more less than the previous value
differs_from_previous(df, col = "n", threshold = 4, direction = "negative")

# Get values, that are either 2 or more greater than the previous value
# or 4 or more less than the previous value
differs_from_previous(df, col = "n", threshold = c(-4, 2), direction = "both")

LudvigOlsen/R-splitters documentation built on March 7, 2024, 6:59 p.m.