% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/logist_plot.R
\name{logist_plot}
\alias{logist_plot}
\alias{logist_plot.default}
\alias{logist_plot.data.frame}
\alias{logist_plot.formula}
\alias{logist_hist}
\alias{logist_point}
\alias{logist_density}
\title{Plot a fitted logistic regression with marginal distributions of the predictor}
\usage{
logist_plot(x, ...)

\method{logist_plot}{default}(
  x,
  y,
  marginal = c("hist", "points", "density"),
  bins = 30,
  adjust = 1,
  xlab = NULL,
  ylab = NULL,
  fit.color = "steelblue",
  marginal.color = "orange",
  fit.args = list(),
  marginal.args = list(),
  group = NULL,
  group.colors = NULL,
  marginal.height = NULL,
  ...
)

\method{logist_plot}{data.frame}(
  x,
  xvar = 1L,
  yvar = 2L,
  marginal = c("hist", "points", "density"),
  bins = 30,
  adjust = 1,
  xlab = NULL,
  ylab = NULL,
  fit.color = "steelblue",
  marginal.color = "orange",
  fit.args = list(),
  marginal.args = list(),
  group = NULL,
  group.colors = NULL,
  marginal.height = NULL,
  ...
)

\method{logist_plot}{formula}(
  formula,
  data,
  marginal = c("hist", "points", "density"),
  bins = 30,
  adjust = 1,
  xlab = NULL,
  ylab = NULL,
  fit.color = "steelblue",
  marginal.color = "orange",
  fit.args = list(),
  marginal.args = list(),
  group = NULL,
  group.colors = NULL,
  marginal.height = NULL,
  ...
)

logist_hist(...)

logist_point(...)

logist_density(...)
}
\arguments{
\item{x}{a numeric predictor vector or a data frame; see \code{formula} below for the
model-formula interface}

\item{...}{arguments passed to methods, or on to \code{logist_plot()} from the convenience
wrappers. Arguments not consumed by the selected method are an error rather than being
silently ignored. Use \code{fit.args} and \code{marginal.args} for layer customization.}

\item{y}{a binary (0/1, or 2-level factor/character/logical) response vector}

\item{marginal}{character string, how to represent the marginal distribution of \code{x} within
each \code{y} group: \code{"hist"}, mirrored histograms (default); \code{"points"}, jittered points; or
\code{"density"}, mirrored filled density estimates}

\item{bins}{number of histogram bins, for \code{marginal = "hist"}; default: 30}

\item{adjust}{positive numeric bandwidth adjustment passed to \code{\link[stats:density]{stats::density()}} for
\code{marginal = "density"}; default: 1}

\item{xlab, ylab}{axis labels; default to the deparsed \code{x}/\code{y} expressions}

\item{fit.color}{color of the fitted logistic curve and its confidence band; default:
"steelblue". This scalar is inactive when \code{group} is supplied; use \code{group.colors}
instead.}

\item{marginal.color}{color of the marginal representation of \code{x} within each \code{y} group
(histogram/density fill, or point color for \code{marginal = "points"}); default: "orange"
This scalar is inactive when \code{group} is supplied; use \code{group.colors} instead.}

\item{fit.args}{named list of graphical arguments for the fitted curve and confidence band.
Values override the defaults established by \code{fit.color}. The fit remains a binomial GLM,
so \code{data}, \code{mapping}, \code{stat}, \code{position}, \code{inherit.aes}, \code{method}, \code{formula}, and
\code{method.args} cannot be replaced. In grouped mode, \code{colour} and \code{fill} must instead be
controlled through \code{group.colors}.}

\item{marginal.args}{named list of graphical arguments for the active marginal layer.
Values override the defaults established by \code{marginal.color}. Valid arguments depend on
\code{marginal}: point aesthetics and \code{position} for \code{"points"}, rectangle aesthetics for
\code{"hist"}, or ribbon aesthetics for \code{"density"}. Histogram computation remains controlled
by \code{bins}; density bandwidth remains controlled by \code{adjust}; and marginal geometry height
remains controlled by \code{marginal.height}. In grouped mode, \code{colour} and \code{fill} must instead
be controlled through \code{group.colors}.}

\item{group}{optional grouping input. For the default method, a vector the same length as
\code{x} and \code{y}; for data-frame and formula methods, a single column name or position.
Grouping is supported for \code{marginal = "points"} and \code{"density"}, but not \code{"hist"}.}

\item{group.colors}{optional character vector of colours for grouped plots. An unnamed
vector is applied in group-level order; a named vector must contain every observed group
label. The same palette is used for fits, marginals, and the legend. The default \code{NULL}
uses ggplot2's discrete scales.}

\item{marginal.height}{optional finite positive number controlling marginal height. For
histograms and ungrouped densities, this is the maximum proportion of the fixed 0--1
probability panel occupied on each side; defaults are 0.25 and 0.15, respectively, and
values cannot exceed 0.5. For grouped densities, it is the full height of each outward
lane in the original probability-coordinate units; the default is 0.05 and values cannot
exceed 1. \code{NULL} selects the applicable default. For \code{marginal = "points"}, a non-\code{NULL}
value is ignored with a warning; control vertical jitter through \code{marginal.args} instead.}

\item{xvar, yvar}{which columns of \code{x} to use as predictor/response -- column name or
position; default to the first two columns (matches the original 2-column-data-frame
calling convention)}

\item{formula}{a model formula, \code{y ~ x} -- exactly one response and one predictor;
\code{formula} method only. The first argument may be passed positionally or as
\code{formula = y ~ x} (matching base R's \code{boxplot()}/\code{lm()} convention) -- unlike the other
methods, it is not named \code{x}}

\item{data}{a data frame -- \code{formula} method only}
}
\value{
A native \code{ggplot} object that can be extended with ordinary ggplot2 additions.
}
\description{
Plots predicted probabilities from a \code{glm(y ~ x, family = binomial)} fit for a single
quantitative predictor \code{x} and binary response \code{y}, and also with the smoothed
logistic fit and its confidence band.
What this plot method adds is a representation of
the marginal distribution of \code{x} within each \code{y} group -- mirrored histograms or filled
density estimates above and below the curve, or jittered points -- as suggested by Smart et
al. (2004). These help you
see where the data supporting the fit exist; e.g., where the data are "thin", so the confidence band is wide.
}
\details{
\code{logist_plot()} is generic, with methods for a pair of vectors, a data frame, or a
model formula. \code{logist_hist()}, \code{logist_point()}, and \code{logist_density()} are convenience
wrappers with \verb{marginal=} fixed to \code{"hist"}/\code{"points"}/\code{"density"}, but otherwise accept
the same \code{x}/\code{...} as \code{logist_plot()} -- i.e., they also work with a data frame or a formula.
An optional \code{group} produces separate fits and colour identities in point and density
modes. Grouped histograms are deliberately unsupported because stacked or overlapping
mirrored bars obscure both the distributions and the fitted curves.
Grouped density lanes begin at 0 and 1 and stack outward in fixed, narrow bands. Each
group's two response-specific densities are normalized together within that band, so the
shapes show conditional distributions but do not encode group sample sizes.

\code{bins}, \code{adjust}, and \code{marginal.height} control computation of the marginal geometry;
they are not graphical layer arguments and therefore belong at the top level rather than
inside \code{marginal.args}.
When a small histogram height would crowd the secondary count axis, its integer ticks are
thinned symmetrically while retaining the correct count-to-height mapping.

All marginal modes return a native ggplot object. Standard additions such as
\code{\link[ggplot2:labs]{ggplot2::labs()}} and \code{\link[ggplot2:theme]{ggplot2::theme()}} can therefore be applied after construction.
Adding another \verb{scale_y_*()} replaces the internally configured probability scale; in
histogram mode this can remove or invalidate the secondary count-axis mapping.
}
\examples{
data(Donner, package = "vcdExtra")

# three interfaces to the same underlying plot
logist_plot(Donner$age, Donner$survived, marginal = "points")
logist_plot(Donner[, c("age", "survived")], marginal = "hist")
logist_plot(survived ~ age, data = Donner, marginal = "density")

# post-hoc labels and themes work in histogram mode
logist_plot(survived ~ age, data = Donner, marginal = "hist") +
  ggplot2::labs(title = "Survival of the Donner Party") +
  ggplot2::theme(plot.title = ggplot2::element_text(face = "bold"))

# layer-specific customization; scoped lists override graphical defaults
logist_plot(
  survived ~ age, data = Donner, marginal = "hist",
  fit.args = list(linewidth = 2, fill = "lightblue"),
  marginal.args = list(colour = "black", linewidth = 0.2, alpha = 0.8)
)

# convenience wrappers -- marginal= fixed, still get all calling conventions
logist_point(survived ~ age, data = Donner)
logist_hist(survived ~ age, data = Donner)
logist_density(survived ~ age, data = Donner, adjust = 1.25)

# grouped fits and marginals; grouped density lanes extend outward from 0 and 1
logist_point(survived ~ age, data = Donner, group = "sex")
logist_density(
  survived ~ age, data = Donner, group = "sex",
  group.colors = c(Female = "#D55E00", Male = "#0072B2"),
  marginal.args = list(alpha = 0.35, linewidth = 0.6)
)

}
\references{
Smart, J. M. R., Sutherland, W. J., Watkinson, A. R., and Gill, J. A. (2004). A New Means of
Presenting the Results of Logistic Regression, \emph{Bulletin of the Ecological Society of
America}, 85(3), 100--102. \doi{10.1890/0012-9623(2004)85[100:ANMOPT]2.0.CO;2}
\url{https://esapubs.org/bulletin/backissues/085-3/bulletinjuly2004_2column.htm#tools1}
}
\seealso{
\code{\link[vcd:binreg_plot]{vcd::binreg_plot()}}, a similar plot using \code{grid} graphics directly.
}
\author{
Gavin Klorfine, Michael Friendly
}
\concept{logistic regression plots}
