Package 'rpanelrev'

Reverse the Order of Values of Time Series and Multidimensional Panels

Description

Reverses the values of selected variables along the last dimension of a data frame. Reversal is performed separately for every combination of the preceding dimensions, while all dimension variables remain unchanged.

Usage

panelrev(
  data,
  vars,
  dimensions,
  replace = FALSE,
  prefix = "rev_",
  preestimation = NULL,
  estimate = NULL,
  formula = NULL,
  postestimation = NULL,
  ...
)

Arguments

data	data frame Input data containing the dimension variables and the variables to be reversed.
vars	character vector Names of the variables whose values are to be reversed.
dimensions	character vector Names of the variables that uniquely identify observations. The last variable specifies the dimension along which values are reversed, while all preceding variables define independent groups.
replace	logical scalar, default = FALSE If TRUE, the original variables are overwritten with their reversed values. If FALSE, new variables are created using prefix.
prefix	character scalar, default = "rev_" Prefix added to the names of reversed variables when replace = FALSE.
preestimation	function or NULL, default = NULL Function evaluated after the selected variables have been reversed and before estimation. The function must accept the transformed data frame as its first argument and return a data frame. The returned data frame is subsequently passed to estimate.
estimate	function or NULL, default = NULL Estimation function evaluated after reversal and, when supplied, preestimation. The function must accept named arguments data and formula, as well as any additional arguments supplied through .... Examples include stats::lm and stats::glm.
formula	formula or NULL, default = NULL Model formula passed to estimate. Required when an estimation function is supplied.
postestimation	function or NULL, default = NULL Function evaluated after estimation. The function must accept the transformed data frame as its first argument and the fitted model as its second argument. It must return the final result as a named list containing components data and model. The function may add predictions, residuals, standard errors, or other post-estimation quantities to the transformed data frame.
...	Optional. Additional arguments passed to estimate.

Details

The reversed values can either replace the original variables or be stored in new variables constructed by adding a prefix to the original variable names. Optional pre-estimation, estimation, and post-estimation functions can be evaluated after the reversal.

The final variable in dimensions determines the ordering along which the selected variables are reversed. All preceding dimension variables define independent groups.

For example, with

dimensions = c("country", "sector", "year")

reversal is performed along year, separately for each country-sector combination.

The dimension variables themselves are not modified, and the original row order of data is preserved.

Missing values in variables listed in vars are treated as ordinary values and therefore participate in the reversal. Missing values in dimension variables are not permitted.

Each combination of the dimension variables must uniquely identify one observation.

The order of operations is:

1. Reverse the selected variables.

2. Apply preestimation to the transformed data.

3. Evaluate estimate.

4. Apply postestimation to the transformed data and fitted model.

The preestimation function must return a data frame. The postestimation function must return the complete final result as a named list containing data and model. This allows predictions, residuals, standard errors, and other post-estimation quantities to be added to the transformed data.

When replace = TRUE, preestimation, estimate, and postestimation use the overwritten variables. When replace = FALSE, they should refer to the prefixed variable names.

Value

A named list containing at least the following components:

data

The transformed data frame after reversal and, when supplied, application of preestimation and postestimation.

model

The object returned by estimate, or the model component returned by postestimation. If no estimation function is supplied, this component is NULL.

See Also

lm, glm

Examples

## Example: reversal and linear estimation

  data <- data.frame(
      country = rep(c("A", "B"), each = 3L),
      year    = rep(2020:2022, 2L),
      y       = c(10, 20, 30, 40, 50, 60),
      x       = c(1, 2, 3, 4, 5, 6)
  )

  # create prefixed reversed variables
  result <- panelrev(
      data       = data,
      vars       = c("y", "x"),
      dimensions = c("country", "year"),
      prefix     = "rev_"
  )
  print(result$data)
  print(result$model)                                # NULL

  # overwrite variables and estimate a linear model
  result <- panelrev(
      data       = data,
      vars       = c("y", "x"),
      dimensions = c("country", "year"),
      replace    = TRUE,
      estimate   = stats::lm,
      formula    = y ~ x
  )
  print(result$data)
  print(result$model)
  print(summary(result$model))

  # pre-estimation, estimation, and prediction
  result <- panelrev(
      data       = data,
      vars       = c("y", "x"),
      dimensions = c("country", "year"),
      replace    = TRUE,
      preestimation = function(data) {
          data$x_squared <- data$x^2
          data
      },
      estimate = stats::lm,
      formula  = y ~ x + x_squared,
      na.action = stats::na.exclude,
      postestimation = function(data, model) {
          prediction <- stats::predict(
              model,
              newdata = data,
              se.fit  = TRUE
          )

          data$prediction <- as.numeric(prediction$fit)
          data$stdp       <- as.numeric(prediction$se.fit)
          data$residual   <- as.numeric(stats::residuals(model))

          list(
              data  = data,
              model = model
          )
      }
  )
  print(result$data)
  print(result$model)

---