Nothing
#' Creates an isotope scatterplot and provides a wrapper to ellipse and hull plotting
#'
#' This function takes a SIBER object as created by
#' \code{\link{createSiberObject}}, and loops over communities and their groups,
#' creating a scatterplot, and adding ellipses and hulls as desired. Ellipses can be
#' added to groups, while convex hulls can be added at both the group and
#' community level (the former for illustrative purposes only, with no
#' analytical tools in SIBER to fit Bayesian hulls to individual groups. This is
#' not mathematically possible in a Bayesian framework.).
#' @param siber a siber object as created by [createSiberObject()].
#' @param ax.pad a padding amount to apply to the x-axis either side of the
#' extremes of the data. Defaults to 1.
#' @param iso.order a vector of length 2, either `c(1,2)` or `c(2,1)`. The order
#' determines which of the columns of raw data are plotted on the x (1) or y
#' (2) axis. N.B. this will be deprecated in a future release, and plotting
#' order will be achieved at point of data-entry.
#' @param hulls a logical defaulting to `TRUE` determining whether or not hulls
#' based on the means of groups within communities should be drawn. That is, a
#' community-level convex hull.
#' @param community.hulls.args a list of plotting arguments to pass to
#' [plotCommunityHulls()]. See [plotCommunityHulls()] for
#' further details.
#' @param ellipses a logical defaulting to TRUE determining whether or not an
#' ellipse should be drawn around each group within each community.
#' @param group.ellipses.args a list of plotting arguments to pass to
#' [plotGroupEllipses()]. See [plotGroupEllipses()] for
#' further details.
#' @param group.hulls a logical defaulting to FALSE determining whether or not
#' convex hulls should be drawn around each group within each community.
#' @param group.hulls.args a list of plotting options to pass to
#' [plotGroupHulls()]. See [plotGroupHulls()] for further
#' details.
#' @param bty a string specifying the box type for the plot. See
#' [graphics::par()] for details.
#' @param xlab a string for the x-axis label.
#' @param ylab a string for the y-axis label.
#' @param las a scalar determining the rotation of the y-axis labels. Defaults
#' to horizontal with `las = 1`. See [graphics::par()] for more
#' details.
#' @param x.limits allows you to specify a two-element vector of lower and upper
#' x-axis limits. Specifying this argument over-rides the automatic plotting
#' and ax.pad option. Defaults to NULL.
#' @param y.limits allows you to specify a two-element vector of lower and upper
#' y-axis limits. Specifying this argument over-rides the automatic plotting
#' and ax.pad option. Defaults to NULL.
#' @param points.order a vector of integers specifying the order of point types
#' to use. See [graphics::points()] for how integers map onto point
#' types. Defaults to the sequence 1:15 as per [graphics::points()].
#' It must have at least as many entries as there are communities to plot,
#' else a warning will be issued, and the order will default to the sequence
#' \code{1:25}.
#' @param ... additional arguments to be passed to [graphics::plot()].
#'
#' @return An isotope scatterplot.
#' @export
plotSiberObject <- function(siber,
iso.order = c(1,2),
ax.pad = 1,
hulls = TRUE, community.hulls.args = NULL,
ellipses = TRUE, group.ellipses.args = NULL,
group.hulls = FALSE, group.hulls.args = NULL,
bty = "L",
xlab = "Isotope 1",
ylab = "Isotope 2",
las = 1,
x.limits = NULL,
y.limits = NULL,
points.order = 1:25,
...){
# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
# some argument checking
if (length(points.order) < siber$n.communities){
points.order = (1:25)
warning(strwrap('Your specified vector of point types to use does not
contain enough entries to plot each of the communites.
Your chosen vector has been ignored, and the default
sequence 1:25 has been used in its place.',
width = 1000))}
# = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
# NOTE - this isotope ordering needs to be passed onwards to the plotting
# functions called below. Im not convinced its that straightforward.
x <- iso.order[1]
y <- iso.order[2]
with(siber,{
# set up a blank plot. X and Y limits are set by padding
# the plot by a fixed amount ax.pad beyond the extremes of
# all the data. This automatic axis scaling can be over-rided
# by specifying x.limits and y.limits as input arguments.
# if the default limits are used, then pad teh data around the max
# min values, else use the user specified values.
if (is.null(x.limits)) {
x.limits <- c(siber$iso.summary["min", x] - ax.pad ,
siber$iso.summary["max", x] + ax.pad )
}
if (is.null(y.limits)) {
y.limits <- c(siber$iso.summary["min", y] - ax.pad ,
siber$iso.summary["max", y] + ax.pad )
}
plot(0, 0, type = "n",
ylab = ylab,
xlab = xlab,
bty = bty,
las = las,
xlim = x.limits,
ylim = y.limits,
...
) # end of plot
# ==========================================================================
# OLD CODE 7/MAR/19 - to be deleted
# if(any(is.null(x.limits),is.null(y.limits)))
# {plot(0, 0, type = "n",
# xlim = c(siber$iso.summary["min", x] - ax.pad ,
# siber$iso.summary["max", x] + ax.pad ),
# ylim = c(siber$iso.summary["min", y] - ax.pad ,
# siber$iso.summary["max", y] + ax.pad ),
# ylab = ylab,
# xlab = xlab,
# bty = bty,
# las = las
#
# )}
# else
# {plot(0, 0, type = "n",
# ylab = ylab,
# xlab = xlab,
# bty = bty,
# las = las,
# xlim = x.limits,
# ylim = y.limits,
# ...
# ) # end of plot
# }
# ==========================================================================
# add each of the data points
for (i in 1:siber$n.communities){
points(siber$raw.data[[i]][,x],
siber$raw.data[[i]][,y],
col = siber$raw.data[[i]]$group,
pch = points.order[i])
}
# --------------------------------------------------------------------------
# Add a convex hull between the means of each group, i.e. a convex hull
# for the community. Only applicable if there are more than 2
# members for a community
# I might move this out block to its own function in the future
# --------------------------------------------------------------------------
if (hulls) {
plotCommunityHulls(siber, community.hulls.args, iso.order)
} # end of if statement for community convex hull drawing
# --------------------------------------------------------------------------
# Add a ML ellipse to each group
# --------------------------------------------------------------------------
if (ellipses) {
plotGroupEllipses(siber, group.ellipses.args, iso.order)
} # end of if statement for ellipse drawing
# --------------------------------------------------------------------------
# Add convex hulls to each group here
# --------------------------------------------------------------------------
if (group.hulls){
# code similar to group ellipses to go here
plotGroupHulls(siber, group.hulls.args, iso.order)
} # end of if statement for group hull drawing
}) # end of with() function
} # end function
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.