plot_mr_scatter: Plot MR Scatter Plots for Multiple Outcomes and Exposures

In autoMR: Automated Mendelian Randomization Workflows and Visualizations

Plot MR Scatter Plots for Multiple Outcomes and Exposures

Description

Generates one scatter plot per outcome-exposure pair using base R graphics, with a regression line overlaid for each requested Mendelian Randomization (MR) method. Plot parameters are stored in an MRScatterPlots S4 object and rendered on demand at export time, so no files are written to disk during this call.

Usage

plot_mr_scatter(
  MR_input_data,
  plot.xlab = "Exposure",
  plot.ylab = "Outcome",
  methods.plot = c("IVW", "RAPS", "Egger", "PRESSO", "Horse"),
  NbDistribution_presso = 1000,
  SignifThreshold_presso = 0.05,
  mr_horse_n_iter = 5000,
  mr_horse_n_burnin = 1000,
  show.legend = TRUE,
  summary_df = NULL,
  effect_scale = "Beta",
  use_df_results = TRUE,
  custom_xlim = NULL,
  custom_ylim = NULL,
  symmetric_ylim = TRUE
)

Arguments

MR_input_data	Harmonised MR input data frame. Must contain Outcome and Exposure columns.
plot.xlab	Character string; prefix for the x-axis label. Default is "Exposure". When effect_scale is "OR" or "HR", the label is automatically prefixed with log(OR) or log(HR).
plot.ylab	Character string; prefix for the y-axis label. Default is "Outcome".
methods.plot	Character vector of MR methods to overlay as regression lines. Supported values: "IVW", "RAPS", "Egger", "PRESSO", "Horse", "GRIP".
NbDistribution_presso	Integer; number of simulated distributions for on-the-fly MR-PRESSO calculation. Default is 1000.
SignifThreshold_presso	Numeric; significance threshold for on-the-fly MR-PRESSO outlier test. Default is 0.05.
mr_horse_n_iter	Integer; number of Markov chain Monte Carlo (MCMC) iterations for on-the-fly MR-Horse. Default is 5000.
mr_horse_n_burnin	Integer; number of MCMC burn-in samples for on-the-fly MR-Horse. Default is 1000.
show.legend	Logical; whether to annotate each plot with method labels, beta estimates, and p-values. Default is TRUE.
summary_df	Optional data frame of pre-calculated results from run_mr_analysis(). When supplied together with use_df_results = TRUE, avoids re-running the analysis.
effect_scale	Character string matching the scale used in summary_df: "Beta", "OR", or "HR". Default is "Beta".
use_df_results	Logical; if TRUE and summary_df is provided, method slopes are read from summary_df instead of being re-calculated. Default is TRUE.
custom_xlim	Optional numeric vector of length 2 for x-axis limits. If NULL, limits are determined from the data. Useful for excluding outlier instruments from the visible range without removing them from the analysis.
custom_ylim	Optional numeric vector of length 2 for y-axis limits. If NULL, limits are determined from the data.
symmetric_ylim	Logical; if TRUE (the default), the y-axis limits are forced to be symmetric around zero (the null on the beta / log scale) for every effect scale. If FALSE, Beta outcomes remain symmetric while OR/HR outcomes use the data range with 10% padding. Ignored when custom_ylim is supplied.

Value

An MRScatterPlots object containing one plot parameter list per outcome-exposure pair, together with outcome and exposure metadata. Each parameter list holds all data and settings needed to render the plot on demand — including show.legend — so settings like show.legend = FALSE are correctly applied at export time. Use export_scatter_plots() to write plots to disk with optional filtering by outcome, exposure, or both.

Examples

data("merged_data")
input3  <- harmonize_mr_data(df = merged_data)$input_df
outcome3 <- run_mr_analysis(
  MR_input_data     = input3,
  outcome.form      = c("Beta","OR"),
  use_ivw           = TRUE,
  use_raps          = FALSE,
  use_median        = FALSE,
  use_egger         = FALSE,
  use_mr_presso     = FALSE,
  use_mr_horse      = FALSE,
  use_mr_grip       = FALSE,
  NbDistribution    = 1000,
  SignifThreshold   = 0.05,
  mr_horse_n_iter   = 5000,
  mr_horse_n_burnin = 1000,
  mr_grip_parameters = NULL
)

# Pass pre-calculated results to avoid rerunning the analysis
plots <- plot_mr_scatter(
  MR_input_data  = input3,
  summary_df     = outcome3,
  use_df_results = TRUE
)

# Inspect the object; for fi_49item this prints:
#   [1] fi_49item :: Zn

# Retrieve the exact outcome/exposure labels stored in the object
out_name <- plots@outcomes[1]   # "fi_49item"
exp_name <- plots@exposures[1]  # "Zn"

# Export all plots as PDF (commented — writes to disk)
export_scatter_plots(plots, save_dir = tempdir(), file_type = "pdf")

# Export one outcome only
export_scatter_plots(plots, save_dir = tempdir(), outcome = out_name)

# Export one exposure only
export_scatter_plots(plots, save_dir = tempdir(), exposure = exp_name)

# Export one specific pair
# export_scatter_plots(plots, save_dir = tempdir(), outcome = out_name, exposure = exp_name)

# Export as PNG instead
export_scatter_plots(plots, save_dir = tempdir(), file_type = "png")

autoMR documentation built on June 12, 2026, 9:07 a.m.