#' splot colors

#'

#' Get a prespecified set of 9 colors, or a set of graded or random, potentially grouped colors.

#' @param x dictates the number and shade of colors. If a single value, returns that many samples of the

#'   first \code{seed} entry. If a vector, returns a color for each entry. If numeric, a single seed color

#'   is sampled in order of the vector. If a character or factor, a separate seed color is assigned to

#'   each level, then sampled within levels. Values or vectors in a list are each assigned a seed color.

#' @param by a vector to group \code{x} by; each level is assigned a seed color.

#' @param seed a vector of color names or codes to adjust from, lining up with levels of \code{x} or

#'   \code{by}, or the name of a palette, partially matching \code{'bright'}, \code{'dark'},

#'   \code{'pastel'}, or \code{'grey'}.

#' @param brightness adjusts the RGB values of the seed color, usually between -1 and 1.

#' @param luminance adjusts the white levels of the seed color, usually between -1 and 1.

#' @param opacity sets the opacity of the seed color, between 0 and 1.

#' @param extend if \code{method='scale'}, extends the range of the gradient beyond the sampled range,

#'   making for more similar colors (defaults is .5, with 0 sampling the full range). If

#'   \code{method='related'}, increases the amount any of the RGB values can be adjusted, making for

#'   potentially more different colors (default is 2).

#' @param lighten logical; if \code{TRUE}, scaled colors are lightened instead of darkened. Only

#'   applicable if \code{method='scale'}.

#' @param shuffle logical; if \code{TRUE}, scaled colors are shuffled. Only applicable if

#'   \code{method='scale'}.

#' @param flat logical; if \code{FALSE} and \code{x} is a character, factor, or list, or \code{by} is not

#'   missing, a list is returned.

#' @param method a character setting the sampling method: If \code{'related'} (\code{'^rel|^ran|^o'}),

#'   RGB values are freely adjusted, resulting in similar colors. If \code{'none'} (\code{'^no|^f|^bin'}),

#'   Seed colors are simply repeated in each level (sampling is off). Otherwise, RGB values are adjusted

#'   together, resulting in a gradient.

#' @param grade logical; if \code{TRUE}, seeds are adjusted on the scale of numeric \code{x}s.

#'   Otherwise, seeds are adjusted in even steps along numeric \code{x}s.

#' @param decreasing logical; if \code{FALSE}, assigns colors to numeric \code{x}s in increasing order.

#' @param nas value to replace missing values with.

#' @return A character vector of color codes, or a list of such vectors if \code{flat} if \code{FALSE}.

#' @details

#' If \code{x} and \code{by} are not specified (or are characters with a length of 1, in which case they

#' are treated as \code{seed}), only the seed palette is returned.

#'

#' To expand on a palette, seed colors are assigned to groups, and variants of each seed are assigned to

#' values or levels within groups, or randomly or as a gradient if there are no values or level to assign to.

#'

#' Seed colors are assigned to groups. If \code{x} is a character or factor and no \code{by} has been

#' specified, groups are the unique levels of \code{x}. If \code{by} is specified and is a character or

#' factor, or has fewer than 10 unique levels, groups are levels of \code{by}. If \code{x} is a list,

#' groups are list entries.

#'

#' The number of variants for each seed color is determined either by a value (if the value has a length

#' of 1; e.g., \code{x=10}), the vector's length (if \code{x} is numeric), or the count of the given level

#' (if \code{x} is a factor or character vector).

#'

#' @examples

#' # including no arguments or just a palette name will only return

#' # the palette as a character vector

#' pastel_palette <- splot.color()

#' dark_palette <- splot.color("dark")

#'

#' # entering a number for x will generate that many variants of the first seed color

#' red_scale <- splot.color(10, "red")

#'

#' # entering a list of values as x will return that many variants of the associated seed

#' red_and_green_scales <- splot.color(list(10, 10), seed = c("red", "green"))

#'

#' # this shows gradients of each color in the default palette

#' # a list entered as colorby is treated as arguments to splot.color

#' # periods before the position name refer to the internally assembled data

#' splot(

#'   rep(splot.color(), each = 100) ~ rep.int(seq.int(.01, 1, .01), 9),

#'   colorby = list(.x, .y),

#'   lines = FALSE, mar = c(2, 4, 0, 0), cex = c(points = 3), leg = FALSE, pch = 15,

#'   title = "'pastel' palette", labx = "value of x", laby = "seed color"

#' )

#'

#' # colors graded by value, entered in a list

#' plot(

#'   1:30, numeric(30),

#'   pch = 15, cex = 10,

#'   col = splot.color(list(1:8, c(7:1, 1:7), 8:1))

#' )

#'

#' # comparing sampling methods:

#' #   on top are 1000 similar colors, with different RGB ratios

#' #   on bottom are 268 colors with the same RGB ratio at different levels

#' splot(

#'   c(rnorm(1000), rnorm(1000, 10)) ~ rnorm(2000),

#'   lines = FALSE,

#'   colors = c(splot.color(1000), splot.color(1000, method = "related"))

#' )

#'

#' @export

splot.color <- function(

    x = NULL, by = NULL, seed = "pastel", brightness = 0, luminance = 0, opacity = 1, extend = .7,

    lighten = FALSE, shuffle = FALSE, flat = TRUE, method = "scale", grade = FALSE, decreasing = FALSE, nas = "#000000") {

  )

  }

  }

      } else {

      }

    }

  }

    } else {

      } else {

      }

    }

  }

  }

      } else {

      }

    } else {

    }

    }

  }

      }

      }

        }

        }

      }

    }

      }, "")

    }

  } else {

      }, "")

    }

  }

  }

  } else {

        }

      } else {

      }

    }

  }

}

#' Split Plot

#'

#' A plotting function aimed at automating some common visualization tasks in order to ease data exploration.

#' @param y a formula (see note), or the primary variable(s) to be shown on the y axis (unless \code{x} is not specified).

#'   When not a formula, this can be one or more variables as objects, or names in \code{data}.

#' @param data a \code{data.frame} to pull variables from. If variables aren't found in \code{data}, they will be looked

#'   for in the environment.

#' @param su a subset to all variables, applied after they are all retrieved from \code{data} or the environment.

#' @param type determines the type of plot to make, between \code{"bar"}, \code{"line"}, \code{"density"}, or

#'   \code{"scatter"}. If \code{"density"}, \code{x} is ignored. Anything including the first letter of each is accepted

#'   (e.g., \code{type='l'}).

#' @param split how to split any continuous variables (those with more than \code{lim} levels as factors). Default is

#'   \code{"median"}, with \code{"mean"}, \code{"standard deviation"}, \code{"quantile"}, or numbers as options. If

#'   numbers, the variable is either cut at each value in a vector, or broken into roughly equal chunks. Entering an

#'   integer (e.g., \code{split = 3L}) that is greater than 1 will force splitting into segments. Otherwise variables will

#'   be split by value if you enter a single value for split and there are at least two data less than or equal to and

#'   greater than the split, or if you enter more than 1 value for split. If a numeric split is not compatible with

#'   splitting by value or segment, splitting will default to the median.

#' @param levels a list with entries corresponding to variable names, used to rename and/or reorder factor levels. To

#'   reorder a factor, enter a vector of either numbers or existing level names in the new order (e.g.,

#'   \code{levels =} \code{list(var =} \code{c(3,2,1))}). To rename levels of a factor, enter a character vector the same

#'   length as the number of levels. To rename and reorder, enter a list, with names as the first entry, and order as the

#'   second entry (e.g., \code{levels =} \code{list(var =} \code{list(c('a','b','c'),} \code{c(3,2,1)))}). This happens

#'   after variables are split, so names and orders should correspond to the new split levels of split variables. For

#'   example, if a continuous variable is median split, it now has two levels ('Under Median' and 'Over Median'), which are

#'   the levels reordering or renaming would apply to. Multiple variables entered as \code{y} can be renamed and sorted

#'   with an entry titled \code{'mv'}.

#' @param sort specified the order of character or factor \code{x} levels. By default, character or factor \code{x} levels

#'   are sorted alphabetically. \code{FALSE} will prevent this (preserving entered order). \code{TRUE} or \code{'d'} will

#'   sort by levels of \code{y} in decreasing order, and anything else will sort in increasing order.

#' @param error string; sets the type of error bars to show in bar or line plots, or turns them off. If \code{FALSE}, no

#'   error bars will be shown. Otherwise, the default is \code{"standard error"} (\code{'^s'}), with \code{"confidence

#'   intervals"} (anything else) as an option.

#' @param error.color color of the error bars. Default is \code{'#585858'}.

#' @param error.lwd line weight of error bars. Default is 2.

#' @param lim numeric; checked against the number of factor levels of each variable. Used to decide which variables should

#'   be split, which colors to use, and when to turn off the legend. Default is \code{9}. If set over \code{20}, \code{lim}

#'   is treated as infinite (set to \code{Inf}).

#' @param lines logical or a string specifying the type of lines to be drawn in scatter plots. By default (and whenever

#'   \code{cov} is not missing, or if \code{lines} matches \code{'^li|^lm|^st'}), a prediction line is fitted with

#'   \code{\link[stats]{lm}}. For (potentially) bendy lines, \code{'loess'} (matching \code{'^loe|^po|^cu'}) will use

#'   \code{\link[stats]{loess}}, and \code{'spline'} (\code{'^sm|^sp|^in'}) will use \code{\link[stats]{smooth.spline}}.

#'   If \code{y} is not numeric and has only 2 levels, \code{'probability'} (\code{'^pr|^log'}) will draw probabilities

#'   estimated by a logistic regression (\code{glm(y ~} \code{x, binomial)}). \code{'connected'} (\code{'^e|^co|^d'}) will

#'   draw lines connecting all points, and \code{FALSE} will not draw any lines.

#' @param colors sets a color theme or manually specifies colors. Default theme is \code{"pastel"}, with \code{"dark"} and

#'   \code{"bright"} as options; these are passed to \code{\link{splot.color}}. If set to \code{"grey"}, or if \code{by}

#'   has more than 9 levels, a grey scale is calculated using \code{\link[grDevices]{gray}}. See the \code{col} parameter

#'   in \code{\link[graphics]{par}} for acceptable manual inputs. To set text and axis colors, \code{col} sets outside

#'   texts (title, sud, labx, laby, and note), \code{col.sub} or \code{col.main} sets the frame titles, and \code{col.axis}

#'   sets the axis text and line colors. To set the color of error bars, use \code{error.color}. For histograms, a vector of

#'   two colors would apply to the density line and bars separately (e.g., for \code{color =} \code{c('red','green')}, the

#'   density line would be red and the histogram bars would be green). See the \code{color.lock} and \code{color.offset}

#'   arguments for more color controls.

#' @param colorby a variable or list of arguments used to set colors and the legend, alternatively to \code{by}. If

#'   \code{by} is not missing, \code{colorby} will be reduced to only the unique combinations of \code{by} and \code{colorby}.

#'   For example, if \code{by} is a participant ID with multiple observations per participant, and \code{by} is a condition

#'   ID which is the same for all observations from a given participant, \code{colorby} would assign a single color to each

#'   participant based on their condition. A list will be treated as a call to \code{\link{splot.color}}, so arguments can be

#'   entered positionally or by name. Data entered directly into splot can be accessed by position name preceded by a

#'   period. For example, \code{splot(rnorm(100),} \code{colorby=.y)} would draw a histogram, with bars colored by the value

#'   of \code{y} (\code{rnorm(100)} in this case).

#' @param ... passes additional arguments to \code{\link[graphics]{par}} or \code{\link[graphics]{legend}}. Arguments before

#'   this can be named partially; those after must by fully named.

#' @param colorby.leg logical; if \code{FALSE}, a legend for \code{colorby} is never drawn. Otherwise, a legend for

#'   \code{colorby} will be drawn if there is no specified \code{by}, or for non-scatter plots (overwriting the usual legend).

#' @param color.lock logical; if \code{FALSE}, colors will not be adjusted to offset lines from points or histogram bars.

#' @param color.offset how much points or histogram bars should be offset from the initial color used for lines. Default is

#'   1.1; values greater than 1 lighten, and less than 1 darken.

#' @param color.summary specifies the function used to collapse multiple colors for a single display. Either a string

#'   matching one of \code{'mean'} (which uses \code{\link{splot.colormean}} to average RGB values), \code{'median'} (

#'   which treats codes as ordered, and selects that at the rounded median), or \code{'mode'} (which selects the most

#'   common code), or a function which takes color codes in its first argument, and outputs a single color code as a

#'   character.

#' @param opacity a number between 0 and 1; sets the opacity of points, lines, and bars. Semi-opaque lines will sometimes

#'   not be displayed in the plot window, but will show up when the plot is written to a file.

#' @param dark logical; if \code{TRUE}, sets text and axis colors to \code{"white"}. Defaults to the \code{splot.dark}

#'   option.

#' @param x secondary variable, to be shown in on the x axis. If not specified, \code{type} will be set to \code{'density'}.

#'   If \code{x} is a factor or vector of characters, or has fewer than \code{lim} levels when treated as a factor,

#'   \code{type} will be set to \code{'line'} unless specified.

#' @param by the 'splitting' variable within each plot, by which the plotted values of \code{x} and \code{y} will be

#'   grouped.

#' @param between a single object or name, or two in a vector (e.g., \code{c(b1, b2)}), the levels of which will determine

#'   the number of plot windows to be shown at once (the cells in a matrix of plots; levels of the first variable as rows,

#'   and levels of the second as columns).

#' @param cov additional variables used for adjustment. Bar and line plots include all \code{cov} variables in their

#'   regression models (via \code{\link[stats]{lm}}, e.g., \code{lm(y ~ 0 + x + cov1 + cov2)}) as covariates. Scatter plots

#'   with lines include all \code{cov} variables in the regression model to adjust the prediction line (e.g.,

#'   \code{lm(y ~ x + x^2)}).

#'   \code{\link[graphics]{par}} options \code{col}, \code{mfrow}, \code{oma}, \code{mar}, \code{mgp}, \code{font.main},

#'   \code{cex.main}, \code{font.lab}, \code{tcl}, \code{pch}, \code{lwd}, and \code{xpd} are all set within the function,

#'   but will be overwritten if they are included in the call. For example, \code{col} sets font colors in this case

#'   (as opposed to \code{colors} which sets line and point colors). The default is \code{'#303030'} for a nice dark grey,

#'   but maybe you want to lighten that up: \code{col='#606060'}. After arguments have been applied to

#'   \code{\link[graphics]{par}}, if any have not been used and match a \code{\link[graphics]{legend}} argument, these will

#'   be applied to \code{\link[graphics]{legend}}.

#' @param line.type a character setting the style of line (e.g., with points at joints) to be drawn in line plots. Default

#'   is \code{'b'} if \code{error} is \code{FALSE}, and \code{'l'} otherwise. See the \code{line} argument of

#'   \code{\link[graphics]{plot.default}} for options. \code{line.type='c'} can look nice when there aren't a lot of

#'   overlapping error bars.

#' @param mv.scale determines whether to center and scale multiple \code{y} variables. Does not center or scale by default.

#'   Anything other than \code{'none'} will mean center each numeric \code{y} variable. Anything matching \code{'^t|z|sc'}

#'   will also scale.

#' @param mv.as.x logical; if \code{TRUE}, variable names are displayed on the x axis, and \code{x} is treated as \code{by}.

#' @param save logical; if \code{TRUE}, an image of the plot is saved to the current working directory.

#' @param format the type of file to save plots as. Default is \code{cairo_pdf}; see

#'   \code{\link[grDevices]{Devices}} for options.

#' @param dims a vector of 2 values (\code{c(width, height)}) specifying the dimensions of a plot to save in inches or

#'   pixels depending on \code{format}. Defaults to the dimensions of the plot window.

#' @param file.name a string with the name of the file to be save (excluding the extension, as this is added depending on

#'   \code{format}).

#' @param myl sets the range of the y axis (\code{ylim} of \code{\link{plot}} or \code{\link[graphics]{barplot}}).

#'   If not specified, this will be calculated from the data.

#' @param mxl sets the range of the x axis (\code{xlim} of \code{\link{plot}}). If not specified, this will be

#'   calculated from the data.

#' @param autori logical; if \code{FALSE}, the origin of plotted bars will be set to 0. Otherwise, bars are adjusted such

#'   that they extend to the bottom of the y axis.

#' @param xlas,ylas numeric; sets the orientation of the x- and y-axis labels. See \code{\link[graphics]{par}}.

#' @param xaxis,yaxis logical; if \code{FALSE}, the axis will not be drawn.

#' @param breaks determines the width of histogram bars. See \code{\link[graphics]{hist}}.

#' @param density.fill logical; \code{FALSE} will turn off polygon fills when they are displayed, \code{TRUE} will replace

#'   histograms with polygons.

#' @param density.opacity opacity of the density polygons, between 0 and 1.

#' @param density.args list of arguments to be passed to \code{\link[stats]{density}}.

#' @param leg sets the legend inside or outside the plot frames (when a character matching \code{'^i'}, or a character

#'   matching \code{'^o'} or a number respectively), or turns it off (when \code{FALSE}). When inside, a legend is drawn in

#'   each plot frame. When outside, a single legend is drawn either to the right of all plot frames, or within an empty

#'   plot frame. By default, this will be determined automatically, tending to set legends outside when there are multiple

#'   levels of \code{between}. A number will try and set the legend in an empty frame within the grid of plot frames. If

#'   there are no empty frames, the legend will just go to the side as if \code{leg='outside'}.

#' @param lpos sets the position of the legend within its frame (whether inside or outside of the plot frames) based on

#'   keywords (see \code{\link[graphics]{legend}}. By default, when the legend is outside, \code{lpos} is either

#'   \code{'right'} when the legend is in a right-hand column, or \code{'center'} when in an empty plot frame. When the

#'   legend is inside and \code{lpos} is not specified, the legend will be placed automatically based on the data. Set to

#'   \code{'place'} to manually place the legend; clicking the plot frame will set the top left corner of the legend.

#' @param lvn level variable name. Logical: if \code{FALSE}, the names of by and between variables will not be shown

#'   before their level (e.g., for a sex variable with a "female" level, "sex: female" would become "female" above each

#'   plot window).

#' @param leg.title sets the title of the legend (which is the by variable name by default), or turns it off with

#'   \code{FALSE}.

#' @param leg.args a list passing arguments to the \code{\link[graphics]{legend}} call.

#' @param title logical or a character: if \code{FALSE}, the main title is turned off. If a character, this will be shown

#'   as the main title.

#' @param labx,laby logical or a character: if \code{FALSE}, the label on the x axis is turned off. If a character, this

#'   will be shown as the axis label.

#' @param lty logical or a vector: if \code{FALSE}, lines are always solid. If a vector, changes line type based on each

#'   value. Otherwise loops through available line types, see \code{\link[graphics]{par}}.

#' @param lwd numeric; sets the weight of lines in line, density, and scatter plots. Default is 2. See

#'   \code{\link[graphics]{par}}.

#' @param sub affects the small title above each plot showing \code{between} levels; text replaces it, and \code{FALSE}

#'   turns it off.

#' @param note logical; if \code{FALSE}, the note at the bottom about splits and/or lines or error bars is turned off.

#' @param font named numeric vector: \code{c(title,sud,leg,leg.title,note)}. Sets the font of the title, su display, legend

#'   levels and title, and note. In addition, \code{font.lab} sets the x and y label font, \code{font.sub} sets the font of

#'   the little title in each panel, \code{font.axis} sets the axis label font, and \code{font.main} sets the between level/n

#'   heading font; these are passed to \code{\link[graphics]{par}}. See the input section.

#' @param cex named numeric vector: \code{c(title,sud,leg,note,points)}. Sets the font size of the title, su display, legend,

#'   note, and points. In addition, \code{cex.lab} sets the x and y label size, \code{cex.sub} sets the size of the little

#'   title in each panel, \code{cex.axis} sets the axis label size, and \code{cex.main} sets the between level/n heading size;

#'   these are passed to \code{\link[graphics]{par}}. See the input section.

#' @param sud affects the heading for subset and covariates/line adjustments (su display); text replaces it, and

#'   \code{FALSE} turns it off.

#' @param ndisp logical; if \code{FALSE}, n per level is no longer displayed in the subheadings.

#' @param labels logical; if \code{FALSE}, sets all settable text surrounding the plot to \code{FALSE} (just so you don't

#'   have to set all of them if you want a clean frame).

#' @param labels.filter a regular expression string to be replaced in label texts with a blank space. Default is

#'   \code{'_'}, so underscores appearing in the text of labels are replace with blank spaces. Set to

#'   \code{FALSE} to prevent all filtering.

#' @param labels.trim numeric or logical; the maximum length of label texts (in number of characters). Default is 20, with

#'   any longer labels being trimmed. Set to \code{FALSE} to prevent any trimming.

#' @param points logical; if \code{FALSE}, the points in a scatter plot are no longer drawn.

#' @param points.first logical; if \code{FALSE}, points are plotted after lines are drawn in a scatter plot, placing lines

#'   behind points. This does not apply to points or lines added in \code{add}, as that is always evaluated after the main

#'   points and lines are drawn.

#' @param byx logical; if \code{TRUE} (default) and \code{by} is specified, regressions for bar or line plots compare

#'   levels of \code{by} for each level of \code{x}. This makes for more intuitive error bars when comparing levels of

#'   \code{by} within a level of \code{x}; otherwise, the model is comparing the difference between the first level of

#'   \code{x} and each of its other levels.

#' @param drop named logical vector: \code{c(x,by,bet)}. Specifies how levels with no data should be treated. All are

#'   \code{TRUE} by default, meaning only levels with data will be presented, and the layout of \code{between} levels

#'   will be minimized. \code{x} only applies to bar or line plots. \code{by} relates to levels presented in the legend.

#'   If \code{bet} is \code{FALSE}, the layout of \code{between} variables will be strict, with levels of \code{between[1]}

#'   as rows, and levels of \code{between[2]} as columns -- if there are no data at an intersection of levels, the

#'   corresponding panel will be blank. See the input section.

#' @param prat panel ratio, referring to the ratio between plot frames and the legend frame when the legend is out. A

#'   single number will make all panels of equal width. A vector of two numbers will adjust the ratio between plot panels

#'   and the legend panel. For example, \code{prat=c(3,1)} makes all plot panels a relative width of 3, and the legend frame

#'   a relative width of 1.

#' @param check.height logical; if \code{FALSE}, the height of the plot frame will not be checked before plotting is

#'   attempted. The check tries to avoid later errors, but may prevent plotting when a plot is possible.

#' @param model logical; if \code{TRUE}, the summary of an interaction model will be printed. This model won't always align

#'   with what is plotted since variables may be treated differently, particularly in the case of interactions.

#' @param options a list with named arguments, useful for setting temporary defaults if you plan on using some of the same

#'   options for multiple plots (e.g., \code{opt = list(}\code{type = 'bar',} \code{colors = 'grey',}

#'   \code{bg = '#999999');} \code{splot(x ~ y,} \code{options = opt)}).

#'   use \code{\link{quote}} to include options that are to be evaluated within the function (e.g.,

#'   \code{opt =} \code{list(su =} \code{quote(y > 0))}).

#' @param add evaluated within the function, so you can refer to the objects that are returned, to variable names (those

#'   from an entered data frame or entered as arguments), or entered data by their position, preceded by '.' (e.g.,

#'   \code{mod =} \code{lm(.y~.x)}). Useful for adding things like lines to a plot while the parameters are still

#'   those set by the function (e.g., \code{add =} \code{abline(v =} \code{mean(x),} \code{xpd = FALSE)} for a vertical

#'   line at the mean of x).

#'

#' @return A list containing data and settings is invisibly returned, which might be useful to check for errors.

#' Each of these objects can also be pulled from within \code{add}:

#' \tabular{ll}{

#'   \code{dat} \tab a \code{data.frame} of processed, unsegmented data.\cr

#'   \code{cdat} \tab a \code{list} of \code{list}s of \code{data.frame}s of processed, segmented data.\cr

#'   \code{txt} \tab a \code{list} of variable names. used mostly to pull variables from \code{data} or the environment.\cr

#'   \code{ptxt} \tab a \code{list} of processed variable and level names. Used mostly for labeling.\cr

#'   \code{seg} \tab a \code{list} containing segmentation information (such as levels) for each variable.\cr

#'   \code{ck} \tab a \code{list} of settings.\cr

#'   \code{lega} \tab a \code{list} of arguments that were or would have been passed to \code{\link[graphics]{legend}}.\cr

#'   \code{fmod} \tab an \code{lm} object if \code{model} is \code{TRUE}, and the model succeeded.

#' }

#'

#' @section Input:

#' \strong{formulas}

#'

#' When \code{y} is a formula (has a \code{~}), other variables will be pulled from it:

#'

#' \code{y ~ x * by * between[1] * between[2] + cov[1] + cov[2] + cov[n]}

#'

#' If \code{y} has multiple variables, \code{by} is used to identify the variable (it becomes a factor with variable names

#' as levels), so anything entered as \code{by} is treated as \code{between[1]}, \code{between[1]} is moved to

#' \code{between[2]}, and \code{between[2]} is discarded with a message.

#'

#' \strong{named vectors}

#'

#' Named vector arguments like \code{font}, \code{cex}, and \code{drop} can be set with a single value, positionally, or

#' with names. If a single value is entered (e.g., \code{drop = FALSE}), this will be applied to each level (i.e.,

#' \code{c(x = FALSE, by = FALSE, bet = FALSE)}). If more than one value is entered, these will be treated positionally

#' (e.g., \code{cex =} \code{c(2, 1.2)} would be read as \code{c(title = 2, sud = 1.2, leg = .9, note = .7, points = 1)}).

#' If values are named, only named values will be set, with other defaults retained (e.g., \code{cex =} \code{c(note = 1.2)}

#' would be read as \code{c(title = 1.5, sud = .9, leg = .9, note = 1.2, points = 1)}).

#'

#' @note

#' \strong{x-axis levels text}

#'

#' If the text of x-axis levels (those corresponding to the levels of \code{x}) are too long, they are hidden before

#' overlapping. To try and avoid this, by default longer texts are trimmed (dictated by \code{labels.trim}), and at some

#' point the orientation of level text is changed (settable with \code{xlas}), but you may still see level text missing.

#' To make these visible, you can reduce \code{labels.trim} from the default of 20 (or rename the levels of that variable),

#' make the level text vertical (\code{xlas = 3}), or expand your plot window if possible.

#'

#' \strong{missing levels, lines, and/or error bars}

#'

#' By default (if \code{drop = TRUE}), levels of \code{x} with no data are dropped, so you may not see every level of your

#' variable, at all or at a level of \code{by} or \code{between}. Sometimes error bars cannot be estimated (if, say, there

#' is only one observation at the given level), but lines are still drawn in these cases, so you may sometimes see levels

#' without error bars even when error bars are turned on. Sometimes (particularly when \code{drop['x']} is \code{FALSE}),

#' you might see floating error bars with no lines drawn to them, or what appear to be completely empty levels. This

#' happens when there is a missing level of \code{x} between two non-missing levels, potentially making an orphaned level

#' (if a non-missing level is surrounded by missing levels). If there are no error bars for this orphaned level, by default

#' nothing will be drawn to indicate it. If you set \code{line.type} to \code{'b'} (or any other type with points), a point

#' will be drawn at such error-bar-less, orphaned levels.

#'

#' \strong{unexpected failures}

#'

#' splot tries to clean up after itself in the case of an error, but you may still run into errors that break things before

#' this can happen. If after a failed plot you find that you're unable to make any new plots, or new plots are drawn over

#' old ones, you might try entering \code{dev.off()} into the console. If new plots look off (splot's

#' \code{\link[graphics]{par}} settings didn't get reset), you may have to close the plot window to reset

#' \code{\link[graphics]{par}} (if you're using RStudio, Plots > "Remove Plot..." or "Clear All..."), or restart R.

#'

#' @examples

#' # simulating data

#' n <- 2000

#' dat <- data.frame(sapply(c("by", "bet1", "bet2"), function(c) sample(0:1, n, TRUE)))

#' dat$x <- with(

#'   dat,

#'   rnorm(n) + by * -.4 + by * bet1 * -.3 + by * bet2 *

#'     .3 + bet1 * bet2 * .9 - .8 + rnorm(n, 0, by)

#' )

#' dat$y <- with(

#'   dat,

#'   x * .2 + by * .3 + bet2 * -.6 + bet1 * bet2 * .8 + x *

#'     by * bet1 * -.5 + x * by * bet1 * bet2 * -.5

#'     + rnorm(n, 5) + rnorm(n, -1, .1 * x^2)

#' )

#'

#' # looking at the distribution of y between bets split by by

#' splot(y, by = by, between = c(bet1, bet2), data = dat)

#'

#' # looking at quantile splits of y in y by x

#' splot(y ~ x * y, dat, split = "quantile")

#'

#' # looking at y by x between bets

#' splot(y ~ x, dat, between = c(bet1, bet2))

#'

#' # sequentially adding levels of split

#' splot(y ~ x * by, dat)

#' splot(y ~ x * by * bet1, dat)

#' splot(y ~ x * by * bet1 * bet2, dat)

#'

#' # same as the last but entered by name

#' splot(y, x = x, by = by, between = c(bet1, bet2), data = dat)

#'

#' # zooming in on one of the windows

#' splot(y ~ x * by, dat, bet1 == 1 & bet2 == 0)

#'

#' # comparing an adjusted lm prediction line with a loess line

#' # this could also be entered as y ~ poly(x,3)

#' splot(y ~ x + x^2 + x^3, dat, bet1 == 1 & bet2 == 0 & by == 1, add = {

#'   lines(x[order(x)], loess(y ~ x)$fitted[order(x)], lty = 2)

#'   legend("topright", c("lm", "loess"), lty = c(1, 2), lwd = c(2, 1), bty = "n")

#' })

#'

#' # looking at different versions of x added to y

#' splot(cbind(

#'   Raw = y + x,

#'   Sine = y + sin(x),

#'   Cosine = y + cos(x),

#'   Tangent = y + tan(x)

#' ) ~ x, dat, myl = c(-10, 15), lines = "loess", laby = "y + versions of x")

#'

#' @export

#' @importFrom grDevices grey dev.copy dev.size dev.off cairo_pdf adjustcolor colors col2rgb

#' @importFrom graphics axis axTicks hist legend lines text mtext plot barplot par points arrows strwidth layout plot.new

#' locator strheight polygon abline

#' @importFrom stats density median quantile sd lm glm confint update loess smooth.spline formula as.formula predict

#' var binomial

splot <- function(

    y, data = NULL, su = NULL, type = "", split = "median", levels = list(), sort = NULL,

    error = "standard", error.color = "#585858", error.lwd = 2, lim = 9, lines = TRUE, ...,

    colors = "pastel", colorby = NULL, colorby.leg = TRUE, color.lock = FALSE, color.offset = 1.1,

    color.summary = "mean", opacity = 1, dark = getOption("splot.dark", FALSE), x = NULL,

    by = NULL, between = NULL, cov = NULL, line.type = "l", mv.scale = "none", mv.as.x = FALSE,

    save = FALSE, format = cairo_pdf, dims = dev.size(), file.name = "splot", myl = NULL,

    mxl = NULL, autori = TRUE, xlas = 0, ylas = 1, xaxis = TRUE, yaxis = TRUE, breaks = "sturges",

    density.fill = TRUE, density.opacity = .4, density.args = list(), leg = "outside",

    lpos = "auto", lvn = TRUE, leg.title = TRUE, leg.args = list(), title = TRUE, labx = TRUE,

    laby = TRUE, lty = TRUE, lwd = 2, sub = TRUE, ndisp = TRUE, note = TRUE,

    font = c(title = 2, sud = 1, leg = 1, leg.title = 2, note = 3),

    cex = c(title = 1.5, sud = .9, leg = .9, note = .7, points = 1), sud = TRUE, labels = TRUE,

    labels.filter = "_", labels.trim = 20, points = TRUE, points.first = TRUE, byx = TRUE,

    drop = c(x = TRUE, by = TRUE, bet = TRUE), prat = c(1, 1), check.height = TRUE, model = FALSE,

    options = NULL, add = NULL) {

  # parsing input and preparing data

    )

  }

  }

    } else {

    },

  )

    } else {

    }

  }

      }

    }

  }

        )

      }

    }

      }

    } else {

    }

    }

  }

  )

  })

      }

    }

      }

    }

  }

  }

  }

    }

  }

  }

    }

    }

    }

  }

  )

      }

      }

    } else {

    }

  }

    # setting up multiple y variables

      }

    }

      }

      } else {

      }

    }

      }

    }

    } else {

    }

      }

    }

  } else {

  }

  }

  }

  }

  }

  }

  # splitting and parsing variables

    } else {

    }

  }

      )

    } else {

    }

  }

  )

      } else {

      }

    }

  }

  }

      }

      }

        } else {

        }

      }

    }

  }

      {

        ))

        }

      },

    )

  }

      {

            } else {

            }

            }

              } else {

                } else {

                }

              }

            } else {

            }

            }

          }

        }

      },

    )

  }

      } else {

      }

    })

    } else {

    }

  } else {

  }

    } else {

    }

      } else {

      }

    } else {

    }

  }

  }

      }

    })

  }

  # figuring out colors

  } else {

  }

  }

    }

    }

    }

        } else {

        }

      } else {

      }

        }

      } else {

      }

    }

      }

    }

          } else {

          }

          } else {

          }

        }

            )

          }

        }

        }

        } else {

            )

        }

      }

    }

        } else {

        }

      }

          } else {

          }

        }

      }

    } else {

        }

    }

    }

      }

    }

        }

      }

    } else {

    }

  } else {

    }

    }

  }

      } else {

        } else {

        }

      }

    }

    }

  }

    } else {

    }

  }

            }, "")

          })

        }

      }

    }

  }

    } else {

    }

  }

  # figuring out parts of the plot

    } else {

      )