Create a monotonic relationship between two variables

monotonic() returns modified values of input vector y that are smoothed, monotonic, and consistent across all values of input x. It was designed to be used post-fusion when one wants to ensure a plausible relationship between consumption (x) and expenditure (y), under the assumption that all consumers face an identical, monotonic pricing structure. By default, the mean of the returned values is forced to equal the original mean of y (preserve = TRUE). The direction of monotonicity (increasing or decreasing) is detected automatically, so use cases are not limited to consumption and expenditure variables.

Usage

monotonic(
  x,
  y,
  w = NULL,
  preserve = TRUE,
  expend = TRUE,
  fast = TRUE,
  nmax = 5000,
  plot = FALSE
)

Arguments

x: Numeric.
y: Numeric.
w: Numeric. Optional observation weights.
preserve: Logical. Preserve the original mean of the y values in the returned values?
expend: Logical. Assume y is an expenditure variable? If TRUE, a safety check is implemented to ensure y > 0 when x > 0.
fast: Logical. If TRUE, only supsmu is used with coercion of result to monotone.
nmax: Integer. Maximum number of observations to use for smoothing. Set lower for faster computation. nmax = Inf eliminates sampling.
plot: Logical. Plot the (sampled) data points and derived monotonic relationship?

Value

A numeric vector of modified y values. Optionally, a plot showing the returned monotonic relationship.

Details

The initial smoothing is accomplished via supsmu with the result coerced to monotone. If fast = FALSE and the coercion step modifies the values too much, a second smooth is attempted via a scam model with either a monotone increasing or decreasing constraint. If the SCAM fails to fit, the function falls back to lm with simple linear predictions. If y = 0 when x = 0 (as typical for consumption-expenditure variables), then that outcome is enforced in the result. The input data are randomly sampled to no more than nmax observations, if necessary, for speed.

Examples

y <- monotonic(x = recs$propane_btu, y = recs$propane_expend, plot = TRUE)
mean(recs$propane_expend)
mean(y)