abcd {behaviorchange}

Acyclic Behavior Change Diagram

Description

This function generates an acyclic behavior change diagram (ABCD) from a specification in a google sheet or .csv file. An ABCD is a logic model that illustrates the assumptions underlying a behavior change intervention. Specifically, the ABCD shows the assumed causal and structural assumptions, thereby showing what is assumed to cause what (e.g. which elements of the intervention are assumed to influence which aspects of the target population's psychology?) and what is assumed to consist of what (e.g. which determinants are assumed to contain which specific aspects of the target population's psychology?).

Usage

abcd(
  specs,
  specCols = c("bcps", "cnds", "apps", "sdts", "dets", "pobs", "behs"),
  localBackup = NULL,
  title = "Acyclic Behavior Change Diagram\n\n",
  outputFile = NULL,
  outputWidth = 3000,
  outputHeight = 1500,
  includeColNames = TRUE,
  maxLabelLength = 30,
  nodeFontSize = 10,
  edgeFontSize = 8,
  colNameFontSize = nodeFontSize,
  grayscale = FALSE,
  colorTheme = behaviorchange::opts$get("aabbcc"),
  penWidth = 1,
  silent = FALSE,
  returnGraphOnly = FALSE,
  returnSvgOnly = FALSE,
  columnWarning = TRUE,
  graphTheme = list(c("fontname", "Arial", "node")),
  regExReplacements = behaviorchange::opts$get("diagrammerSanitization")
)

## S3 method for class 'abcdiagram'
print(
  x,
  width = x$input$width,
  height = x$input$height,
  title = DiagrammeR::get_graph_name(x$output$graph),
  ...
)

Arguments

specs

The specifications: either a google sheets URL, the path to a local file, a character vector with both, or a matrix or data frame

specCols

The order of the columns. This character vector specified the order of the elements of an ABCD. In the default order, from left to right, these are (see below for definitions and more details):

• bcps = Behavior Change Principles (BCPs);

• cnds = Conditions for effectiveness;

• apps = Applications;

• sdts = Sub-determinants;

• dets = Determinants;

• pobs = Performance Objectives;

• behs = Behaviors;

localBackup

Whether to write the specifications to a local backup

title

The title of the diagram

outputFile

If specified, the ABCD is written to this file using DiagrammeR::export_graph.

outputWidth, outputHeight

If an outputFile is specified, these determine its width and height (in pixels)

includeColNames

Whether to include the column names as titles/legend for the entities in each 'column' of the ABCD.

maxLabelLength

At which width to word wrap the labels.

nodeFontSize, edgeFontSize, colNameFontSize

Font sizes of the nodes (i.e. the text in boxes), edges (basically the conditions for effectiveness) and the column names (at the bottom).

grayscale

Whether to use the colorTheme or produce a grayscale ABCD.

colorTheme

The color theme, a named list containing the colors, each a character vector with three HTML (hex) color values. The list elements have to be named bcp, condition_for_effectiveness, application, sub_determinant, determinant, sub_behavior, and target_behavior, and each must contain a named vector with two elements named fill, stroke, and text, containing the color codes for the fill, stroke, and text, respectively; see behaviorchange::opts$get("aabbcc") for an example.

penWidth

The width of the pen to draw the strokes.

silent

Whether to suppress (TRUE) or show (FALSE) more detailed information.

returnGraphOnly, returnSvgOnly

Whether to return the full results object or only either the DiagrammeR::DiagrammeR graph or a one-value character vector containing a Scalable Vector Graphic as produced by DiagrammeRsvg::export_svg().

columnWarning

Can be used to suppress the warning if the number of columns is too large.

graphTheme

Specific settings to apply to the graph using apply_graph_theme(); a list of vectors, where each vector has three elements: the setting, the value, and what to apply it to ('node', 'edge', or 'graph').

regExReplacements

A list of pairs of regular expressions that will be applied to the specifications before generating the ABCD. This can be used to sanitize problematic characters (e.g. ', " and \).

x

The ABCD object to print (as generated by a call to abcd).

width, height

Width and height to use when printing the ABCD.

...

Any additional arguments are passed on to DiagrammeR::render_graph().

Details

Specifically, a full ABCD is a model that shows the following elements:

• Behavior Change Principles (BCPs): The specific psychological principles engaged to influence the relevant sub-determinants, usually selected using the determinants to which the sub-determinants 'belong'. These are also known as methods of behavior change in the Intervention Mapping framework, or behavior change techniques, BCTs, in the Behavior Change Wheel approach. For a list of 99 BCPs, see Kok et al. (2016).

• Conditions for effectiveness: The conditions that need to be met for a Behavior Change Principle (BCP) to be effective. These conditions depend on the specific underlying Evolutionary Learning Processes (ELPs) that the BCP engages (Crutzen & Peters, 2018). If the conditions for effectiveness (called parameters for effectiveness in the Intervention Mapping framework) are not met, the method will likely not be effective, or at least, not achieve its maximum effectiveness.

• Applications: Since BCP's describe aspects of human psychology in general, they are necessarily formulated on a generic level. Therefore, using them in an intervention requires translating them to the specific target population, culture, available means, and context. The result of this translation is the application of the BCP. Multiple BCPs can be combined into one application; and one BCP can be applied in multiple applications (see Kok, 2014).

• Sub-determinants: Behavior change interventions engage specific aspects of the human psychology (ideally, they specifically, target those aspects found most important in predicting the target behavior, as can be established with CIBER plots. These aspects are called sub-determinants (the Intervention Mapping framework references Change Objectives, which are sub-determinants formulated according to specific guidelines). In some theoretical traditions, sub-determinants are called beliefs.

• Determinants: The overarching psychological constructs that are defined as clusters of specific aspects of the human psychology that explain humans' behavior (and are targeted by behavior change interventions). Psychological theories contain specific definitions of such determinants, and make statements about how they relate to each other and to human behavior. There are also theories (and exists empirical evidence) on how these determinants can be changed (i.e. BCPs), so althought the sub-determinants are what is targeted in an intervention, the selection of feasible BCPs requires knowing to which determinants those sub-determinants belong.

• Performance objectives: The specific sub-behaviors that often underlie (or make up) the ultimate target behavior. These are distinguished from the overarching target behavior because the relevant determinants of these sub-behaviors can be different: for example, the reasons why people do or do not buy condoms can be very different from the reasons why they do or do not carry condoms or why they do or do not negotiate condom use with a sexual partner.

• Behavior: The ultimate target behavior of the intervention, usually an umbrella that implicitly contains multiple performance objectives.

For details, see Peters et al. (2019).

Value

A list consisting of an input, intermediate, and output list, where the ABCD is stored in the output list as a DiagrammeR::DiagrammeR called graph.

Author(s)

Gjalt-Jorn Peters, [e-mail], with contributions from Matti Heino and Sander Eggers.

References

Crutzen, R., & Peters, G.-J. Y. (2018). Evolutionary learning processes as the foundation for behaviour change. Health Psychology Review, 12(1), 43–57. https://doi.org/10.1080/17437199.2017.1362569

Kok, G. (2014). A practical guide to effective behavior change: How to apply theory- and evidence-based behavior change methods in an intervention. European Health Psychologist, 16(5), 156–170. https://doi.org/10.31234/osf.io/r78wh

Kok, G., Gottlieb, N. H., Peters, G.-J. Y., Mullen, P. D., Parcel, G. S., Ruiter, R. A. C., … Bartholomew, L. K. (2016). A taxonomy of behavior change methods: an Intervention Mapping approach. Health Psychology Review, 10(3), 297–312. https://doi.org/10.1080/17437199.2015.1077155

Peters, G.-J. Y., et al. (2019) The core of behavior change: introducing the Acyclic Behavior Change Diagram to report and analyze interventions.

Examples

### Load one of the ABCD matrices supplied
### with the behaviorchange package
data(abcd_specification_example_xtc);

### Create ABCD matrix (using 'print' to allow pkgdown() to print properly).
print(behaviorchange::abcd(abcd_specification_example_xtc));

### Other examples not executed during testing as creating ABCDs takes long

## Not run: 
### Change the appearance; note that many attributes are specified
### for specific elements, and element-level settings always override
### the global settings that can be specified here.
print(
  behaviorchange::abcd(
    abcd_specification_example_xtc,
    graphTheme = list(
      c("fontname", "Courier New", "node")
    )
  )
);

## End(Not run)