% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mr_workflows.R
\name{plot_mr_scatter}
\alias{plot_mr_scatter}
\title{Plot MR Scatter Plots for Multiple Outcomes and Exposures}
\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{
\item{MR_input_data}{Harmonised MR input data frame. Must contain
\code{Outcome} and \code{Exposure} columns.}

\item{plot.xlab}{Character string; prefix for the x-axis label.
Default is \code{"Exposure"}. When \code{effect_scale} is \code{"OR"} or
\code{"HR"}, the label is automatically prefixed with \code{log(OR)} or
\code{log(HR)}.}

\item{plot.ylab}{Character string; prefix for the y-axis label.
Default is \code{"Outcome"}.}

\item{methods.plot}{Character vector of MR methods to overlay as
regression lines. Supported values: \code{"IVW"}, \code{"RAPS"},
\code{"Egger"}, \code{"PRESSO"}, \code{"Horse"}, \code{"GRIP"}.}

\item{NbDistribution_presso}{Integer; number of simulated distributions
for on-the-fly MR-PRESSO calculation. Default is \code{1000}.}

\item{SignifThreshold_presso}{Numeric; significance threshold for
on-the-fly MR-PRESSO outlier test. Default is \code{0.05}.}

\item{mr_horse_n_iter}{Integer; number of Markov chain Monte Carlo (MCMC)
iterations for on-the-fly MR-Horse. Default is \code{5000}.}

\item{mr_horse_n_burnin}{Integer; number of MCMC burn-in samples for
on-the-fly MR-Horse. Default is \code{1000}.}

\item{show.legend}{Logical; whether to annotate each plot with method
labels, beta estimates, and p-values. Default is \code{TRUE}.}

\item{summary_df}{Optional data frame of pre-calculated results from
\code{run_mr_analysis()}. When supplied together with
\code{use_df_results = TRUE}, avoids re-running the analysis.}

\item{effect_scale}{Character string matching the scale used in
\code{summary_df}: \code{"Beta"}, \code{"OR"}, or \code{"HR"}.
Default is \code{"Beta"}.}

\item{use_df_results}{Logical; if \code{TRUE} and \code{summary_df} is
provided, method slopes are read from \code{summary_df} instead of
being re-calculated. Default is \code{TRUE}.}

\item{custom_xlim}{Optional numeric vector of length 2 for x-axis limits.
If \code{NULL}, limits are determined from the data. Useful for excluding
outlier instruments from the visible range without removing them from
the analysis.}

\item{custom_ylim}{Optional numeric vector of length 2 for y-axis limits.
If \code{NULL}, limits are determined from the data.}

\item{symmetric_ylim}{Logical; if \code{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 \code{FALSE}, Beta outcomes remain
symmetric while OR/HR outcomes use the data range with 10\% padding.
Ignored when \code{custom_ylim} is supplied.}
}
\value{
An \code{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 \code{show.legend} — so settings like
  \code{show.legend = FALSE} are correctly applied at export time.
  Use \code{export_scatter_plots()} to write plots to disk with optional
  filtering by outcome, exposure, or both.
}
\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
\code{MRScatterPlots} S4 object and rendered on demand at export
time, so no files are written to disk during this call.
}
\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
)
\donttest{
# 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")

}
}
