% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plotly_Utils.R
\name{add_smooth}
\alias{add_smooth}
\title{Add regression to plotly plot}
\usage{
add_smooth(
  p = plotly::last_plot(),
  x = NULL,
  y = NULL,
  data = NULL,
  method = c("lm", "loess"),
  span = 0.75,
  line = TRUE,
  ci = 0.95,
  stats = TRUE
)
}
\arguments{
\item{p}{The plot to which the shape should be added. Default is the
\code{plotly::last_plot()}.}

\item{x}{X value for regression if not the original x value of the plot. Be
sure to specify as a formula, e.g. \code{x = ~pred}.}

\item{y}{Y value for regression if not the original y value of the plot. Be
sure to specify as a formula, e.g. \code{y = ~obs}.}

\item{data}{A secondary data object to use for regression other than the
original plot data.}

\item{method}{The tegression method, currently either "lm" (the default) for
linear regression, or "loess" for loess regression.}

\item{span}{Only used for \code{method = "loess"}. The span parameter to control
the degree of smoothing. Default is 0.75.}

\item{line}{Controls characteristics of lines. This argument maps to plotly line attributes. \code{TRUE} will plot default lines. \code{FALSE} will suppress lines. If a list, can control many line characteristics, including overriding defaults. Use the plotly \code{plotly::schema()} command in the console and navigate to traces > scatter > attributes > line to see all the ways the line can be formatted. Most common will be:  \itemize{ \item{\code{color}} Line color. \item{\code{dash}} Plotting character. See \code{plotly::schema()}, traces > scatter >  attributes > line > dash > values. \item{\code{width}} Thickness in points. }

Example: \code{line = list(color = "red", dash = "longdash", width = 2)}
Default is \code{list(color = "blue", width = 2)}.
The confidence interval will have the same color but at opacity 0.2.}

\item{ci}{Confidence interval for regressions. Default is 0.95. It can be suppressed
by setting to 0.}

\item{stats}{Add the statistics from linear regression to the plot. Ignored if
\code{method = "loess"}. If missing or
\code{FALSE}, will be suppressed. Can be set to \code{TRUE} which results in default format of
\code{list(x= 0.8, y = 0.1, bold = F, font = list(color = "black", family = "Arial", size = 14))}.
The coordinates are relative to the plot with lower left = (0,0), upper right = (1,1). This
argument maps to \code{plotly::add_text()}. It is also an option that can be set in
\link{setPMoptions} to avoid specifying this argument for every plot. The default option
is \code{TRUE}. If specified as a
Pmetrics option, it can be overridden for specific plots by supplying a value.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#stable}{\figure{lifecycle-stable.svg}{options: alt='[Stable]'}}}{\strong{[Stable]}}

Modifies an existing plot to include a regression line with  confidence interval.
}
\details{
This function adds a regression line to an existing  plotly plot.
The default is to use the x and y values in the plot, but this can be overridden
by specifying a data object. If another \code{data} object is used, values for \code{x} and \code{y}
must also be specified. Alternatively, the original data can be used and new columns
selected for regression by omitting the \code{data} argument and specifying new \code{x} and
\code{y} values. The intent of this function is to replicate the behavior of
\code{ggplot::geom_smooth()}.
}
\examples{
\dontrun{
plotly::plot_ly(mtcars,
  x = ~hp, y = ~mpg,
  type = "scatter", mode = "markers", showlegend = FALSE
) |>
  add_smooth()
plotly::plot_ly(iris,
  x = ~Sepal.Length, y = ~Petal.Length,
  type = "scatter", mode = "markers", showlegend = FALSE
) |>
  add_smooth(method = "loess", ci = 0.9, line = list(color = "red", dash = "dash"))
}
}
\seealso{
\link{add_shapes}
}
