Draw and export stepped-wedge cluster randomised trial design diagrams

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

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".

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.

Details

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

See also

design_sw

Author

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()
#> a flextable object.
#> col_keys: `Cluster`, `i`, `1`, `2`, `3`, `4`, `5` 
#> header has 1 row(s) 
#> body has 4 row(s) 
#> original dataset sample: 
#>   Cluster i 1 2 3 4 5
#> 1 Cluster 1 0 1 1 1 1
#> 2 Cluster 2 0 0 1 1 1
#> 3 Cluster 3 0 0 0 1 1
#> 4 Cluster 4 0 0 0 0 1
# 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
if (FALSE) {
complex_draw   <- draw_sw(complex_design, combine_rows = TRUE,
                          merge_cols = TRUE,
                          make = c("docx", "png", "pptx", "print"))
}