Skip to contents

Create a Margot Plot with Interpretation

Source: R/margot_plot.R
margot_plot.Rd

This function creates a Margot plot, which is useful for visualising causal effects. It provides various options for customizing the plot and transforming labels. Additionally, it generates a compact interpretation of the results and returns a transformed table.

Usage

margot_plot(
  .data,
  type = c("RD", "RR"),
  order = c("alphabetical", "magnitude", "custom", "default"),
  title_binary = NULL,
  include_coefficients = TRUE,
  standardize_label = c("NZ", "US", "none"),
  interpret_all_E_gt1 = TRUE,
  ...,
  options = list(),
  label_mapping = NULL,
  save_output = FALSE,
  use_timestamp = FALSE,
  base_filename = "margot_plot_output",
  prefix = NULL,
  save_path = here::here("push_mods"),
  original_df = NULL
)

Arguments

.data

A data frame containing the data to be plotted. It must include an `outcome` column and either `E[Y(1)]-E[Y(0)]` or `E[Y(1)]/E[Y(0)]` columns representing the causal estimates.

type

Character string specifying the type of plot. Either `"RD"` (Risk Difference) or `"RR"` (Risk Ratio). Default is `"RD"`.

order

Character string specifying the order of outcomes. Can be `"alphabetical"`, `"magnitude"`, `"custom"`, or `"default"`. - `"alphabetical"`: Orders outcomes alphabetically. - `"magnitude"`: Orders outcomes by the absolute magnitude of the effect size in descending order. - `"custom"`: Allows for a custom ordering (requires additional implementation). - `"default"`: Equivalent to `"magnitude"` for backward compatibility. Default is `"alphabetical"`.

title_binary

Optional title for the plot. If not provided, the title from `options` is used.

include_coefficients

Logical. If `TRUE`, includes the text of the coefficients in the plot. Default is `TRUE`.

standardize_label

Character. If `"NZ"`, the x-axis uses "Standardised" (NZ/UK style) for RD effects. If `"US"`, the x-axis uses "Standardized". If `"none"`, omits that word entirely. Default is `"NZ"`. When `type == "RR"`, this word is always omitted.

interpret_all_E_gt1

Logical. If `TRUE`, interprets any effect estimate with an `E_Value` > 1. In that case, the final interpretation text reads "All other effect estimates presented unreliable evidence for causality." Default is `FALSE`.

...

Additional arguments passed to the plotting function, allowing further customization.

options

A list of additional options for customizing the plot. See **Details** for available options.

label_mapping

A named list for custom outcome label mapping. See **Details** for usage.

save_output

Logical. If `TRUE`, saves the complete output to a file. Default is `FALSE`.

use_timestamp

Logical. If `TRUE`, adds a timestamp to the saved filename. Default is `FALSE`.

base_filename

Character string. The base name for the saved file. Default is `"margot_plot_output"`.

prefix

Character string. An optional prefix for the saved filename. Default is `NULL`.

save_path

Character string. The directory path where the output will be saved. Default is `here::here("push_mods")`.

original_df

Optional data frame containing the original (non-transformed) data for back-transformation of results. If provided, it should correspond to `.data` before any transformations.

Value

A list containing three elements:

  • `plot`: A `ggplot` object representing the Margot plot.

  • `interpretation`: A character string containing the compact interpretation of the results.

  • `transformed_table`: A data frame with the original data and transformed row names, using the same transformation options as the plot labels.

If `save_output` is `TRUE`, the complete output will be saved to a file using `margot::here_save_qs()`.

Details

The `options` list can include the following parameters:

  • `title`: Character string. Main title for the plot.

  • `subtitle`: Character string. Subtitle for the plot.

  • `estimate_scale`: Numeric. Scaling factor for estimates. Default is `1`.

  • `base_size`: Numeric. Base font size for the plot. Default is `18`.

  • `text_size`: Numeric. Font size for text labels. Default is `2.75`.

  • `point_size`: Numeric. Size of points in the plot. Default is `3`.

  • `title_size`: Numeric. Font size for the main title. Default is `20`.

  • `subtitle_size`: Numeric. Font size for the subtitle. Default is `18`.

  • `legend_text_size`: Numeric. Font size for legend text. Default is `10`.

  • `legend_title_size`: Numeric. Font size for legend title. Default is `10`.

  • `linewidth`: Numeric. Width of lines in the plot. Default is `0.4`.

  • `x_offset`: Numeric. Horizontal offset for text labels on the plot. If `NULL`, it is set based on the `type` (`0` for "RR" and `-1.75` for "RD").

  • `x_lim_lo`: Numeric. Lower limit for the x-axis. If `NULL`, it is set based on the `type` (`0.1` for "RR" and `-1.75` for "RD").

  • `x_lim_hi`: Numeric. Upper limit for the x-axis. If `NULL`, it is set based on the `type` (`2.5` for "RR" and `1` for "RD").

  • `plot_theme`: ggplot2 theme object. Custom theme for the plot.

  • `colors`: Named vector. Custom colors for different estimate categories. Example: `c("positive" = "green", "not reliable" = "gray", "negative" = "red")`.

  • `facet_var`: Character string. Variable name for faceting the plot. Allows creating subplots based on a categorical variable.

  • `confidence_level`: Numeric. Confidence level for intervals. Default is `0.95`.

  • `annotations`: ggplot2 layer. Custom annotations to add to the plot, such as text or shapes.

  • `show_evalues`: Logical. If `TRUE`, shows E-values in the plot. Default is `TRUE`.

  • `evalue_digits`: Integer. Number of digits for E-value display. Default is `2`.

  • `remove_tx_prefix`: Logical. If `TRUE`, removes `"tx_"` prefix from labels and interpretation. Default is `TRUE`.

  • `remove_z_suffix`: Logical. If `TRUE`, removes `"_z"` suffix from labels and interpretation. Default is `TRUE`.

  • `use_title_case`: Logical. If `TRUE`, converts labels and interpretation to title case. Default is `TRUE`.

  • `remove_underscores`: Logical. If `TRUE`, removes underscores from labels and interpretation. Default is `TRUE`.

The `label_mapping` parameter allows for custom renaming of specific outcomes:

  • It should be a named list where names are original outcome labels and values are new labels.

  • Outcomes not specified in `label_mapping` will use default transformations based on `options`.

  • Custom mapped labels are used as-is, without applying default transformations.

Examples

if (FALSE) { # \dontrun{
# Create sample data
sample_data <- data.frame(
  outcome = c("t1_outcome_a_z", "t2_outcome_b_z", "t3_outcome_c_z"),
  `E[Y(1)]-E[Y(0)]` = c(0.1, -0.2, 0.3),
  `2.5 %` = c(0.05, -0.3, 0.2),
  `97.5 %` = c(0.15, -0.1, 0.4),
  E_Value = c(1.5, 1.8, 2.0),
  E_Val_bound = c(1.3, 1.5, 1.7),
  unit = c("unit1", "unit2", "unit3")
)

# Create a Margot plot with interpretation and transformed table.
# With interpret_all_E_gt1 = TRUE, all estimates with E_Value > 1 are interpreted.
result <- margot_plot(
  .data = sample_data,
  type = "RD",
  order = "alphabetical",
  standardize_label = "US",
  interpret_all_E_gt1 = TRUE,
  options = list(
    title = "Causal Effect Estimates",
    subtitle = "Risk Difference Scale",
    colors = c("positive" = "green", "not reliable" = "black", "negative" = "red"),
    remove_tx_prefix = TRUE,
    remove_z_suffix = TRUE,
    use_title_case = TRUE,
    remove_underscores = TRUE
  ),
  label_mapping = list(
    "t1_outcome_a_z" = "Outcome A",
    "t2_outcome_b_z" = "Outcome B",
    "t3_outcome_c_z" = "Outcome C"
  ),
  include_coefficients = FALSE,
  save_output = FALSE
)

# Display the plot
print(result$plot)

# Display the interpretation
cat(result$interpretation)

# Display the transformed table
print(result$transformed_table)
} # }