Type:	Package
Title:	Tools for Behavior Change Researchers and Professionals
Version:	0.5.5
Maintainer:	Gjalt-Jorn Peters <behaviorchange@opens.science>
License:	GPL (≥ 3)
Description:	Contains specialised analyses and visualisation tools for behavior change science. These facilitate conducting determinant studies (for example, using confidence interval-based estimation of relevance, CIBER, or CIBERlite plots, see Crutzen, Noijen & Peters (2017) <doi:10/ghtfz9>), systematically developing, reporting, and analysing interventions (for example, using Acyclic Behavior Change Diagrams), and reporting about intervention effectiveness (for example, using the Numbers Needed for Change, see Gruijters & Peters (2017) <doi:10/jzkt>), and computing the required sample size (using the Meaningful Change Definition, see Gruijters & Peters (2020) <doi:10/ghpnx8>). This package is especially useful for researchers in the field of behavior change or health psychology and to behavior change professionals such as intervention developers and prevention workers.
URL:	https://r-packages.gitlab.io/behaviorchange
BugReports:	https://gitlab.com/r-packages/behaviorchange/-/issues
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.3
Depends:	R (≥ 3.5.0)
Imports:	BiasedUrn (≥ 1.07), data.tree (≥ 0.7.5), DiagrammeR (≥ 1.0.0), DiagrammeRsvg (≥ 0.1.0), ggplot2 (≥ 2.2.1), googlesheets4 (≥ 0.2.0), gridExtra (≥ 2.3), gtable (≥ 0.2.0), knitr (≥ 1.0), methods (≥ 3.0), rmdpartials (≥ 0.5.0), ufs (≥ 0.3.2), viridis (≥ 0.5.1), yum (≥ 0.0.1)
Suggests:	htmltools, kableExtra, openxlsx, png (≥ 0.1), rmarkdown, rstudioapi, rsvg, webshot
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2023-03-04 22:07:43 UTC; gjalt
Author:	Gjalt-Jorn Peters [aut, cre], Rik Crutzen [ctb], Stefan Gruijters [ctb]
Repository:	CRAN
Date/Publication:	2023-03-04 23:20:02 UTC

behaviorchange: Tools for Behavior Change Researchers and Professionals

Description

Contains specialised analyses and visualisation tools for behavior change science. These facilitate conducting determinant studies (for example, using confidence interval-based estimation of relevance, CIBER, or CIBERlite plots, see Crutzen, Noijen & Peters (2017) doi:10/ghtfz9), systematically developing, reporting, and analysing interventions (for example, using Acyclic Behavior Change Diagrams), and reporting about intervention effectiveness (for example, using the Numbers Needed for Change, see Gruijters & Peters (2017) doi:10/jzkt), and computing the required sample size (using the Meaningful Change Definition, see Gruijters & Peters (2020) doi:10/ghpnx8). This package is especially useful for researchers in the field of behavior change or health psychology and to behavior change professionals such as intervention developers and prevention workers.

Details

Contains specialised analyses and visualisation tools for behavior change science. These facilitate conducting determinant studies (for example, using confidence interval-based estimation of relevance, CIBER, or CIBERlite plots), systematically developing, reporting, and analysing interventions (for example, using acyclic behavior change diagrams), and reporting about intervention effectiveness (for example, using the Numbers Needed for Change), and computing the required sample size (using the Meaningful Change Definition). This package is especially useful for researchers in the field of behavior change or health psychology and to behavior change professionals such as intervention developers and prevention workers.

Author(s)

Maintainer: Gjalt-Jorn Peters behaviorchange@opens.science (ORCID)

Other contributors:

• Rik Crutzen rik.crutzen@maastrichtuniversity.nl (ORCID) [contributor]

• Stefan Gruijters mail@stefangruijters.nl (ORCID) [contributor]

See Also

Useful links:

• https://r-packages.gitlab.io/behaviorchange

• Report bugs at https://gitlab.com/r-packages/behaviorchange/-/issues

Confidence Interval-Based Estimation of Relevance (CIBER)

Description

This function generates a high-level plot consisting of several diamond plots. This function is useful for estimating the relative relevance of a set of determinants of, for example, behavior. The plot in the left hand panel shows each determinant's distribution with a diamond representing the confidence interval. The right hand plot shows the determinants' associations to one or more 'target' variables, such as behavior or determinants of behavior.

Usage

CIBER(
  data,
  determinants,
  targets,
  conf.level = list(means = 0.9999, associations = 0.95),
  subQuestions = NULL,
  leftAnchors = rep("Lo", length(determinants)),
  rightAnchors = rep("Hi", length(determinants)),
  outputFile = NULL,
  outputWidth = NULL,
  outputHeight = NULL,
  outputUnits = "in",
  outputParams = list(),
  orderBy = NULL,
  decreasing = NULL,
  numberSubQuestions = FALSE,
  generateColors = list(means = c("red", "blue", "green"), associations = c("red",
    "grey", "green")),
  strokeColors = viridis::viridis(length(targets)),
  vLines = c(-0.5, 0, 0.5),
  vLineColors = "grey",
  titlePrefix = "Means and associations (r) with",
  titleVarLabels = NULL,
  titleSuffix = "",
  fullColorRange = NULL,
  associationsAlpha = 0.5,
  returnPlotOnly = TRUE,
  drawPlot = TRUE,
  jitterWidth = 0.45,
  baseSize = 0.8,
  dotSize = 2.5 * baseSize,
  baseFontSize = 10 * baseSize,
  theme = ggplot2::theme_bw(base_size = baseFontSize),
  xbreaks = NULL,
  rsq = TRUE,
  ...
)

binaryCIBER(
  data,
  determinants,
  targets,
  conf.level = list(means = 0.9999, associations = 0.95),
  subQuestions = NULL,
  leftAnchors = rep("Lo", length(determinants)),
  rightAnchors = rep("Hi", length(determinants)),
  outputFile = NULL,
  outputWidth = NULL,
  outputHeight = NULL,
  outputUnits = "in",
  outputParams = list(),
  orderBy = NULL,
  decreasing = NULL,
  numberSubQuestions = FALSE,
  comparisonColors = viridis::viridis(2, end = 0.5),
  categoryLabels = NULL,
  generateColors = list(means = c("red", "blue", "green"), associations = c("red",
    "grey", "green")),
  strokeColors = viridis::viridis(length(targets)),
  vLines = c(-0.8, 0, 0.8),
  vLineColors = "grey",
  titlePrefix = "Means and associations (d) with",
  titleVarLabels = NULL,
  titleSuffix = "",
  fullColorRange = NULL,
  associationsAlpha = 0.5,
  returnPlotOnly = TRUE,
  drawPlot = TRUE,
  baseSize = 0.8,
  dotSize = 2.5 * baseSize,
  baseFontSize = 10 * baseSize,
  theme = ggplot2::theme_bw(base_size = baseFontSize),
  xbreaks = NULL,
  ...
)

detStructCIBER(
  determinantStructure,
  data,
  conf.level = list(means = 0.9999, associations = 0.95),
  subQuestions = NULL,
  leftAnchors = rep("Lo", length(determinants)),
  rightAnchors = rep("Hi", length(determinants)),
  orderBy = 1,
  decreasing = NULL,
  generateColors = list(means = c("red", "blue", "green"), associations = c("red",
    "grey", "green")),
  strokeColors = NULL,
  titlePrefix = "Means and associations with",
  titleVarLabels = NULL,
  titleSuffix = "",
  fullColorRange = NULL,
  associationsAlpha = 0.5,
  baseSize = 0.8,
  dotSize = 2.5 * baseSize,
  baseFontSize = 10 * baseSize,
  theme = ggplot2::theme_bw(base_size = baseFontSize),
  ...
)

Arguments

Details

Details are explained in Crutzen & Peters (2017).

Value

Depending on the value of returnPlotOnly, either the plot only (a gtable object) or an object containing most objects created along the way (in which case the plot is stored in $output$plot).

The plot has width and height attributes which can be used when saving the plot.

References

Crutzen, R., Peters, G.-J. Y., & Noijen, J. (2017). How to Select Relevant Social-Cognitive Determinants and Use them in the Development of Behaviour Change Interventions? Confidence Interval-Based Estimation of Relevance. http://dx.doi.org/

See Also

determinantStructure

Examples

### This example uses the determinant study Party Panel 17.1;
### see ?behaviorchange::BBC_data for more information.
data(BBC_pp17.1);
behaviorchange::CIBER(data=BBC_pp17.1,
                      determinants=c('epw_AttExpect_hearingDamage',
                                     'epw_AttExpect_highTone',
                                     'epw_AttExpect_musicVolume',
                                     'epw_AttExpect_musicFidelity',
                                     'epw_AttExpect_loudConversation',
                                     'epw_AttExpect_musicFocus',
                                     'epw_AttExpect_musicEnjoy'),
                      targets=c('epw_attitude'));

### With a binary target
data(BBC_pp17.1);
behaviorchange::binaryCIBER(data=BBC_pp17.1,
                            determinants=c('epGeneralBeliefs_loudnessPreference',
                                           'epGeneralBeliefs_loudnessGenre',
                                           'epGeneralBeliefs_loudnessTooMuch',
                                           'epGeneralBeliefs_priceFoam',
                                           'epGeneralBeliefs_priceSilicon',
                                           'epGeneralBeliefs_priceCustom'),
                            targets=c('epPossession'),
                            categoryLabels = c('no',
                                               'yes'));

CIBERlite

Description

CIBERlite plots can be used to quickly get an idea of means and correlations of a small number of determinants. They were developed to facilitate conducting and interpreting determinant studies by prevention professionals.

Usage

CIBERlite(
  data,
  determinants,
  targets,
  determinantOrder = NULL,
  determinantLabels = NULL,
  subDeterminantLabels = NULL,
  title = NULL,
  conf.level = 0.95,
  scaleRange = NULL,
  determinantAesthetics = list(fill = "black", color = NA, alpha = 0.5),
  subDeterminantAesthetics = list(fill = "black", color = NA, alpha = 0.5),
  rDiamondAesthetics = list(fill = "#c4c4c4", color = NA, alpha = 0.75)
)

Arguments

Details

More details will be provided in a forthcoming paper; until then, see https://CIBERlite.com

Value

A ggplot.

Examples

### This example uses the determinant study Party Panel 15.1;
### see ?behaviorchange::BBC_data for more information.
data(BBC_pp15.1);
CIBERlite(data=BBC_pp15.1,
          determinants=c('highDose_attitude',
                         'highDose_perceivedNorm',
                         'highDose_pbc'),
          targets=c('highDose_intention'));

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

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, gjalt-jorn@a-bc.eu, 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)

Simple example datasets for ABCDs

Description

This are three (nested) datasets illustrating the logic model of change for a simple condom use intervention in a way that can be visualised using the abcd function. The full dataset is abcd_specs_full, a subset that does not explicitly include the conditions for effectiveness (instead showing letters that can then be explained in, for example, the manuscript text) is called abcd_specs_without_conditions, and a version that only contains the information about one sub-behavior (performance objective) is available as abcd_specs_single_po_without_conditions. The variables in the full dataset are:

Usage

data(abcd_specs_complete)

data(abcd_specs_without_conditions)

data(abcd_specs_single_po_without_conditions)

data(abcd_specification_example_xtc)

data(abcd_specs_dutch_xtc)

data(abcd_specification_empty)

Format

For abcd_specs_complete, a data frame with 7 variables and 7 rows; for abcd_specs_without_conditions, a data frame with 6 variables and 7 rows; for abcd_specs_single_po_without_conditions, a data frame with 5 variables and 4 rows; for abcd_specification_example_xtc and abcd_specs_dutch_xtc, a data frame with 7 variables and 5 rows' and for abcd_specification_empty, a data frame with 7 variables and 1 row.

Details

• ⁠Behavior Change Principles⁠: The behavior change principles (BCPs), also known as methods for behavior change or 'behavior change techniques' (BCTs), that describe the psychological principles that are assumed to realise the change in the (sub-)determinants.

• ⁠Conditions for effectiveness\\n(e.g. parameters for use)⁠: The conditions for effectiveness that describe the constraints and considerations taken into account in the translation of the BCPs to practical applications for the relevant target population, context, culture, etc.

• Applications: The applications of these BCPs. Where the BCPs describe theoretical principles, the applications are more or less tangible intervention elements.

• ⁠Sub-determinants\\n(e.g. beliefs; can be formulated as Change Objectives)⁠: The specific aspects of teh target population's psychology that are targeted by the BCPs (e.g. beliefs, or in Intervention Mapping vocabulary, Change Objectives).

• Determinants: The determinants, psychological constructs, that the targeted sub-determinants are a part of, and that together predict the Performance Objectives (sub-behaviors).

• ⁠Performance Objectives⁠: Explicitly defined sub-behaviors at a level of specificity that distinguishes them from other sub-behaviors, and that together form the target behavior.

• ⁠Target Behavior⁠: The ultimate target behavior, usually defined at a relatively general level.

In addition to these three datasets, a Dutch example specification is included named abcd_specs_dutch_xtc, and the same in English as abcd_specification_example_xtc.

Finally, abcd_specification_empty is an empty 'template' ABCD matrix.

Apply multiple DiagrammeR global graph attributes

Description

Apply multiple DiagrammeR global graph attributes

Usage

apply_graph_theme(graph, ...)

Arguments

Value

The DiagrammeR::DiagrammeR graph.

Examples

abcd_complete  <- behaviorchange::abcd(behaviorchange::abcd_specs_complete)$output$graph;
abcd_complete <- apply_graph_theme(abcd_complete,
                                   c("penwidth", 5, "node"),
                                   c("penwidth", 15, "edge"));

Concatenate to screen without spaces

Description

The cat0 function is to cat what paste0 is to paste; it simply makes concatenating many strings without a separator easier.

Usage

cat0(..., sep = "")

Arguments

Value

Nothing (invisible NULL, like cat).

Examples

cat0("The first variable is '", names(mtcars)[1], "'.");

Create a COMPLECS graph

Description

COMPLECS was developed to help make sense of complex systems. It reads data from a number of worksheets in a spreadsheet and generates a diagram according to those specifications. Originally, COMPLECS was developed to visualise a problem during the needs assessment phase of intervention development.

Usage

complecs(
  input,
  title = "COMPLECS overview",
  layout = "fdp",
  graph_styling = list(c("outputorder", "edgesfirst", "graph"), c("overlap", "false",
    "graph"), c("fixedsize", "false", "node"), c("fontname", "Arial", "graph"),
    c("fontname", "Arial", "node"), c("fontname", "Arial", "edge"), c("headclip", "true",
    "edge"), c("tailclip", "false", "edge")),
  directed = TRUE,
  outputFile = NULL,
  outputWidth = 1600,
  outputHeight = NULL,
  returnDotOnly = FALSE,
  returnSvgOnly = FALSE,
  returnGraphOnly = TRUE,
  maxLabelLength = 20,
  regExReplacements = opts$get("diagrammerSanitization"),
  silent = opts$get("silent")
)

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

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

Arguments

Details

COMPLECS is a recursive acronym for COMPLECS Organises Multiple Players & Linked Environments using Connected Specifications.

Value

A complecs object that includes the graph and the graph in SVG in output$graph and output$graphSvg.

Examples

## Not run: 
### Path in the package with example COMPLECS
exampleCOMPLECS <-
  system.file(
    "extdata",
    "COMPLECS-spec-example.xlsx",
    package = "behaviorchange"
  );

behaviorchange::complecs(
  exampleCOMPLECS
);

### Loading that COMPLECS from a google sheet - but note that
### this requires an internet connection!
behaviorchange::complecs(
  paste0(
    "https://docs.google.com/spreadsheets/d/",
    "1WMO15xroy4a0RfpuZ8GhT-NfDoxwS34w9PrWp8rGjjk"
  )
);

## End(Not run)

Represent a COMPLECS specification as a PRECEDE model

Description

This function reads in a complecs specification and draw a PRECEDE model, with a number of assumptions (see Details section).

Usage

complecs_to_precede(
  input,
  title = "PRECEDE diagram",
  layout = "fdp",
  graph_styling = list(c("outputorder", "edgesfirst", "graph"), c("rankdir", "LR",
    "graph"), c("overlap", "false", "graph"), c("fixedsize", "false", "node"),
    c("fontname", "Arial", "graph"), c("fontname", "Arial", "node"), c("fillcolor",
    "White", "node"), c("shape", "box", "node"), c("style", "filled", "node"),
    c("fontname", "Arial", "edge"), c("headclip", "true", "edge"), c("tailclip", "false",
    "edge")),
  directed = TRUE,
  outputFile = NULL,
  outputWidth = 1600,
  outputHeight = NULL,
  returnDotOnly = FALSE,
  returnSvgOnly = FALSE,
  returnGraphOnly = TRUE,
  maxLabelLength = 60,
  regExReplacements = opts$get("diagrammerSanitization"),
  silent = opts$get("silent")
)

Arguments

Details

Only entities with the following entity types are used from the COMPLECS specification:

• person

• organization

• environmental_condition

• behavior

• determinant

• outcome

Furthermore, it will be assumed that the only direct connections from behavior entities to outcome entities belong to the focal population; therefore, if behaviors of environmental actors are important for an outcome, those behaviors' effects must be represented as environmental_condition entities - otherwise the relevant persons or organizationss will be erroneously considered as focal population members.

Value

A complecs object that includes the graph and the graph in SVG in output$graph and output$graphSvg.

Examples

## Not run: 
### Path in the package with example COMPLECS
exampleCOMPLECS <-
  system.file(
    "extdata",
    "COMPLECS-spec-example.xlsx",
    package = "behaviorchange"
  );

behaviorchange::complecs_to_precede(
  exampleCOMPLECS
);

### Loading that COMPLECS from a google sheet - but note that
### this requires an internet connection!
behaviorchange::complecs_to_precede(
  paste0(
    "https://docs.google.com/spreadsheets/d/",
    "1WMO15xroy4a0RfpuZ8GhT-NfDoxwS34w9PrWp8rGjjk"
  )
);

## End(Not run)

Visualising Numbers Needed for Change

Description

These functions can be used to visualise Numbers Needed for Change (or Numbers Needed to Treat). erDataSeq is a helper function to generate an Event Rate Data Sequence, and it uses convert.threshold.to.er and convert.er.to.threshold to convert thresholds to event rates and vice versa.

Usage

convert.threshold.to.er(
  threshold,
  mean,
  sd,
  eventIfHigher = TRUE,
  pdist = stats::pnorm
)

convert.er.to.threshold(
  er,
  mean,
  sd,
  eventIfHigher = TRUE,
  qdist = stats::qnorm
)

erDataSeq(
  er = NULL,
  threshold = NULL,
  mean = NULL,
  sd = NULL,
  eventIfHigher = TRUE,
  pRange = c(1e-06, 0.99999),
  xStep = 0.01
)

ggNNC(
  cerDataSeq,
  d = NULL,
  eventDesirable = TRUE,
  r = 1,
  xlab = "Continuous outcome",
  plotTitle = c("Numbers Needed for Change = ", ""),
  theme = ggplot2::theme_bw(),
  lineSize = 1,
  cerColor = "#EBF2F8",
  eerColor = "#172F47",
  cerLineColor = "#888888",
  eerLineColor = "#000000",
  dArrowColor = "#000000",
  cerAlpha = 0.66,
  eerAlpha = 0.66,
  xLim = NULL,
  xLimAutoDensityTolerance = 0.001,
  showLegend = TRUE,
  verticalLineColor = "#172F47",
  desirableColor = "#00FF00",
  desirableAlpha = 0.2,
  undesirableColor = "#FF0000",
  undesirableAlpha = 0.2,
  desirableTextColor = "#009900",
  undesirableTextColor = "#990000",
  dArrowDistance = 0.04 * max(cerDataSeq$density),
  dLabelDistance = 0.08 * max(cerDataSeq$density)
)

Arguments

Details

These functions are used by nnc() to show the distributions, and event rates. They probably won't be used much on their own.

Value

erDataSeq returns a data sequence; ggNNC a ggplot2::ggplot().

Author(s)

Gjalt-Jorn Peters & Stefan Gruijters

Maintainer: Gjalt-Jorn Peters gjalt-jorn@userfriendlyscience.com

References

Gruijters, S. L., & Peters, G. Y. (2019). Gauging the impact of behavior change interventions: A tutorial on the Numbers Needed to Treat. PsyArXiv. doi:10.31234/osf.io/2bau7

See Also

nnc()

Examples

### Show distribution for an event rate value of 125
behaviorchange::ggNNC(behaviorchange::erDataSeq(threshold=125, mean=90, sd=30));

### If the event occurs under the threshold instead of
### above it
behaviorchange::ggNNC(behaviorchange::erDataSeq(threshold=125,
                                                mean=90, sd=30,
                      eventIfHigher = FALSE));

### ... And for undesirable events (note how
### desirability is an argument for ggNNC, whereas
### whether an event occurs 'above' or 'below' the
### threshold is an argument for erDataSeq):
behaviorchange::ggNNC(behaviorchange::erDataSeq(threshold=125,
                                                mean=90, sd=30,
                      eventIfHigher = FALSE),
      eventDesirable = FALSE);

### Show event rate for both experimental and
### control conditions, and show the numbers
### needed for change
behaviorchange::ggNNC(behaviorchange::erDataSeq(threshold=125,
                                                mean=90, sd=30),
                      d=.5);

### Illustration of how even with very large effect
### sizes, if the control event rate is very high,
### you'll still need a high number of NNC
behaviorchange::ggNNC(behaviorchange::erDataSeq(er=.9),
                      d=1);

Estimate Cohen's d corresponding to a Meaningful Change Definition

Description

This function uses a base rate (Control Event Rate, argument cer) and a Meaningful Change Definitions (MCD, argument mcd) to compute the corresponding Cohen's d. See Gruijters & Peters (2019) for details.

Usage

dMCD(
  cer,
  mcd = NULL,
  eer = NULL,
  plot = TRUE,
  mcdOnX = FALSE,
  plotResultValues = TRUE,
  resultValueLineColor = "blue",
  resultValueLineSize = 1,
  returnLineLayerOnly = FALSE,
  theme = ggplot2::theme_bw(),
  highestPossibleEER = 0.999999999,
  xLab = ifelse(mcdOnX, "Meaningful Change Definition", "Control Event Rate"),
  yLab = "Cohen's d",
  dist = "norm",
  distArgs = list(),
  distNS = "stats",
  ...
)

## S3 method for class 'dMCD'
print(x, ...)

Arguments

Value

The Cohen's d value, optionally with a ggplot2 plot stored in an attribute (which is only a ggplot2 layer if returnLineLayerOnly=TRUE).

References

Gruijters, S. L. K., & Peters, G.-J. Y. (2020). Meaningful change definitions: Sample size planning for experimental intervention research. PsyArXiv. doi:10.31234/osf.io/jc295

Examples

dMCD(.2, .05);

Functions to preprocess determinant structures

Description

These functions are used in conjunction with the determinantStructure family of funtions to conveniently work with determinant structures.

Usage

detStructAddVarLabels(
  determinantStructure,
  varLabelDf,
  varNameCol = "varNames.cln",
  leftAnchorCol = "leftAnchors",
  rightAnchorCol = "rightAnchors",
  subQuestionCol = "subQuestions",
  questionTextCol = "questionText"
)

detStructAddVarNames(determinantStructure, names)

detStructComputeProducts(determinantStructure, data, append = TRUE)

detStructComputeScales(
  determinantStructure,
  data,
  append = TRUE,
  separator = "_"
)

Arguments

Details

This family of functions will be explained more in detail in a forthcoming paper.

Value

detStructAddVarLabels and detStructAddVarNames just change the determinantStructure object; detStructComputeProducts and detStructComputeScales return either the dataframe with the new variables appended (if append = TRUE) or just a dataframe with the new variables (if append = FALSE).

References

(Forthcoming)

See Also

determinantStructure, determinantVar, subdeterminants, subdeterminantProducts, detStructCIBER

Examples

### Create some bogus determinant data
detStudy <- mtcars[, c(1, 3:7)];
names(detStudy) <- c('rUse_behav',
                     'rUse_intention',
                     'rUse_attitude1',
                     'rUse_attitude2',
                     'rUse_expAtt1',
                     'rUse_expAtt2');

### Specify the determinant structure

### First a subdeterminant
expAtt <-
  behaviorchange::subdeterminants("Subdeterminants",
                                  "expAtt");

### Then two determinants
attitude <-
  behaviorchange::determinantVar("Determinant",
                                 "attitude",
                                 expAtt);

intention <-
  behaviorchange::determinantVar("ProximalDeterminant",
                                 "intention",
                                 attitude);

### Then the entire determinant strcture
detStruct <-
  behaviorchange::determinantStructure('Behavior',
                                       list('behav',
                                       behaviorRegEx = 'rUse'),
                                       intention);

### Add the variable names
behaviorchange::detStructAddVarNames(detStruct,
                                     names(detStudy));

### Add the determinant scale variable to the dataframe
detStudyPlus <-
  behaviorchange::detStructComputeScales(detStruct,
                                         data=detStudy);

### Show its presence
names(detStudyPlus);
mean(detStudyPlus$rUse_Determinant);

Determinant Structure specification

Description

These functions can be used to specify a determinant structure: a hierarchical structure of determinants that can then be conveniently plotted and analysed, for example using detStructCIBER. These functions are made to be used together; see the example and the forthcoming article for more information.

Usage

determinantStructure(name, selection = NULL, ...)

determinantVar(name, selection = NULL, ...)

subdeterminants(name, selection = NULL, ...)

subdeterminantProducts(name, selection = NULL, ...)

## S3 method for class 'determinantStructure'
plot(x, useDiagrammeR = FALSE, ...)

## S3 method for class 'determinantStructure'
print(x, ...)

Arguments

Details

This family of functions will be explained more in detail in a forthcoming paper.

plot and print methods plot and print a determinantStructure object.

Value

A determinantStructure object, which is a data.tree object.

Author(s)

Gjalt-Jorn Peters, gjalt-jorn@a-bc.eu

See Also

detStructAddVarLabels, detStructAddVarNames, detStructComputeProducts, detStructComputeScales, detStructCIBER

Examples

determinantStructure('using R',
                     list('using R',
                          behaviorRegEx = 'some RegEx'),
                     determinantVar("Intention",
                                    "another RegEx",
                                    determinantVar("Attitude",
                                                   "third RegEX",
                                                   subdeterminants("Likelihood",
                                                                   "4th RegEx"),
                                                  subdeterminants("Evaluation",
                                                                  "5th RegEx"),
                                                  subdeterminantProducts("attProduct",
                                                                         c("4th RegEx",
                                                                           "5th RegEx"))),
                                    determinantVar("perceivedNorm",
                                                   "6th RegEx",
                                                   subdeterminants("Approval",
                                                                   "7th RegEx"),
                                                   subdeterminants("Motivation to comply",
                                                                   "8th RegEx"),
                                                   subdeterminantProducts("normProduct",
                                                                          c("7th RegEx",
                                                                            "8th RegEx"))),
                                              determinantVar("pbc",
                                                             "9th RegEx",
                                                             subdeterminants("Control beliefs",
                                                                             "10th RegEx"))));

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 class 'determinantSelectionTable'
knit_print(
  x,
  digits = attr(x, "digits"),
  headingLevel = attr(x, "headingLevel"),
  echoPartial = FALSE,
  partialFile = NULL,
  quiet = TRUE,
  ...
)

## S3 method for class '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
)

Arguments

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.

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.

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. 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 doi:10.1080/09603123.2012.699032

Examples

### 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
);

Obtaining an R squared confidence interval estimate for an lm regression

Description

The lm_rSq_ci function uses the base R lm function to conduct a regression analysis and then computes the confidence interval for R squared.

Usage

lm_rSq_ci(
  formula,
  data = NULL,
  conf.level = 0.95,
  ci.method = c("widest", "r.con", "olkinfinn"),
  env = parent.frame()
)

Arguments

Value

The confidence interval

Author(s)

Gjalt-Jorn Peters

Maintainer: Gjalt-Jorn Peters gjalt-jorn@a-bc.eu

Examples

### Do a simple regression analysis
lm_rSq_ci(age ~ circumference, dat=Orange);

Numbers Needed for Change

Description

This function computes the Numbers Needed for Change, and shows a visualisation to illustrate them. Numbers Needed for Change is the name for a Numbers Needed to Treat estimate that was computed for a continuous outcome as is common in behavior change research.

Usage

nnc(
  d = NULL,
  cer = NULL,
  r = 1,
  n = NULL,
  threshold = NULL,
  mean = 0,
  sd = 1,
  poweredFor = NULL,
  thresholdSensitivity = NULL,
  eventDesirable = TRUE,
  eventIfHigher = TRUE,
  conf.level = 0.95,
  dReliability = 1,
  d.ci = NULL,
  cer.ci = NULL,
  r.ci = NULL,
  d.n = NULL,
  cer.n = NULL,
  r.n = NULL,
  plot = TRUE,
  returnPlot = TRUE,
  silent = FALSE
)

## S3 method for class 'nnc'
print(x, digits = 2, ...)

Arguments

Details

Numbers Needed to Treat is a common and very useful effect size measure in use in the medical sciences. It is computed based on the Control Event Rate (CER) and the Experimental Event Rate (EER), and expresses how many people would need to received a treatment to yield a beneficial result for one person. In behavior change research, a similar measure would be useful, but the outcome is normally not dichotomous as is common in the medical literature (i.e. whether a participants survives or is cured), but continuous. Numbers Needed for Change fills this lacuna: it is simply the Numbers Needed to Treat, but converted from a Cohen's d value. nnt is an alias for nnc.

For more details, see Gruijters & Peters (2019) for details.

Value

The Numbers Needed for Change (NNC), potentially with a plot visualising the NNC in an attribute.

Author(s)

Gjalt-Jorn Peters & Stefan Gruijters

Maintainer: Gjalt-Jorn Peters gjalt-jorn@userfriendlyscience.com

References

Gruijters, S. L., & Peters, G. Y. (2019). Gauging the impact of behavior change interventions: A tutorial on the Numbers Needed to Treat. PsyArXiv. doi:10.31234/osf.io/2bau7

Examples

### Simple example
behaviorchange::nnc(d=.4, cer=.3);

### Or for a scenario where events are undesirable, and the
### intervention effective (therefore having a negative value for d):
behaviorchange::nnc(d=-.4, cer=.3, eventDesirable=FALSE);

Options for the behaviorchange package

Description

The behaviorchange::opts object contains three functions to set, get, and reset options used by the escalc package. Use behaviorchange::opts$set to set options, behaviorchange::opts$get to get options, or behaviorchange::opts$reset to reset specific or all options to their default values.

Usage

opts

Format

An object of class list of length 4.

Details

It is normally not necessary to get or set behaviorchange options.

The following arguments can be passed:

...

For behaviorchange::opts$set, the dots can be used to specify the options to set, in the format option = value, for example, EFFECTSIZE_POINTESTIMATE_NAME_IN_DF = "\n". For behaviorchange::opts$reset, a list of options to be reset can be passed.

option

For behaviorchange::opts$set, the name of the option to set.

default

For behaviorchange::opts$get, the default value to return if the option has not been manually specified.

To see the full list of options and their default values, use behaviorchange::opts$default(). Some examples are:

aabbcc

A color theme for abcd().

complecs_*

The worksheet and columns names for complecs().

silent

Whether to be chatty or silent.

Examples

### Get the default utteranceMarker
behaviorchange::opts$get(complecs_entitySheet);

### Set it to a custom version, so that every line starts with a pipe
behaviorchange::opts$set(complecs_entitySheet = "sheet_with_entities");

### Check that it worked
behaviorchange::opts$get(complecs_entitySheet);

### Reset this option to its default value
behaviorchange::opts$reset(complecs_entitySheet);

### Check that the reset worked, too
behaviorchange::opts$get(complecs_entitySheet);

Subsets of Party Panel datasets

Description

These are subsets of Party Panel datasets. Party Panel is an annual semi-panel determinant study among Dutch nightlife patrons, where every year, the determinants of another nightlife-related risk behavior are mapped.

Usage

data(BBC_pp15.1)

data(BBC_pp16.1)

data(BBC_pp17.1)

data(BBC_pp18.1)

Format

For BBC_pp15.1, a data.frame with 123 columns and 829 rows. For BBC_pp16.1, a data.frame with 63 columns and 1077 rows. For BBC_pp17.1, a data.frame with 94 columns and 943 rows. For BBC_pp18.1, a data.frame with 84 columns and 880 rows. Note that many rows contain missing values; the columns and rows were taken directly from the original Party Panel datasets, and represent all participants that made it past a given behavior.

Details

The behaviors of the Party Panel waves were:

• 2015: Behaviors related to using highly dosed ecstasy pills

• 2016: Behaviors related to visiting nightlife first-aid facilities

• 2017: Behaviors related to hearing protection

• 2018: Behaviors related to flirting and boundary crossing

• 2019: Behaviors related to sleeping hygiene surrounding nightlife participation

The full datasets are publicly available through the Open Science Framework (https://osf.io/s4fmu/). Also see the GitLab repositories (https://gitlab.com/partypanel) and the website at https://partypanel.eu.

Examples

data('BBC_pp17.1', package='behaviorchange');
behaviorchange::CIBERlite(data=BBC_pp17.1,
                          determinants=c("epw_attitude",
                                         "epw_perceivedNorm",
                                         "epw_pbc",
                                         "epw_habit"),
                          targets=c("epw_intention"));

Practically Important Effect Sizes

Description

Practically Important Effect Sizes

Usage

pies(
  data = NULL,
  controlCol = NULL,
  expCol = NULL,
  d = NULL,
  cer = NULL,
  r = 1,
  n = NULL,
  threshold = NULL,
  mean = 0,
  sd = 1,
  bootstrapA = FALSE,
  conf.level = 0.95
)

Arguments

Value

A dataframe with all values.

Examples

pies(d = .5, n = 100, cer = .2, threshold = 2);

Repeat a string a number of times

Description

Repeat a string a number of times

Usage

repeatStr(n = 1, str = " ")

Arguments

Value

A character vector of length 1.

Examples

### 10 spaces:
repStr(10);

### Three euro symbols:
repStr("\u20ac", 3);

Easily parse a vector into a character value

Description

Easily parse a vector into a character value

Usage

vecTxt(
  vector,
  delimiter = ", ",
  useQuote = "",
  firstDelimiter = NULL,
  lastDelimiter = " & ",
  firstElements = 0,
  lastElements = 1,
  lastHasPrecedence = TRUE
)

vecTxtQ(vector, useQuote = "'", ...)

Arguments

Value

A character vector of length 1.

Examples

vecTxtQ(names(mtcars));

Wrap all elements in a vector

Description

Wrap all elements in a vector

Usage

wrapVector(x, width = 0.9 * getOption("width"), sep = "\n", ...)

Arguments

Value

A character vector

Examples

res <- wrapVector(
  c(
    "This is a sentence ready for wrapping",
    "So is this one, although it's a bit longer"
  ),
  width = 10
);

print(res);
cat(res, sep="\n");