complecs_to_precede {behaviorchange}

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

input

Either a link to a Google Sheet, or a path to an Excel file.

title

The title of the COMPLECS graph.

layout

The layout to use; has to be one of the DiagrammeR layout types (dot, neato, circo and twopi).

graph_styling

Additional styling to apply; a list with three-element vectors, where the three elements correspond to, respectively, the attr, value, and attr_type arguments for DiagrammeR::add_global_graph_attrs(). Note that these attributes may override attributes specified in the COMPLECS specification.

directed

Whether to draw directed arrows or not.

outputFile

A character vector where each element is one path (including filename) to write the graph to.

outputWidth, outputHeight

If not NULL, a way to override the width and height when calling complecs to generate a COMPLECS overview.

returnDotOnly

Whether to only return the produced DOT code.

returnSvgOnly

Whether to only return the SVG in a character vector.

returnGraphOnly

Whether to only return the produced graph.

maxLabelLength

The number of characters where to wrap the labels.

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 \).

silent

Whether to be chatty or silent.

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)