Learn R Programming

behaviorchange (version 26.11.1)

CIBORG: Confidence Interval-Based Overview of Relevant Group patterns in behavioral determinants (CIBORG)

Description

CIBORG plots allow you to compare determinant stuctures for multiple groups.

Usage

CIBORG(
  data,
  determinants,
  target,
  group,
  conf.level = list(means = 0.9999, associations = 0.95),
  subQuestions = NULL,
  leftAnchors = NULL,
  rightAnchors = NULL,
  output_plot = NULL,
  outputWidth = NULL,
  outputHeight = NULL,
  outputUnits = "in",
  outputParams = list(),
  output_tables = NULL,
  groupColorPalette = NULL,
  strokeColors = c("white", "black"),
  titlePrefix = "Means and associations (r) with",
  titleVarLabels = NULL,
  titleSuffix = "",
  titleGroupNames = NULL,
  FootnoteText = NULL,
  jitterWidth = 0.4,
  jitterHeight = 0.4,
  titleSize = 15,
  dotSize = 2.5,
  determinantSize = 14,
  axisSize = 12,
  rsq = TRUE,
  leftScaleRange = NULL,
  scaleRanges = NULL,
  drawPlot = TRUE,
  useCompleteCases = FALSE,
  na.random = FALSE,
  silent = behaviorchange::opts$get("silent"),
  ...
)

Value

An object with the results, including the CIBORG plot.
Example --> x <- CIBORG()

Arguments

data

A data frame containing the determinants, target, and group variables.
Example --> data = mydataframe

determinants

The determinant variables (columns in data). --> e.g.,
Example --> c('det1', 'det2', 'det3')

target

The target variable (column in data); only one target per plot is allowed.
Example --> target = 'behavior',

group

The grouping variable (column in data); max 9 groups can be included in a plot.
Example --> group = 'group_variable'

conf.level

An list with confidence levels used for the mean and associations (diamond widths)
Example --> conf.level = list(means = .9999, associations = .95),

subQuestions

Optional character vector to give labels to determinants
Example --> c('name1', 'name2', 'name3')

leftAnchors

Optional character vector with the lowest-value per determinant, in the same order as determinants; defaults is 'Lo'.
Example --> c('lowest', 'not at all', 'never')

rightAnchors

Optional character vector with the highest-value per determinant, in the same order as determinants; defaults to 'Hi'.
Example --> c('highest', 'very much', 'always')

output_plot

Optional name and extention with path to save the plot.
Example --> output_plot = 'plots/Awesome_plot.pdf',

outputWidth

Optional width of the saved plot; if NULL, computed automatically.
Example --> outputWidth = 30

outputHeight

Optional height of the saved plot; if NULL, computed automatically based on the number of determinants.
Example --> outputHeight = 30

outputUnits

Units for outputWidth & outputHeight (e.g. 'in', 'cm'); defaults to 'i'n.
Example --> outputUnits = 'cm'

outputParams

A list with optional ggplot arguments; works only if output_plot is specified
Example --> outputParams = list(dpi = 600)

output_tables

Optional directory path to store CSV tables means.csv and associations.csv.
Example --> output_tables = '/Users/JohnDoe/Desktop/'

groupColorPalette

Optional character vector of colors, one per group; if NULL, a colorblind-friendly default is used.
Example: groupColorPalette = c('gold', 'purple', 'green')

strokeColors

Optional character vector for the diamond outline colors of means associations
Example --> strokeColors = c('black', 'orange')

titlePrefix

Optional HTML-editable string to add a prefix of the plot title, before the target variable name.
Example --> titlePrefix = "Figure 1.
The means and associations",

titleVarLabels

Optional HTML-editable string to rename the target variable's in the title, instead of the raw target name.
Example --> titleVarLabels = 'eductional level'

titleSuffix

Optional HTML-editable string to the end of the title; empty by default.
Example --> titleSuffix = 'this is just an example'

titleGroupNames

Optional character vector to display names for the groups in the title that serve as legend.
Example --> titleGroupNames = c('one', 'two', 'three')

FootnoteText

Optional HTML-style character string to add a footnote below the plot; if NULL, no footnote is shown.
Example --> FootnoteText = 'In this footnote you can provide HTML-styled info to readers'

jitterWidth

Numeric value to set jitter along the width of points in the left (means) scatter plot.
Example --> jitterWidth = 1

jitterHeight

Numeric value controlling jitter along the height of points in the left (means) scatter plot.
Example --> jitterHeight = 0.3

titleSize

Numeric value for the font size of the plot title.
Example --> titleSize = 18

dotSize

Numeric value for the size of individual data points in the left (means) scatter plot.
Example --> dotSize = 3

determinantSize

Numeric value for the font size of the determinant labels/subquestions on the y-axis.
Example --> determinantSize = 14

axisSize

Numeric value for the font size of the axis text below the plots.
Example --> axisSize = 12

rsq

if TRUE (default) the \(R^2\) (CIs) are calculated per group and shown in the title; if FALSE, this is not performed.
Example --> rsq = FALSE

leftScaleRange

Optional to set the min/max range for ALL determinants scales (leftplot); auto-detected if NULL; ignored if scaleRanges is set.
Example --> leftScaleRange = c(0,7),

scaleRanges

Optional list to set the min/max per determinant, to normalize (0 to 1) determinants measured on different scales.
Example --> scaleRanges = list(det1 = c(1,3), det2 = c(1,7), det3 = c(1,7))

drawPlot

if TRUE (default) the plot is drawn; if FALSE, it is built and returned but not drawn.
Example --> drawPlot = FALSE

useCompleteCases

if TRUE, only complete cases (no NA) on determinants or target are used; defaults is FALSE.
Example --> useCompleteCases = TRUE

na.random

if TRUE, NAs are considered random and the warning is suppresed if means and associations plots are based on different sample sizes.
Example --> na.random = TRUE

silent

Whether to be silent (TRUE, the default) or chatty (FALSE).

...

Any additional arguments are ignored.

Details

This function is based on the CIBER() function and on this post and on this post by Matthew Kay.

See Also

CIBER() for "regular" CIBER plots.

Examples

Run this code
### This example uses the determinant study Party Panel 17.1;
### see ?behaviorchange::BBC_data for more information.
data(BBC_pp17.1);

### Create a three-level group variable
BBC_pp17.1$genderPrivilege <-
  ifelse(
    is.na(BBC_pp17.1$gender),
    3,
    as.numeric(BBC_pp17.1$gender != "Male") + 1
  );

### Produce the CIBORG plot

### Note that all question start with
### (translated from Dutch) "If I'm in a venue
### with loud music, and I wear earplugs, then..."

behaviorchange::CIBORG(
  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'
  ),
  subQuestions = c(
    "...the probability of hearing damage is...",
    "...the probability of hearing a beep the next day is...",
    "...I hear the music...",
    "...I hear the music...",
    "...loud conversation bothers me...",
    "...focusing on the music is...",
    "...I enjoy the music..."
  ),
  leftAnchors = c(
    "very small",
    "very small",
    "very softly",
    "exactly the same",
    "not at all",
    "much harder",
    "much less"
  ),
  rightAnchors = c(
    "very large",
    "very large",
    "very loudly",
    "very distorted",
    "a lot",
    "much easier",
    "much more"
  ),
  target = 'epw_attitude',
  group = 'genderPrivilege'
);


Run the code above in your browser using DataLab