monotonic: Create a monotonic relationship between two variables

In ummel/fusionModel: Data fusion and analysis of synthetic data in R

Create a monotonic relationship between two variables

Description

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?

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.

Value

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

Examples

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

ummel/fusionModel documentation built on June 1, 2025, 11 p.m.