groupdata2 (version 2.0.5)

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

Description

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
)

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()).

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)

Author

Ludvig Renbo Olsen,

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")