determinant_selection_table: Potential for Change Index and the Determinant Selection Table

Description

These functions compute the Potential for Change Index for one or multiple (sub-)determinants, the room for improvement (an intermediate estimate), and produce a convenient table with an overview of all (sub-)determinants. Note that for determinant selection purposes, quantitative estimates such as the Potential for Change Index should never be used without also thoroughly inspecting the visualisations of the univariate distributions and the confidence intervals for the associations to the ultimate intervention targets (usually the target behavior or a proxy measure). For this purpose, the Confidence Interval-Based Estimation of Relevance plots can be used (see CIBER()).

Usage

determinant_selection_table(
  data,
  determinants,
  target,
  determinantLabels = NULL,
  targetLabel = NULL,
  sortBy = NULL,
  sortByAbs = TRUE,
  decreasing = TRUE,
  digits = 3,
  increasesAreImprovements = TRUE,
  minimum = base::min,
  maximum = base::max,
  center = base::mean,
  weight = stats::cor,
  type = NULL,
  minimumArgs = list(na.rm = TRUE),
  maximumArgs = list(na.rm = TRUE),
  centerArgs = list(na.rm = TRUE),
  weightArgs = list(use = "complete.obs"),
  potentialScale = NULL,
  headingLevel = 3,
  output = behaviorchange::opts$get("tableOutput")
)
determinantSelectionTable_partial(
  x,
  digits = attr(x, "digits"),
  headingLevel = attr(x, "headingLevel"),
  echoPartial = FALSE,
  partialFile = NULL,
  quiet = TRUE,
  ...
)
# S3 method for determinantSelectionTable
knit_print(
  x,
  digits = attr(x, "digits"),
  headingLevel = attr(x, "headingLevel"),
  echoPartial = FALSE,
  partialFile = NULL,
  quiet = TRUE,
  ...
)
# S3 method for determinantSelectionTable
print(
  x,
  digits = attr(x, "digits"),
  headingLevel = attr(x, "headingLevel"),
  output = attr(x, "output"),
  forceKnitrOutput = FALSE,
  ...
)
potential_for_change_index(
  data,
  determinants,
  target,
  increasesAreImprovements = TRUE,
  sampleLevel = FALSE,
  minimum = base::min,
  maximum = base::max,
  center = base::mean,
  weight = stats::cor,
  type = NULL,
  minimumArgs = list(na.rm = TRUE),
  maximumArgs = list(na.rm = TRUE),
  centerArgs = list(na.rm = TRUE),
  weightArgs = list(use = "complete.obs")
)
room_for_improvement(
  x,
  increasesAreImprovements = TRUE,
  sampleLevel = FALSE,
  minimum = base::min,
  maximum = base::max,
  center = base::mean,
  minimumArgs = list(na.rm = TRUE),
  maximumArgs = list(na.rm = TRUE),
  centerArgs = list(na.rm = TRUE),
  varName = NULL
)

Value

For the individual-level version, a vector or data frame with the same dimensions as provided; for the sample-level version, if a vector is provided, a single number, and if a data frame is provided, a vector with as many values as the data frame has columns. For Determinant Selection Table, a data frame.

Arguments

data: The dataframe containing the variables.
determinants: The name(s) of the determinant(s).
target: The target (e.g. behavior or intention).
determinantLabels, targetLabel: Optionally, labels to use for the (sub-)determinants and the target. The determinantLabels must have the same order as the determinants vector.
sortBy: The column to sort the results by; if not NULL, a number from 1-6 that corresponds to the six columns of the Determinant Selection Table.
sortByAbs: Whether to sort by raw values (FALSE) or their absolute value (TRUE).
decreasing: Whether to sort in decreasing (TRUE) or increasing (FALSE) order.
digits: The number of digits to round to.
increasesAreImprovements: Whether increases are improvements (TRUE) or decreases are improvements (FALSE).
minimum, maximum: The minimum and maximum, as functions that take a vector and return the minimum and maximum scores, as numbers, or as vectors of numbers specifying the minimum and maximum to use for each column in x or determinants, or a lists of functions specifying the functions to use for each column in x or determinants.
center: For the sample-level version, a function that takes a vector and returns the center (e.g. mean, median, etc), or a list of functions specifying the function to use for each column in x or determinants.
weight: The function to return the weight/multiplier to use in the computation.
type: The type of potential for change index. Currently implemented are type '1' and type '2' - see details for more information.
minimumArgs, maximumArgs, centerArgs, weightArgs: lists with arguments to pass to the corresponding functions. Note that these are not vectorized.
potentialScale: The scale with minimum and maximum possible values for the Potential for Change index. If NULL, the minimum is set to 0 and the maximum is set to the highest observed value.
headingLevel: The number of hashes to print in front of the headings when printing while knitting
output: Whether to only output to the viewer (if possible; output='viewer'), or only to the console (output='console'), or to both (output=c('viewer', 'console')). Note that displaying in the viewer requires the htmltools package.
x: For room for improvement, either a numeric vector with scores on a (sub-)determinant, or a data frame with multiple such vectors. For the Determinant Selection Table functions, the object to print/knit.
echoPartial: Whether to show the executed code in the R Markdown partial (TRUE) or not (FALSE).
partialFile: This can be used to specify a custom partial file. The file will have object x available.
quiet: Passed on to knitr::knit() whether it should e chatty (FALSE) or quiet (TRUE).
...: Any additional arguments are passed to the default print method by the print method, and to rmdpartials::partial() when knitting a RMarkdown partial.
forceKnitrOutput: Force knitr output.
sampleLevel: Whether to return sample-level estimates (TRUE) or individual-level estimates (FALSE).
varName: For internal use.

Details

The Potential for Change index was developed by Keegan et al. and is a numerical representation of a number of important features in CIBER() plots (for more details, please see the references below). It turned out a similar measure, the Intervention Potential, was developed by Huber & Mosler (2013). The latter uses regression coefficients as weights, which is problematic for a number of reasons (see Crutzen, Peters & Noijen, 2017), and has therefore not been implemented as a default, but it is possible to use regression coefficients by specifying a custom weight function.

The original Potential for Change Index was conceptualized to optimize intervention tailoring and improve the prediction of individual-level intervention effectiveness. A second conceptualization of the Potential for Change Index can facilitate sub-determinant selection.

In addition to using the minimum, maximum, center, and weight functions to specify custom functions, specific types have also been implemented to quickly use a prespecified combination of functions.

The first (type = '1') is computed as follows:

For sub-determinants with a positive zero-order correlation with behavior, the sample mean is subtracted from the observed maximum score, and the result is multiplied by the zero-order correlation;
For sub-determinants with a negative zero-order correlation with behavior, the sample mean is subtracted from the observed minimum score, and the result is multiplied by the zero-order correlation.

The second (type = '2') is computed as follows:

For sub-determinants with a positive zero-order correlation with behavior, the sample mean is subtracted from the .95 quantile of the scores, and the result is multiplied by the squared zero-order correlation (i.e. the proportion of explained variance);
For sub-determinants with a negative zero-order correlation with behavior, the sample mean is subtracted from the .05 quantile of the scores, and the result is multiplied by the squared zero-order correlation (i.e. the proportion of explained variance);

The second variant effectively takes the 5% trimmed maximum and minimum, rendering it less sensitive to outliers, penalizes weak associations with behavior more severely, and decreases sensitivity to differences between correlations. These differences should render the second variant a bit more robust over different samples.

The room for improvement is one of the ingredients of the Potential for Change Index or P_delta, a generalized version of the Intervention Potential. The Determinant Selection Table efficiently presents the Potential for Change Indices for a set of (sub-)determinants.

References

Knittle, K. P., Peters, G.-J. Y., Heino, M. T. J., Tobias, R., & Hankonen, N. (2019). Potential for change: New metrics for tailoring and predicting response to behavior change interventions. tools:::Rd_expr_doi("10/ghqmg3")

Huber, A. C. & Mosler, H.-J. (2013) Determining behavioral factors for interventions to increase safe water consumption: a cross-sectional field study in rural Ethiopia, International Journal of Environmental Health Research, 23:2, 96-107 tools:::Rd_expr_doi("10.1080/09603123.2012.699032")

Examples

Run this code

### Get example data
dat <- get(data("BBC_pp15.1", package="behaviorchange"));

### Individual-level version, for one sub-determinant
P_delta_example <-
  behaviorchange::potential_for_change_index(
    data=dat,
    determinants='highDose_attitude',
    target='highDose_intention'
  );

head(P_delta_example);
hist(P_delta_example);

### Sample-level version
behaviorchange::potential_for_change_index(
  data=dat,
  determinants='highDose_attitude',
  target='highDose_intention',
  sampleLevel = TRUE
);

### Individual-level for multiple determinants
P_delta_example <-
  behaviorchange::potential_for_change_index(
    data=dat,
    determinants=c('highDose_attitude', 'highDose_perceivedNorm'),
    target='highDose_intention'
  );
head(P_delta_example);

### Sample-level version for multiple determinants
behaviorchange::potential_for_change_index(
  data=dat,
  determinants=c('highDose_attitude', 'highDose_perceivedNorm'),
  target='highDose_intention',
  sampleLevel = TRUE
);

### Get the Potential for Change Index Type 2
behaviorchange::potential_for_change_index(
  data=dat,
  determinants=c('highDose_attitude', 'highDose_perceivedNorm'),
  target='highDose_intention',
  type = '2',
  sampleLevel = TRUE
);

### Get a Determinant Selection Table
behaviorchange::determinant_selection_table(
  data=dat,
  determinants = c('highDose_AttBeliefs_long',
                   'highDose_AttBeliefs_intensity',
                   'highDose_AttBeliefs_euphoria'),
  target = 'highDose_intention',
  sortBy = 6
);

### R Markdown partials can smoothly be included in RMarkdown documents
behaviorchange::determinantSelectionTable_partial(
  behaviorchange::determinant_selection_table(
    data=dat,
    determinants = c('highDose_AttBeliefs_long',
                     'highDose_AttBeliefs_intensity',
                     'highDose_AttBeliefs_euphoria'),
    target = 'highDose_intention',
    sortBy = 6
  )
);

### Room for improvement for one variable
head(
  room_for_improvement(
    dat$highDose_AttBeliefs_long
  )
);

room_for_improvement(
  dat$highDose_AttBeliefs_long,
  sampleLevel = TRUE
);

### For multiple (sub-)determinants
head(
  room_for_improvement(
    dat[, c('highDose_AttBeliefs_long',
            'highDose_AttBeliefs_intensity',
            'highDose_AttBeliefs_euphoria')]
  )
);

room_for_improvement(
  dat[, c('highDose_AttBeliefs_long',
          'highDose_AttBeliefs_intensity',
          'highDose_AttBeliefs_euphoria')],
  sampleLevel = TRUE
);

Run the code above in your browser using DataLab