% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/UserFacingCoreFunctions.R
\name{geom_point_plus}
\alias{geom_point_plus}
\title{Create and add a scatterplot layer to your \code{ggplot2} graph with new, distinctive shapes.}
\usage{
geom_point_plus(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  avail_shapes = NULL,
  n_shapes = length(avail_shapes),
  chosen_shapes = NULL,
  legend_title = NULL,
  legend_labels = NULL,
  include_shape_legend = TRUE,
  ...,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  show_shape_scale = TRUE
)
}
\arguments{
\item{mapping}{Set of aesthetic mappings created by aes(), as in \code{ggplot2::geom_point()}.}

\item{data}{The data to be displayed in this layer, as in \code{ggplot2::geom_point()}.}

\item{stat}{The statistical transformation to use on the data for this layer, as in \code{ggplot2::geom_point()}.}

\item{position}{A position adjustment to use on the data for this layer, as in \code{ggplot2::geom_point()}.}

\item{avail_shapes}{A named list of custom shapes to be drawn in place of \code{ggplot2}'s standard palette of shapes. Defaults to \code{NULL} and is replaced internally with the palette of shapes designed specifically for use in \code{geom_point_plus()}. This should probably not be changed unless users have created new shapes they would like to use instead.}

\item{n_shapes}{A length-1 integer corresponding to the number of distinct shapes the function is allowed to pull from the shapes palette specified to \code{avail_shapes}. Defaults to the length of \code{avail_shapes} and should probably not be changed.}

\item{chosen_shapes}{A character string referring by name to elements in the current shapes registry that the function should use to allocate shapes to values, e.g. \verb{c("flower", "octagon", "squircle)}. These are provided internally to a \code{scale_shape_manual()} call and are meant to circumvent the need for such a call to specify a specific subset of shapes to be used from the new shapes palette. Defaults to \code{NULL}, i.e., shapes are pulled from \code{shapes.list} in order. Numerical values will use \code{ggplot2}'s default shapes instead.}

\item{legend_title}{A length-1 character string corresponding to the name to be used for the shape legend title (if any). This is passed internally to \code{scale_shape_manual()} and is meant to help circumvent the need for the user to specify any such call directly.}

\item{legend_labels}{A character vector corresponding to the names to be used for the shape legend labels (if any). This is passed internally to \code{scale_shape_manual()} and is meant to help circumvent the need for the user to specify any such call directly.}

\item{include_shape_legend}{Logical indicating whether a shape legend will be shown (one is always shown unless this is set to FALSE, even when shape is being mapped to a constant and thus a legend may not be appropriate).}

\item{...}{Other arguments passed on to this layer()'s params argument, as in \code{ggplot2::geom_point()}.}

\item{na.rm}{Logical value controlling whether missing values should be removed from the data with a warning or silently, as in \code{ggplot2::geom_point()}.}

\item{show.legend}{Logical value controlling whether this layer should be included in the legend(s), as in \code{ggplot2::geom_point()}.}

\item{inherit.aes}{Logical controlling whether global aesthetics specified in \code{ggplot2::ggplot()} should be inherited locally by this layer or not, as in \code{ggplot2::geom_point()}.}

\item{show_shape_scale}{Logical controlling whether a call to \code{ggplot2::shape_scale_manual()} should be included as part of the function's operations. Generally, this should be set to \code{TRUE} unless shape is being mapped to a constant, in which case leaving this \code{TRUE} would trigger a legend that is redundant.}
}
\value{
A ggplot2 layer object.
}
\description{
This function behaves similarly to \code{ggplot2::geom_point()} except that it takes several new inputs: \code{shapes}, \code{n_shapes}, \code{shape_values}, \code{legend_title}, \code{key_size}, and \code{show_shape_scale}. These are explained below.
}
\details{
Collectively, these inputs allow \code{geom_point_plus()} to access and draw several new and distinctive shapes that are designed to be more readily distinguishable from one another when shape communicates difference.

To see the special shapes available via this function run \code{geom_point_plus_shapes()}.

Note: As of Version 0.5.2, shapes 21-25 in R's default shapes palette are now also available via \code{geom_point_plus_shapes()}; these are called "circle", "square", "diamond", "triangle_up", and "triangle_down", respectively, though they can also be referred to by number.
}
\examples{
ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg, fill = drat)) +
geom_point_plus(ggplot2::aes(shape = factor(gear)), size = 5)
ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg, fill = factor(cyl))) +
geom_point_plus(ggplot2::aes(shape = factor(carb)),
shape_values = c("squircle", "lotus", "sunburst", "octagon", "cross", "oval"),
size = 5, stroke = 0.4)
ggplot2::ggplot(iris, ggplot2::aes(Petal.Width, Petal.Length, fill = Species)) +
geom_point_plus(ggplot2::aes(shape = Species), size = 5, alpha = 0.7)

}
