stepwise_replacement: implementation of the decomposition algorithm of stepwise...

In DemoDecomp: Decompose Demographic Functions

implementation of the decomposition algorithm of stepwise replacement

Description

This implements the algorithm described in Andreev et al (2002), with defaults set to approximate their recommendations for replacement ordering and result averaging.

Usage

stepwise_replacement(
  func,
  pars1,
  pars2,
  symmetrical = TRUE,
  direction = "up",
  ...
)

Arguments

func	A function specified by the user. This must be able to take the vectors pars1 or pars2 as its argument, and to return the value of the function, y, when evaluated for these rates. It may also have additional arguments, not to be decomposed.
pars1	vector of covariates to be passed on as arguments to func(). Covariates can be in any order, as long as func() knows what to do with them. pars1 is for time 1 (or population 1).
pars2	is the same as pars1 but for time/population 2.
symmetrical	logical. default TRUE as recommended by authors. Shall we average the results of replacing 1 with 2 and 2 with 1?
direction	character. One of "up", "down", or "both". Default "up", as recommended by authors.
...	optional parameters to pass on to func().

Details

The symmetrical argument toggles whether or not we replace pars1 with pars2 (FALSE), or take the arithmetic average or replacement in both directions. direction refers to whether we go from the bottom up or top down, or take the arithmetic average of these when replacing vector elements. Although the total difference will always sum correctly, the calculated contribution from individual components can vary greatly depending on the order in general. Defaults are set to symmetrically replace from the bottom up, per the authors' suggestion.

Value

a matrix of the variable effects that is organized in the same way as pars1 and pars2.

References

\insertRef

horiuchi2008decompositionDemoDecomp \insertRefandreev2012excelDemoDecomp

Examples

data(Mxc1)
data(Mxc2)
# we'll want to pass in these dimensions
dims  <- dim(Mxc1)
# we need parameters in vec form
Mxc1v <- c(Mxc1)
Mxc2v <- c(Mxc2)
B     <- stepwise_replacement(func = Mxc2e0abrvec, 
		pars1 = Mxc1v, pars2 = Mxc2v, dims = dims, 
		# authors' recommendations:
		symmetrical = TRUE, direction = "up")
dim(B) <- dims
# the output, B, is also a single vector. Each element corresponds 
# to the effect of changes in that particular covariate toward the 
# overall change in the function value. sum(B) should equal the
# original difference
(check1 <- Mxc2e0abr(Mxc2) - Mxc2e0abr(Mxc1))
(check2 <- sum(B))


# This package does not supply default plotting functions, but one 
# strategy might be the following:
## Not run: 
Age <- c(0, 1, seq(5, 85, by = 5))
matplot(Age, B, type = 'l', 
xlab = "Age", ylab = "Contrib to diff in e(0)", col = 1:6)
legend("bottomleft",lty=1:5,col=1:6, 
         legend = c("Neoplasms","Circulatory","Respiratory",
			     "Digestive","Acc/viol","Other"))

## End(Not run)

DemoDecomp documentation built on Sept. 20, 2024, 5:09 p.m.