Type: Package
Title: Tidy Flowchart Generator
Version: 0.9.0
Maintainer: Pau Satorra <psatorra@igtp.cat>
Description: Creates participant flow diagrams directly from a dataframe. Representing the flow of participants through each stage of a study, especially in clinical trials, is essential to assess the generalisability and validity of the results. This package provides a set of functions that can be combined with a pipe operator to create all kinds of flowcharts from a data frame in an easy way.
License: GPL (≥ 3)
BugReports: https://github.com/bruigtp/flowchart/issues
Encoding: UTF-8
LazyData: true
Imports: Gmisc, grid, tidyr, dplyr (≥ 1.1.0), purrr, stringr, tibble, tidyselect, rlang, grDevices, cli
Suggests: knitr, ragg, rmarkdown, testthat (≥ 3.0.0), withr
VignetteBuilder: knitr
Depends: R (≥ 4.1.0)
RoxygenNote: 7.3.2
URL: https://bruigtp.github.io/flowchart/
Config/testthat/edition: 3
Config/Needs/website: rmarkdown
NeedsCompilation: no
Packaged: 2025-08-22 17:30:27 UTC; psatorra
Author: Pau Satorra ORCID iD [aut, cre], João Carmezim ORCID iD [aut], Natàlia Pallarès ORCID iD [aut], Cristian Tebé ORCID iD [aut], Kenneth Taylor ORCID iD [aut]
Repository: CRAN
Date/Publication: 2025-08-22 18:00:10 UTC

as_fc

Description

This function allows to initialize a flow chart given any database. It will create a fc object showing the number of rows of the database. If a database is not available, the user can instead directly enter the number of rows in the study.

Usage

as_fc(
  .data = NULL,
  N = NULL,
  label = "Initial dataframe",
  text_pattern = "{label}\n{N}",
  just = "center",
  text_color = "black",
  text_fs = 8,
  text_fface = 1,
  text_ffamily = NA,
  text_padding = 1,
  bg_fill = "white",
  border_color = "black",
  width = NA,
  height = NA,
  hide = FALSE,
  title = NULL,
  x_title = 0.1,
  text_color_title = "black",
  text_fs_title = 10,
  text_fface_title = 1,
  text_ffamily_title = NA,
  text_padding_title = 0.6,
  bg_fill_title = "#B3D1FF",
  border_color_title = "black",
  width_title = NA,
  height_title = NA
)

Arguments

.data

Data frame to be initialised as a flowchart.

N

Number of rows of the study in case .data is NULL.

label

Character or expression with the text that will be shown in the box.

text_pattern

Character or expression defining the structure that will have the text in each of the boxes. It recognizes label, n, N and perc within brackets. For default it is "{label}\n {n}". If text_pattern or label is an expression, the label is always placed at the beginning of the pattern, followed by a line break where the structure specified by text_pattern is placed.

just

Justification for the text: left, center or right. Default is center.

text_color

Color of the text. It is "black" by default. See the col parameter for gpar.

text_fs

Font size of the text. It is 8 by default. See the fontsize parameter for gpar.

text_fface

Font face of the text. It is 1 by default. See the fontface parameter for gpar.

text_ffamily

Changes the font family of the text. Default is NA. See the fontfamily parameter for gpar.

text_padding

Changes the text padding inside the box. Default is 1. This number has to be greater than 0.

bg_fill

Box background color. It is white by default. See the fill parameter for gpar.

border_color

Box border color. It is "black" by default. See the col parameter for gpar.

width

Width of the box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

height

Height of the box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

hide

Logical value to hide the initial box or not. Default is FALSE. hide = TRUE can only be combined with fc_split().

title

Add a title box to the initial box. Default is NULL.

x_title

x-coordinate of the title box. Default is 0.1 (placed in the left).

text_color_title

Color of the title text. It is "black" by default.

text_fs_title

Font size of the title text. It is 8 by default.

text_fface_title

Font face of the title text. It is 1 by default. See the fontface parameter for gpar.

text_ffamily_title

Changes the font family of the title text. Default is NA. See the fontfamily parameter for gpar.

text_padding_title

Changes the title text padding inside the box. Default is 1. This number has to be greater than 0.

bg_fill_title

Title box background color. It is "white" by default.

border_color_title

Title box border color. It is "black" by default.

width_title

Width of the title box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

height_title

Height of the title box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

Value

List with the dataset and the initialized flowchart parameters.

Examples

safo |>
as_fc(label = "Patients assessed for eligibility") |>
fc_draw()

fc_draw

Description

This function allows to draw the flowchart from a fc object.

Usage

fc_draw(
  object,
  big.mark = "",
  box_corners = "round",
  arrow_angle = 30,
  arrow_length = grid::unit(0.1, "inches"),
  arrow_ends = "last",
  arrow_type = "closed",
  arrow_color = "black",
  arrow_fill = "black",
  arrow_lwd = 1,
  arrow_lineend = "round",
  arrow_linejoin = "round",
  title = NULL,
  title_x = 0.5,
  title_y = 0.9,
  title_color = "black",
  title_fs = 15,
  title_fface = 2,
  title_ffamily = NULL,
  canvas_bg = "white"
)

Arguments

object

fc object that we want to draw.

big.mark

character. Used to specify the thousands separator for patient count values. Defaults is no separator (""); if not empty used as mark between every 3 digits (ex: big.mark = "," results in ⁠1,000⁠ instead of 1000).

box_corners

Indicator of whether to draw boxes with round ("round") vs non-round ("sharp") corners. Default is "round".

arrow_angle

The angle of the arrow head in degrees, as in arrow.

arrow_length

A unit specifying the length of the arrow head (from tip to base), as in arrow.

arrow_ends

One of "last", "first", or "both", indicating which ends of the line to draw arrow heads, as in arrow.

arrow_type

One of "open" or "closed" indicating whether the arrow head should be a closed triangle, as in arrow.

arrow_color

Color of the arrows. Default is "black". See the col parameter for gpar.

arrow_fill

Color for filling the arrow head. Default is "black". See the fill parameter for gpar.

arrow_lwd

Line width of the arrows. Default is 1. See the lwd parameter for gpar.

arrow_lineend

Line end style for arrows. One of "round", "butt", or "square". Default is "round". See the lineend parameter for gpar.

arrow_linejoin

Line join style for arrow heads (i.e., shape of arrow head corners). One of "round", "mitre", or "bevel". Default is "round". See the linejoin parameter for gpar.

title

The title of the flowchart. Default is NULL (no title).

title_x

x coordinate for the title. Default is 0.5.

title_y

y coordinate for the title. Default is 0.9.

title_color

Color of the title. It is "black" by default. See the col parameter for gpar.

title_fs

Font size of the title. It is 15 by default. See the fontsize parameter for gpar.

title_fface

Font face of the title. It is 2 by default. See the fontface parameter for gpar.

title_ffamily

Changes the font family of the title. Default is NA. See the fontfamily parameter for gpar.

canvas_bg

Background color for the entire canvas (the area behind the flowchart boxes). Default is "white". Set to "transparent" or NULL for a transparent background; "transparent" background will only be noticeable when exporting drawn flowcharts via fc_export() and is compatible with all fc_export() formats except "jpeg" and "bmp".

Value

Invisibly returns the same object that has been given to the function, with the given arguments to draw the flowchart stored in the attributes.

Examples

safo |>
  as_fc(label = "Patients assessed for eligibility") |>
  fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
  fc_split(group) |>
  fc_filter(itt == "Yes", label = "Included in ITT") |>
  fc_filter(pp == "Yes", label = "Included in PP") |>
  fc_draw()

fc_export

Description

This function allows you to export the drawn flowchart to the most popular graphic formats, including bitmap formats (png, jpeg, tiff, bmp) and vector formats (svg, pdf). For bitmap formats, it uses the ragg package devices when available for higher performance and higher quality output than standard raster devices provide by grDevices.

Usage

fc_export(
  object,
  filename,
  path = NULL,
  format = NULL,
  width = NA,
  height = NA,
  units = NULL,
  res = 100,
  ...
)

Arguments

object

fc object that we want to export.

filename

File name to create on disk.

path

Path of the directory to save plot to: path and filename are combined to create the fully qualified file name. Defaults to the working directory.

format

Name of the graphic device. One of "png", "jpeg", "tiff", "bmp", "svg", or "pdf". If NULL (default), the format is guessed based on the filename extension.

width, height

Plot size in units expressed by the units argument. Default is 600px for bitmap formats and 6 inches for vector formats.

units

One of the following units in which the width and height arguments are expressed: "in", "cm", "mm" for vector formats and "in", "cm", "mm" or "px" for bitmap formats. If left NULL (default), the function will automatically use "px" for bitmap formats and "in" for vector formats.

res

The nominal resolution in ppi which will be recorded in the bitmap file, if a positive integer. Also used for units other than the default, and to convert points to pixels. Default is 100 if exporting in bitmap format. This argument is unused if exporting to a vector format.

...

Arguments to be passed to the device function used to save the flowchart. The available parameters will differ depending on the format (e.g., png).

Details

Value

Invisibly returns the same object that has been given to the function.

Examples

## Not run: 
safo |>
 as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
 fc_draw() |>
 fc_export("flowchart.png")

#Specifying size and resolution
safo |>
 as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
 fc_draw() |>
 fc_export("flowchart.png", width = 3000, height = 4000, res = 700)

#Exporting to an SVG file
safo |>
 as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
 fc_draw() |>
 fc_export("flowchart.svg")

#Exporting to a PDF file
safo |>
 as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
 fc_draw() |>
 fc_export("flowchart.pdf")

## End(Not run)

fc_filter

Description

This function allows to filter the flowchart in function of a expression that returns a logic value that are defined in terms of the variables in the database. It will generate one box per group showing the number of rows of the group that matches the condition, and will retain only those rows in the data base.

Usage

fc_filter(
  object,
  filter = NULL,
  N = NULL,
  label = NULL,
  text_pattern = "{label}\n {n} ({perc}%)",
  perc_total = FALSE,
  show_exc = FALSE,
  direction_exc = "right",
  label_exc = "Excluded",
  text_pattern_exc = "{label}\n {n} ({perc}%)",
  sel_group = NULL,
  round_digits = 2,
  trim_trailing_zeros = FALSE,
  just = "center",
  text_color = "black",
  text_fs = 8,
  text_fface = 1,
  text_ffamily = NA,
  text_padding = 1,
  bg_fill = "white",
  border_color = "black",
  width = NA,
  height = NA,
  just_exc = "center",
  text_color_exc = "black",
  text_fs_exc = 6,
  text_fface_exc = 1,
  text_ffamily_exc = NA,
  text_padding_exc = 1,
  bg_fill_exc = "white",
  border_color_exc = "black",
  offset_exc = NULL,
  width_exc = NA,
  height_exc = NA,
  title = NULL,
  x_title = 0.1,
  text_color_title = "black",
  text_fs_title = 10,
  text_fface_title = 1,
  text_ffamily_title = NA,
  text_padding_title = 0.6,
  bg_fill_title = "#B3D1FF",
  border_color_title = "black",
  width_title = NA,
  height_title = NA
)

Arguments

object

fc object that we want to filter.

filter

Expression that returns a logical value and are defined in terms of the variables in the data frame. The data base will be filtered by this expression, and it will create a box showing the number of rows satisfying this condition.

N

Number of rows after the filter in case filter is NULL.

label

Character or expression that will be the title of the box. By default it will be the evaluated condition.

text_pattern

Character or expression defining the structure that will have the text in each of the boxes. It recognizes label, n, N and perc within brackets. For default it is "{label}\n {n} ({perc}%)". If text_pattern or label is an expression, the label is always placed at the beginning of the pattern, followed by a line break where the structure specified by text_pattern is placed.

perc_total

logical. Should percentages be calculated using the total number of rows at the beginning of the flowchart? Default is FALSE, meaning that they will be calculated using the number at the parent leaf.

show_exc

Logical value. If TRUE a box showing the number of excluded rows will be added to the flow chart.

direction_exc

One of "left" or "right" indicating if the exclusion box goes into the left direction or in the right direction. By default is "right".

label_exc

Character or expression that will be the title of the added box showing the excluded patients. By default it will show "Excluded".

text_pattern_exc

Character or expression defining the structure that will have the text in the exclude box. It recognizes label, n, N and perc within brackets. For default it is "{label}\n {n} ({perc}%)". If text_pattern or label is an expression, the label is always placed at the beginning of the pattern, followed by a line break where the structure specified by text_pattern_exc is placed.

sel_group

Select the group in which to perform the filter. The default is NULL. Can only be used if the flowchart has previously been split. If the flowchart has more than one group, it can either be given the full name as it is stored in the ⁠$fc⁠ component (separated by '\'), or it can be given as a vector with the names of each group to be selected.

round_digits

Number of digits to round percentages. It is 2 by default.

trim_trailing_zeros

Logical value. If TRUE, allows trailing zeros after the decimal to be trimmed (default is FALSE).

just

Justification for the text: "left", "center" or "right". Default is "center".

text_color

Color of the text. It is "black" by default. See the col parameter for gpar.

text_fs

Font size of the text. It is 8 by default. See the fontsize parameter for gpar.

text_fface

Font face of the text. It is 1 by default. See the fontface parameter for gpar.

text_ffamily

Changes the font family of the text. Default is NA. See the fontfamily parameter for gpar.

text_padding

Changes the text padding inside the box. Default is 1. This number has to be greater than 0.

bg_fill

Box background color. It is "white" by default. See the fill parameter for gpar.

border_color

Box border color. It is "black" by default. See the col parameter for gpar.

width

Width of the box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

height

Height of the box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

just_exc

Justification for the text of the exclude box: "left", "center" or "right". Default is "center".

text_color_exc

Color of the text of the exclude box. It is "black" by default. See text_color.

text_fs_exc

Font size of the text of the exclude box. It is 6 by default. See text_fs.

text_fface_exc

Font face of the text of the exclude box. It is 1 by default. See the fontface parameter for gpar. See text_fface.

text_ffamily_exc

Changes the font family of the text of the exclude box. Default is NA. See the fontfamily parameter for gpar. See text_ffamily.

text_padding_exc

Changes the text padding inside the exclude box. Default is 1. This number has to be greater than 0.

bg_fill_exc

Exclude box background color. It is "white" by default. See bg_fill.

border_color_exc

Box background color of the exclude box. It is "black" by default. See border_color.

offset_exc

Amount of space to add to the distance between the box and the excluded box (in the x coordinate). If positive, this distance will be larger. If negative, it will be smaller. This number has to be at least between 0 and 1 (plot limits) and the resulting x coordinate cannot exceed these plot limits. The default is NULL (no offset).

width_exc

Width of the exclude box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

height_exc

Height of the box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

title

Add a title box to the filter. Default is NULL.

x_title

x-coordinate of the title box. Default is 0.1 (placed in the left).

text_color_title

Color of the title text. It is "black" by default.

text_fs_title

Font size of the title text. It is 8 by default.

text_fface_title

Font face of the title text. It is 1 by default. See the fontface parameter for gpar.

text_ffamily_title

Changes the font family of the title text. Default is NA. See the fontfamily parameter for gpar.

text_padding_title

Changes the title text padding inside the box. Default is 1. This number has to be greater than 0.

bg_fill_title

Title box background color. It is "white" by default.

border_color_title

Title box border color. It is "black" by default.

width_title

Width of the title box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

height_title

Height of the title box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

Value

List with the filtered dataset and the flowchart parameters with the resulting filtered box.

Examples

safo |>
  as_fc(label = "Patients assessed for eligibility") |>
  fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
  fc_draw()

fc_merge

Description

This function allows to combine horizontally two different flowcharts.

Usage

fc_merge(fcs)

Arguments

fcs

list with all the flowcharts that we want to merge

Value

List containing a list with the datasets belonging to each flowchart and another list with each of the flowcharts parameters to merge.

Examples

# Create first flowchart for ITT
fc1 <- safo |>
  as_fc(label = "Patients assessed for eligibility") |>
  fc_filter(itt == "Yes", label = "Intention to treat (ITT)")


# Create second flowchart for PP
fc2 <- safo |>
  as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(pp == "Yes", label = "Per protocol (PP)")

list(fc1, fc2) |>
  fc_merge() |>
  fc_draw()

fc_modify

Description

This function allows to modify the .$fc tibble included in each fc object that contains all the parameters of the flowchart.

Usage

fc_modify(object, fun, ...)

Arguments

object

flowchart created as a fc object.

fun

A function or formula that will be applied to .$fc. If a function, it is used as is. If a formula, e.g. fun = ~.x |> mutate(x = x + 0.2), it is converted to a function.

...

Additional arguments passed on to the mapped function.

Value

List with the dataset and the modified flowchart parameters.

Examples

#Example: let's modify the excluded box
text_exc <- paste0(
  sum(safo$inclusion_crit == "Yes"),
  " not met the inclusion criteria\n",
  sum(safo$exclusion_crit == "Yes"),
  " met the exclusion criteria"
)

safo |>
  as_fc(label = "Patients assessed for eligibility") |>
  fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
  fc_modify(
    ~ . |>
      dplyr::mutate(
        text = ifelse(id == 3, text_exc, text),
        x = ifelse(id == 3, 0.75, x)
      )
  ) |>
  fc_draw()

fc_split

Description

This function allows to split the flowchart in function of the categories of a column of the database. It will generate as many boxes as categories has the column showing in each one the frequency of each category. It will additionally group the database per this column.

Usage

fc_split(
  object,
  var = NULL,
  N = NULL,
  label = NULL,
  text_pattern = "{label}\n {n} ({perc}%)",
  perc_total = FALSE,
  sel_group = NULL,
  na.rm = FALSE,
  show_zero = FALSE,
  round_digits = 2,
  trim_trailing_zeros = FALSE,
  just = "center",
  text_color = "black",
  text_fs = 8,
  text_fface = 1,
  text_ffamily = NA,
  text_padding = 1,
  bg_fill = "white",
  border_color = "black",
  width = NA,
  height = NA,
  title = NULL,
  x_title = 0.1,
  text_color_title = "black",
  text_fs_title = 10,
  text_fface_title = 1,
  text_ffamily_title = NA,
  text_padding_title = 0.6,
  bg_fill_title = "#B3D1FF",
  border_color_title = "black",
  width_title = NA,
  height_title = NA,
  offset = NULL
)

Arguments

object

fc object that we want to split.

var

variable column of the database from which it will be splitted.

N

Number of rows after the split in case var is NULL.

label

Vector of characters or vector of expressions with the label of each category in order. It has to have as many elements as categories has the column. By default, it will put the labels of the categories.

text_pattern

Character or expression defining the structure that will have the text in each of the boxes. It recognizes label, n, N and perc within brackets. For default it is "{label}\n {n} ({perc}%)". If text_pattern or label is an expression, the label is always placed at the beginning of the pattern, followed by a line break where the structure specified by text_pattern is placed.

perc_total

logical. Should percentages be calculated using the total number of rows at the beginning of the flowchart? Default is FALSE, meaning that they will be calculated using the number at the parent leaf.

sel_group

Select the group in which to perform the filter. The default is NULL. Can only be used if the flowchart has previously been split. If the flowchart has more than one group, it can either be given the full name as it is stored in the ⁠$fc⁠ component (separated by '\'), or it can be given as a vector with the names of each group to be selected.

na.rm

logical. Should missing values of the grouping variable be removed? Default is FALSE.

show_zero

logical. Should the levels of the grouping variable that don't have data be shown? Default is FALSE.

round_digits

Number of digits to round percentages. It is 2 by default.

trim_trailing_zeros

Logical value. If TRUE, allows trailing zeros after the decimal to be trimmed (default is FALSE).

just

Justification for the text: "left", "center" or "right". Default is "center".

text_color

Color of the text. It is "black" by default.

text_fs

Font size of the text. It is 8 by default.

text_fface

Font face of the text. It is 1 by default. See the fontface parameter for gpar.

text_ffamily

Changes the font family of the text. Default is NA. See the fontfamily parameter for gpar.

text_padding

Changes the text padding inside the box. Default is 1. This number has to be greater than 0.

bg_fill

Box background color. It is "white" by default.

border_color

Box border color. It is "black" by default.

width

Width of the box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

height

Height of the box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

title

Add a title box to the split. Default is NULL. It can only be used when there are only two resulting boxes after the split.

x_title

x-coordinate of the title box. Default is 0.1 (placed in the left).

text_color_title

Color of the title text. It is "black" by default.

text_fs_title

Font size of the title text. It is 8 by default.

text_fface_title

Font face of the title text. It is 1 by default. See the fontface parameter for gpar.

text_ffamily_title

Changes the font family of the title text. Default is NA. See the fontfamily parameter for gpar.

text_padding_title

Changes the title text padding inside the box. Default is 1. This number has to be greater than 0.

bg_fill_title

Title box background color. It is "white" by default.

border_color_title

Title box border color. It is "black" by default.

width_title

Width of the title box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

height_title

Height of the title box. If NA, it automatically adjusts to the content (default). Must be an object of class unit or a number between 0 and 1.

offset

Amount of space to add to the distance between boxes (in the x coordinate). If positive, this distance will be larger. If negative, it will be smaller. This number has to be at least between 0 and 1 (plot limits) and the resulting x coordinate cannot exceed these plot limits. The default is NULL (no offset).

Value

List with the dataset grouped by the splitting variable and the flowchart parameters with the resulting split.

Examples

safo |>
  dplyr::filter(!is.na(group)) |>
  as_fc(label = "Randomized patients") |>
  fc_split(group) |>
  fc_draw()

fc_stack

Description

This function allows to combine vertically two different flowcharts.

Usage

fc_stack(fcs, unite = FALSE)

Arguments

fcs

list with all the flowcharts that we want to merge

unite

logical value if the boxes have to be united or not. Default is FALSE.

Value

List containing a list with the datasets belonging to each flowchart and the flowchart parameters combining all the flowcharts.

Examples

# Create first flowchart for ITT
fc1 <- safo |>
  as_fc(label = "Patients assessed for eligibility") |>
  fc_filter(itt == "Yes", label = "Intention to treat (ITT)")


# Create second flowchart for PP
fc2 <- safo |>
  as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(pp == "Yes", label = "Per protocol (PP)")

list(fc1, fc2) |>
  fc_stack() |>
  fc_draw()

fc_theme

Description

This function allows you to change the appearance of all boxes of a flowchart at once.

Usage

fc_theme(
  object,
  text_pattern = NULL,
  text_pattern_init = NULL,
  text_pattern_exc = NULL,
  just = NULL,
  text_color = NULL,
  text_fs = NULL,
  text_fface = NULL,
  text_ffamily = NULL,
  text_padding = NULL,
  bg_fill = NULL,
  border_color = NULL,
  width = NULL,
  height = NULL,
  just_exc = NULL,
  text_color_exc = NULL,
  text_fs_exc = NULL,
  text_fface_exc = NULL,
  text_ffamily_exc = NULL,
  text_padding_exc = NULL,
  bg_fill_exc = NULL,
  border_color_exc = NULL,
  width_exc = NULL,
  height_exc = NULL,
  text_color_title = NULL,
  text_fs_title = NULL,
  text_fface_title = NULL,
  text_ffamily_title = NULL,
  text_padding_title = NULL,
  bg_fill_title = NULL,
  border_color_title = NULL,
  width_title = NULL,
  height_title = NULL
)

Arguments

object

fc object.

text_pattern

Text pattern for all the boxes, except the initial and exclusion ones.

text_pattern_init

Text pattern for the initial box.

text_pattern_exc

Text pattern for the exclusion box.

just

Justification for the text: "left", "center" or "right".

text_color

Color of the text. See the col parameter for gpar.

text_fs

Font size of the text. See the fontsize parameter for gpar.

text_fface

Font face of the text. See the fontface parameter for gpar.

text_ffamily

Changes the font family of the text. See the fontfamily parameter for gpar.

text_padding

Changes the text padding inside the box. This number has to be greater than 0.

bg_fill

Box background color. See the fill parameter for gpar.

border_color

Box border color. See the col parameter for gpar.

width

Width of the box. Must be an object of class unit or a number between 0 and 1.

height

Height of the box. Must be an object of class unit or a number between 0 and 1.

just_exc

Justification for the text of the exclude box: "left", "center" or "right".

text_color_exc

Color of the text of the exclude box. See text_color.

text_fs_exc

Font size of the text of the exclude box. See text_fs.

text_fface_exc

Font face of the text of the exclude box. See the fontface parameter for gpar. See text_fface.

text_ffamily_exc

Changes the font family of the text of the exclude box. See the fontfamily parameter for gpar. See text_ffamily.

text_padding_exc

Changes the text padding inside the exclude box. This number has to be greater than 0.

bg_fill_exc

Exclude box background color. See bg_fill.

border_color_exc

Box background color of the exclude box. See border_color.

width_exc

Width of the exclude box. Must be an object of class unit or a number between 0 and 1.

height_exc

Height of the box. Must be an object of class unit or a number between 0 and 1.

text_color_title

Color of the title text.

text_fs_title

Font size of the title text.

text_fface_title

Font face of the title text. See the fontface parameter for gpar.

text_ffamily_title

Changes the font family of the title text. See the fontfamily parameter for gpar.

text_padding_title

Changes the title text padding inside the box. This number has to be greater than 0.

bg_fill_title

Title box background color.

border_color_title

Title box border color.

width_title

Width of the title box. Must be an object of class unit or a number between 0 and 1.

height_title

Height of the title box. Must be an object of class unit or a number between 0 and 1.

Value

List with the dataset and the flowchart parameters with their modifications.

Examples

safo |>
  dplyr::filter(!is.na(group)) |>
  as_fc(label = "Randomized patients") |>
  fc_split(group) |>
  fc_theme(text_fs = 11, text_color = "#324C54", text_fface = 2, bg_fill = "#ADD8E6") |>
  fc_draw()

fc_view

Description

This function allows you to return either the data stored in ⁠$data⁠ or the flowchart information stored in ⁠$fc⁠.

Usage

fc_view(object, what)

Arguments

object

fc object that we want to access.

what

Choose "data" to return the data associated to the flowchart stored in ⁠$data⁠ or "fc" to return the flowchart information stored in ⁠$fc⁠.

Value

Returns a tibble. Either ⁠$data⁠ or ⁠$fc⁠.

Examples

#Return the data associated to the flowchart
safo |>
 as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
 fc_view("data")

#Return the flowchart information
safo |>
 as_fc(label = "Patients assessed for eligibility") |>
 fc_filter(!is.na(group), label = "Randomized", show_exc = TRUE) |>
 fc_view("fc")

format_percentage

Description

rounds percentage values while allowing the option to trim_trailing_zeros

Usage

format_percentage(value, round_digits, trim_trailing_zeros)

Arguments

value

numeric; percentage value to be rounded

round_digits

integer; number of digits past the decimal to round to

trim_trailing_zeros

logical; trim trailing zeros or not in returned value.

is_class

Description

Function to check if an object is from a given class.

Usage

is_class(x, class)

Arguments

x

element to check

class

desired class to check

quiet_prettyNum

Description

Wrapper for prettyNum() that suppresses the original warning message if user big.mark equal to the character defined in the R environment OutDec option.

Usage

quiet_prettyNum(x, big.mark)

Arguments

x

an atomic numerical or character object, possibly complex, typically a vector of real numbers.

big.mark

character. Used to specify the thousands separator for patient count values.

replace_num_in_expr

Description

Helper function for update_numbers().

Usage

replace_num_in_expr(expr, row, big.mark)

Arguments

expr

expression in fc$text.

row

A row from the fc object containing n, N, and perc values.

big.mark

character. Used to specify the thousands separator for patient count values.

Random generated dataset from the SAFO study

Description

This dataset is a random generated dataset to reproduce the numbers needed to generate the flowchart of the SAFO study. SAFO is an open-label, multicenter, phase III–IV superiority randomized clinical trial to assess whether cloxacillin plus fosfomycin administered for the initial 7-days of therapy achieves better treatment success than cloxacillin alone in hospitalized patients with MSSA bacteremia.

Usage

data(safo)

Format

A data frame with 925 rows and 21 columns

id:

Identifier of each patient. This information does not match the real data.

inclusion_crit:

The patient not met the inclusion criteria?

exclusion_crit:

The patient met the exclusion criteria?

chronic_heart_failure:

Exc1: Chronic heart failure?

expected_death_24h:

Exc2: Clinical status with expected death in <24h?

polymicrobial_bacteremia:

Exc3: Polymicrobial bacteremia?

conditions_affect_adhrence:

Exc4: Conditions expected to affect adhrence to the protocol?

susp_prosthetic_valve_endocard:

Exc5: Suspicion of prosthetic valve endocarditis?

severe_liver_cirrhosis:

Exc6: Severe liver cirrhosis?

acute_sars_cov2:

Exc7: Acute SARS-CoV-2 infection?

blactam_fosfomycin_hypersens:

Exc8: Beta-lactam or fosfomycin hypersensitivity?

other_clinical_trial:

Exc9: Participation in another clinical trial?

pregnancy_or_breastfeeding:

Exc10: Pregnancy or breastfeeding?

previous_participation:

Exc11: Previous participation in the SAFO trial?

myasthenia_gravis:

Exc12: Myasthenia gravis?

decline_part:

The patient declined to participate?

group:

Randomized treatment received: cloxacilin alone / cloxacilin plus fosfomycin

itt:

The patient belongs to the intention to treat (ITT) group?

reason_itt:

Reason for exclusion from the ITT group.

pp:

The patient belongs to the per protocol (PP) group?

reason_pp:

Reason for exclusion from the PP group.

References

Grillo, S., Pujol, M., Miró, J.M. et al. Cloxacillin plus fosfomycin versus cloxacillin alone for methicillin-susceptible Staphylococcus aureus bacteremia: a randomized trial. Nat Med 29, 2518–2525 (2023). https://doi.org/10.1038/s41591-023-02569-0

update_numbers

Description

Updates values of n or N referenced in the text column when user specifies big.mark argument in fc_draw.

Usage

update_numbers(object, big.mark = "")

Arguments

object

fc object that we want to draw.

big.mark

character. Used to specify the thousands separator for patient count values. Defaults is no separator (""); if not empty used as mark between every 3 digits (ex: big.mark = "," results in ⁠1,000⁠ instead of 1000).

update_x

Description

Function to update the horizontal position of the previuosly created flow charts, to merge two flowcharts used in fc_merge().

Usage

update_x(x, i, n)

Arguments

x

old horizontal position of the boxes

i

position of the flowchart within the list of flowcharts.

n

number of total flowcharts to merge

update_y

Description

Function to update the vertical position of the previuosly created boxes, to add the new ones with fc_split() or fc_filter().

Usage

update_y(y, type, x, group)

Arguments

y

old height of the boxes

type

type of box

x

horizontal position of the boxes

update_y_stack

Description

Function to update the vertical position of the previuosly created flowcharts, to stack the two flowcharts with fc_stack().

Usage

update_y_stack(y, x, type, i, n)

Arguments

y

old vertical position of the boxes

x

old horizontal position of the boxes

type

type of the boxes

i

position of the flowchart within the list of flowcharts.

n

number of total flowcharts to merge

update_y_stack_unite

Description

Function to update the vertical position of the previuosly created flowcharts, to stack the two flowcharts with fc_stack(), when unite is TRUE.

Usage

update_y_stack_unite(y, x, type)

Arguments

y

old vertical position of the boxes

x

old horizontal position of the boxes

type

type of the boxes