draw_sw: Draw and export stepped-wedge cluster randomised trial design...
In mjg211/swcrt: Draw and export stepped-wedge cluster randomised trial design diagrams

View source: R/draw_sw.R

draw_sw

R Documentation

Draw and export stepped-wedge cluster randomised trial design diagrams

Description

draw_sw draws stepped-wedge cluster randomised trial (SW-CRT) design diagrams that can be exported in .docx, .png, and .pptx formats.

Usage

draw_sw(design         = design_sw(),
        cp_contents    = design,
        row_names      = FALSE,
        col_names      = FALSE,
        colours,
        combine_rows   = FALSE,
        merge_cols     = FALSE,
        xlab           = "Time period",
        ylab           = "Cluster",
        cp_text_colour = "black",
        key_interventions,
        key_time_periods,
        make           = "print",
        filename       = "swcrt")

Arguments

`design`	A SW-CRT design (i.e., information on the planned roll-out) to draw a diagram for. Must be either a `data.frame` or a `matrix`. Defaults to `design_sw()`.
`cp_contents`	Values to add to the cluster-period cells in the produced diagram; modify this when cluster-period cells should contain details on something other than the intervention condition. Must be either a `data.frame` or a `matrix`. Defaults to `design`.
`row_names`	A `logical` variable, indicating whether the row names in the produced diagram should be taken from `design` or constructed internally. Defaults to `FALSE`.
`col_names`	A `logical` variable, indicating whether the column names in the produced diagram should be taken from `design` or constructed internally. Defaults to `FALSE`.
`colours`	A named (see `names`) `character` `vector`, giving the fill colours to add to the cluster-period cells for each of the intervention conditions. Specified internally by default.
`combine_rows`	A `logical` variable, indicating whether to combine rows that have identical sequences in the produced diagram. Defaults to `FALSE`.
`merge_cols`	A `logical` variable, indicating whether to merge across columns when adjacent cluster-period cells have the same intervention condition in the produced diagram. Defaults to `FALSE`.
`xlab`	A `character` string, giving the label for the x-axis in the produced diagram. Defaults to `"Time period"`.
`ylab`	A `character` string, giving the label for the y-axis in the produced diagram. Defaults to `"Cluster"`.
`cp_text_colour`	A `character` string, giving the colour to use for the text in the cluster-period cells in the produced diagram. Defaults to `"black"`.
`key_interventions`	A named (see `names`) `character` `vector`, giving information to include an intervention key. Not produced by default.
`key_time_periods`	A named (see `names`) `character` `vector`, giving information to include a time period key. Not produced by default.
`make`	A `character` `vector`, giving the (potentially multiple) types of output (export) that are desired. Can include `"print"` (view within R), "docx" (save a .docx MS Word file), "png" (save a .png file), and "pptx" (save a .pptx MS PowerPoint file). Defaults to `"print"`.
`filename`	A `character` string, giving the filename to use for any files that are to be saved. Defaults to `"swcrt"`.

Details

More details on each of the input variables can be found in the package vignette.

Value

A list containing the following elements:

A flextable in the slot $table_design containing the constructed SW-CRT diagram.
A flextable in the slot $table_interventions containing the constructed key summarising the various intervention states. Will be NULL if input key_interventions is not specified.
A flextable in the slot $table_time_periods containing the constructed key summarising the various time periods. Will be NULL if input key_time_periods is not specified.
A list in the slot $inputs containing each of the input variables.

Author(s)

Michael J Grayling (michael.grayling@newcastle.ac.uk)

Examples

# The default is to draw a 'standard' SW-CRT design, with four clusters and
# five time periods
default_draw   <- draw_sw()
# Specify a more complex design, where all clusters begin in the intervention
# condition, there is an unequal number of clusters who switch per time
# period, and there are two trailing extra time periods with all clusters in
# the intervention condition. Also modify the row and column names
complex_design <- design_sw(clusters_per_time_period = c(1, 2, 3, 2, 0, 0),
                            row_names                = paste("Cluster", 1:8),
                            col_names                = paste("Time period",
                                                             1:6))
# Pass this to draw_sw(), producing .docx, .png, and .pptx files, merging
# columns, and combining rows
## Not run: 
complex_draw   <- draw_sw(complex_design, combine_rows = TRUE,
                          merge_cols = TRUE,
                          make = c("docx", "png", "pptx", "print"))

## End(Not run)

mjg211/swcrt documentation built on May 1, 2022, 4:26 a.m.