apply_limit_max: apply_limit_max
In daviddoret/GRCRToolkit: GRC Toolkit

Description Usage Arguments Value Fields Future enhancements Examples

A shortcut function to apply various types of maximum limits on a data set.

1 2	apply_limit_max(x, limit_value = NULL, limit_behavior = NULL, replace_function = NULL, target_column = NULL, verbosity = NULL, ...)

`x`	A vector of numeric values. Or a dataframe but then parameter `target_column` must be provided or, by default, the limit will be applied to the first column.

A modified vector or dataframe whose values are within the limit

limit_value

A strict (inclusive) lower bound applied to the original values. If NULL or NA, no limit will be applied.

limit_behavior

One of the following options determining how the limit will be applied to the original set of data:

Limit: (default) When a value is beyond limit, apply min/max functions to force it within bounds.
Replace: When a value is beyond limit, get a new one from replace_function until its is within bound.
Discard: When a value is beyond limit, remove it from the sample.
Info: Return a vector of boolean values with TRUE matching the positions of values within limit and FALSE the positions of values beyond limit.

replace_function

If limit_behavior equals Replace, the function to be called to draw new individuals from the population. It is expected that the function receives first an integer parameter corresponding to the number of individuals to be drawn, followed by ...
WARNING #1: replace_function will be called until the population reaches its original size, which may end up in numerous calls or an infinite loop if replace_function does not return enough individuals within limit bounds.
WARNING #2: if x is a dataframe, replace_function must return a dataframe with the same data structure for rbind to succeed.

target_column

If x is a dataframe, the name or index position of the column containing the numeric vector on which to apply the limit.

The replacement algorithm implemented is extremely naive. First, a protection mechanism should be implemented to prevent infinite loops. Second, the ratio of individuals within the limit should be computed from the original population and replacement samples, and should be used to retrieve more individuals than necessary when calling replace_function to reduce the number of loops required.
Provide support for matrices
Provide support for lists

# Examples with vectors
apply_limit_max(x = 1:10)
# Output: [1]  1  2  3  4  5  6  7  8  9 10
apply_limit_max(x = 1:10, limit_value = 5)
# Output: [1]  5  5  5  5  5  6  7  8  9 10
apply_limit_max(x = 1:10, limit_value = 5, limit_behavior = "Limit")
# Output: [1]  5  5  5  5  5  6  7  8  9 10
apply_limit_max(x = 1:10, limit_value = 5, limit_behavior = "Discard")
# Output: [1]  6  7  8  9 10
apply_limit_max(x = rnorm(n=20), limit_value = 0, limit_behavior = "Replace", replace_function = rnorm)
# Output: a default normal sample of size 20 whose values are all >= 0

# Examples with dataframes
apply_limit_max(x = data.frame(x = 1:10, y = 2, z = rnorm(n=10)), limit_value = 5, limit_behavior = "limit", target_column = "x")
apply_limit_max(x = data.frame(x = 1:10, y = 2, z = rnorm(n=10)), limit_value = 5, limit_behavior = "discard", target_column = "x")

# Example with dataframe and replacement
rf <- function(x,...){return(data.frame(x = rnorm(x,...), y = "new individuals"))}
df_original <- data.frame(x = rnorm(12), y = "old individuals")
apply_limit_max(x = df_original, limit_value = 0, limit_behavior = "replace", target_column = "x", replace_function = rf)