Plot an mfsusie() / fsusie() fit — mfsusie

One unified plot for both single-outcome (fsusie()) and multi-outcome (mfsusie()) fits. When M = 1 the layout is a single 2-panel column (PIP on top, effect curves on bottom). When M > 1 the layout tiles per-outcome panels on a dense grid with the PIP plot in the top-left slot.

Usage

mfsusie_plot(
  fit,
  m = NULL,
  pos = NULL,
  effect_style = c("band", "errorbar"),
  facet_cs = c("auto", "stack", "overlay"),
  show_grid_dots = FALSE,
  show_lfsr_curve = TRUE,
  show_affected_region = TRUE,
  lfsr_threshold = 0.01,
  lwd = 2,
  add_legend = TRUE,
  truth = NULL,
  effect_variables = NULL,
  smooth_method = NULL,
  save = NULL,
  ...
)

Arguments

fit: a fit returned by mfsusie() or fsusie().
m: optional integer index. When supplied, plot only that outcome's effect panel (no PIP). Default NULL: full layout.
pos: optional length-p vector for the PIP x-axis.
effect_style: "band" (default) or "errorbar". Style of the effect panel.
facet_cs: "auto" (default), "stack", or "overlay". Layout of multiple credible sets within an effect panel.
show_grid_dots: logical, draw circles at each post-remap grid point on top of the curves. Default FALSE.
show_lfsr_curve: logical, overlay HMM lfsr curves on a secondary axis when fit$lfsr_curves is populated. Only honored in effect_style = "band". Default TRUE. The solid line is the effect (left axis), the dashed line is the lfsr (right axis, 0 to 1). For a dedicated per-CS lfsr view see mfsusie_plot_lfsr().
show_affected_region: logical, mark contiguous segments where each CS's credible band excludes zero with thick bars at the bottom of the effect panel (band mode) or with black dots on the zero line (errorbar mode). Default TRUE.
lfsr_threshold: numeric, dashed reference line on the lfsr secondary axis. Default 0.01.
lwd: numeric, curve line width. Default 1.5.
add_legend: logical, show CS legend on each panel. Default TRUE.
truth: optional ground-truth overlay for the effect-target panels (positions along the function where the true effect is non-zero). For M = 1: a length-T_1 numeric vector (replicated across all CS panels) or a length-K list of length-T_1 vectors (per-CS truth). For M > 1: a length-M list, each entry one of those two shapes (or NULL to skip an outcome). Truth values are overlaid as dark-grey dots in each effect panel. Default NULL (no overlay).
effect_variables: optional indicator of the true-effect variables (column indices of X that carry a non-zero true effect). When non-NULL, the PIP panel draws a red bold open circle around each indicated variable's PIP dot, mirroring susieR::susie_plot()'s b argument. Accepts: integer index vector (1-based), length-p logical (TRUE = true effect), or length-p numeric (non-zero = true effect). Default NULL.
save: optional file path. When non-NULL the plot is written to the file at the dimensions returned by mfsusie_plot_dimensions(). The graphics device is selected from the file extension: .pdf, .png, .jpg/.jpeg, or .svg. Default NULL (draw to the current device).
...: reserved.

Value

Called for side effect; returns invisible(NULL).

Details

Effect curves come from fit$effect_curves when post-processed smoothing has been applied (see mf_post_smooth()); otherwise from the wavelet-domain inverse via coef(). With effect_style = "band" (default) credible bands are drawn as transparent ribbons; with effect_style = "errorbar" each position gets a dot at the mean and a vertical bar to the credible band (errorbar mode requires post-smoothed credible bands and errors otherwise).

Multiple credible sets can be drawn overlaid (facet_cs = "overlay") or in stacked rows (facet_cs = "stack"); the default "auto" picks stack when there are at least 3 CSes or when their affected-region masks are pairwise disjoint.

After mf_post_smooth(method = "HMM") the per-position lfsr curves are overlaid on a secondary axis (band mode) with a threshold line at lfsr_threshold (default 0.01). For the per-CS lfsr bubble grid see mfsusie_plot_lfsr().