% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stimulus.plot.R
\name{stimulus.plot}
\alias{stimulus.plot}
\title{Make stimulus plots as in "Stimulus Sampling Reimagined"}
\usage{
stimulus.plot(
  plot.type = "means",
  data,
  dv,
  condition,
  stimulus,
  participant = "",
  save.as = "",
  svg.width = "",
  svg.height = "",
  sort.by = "",
  flip.conditions = FALSE,
  model = c(),
  overall.estimate = c(),
  overall.ci = c(),
  overall.p = c(),
  overall.label = c(),
  ylab1 = "",
  ylab2 = "",
  xlab1 = "Stimuli",
  xlab2 = "",
  decimals = "auto",
  null.method = "shuffle",
  dv.is.percentage = FALSE,
  legend.title = "",
  simtot = 1000,
  watermark = TRUE,
  seed = 2024,
  ylim = c(),
  main = "",
  ...
)
}
\arguments{
\item{plot.type}{Either `"means"` or `"effects"`; determines what is plotted on the y-axis.}

\item{data}{Data frame containing variables to be analyzed.}

\item{dv}{Name of the dependent variable (e.g., `dv = 'y'`); quotes are not required.}

\item{condition}{Name of the variable containing the condition indicator.}

\item{stimulus}{Name of the variable containing the stimulus ID.}

\item{participant}{Name of the variable containing participant IDs; necessary for valid
inference when `plot.type = 'effects'` and each participant provided more than one observation.}

\item{save.as}{File path for saving the figure (`.svg` or `.png`, optional).}

\item{svg.width}{Optional width when saving to SVG/PNG.}

\item{svg.height}{Optional height when saving to SVG/PNG.}

\item{sort.by}{Variable to sort stimuli by. Defaults to sorting by observed effect size.}

\item{flip.conditions}{If `TRUE`, subtract the first condition from the second instead of the default.}

\item{model}{Method used to compute overall average: `'regression'`, `'intercepts'`,
`'slopes'`, and/or `'all'`.}

\item{overall.estimate}{Scalar or vector of overall average effect computed outside statuser.}

\item{overall.ci}{Confidence interval bounds for `overall.estimate`.}

\item{overall.p}{P-value for overall average effect computed outside statuser.}

\item{overall.label}{Label for overall averages on the x-axis.}

\item{ylab1, ylab2}{Labels on the y-axis (optional).}

\item{xlab1, xlab2}{Labels on the x-axis (optional).}

\item{decimals}{Number of decimals for value labels (`"auto"` by default).}

\item{null.method}{Null method for effects plots: `"shuffle"` or `"demean"`.}

\item{dv.is.percentage}{If `TRUE`, format the dependent variable as percentages.}

\item{legend.title}{Text with title above legend (optional).}

\item{simtot}{Number of resamples for heterogeneity under null (effects plots).}

\item{watermark}{If `TRUE`, display package version watermark.}

\item{seed}{Seed used when resampling for effects plots.}

\item{ylim}{Optional y-axis limits.}

\item{main}{Plot title.}

\item{...}{Additional arguments passed to [graphics::plot.default()].}
}
\value{
Invisibly, a data frame (means plot) or list (effects plot).
}
\description{
Build stimulus plots comparing results for individual stimuli in an experiment
(Simonsohn, Montealegre, & Evangelidis, 2024).
}
