Package 'flowchart'

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",
  hide = FALSE
)

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	Structure that will have the text in the box. It recognizes label, n, N and perc within brackets. By default it is "{label}\n{N}". If 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.
hide	Logical value to hide the initial box or not. Default is FALSE. hide = TRUE can only be combined with fc_split().

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,
  box_corners = "round",
  arrow_angle = 30,
  arrow_length = grid::unit(0.1, "inches"),
  arrow_ends = "last",
  arrow_type = "closed",
  title = NULL,
  title_x = 0.5,
  title_y = 0.9,
  title_color = "black",
  title_fs = 15,
  title_fface = 2,
  title_ffamily = NULL
)

Arguments

object	fc object that we want to draw.
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'.
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.

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.

Details

- **Vector Formats ('svg', 'pdf'):** These formats are ideal for graphics that need to be scaled without loss of quality. The default units for width and height are inches. If user specifies 'units' other than inches ("mm" or "cm"), the function will convert the dimensions to inches using standard conversion formulas. - **Bitmap Formats ('png', 'jpeg', 'tiff', 'bmp'):** For these formats (with the exception of 'bmp'), the function uses the 'ragg' package devices when available, providing higher performance and higher quality output. The default units for width and height are pixels. - **Suggested Dependencies:** For superior performance and quality bitmap outputs, it is recommended to install the ‘ragg' package. For exporting to ’pdf' format with enhanced features, the Cairo graphics library will be used if it is available.

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,
  just = "center",
  text_color = "black",
  text_fs = 8,
  text_fface = 1,
  text_ffamily = NA,
  text_padding = 1,
  bg_fill = "white",
  border_color = "black",
  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
)

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	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 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	Structure that will have the text in each of the excluded boxes. It recognizes label, n, N and perc within brackets. For default it is "{label}\n {n} ({perc}%)". If label_exc 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.
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.
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).

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,
  just = "center",
  text_color = "black",
  text_fs = 8,
  text_fface = 1,
  text_ffamily = NA,
  text_padding = 1,
  bg_fill = "white",
  border_color = "black",
  title = NULL,
  text_color_title = "black",
  text_fs_title = 10,
  text_fface_title = 1,
  text_ffamily_title = NA,
  text_padding_title = 0.6,
  bg_fill_title = "white",
  border_color_title = "black",
  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	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 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.
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.
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.
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.
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_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")

---

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

---