Data Cleanning Helper for Eclipse Plot

Description

Standardizes both column names and cell values to ensure compatibility with the 'eclipseplot' engine. It uses fuzzy matching via regular expressions to identify headers and a robust dictionary to map various shorthand judgments into the four standard risk-of-bias levels.

Usage

eclipsedf(df)

Arguments

Details

Column Name Standardization: The function identifies columns regardless of case and replaces them with:

• study: Matches "study", "article", "label", "paper", or "estudo".

• pmid: Matches "pmid", "pm_id", "pm id", "article id", "article_id", or "id".

• itemX_stepY: Matches any string containing "item" followed by a number and "step" followed by a number (e.g., "Item 1, Step 2" becomes "item1_step2").

Value Standardization (Fuzzy Mapping): Judgment inputs are converted to lowercase and trimmed of whitespace. The mapping logic is as follows:

• "Definitely Low": Result for "definitely yes", "definitely low", "dy", "dl", "yes", or "y".

• "Probably Low": Result for "probably yes", "probably low", "py", or "pl".

• "Probably High": Result for "probably no", "probably high", "pn", "ph", or "probably-no".

• "Definitely High": Result for "definitely no", "definitely high", "dn", "dh", "no", or "n".

• "Not applicable": Assigned to any other value, including empty cells (NA) or unrecognized text.

Value

A standardized data frame with specific categorical levels ("Definitely Low", "Probably Low", "Probably High", and "Definitely High") and column names (itemX_stepY) for use in the eclipse plot.

Note

For the purposes of the 'eclipseplot' function, there is no distinction between the internal mapping of Step 1 and Step 2 values. Both are standardized using the Step 2 visual scheme (color palette) to ensure a cohesive graphical representation, as the underlying directional logic remains the same.

#' @example data(messy) view(messy) organized <- eclipsedf(messy) view(organized)

Create a plot for a risk of bias assessment with the ROBUST-RCT tool

Description

A visual representation of risk-of-bias assessments of randomized controlled trials using the ROBUST-RCT framework, as described in Wang et al. (2025) <doi:10.1136/bmj-2024-081199>. It can display either the standard two-step assessment or a simplified judgment-only version.

Usage

eclipseplot(
  robust_data,
  standard = TRUE,
  optionals = FALSE,
  title = NULL,
  plot = "full",
  design = "horizontal",
  proportions = NULL
)

Arguments

Details

The input data frame must include the required columns for the ROBUST-RCT domains. The following columns are expected:

• pmid: PubMed ID or unique identifier.

• study: Study name (e.g., "Author, 2026").

• Core Items (1-6): Columns named 'itemX_step1' and 'itemX_step2' (where X is 1 to 6). As standard in the ROBUST-RCT tool, item 6 does not have a multiple-choice step 1 evaluation, so it is automatically marked as NA.

• Optional Items: If optionals = TRUE, columns named 'optX_step1' and 'optX_step2' (where X is 1 to 9).

Allowed values for Step 1 (Evaluation): "Definitely Yes", "Probably Yes", "Probably No", "Definitely No", "Not applicable".

Allowed values for Step 2 (Judgment): "Definitely Low", "Probably Low", "Probably High", "Definitely High", "Not applicable".

Value

A ggplot object (specifically a ggdraw object from the cowplot package) representing the visualization of the risk of bias. The output can be further customized using standard ggplot2 functions or saved via save_eclipseplot.

Dataset Structure

Your CSV should look like this (Top 2 rows):

"pmid","study","item1_step1","item1_step2","item2_step1"..."item6_step2"
"40001","Albert, 2024","Definitely Yes","Definitely Low",..."Probably Low"

Color Mapping:

• Definitely Low / Definitely Yes: Blue (#4C72B0)

• Probably Low / Probably Yes: Light Blue (#c3d0e4)

• Probably High / Probably No: Light Red (#f5c7c7)

• Definitely High / Definitely No: Red (#E15759)

• Not applicable: Grey (#D3D3D3)

Author(s)

Pedro Rodrigues Vidor pedro.vidor@ufrgs.br

Yohan Casiraghi (Contributor)

Sofia Simoni Rossi Fermo (Contributor)

Adolfo Moraes de Souza (Contributor)

Patricia Klarmann Ziegelmann (Contributor)

Maria Inês Schmidt (Contributor)

Maicon Falavigna (Contributor)

Examples

# 1. Standard plot (Core items, Steps 1 & 2)
data(sample_brief)
eclipseplot_plot <- eclipseplot(sample_brief)
print(eclipseplot_plot)


# 2. Judgment only (Core items, Step 2)
eclipseplot(sample_long, standard = FALSE)

# 3. Plot with optional items (Core and optional items, Steps 1 & 2)
eclipseplot(sample_long, optionals = TRUE)

# 4. Judgment only with optional items (Core and optional items, Step 2)
eclipseplot(sample_long, standard = FALSE, optionals = TRUE)

# 5. Vertical full-page plot
eclipseplot(sample_long, design = "vertical", proportions = c(0.7, 0.3))

# 6. Plotting only the dots
eclipseplot(sample_brief, plot = "eclipses")

# 7. Plotting only the legend
eclipseplot(sample_brief, plot = "legend")

Convert ROBUST Standard Spreadsheet to eclipseplot format

Description

This function facilitates the conversion of data extracted using the standard ROBUST spreadsheet into the format required by 'eclipseplot'. It automatically identifies header locations, maps Step 1 and Step 2 columns for each domain, and filters out common spreadsheet artifacts (e.g., merged cells or labels like "Intervention Group").

Usage

from_xlsx(path, sheet = 1)

Arguments

Value

A standardized data frame formatted for 'eclipseplot' with specific column names (itemX_stepY) and categorical levels for bias assessment.

Get path to example files (.csv)

Description

Get path to example files (.csv)

Usage

get_eclipse_data(name = "brief")

Arguments

Value

A character string containing the absolute file path to the requested sample CSV file within the package installation directory.

Mock messy data for eclipsedf testing

Description

A dataset containing messy headers and non-standard values to test the cleaning and standardization capabilities of the eclipsedf function.

Usage

messy

Format

A data frame with 4 rows and 13 variables of varied naming conventions.

Sample brief dataset for eclipseplot

Description

A small dataset containing risk of bias assessments for testing.

Usage

sample_brief

Format

A data frame with 5 rows and 13 variables:

pmid

PubMed ID

study

Study citation label

item1_step1, item1_step2, item2_step1, item2_step2, item3_step1, item3_step2, item4_step1, item4_step2, item5_step1, item5_step2, item6_step2

Risk of bias for the core items

Sample long dataset for eclipseplot

Description

A larger dataset with more studies and optional items.

Usage

sample_long

Format

A data frame with 26 rows and 13 variables.

Export the eclipseplot to a file

Description

Export the eclipseplot to a file

Usage

save_eclipseplot(plot_object, filename, width = 14, height = 9.8, dpi = 72)

Arguments

Value

No return value, called for side effects (saves a file to the specified location).

Examples

  # Using a temporary directory
  data(sample_brief)
  p <- eclipseplot(sample_brief)
  tmp_file <- file.path(tempdir(), "test_plot.png")
  save_eclipseplot(p, filename = tmp_file)