lhs.plot.scatter: Create scatterplot of hull metrics
In tlocoh: Constructs homeranges and explores time use patterns from location data

Description Usage Arguments Details Value See Also

Multi-purpose scatterplot function for the hull metrics in a LoCoH-hullset

lhs.plot.scatter(lhs, id = NULL, k = NULL, r = NULL, a = NULL,
  s = NULL, hs.names = NULL, x.axis = NULL, y.axis = NULL,
  limx = NULL, limy = NULL, trans.x = NULL, trans.y = NULL,
  jiggle.x = "auto", jiggle.y = "auto", filter = NULL,
  filter.label.in.subtitle = TRUE, filter.sampsize.in.subtitle = TRUE,
  filter.col.use = TRUE, filter.axes.uniform = TRUE, title = NULL,
  title.show = TRUE, title.hs.name.include = TRUE,
  title.two.id = FALSE, title.axes = TRUE, col = c("gray50",
  "spiral")[1], bg = NULL, mar = c(4, 3.2, if (title.show) (if
  (title.hs.name.include) 3.9 else 3.2) else 0.5, 0.5), mgp = c(2.1, 0.8,
  0), lo.save = TRUE, lo.margins.set = TRUE, lo.colors.set = TRUE,
  lo.bg.as.box = FALSE, sat.base = NULL, val.base = NULL,
  hue.offset = NULL, center.method = c("bbox", "mean")[2], cex = 0.6,
  type = c("p", "l", "b")[1], ufat = NULL, figs.per.page = 1,
  add = FALSE, regions = NULL, prompt.labels = TRUE, hsp = NULL,
  hsp.reg.col = TRUE, hsp.reg.out = FALSE, hsp.reg.lbl = FALSE,
  hsp.override = TRUE, png.fn = NULL, png.dir = NULL,
  png.dir.make = TRUE, png.width = 800, png.height = png.width,
  png.pointsize = 12 + (png.width - 480)/80, png.fn.pre = NULL,
  png.fn.mid = NULL, png.fn.suf = NULL, png.exists = c("overwrite",
  "skip", "abort")[1], status = TRUE, desc = c(NONE <- 0, BOTTOM <- 1,
  TOP <- 3)[ifelse(figs.per.page == 1, 2, 1)], cex.desc = 0.8,
  col.desc = NULL, panel.num = NULL,
  panel.num.inside.plot = !title.show, hmap = NULL,
  hmap.in.subtitle = TRUE, check.ap.value.in.hmparams = TRUE, ...)

`lhs`	A LoCoH-hullset object
`id`	The name(s) of the individual(s) to include in the plot. Character vector or comma-delimited character.
`k`	The k value(s) of the hullset(s) to include in the plot. Numeric vector or comma-delimited character object.
`r`	The r value(s) of the hullset(s) to include in the plot. Numeric vector or comma-delimited character object.
`a`	The a value(s) of the hullset(s) to include in the plot. Numeric vector or comma-delimited character object.
`s`	The s value(s) of the hullset(s) to include in the plot. Numeric vector or comma-delimited character object.
`hs.names`	The name(s) of saved hullsets to include in the plot.
`x.axis`	The name of a hull metric (see `hm.expr`)
`y.axis`	The name of a hull metric
`limx`	The lower and upper limits of the x-axis. Two-element numeric vector.
`limy`	The lower and upper limits of the y-axis. Two-element numeric vector.
`trans.x`	The name of a function that will be used to transform the x-axis values. Can be any R function (e.g., "log", "sqrt"), also "square" and "cube"
`trans.y`	The name of a function that will be used to transform the y-axis values
`jiggle.x`	"auto" or a numeric value which will be used to add a normally distributed stochastic value (mean 0, sd=jiggle.x) to the x-axis values for better visualization of the number of points in each group (helpful when the x-values take on discrete values)
`jiggle.y`	"auto" or a numeric value which will be used to add a normally distributed stochastic value (mean 0, sd=jiggle.y) to the y-axis values
`filter`	NULL or a list of filter parameters. See details.
`filter.label.in.subtitle`	Whether to add the filter label to the plot subtitle. Ignored if title is passed or filter is NULL. T/F.
`filter.sampsize.in.subtitle`	Whether to add the filter sample size to the plot subtitle. Ignored if title is passed or filter is NULL. T/F.
`filter.col.use`	Whether the points will be displayed with the color(s) saved in the filter (overriding the 'col' parameter). Ignored if filter is NULL. T/F.
`filter.axes.uniform`	Whether the upper and lower limits of the axes for each plot will be set as the limit for the entire combined dataset. Ignored if filter is NULL or values are passed for limx or limy. T/F.
`title`	The title to be displayed. Character. If NULL a title will be constructed.
`title.show`	Whether to show the title. T/F.
`title.hs.name.include`	Whether to include the hullset name as part of the title. Ignored if title is passed. T/F.
`title.two.id`	An ad-hoc way to construct a title consisting of the ids of the hullset and hs2
`title.axes`	Whether to include the names of the hull metrics on the axes as part of the subtitle. Ignored if title is passed. T/F.
`col`	A single color value, or a vector of color values of the same length as the number of hulls, or "spiral" (see additional parameters below). Ignored if filter.col.use=T or something is passed for hsp (in which case col will be extracted from hsp).
`bg`	Background color
`mar`	The plot margins. A four item numeric vector.
`mgp`	The distance away from the edge of the plot for the 1) label, 2) tick marks, and 3) axis line. A three-item numeric vector.
`lo.save`	Whether to save and reset the plot device margin settings (some wrapper functions that call this function don't want device settings reset). T/F.
`lo.margins.set`	Whether to save and reset the plot device margin settings (some wrapper functions that call this function don't want device settings reset). T/F.
`lo.colors.set`	Whether to set the background, foreground color on the plot device. T/F.
`lo.bg.as.box`	Whether to display the background color as a box on the plot (needed by some wrapper function that want the axes and margins to be a different color). This overrides the setting of lo.colors.set. T/F.
`sat.base`	A number between 0 and 1 for the base staturation (how much of the color is present) of the center color (s=0.4 gives pastels), ramping up to 1 (full color) at edges.
`val.base`	A number between 0 and 1 controlling how much black is in the center color (0 is total black), ramping out to no blackness at the edges
`hue.offset`	A number between 0 and 2*pi for the color wheel rotation (in radians), which controls the color of points directly to the right of the center.
`center.method`	Determines how the center of the color will be computed. "bbox" = the center of the bounding box of the full range of points; "mean" = the mean of the data splot
`cex`	Expansion factor for the points on the scatterplot
`type`	The type of plot: 'p'=points only, 'l'=line, 'b'=both
`ufat`	Whether to substitute user-friendly axis titles. T/F.
`figs.per.page`	The number of plots per page
`add`	Whether to add to the current plot device. T/F.
`regions`	Determines whether the user will be prompted to draw regions (polygons) on the scatterplot window with the mouse, that will be saved as part of the scatterplot objecr returned. Values can be 1) a number whereby the user will be prompted to create N regions with randomly assigned colors, or 2) a vector of color values in which case the regions will be assigned those colors.
`prompt.labels`	Whether the user should be prompted to also enter labels for each of the regions drawn. Ignored if regions = NULL. T/F.
`hsp`	Either the index(s) of a hull scatterplot(s) saved in lhs (use summary() command to which how many hsp objects have been saved), or a list of objects of class locoh.hsp. When passed, the parameters in hsp will be used to create the scatterplot
`hsp.reg.col`	Whether to use the colors assigned to the regions in hsp. Ignored if hsp is NULL. T/F.
`hsp.reg.out`	Whether to display the outline of the regions in hsp. Ignored if hsp is NULL. T/F.
`hsp.reg.lbl`	Whether to display the labels of the regions in hsp. Ignored if hsp is NULL. T/F.
`hsp.override`	Whether the parameters in hsp should override other parameters passed. Ignored if hsp is NULL. T/F.
`png.fn`	The path and name of the PNG file to create (instead of displaying in a plot window).
`png.dir`	The directory for a PNG file (filename will be constructed automatically). Ignored if png.fn is passed.
`png.dir.make`	Whether to create png.dir if it doesn't exist. T/F.
`png.width`	The width of the PNG image. Ignored if png.fn is passed.
`png.height`	The height of the PNG image. Ignored if png.fn is passed.
`png.pointsize`	The pointsize (in pixels) for the PNG image (increase to make labels appear larger). Equivalent to the height or width of a character in pixels.
`png.fn.pre`	A prefix that will be used in the construction of the PNG filename. Ignored if png.fn is passed.
`png.fn.mid`	A mid-fix that will be used in the construction of the PNG filename. Ignored if png.fn is passed.
`png.fn.suf`	A suffix that will be used in the construction of the PNG filename. Ignored if png.fn is passed.
`png.exists`	What to do if a PNG with the same filename already exists: "overwrite", "skip", or "abort"
`status`	Whether to show messages. T/F.
`desc`	Which side to display automatically generated desciptive text (e.g. caption). 0=none, 1=bottom, 3=top.
`cex.desc`	The expansion factor for the descriptive text. Numeric value.
`col.desc`	The color of the descriptive text. Color value.
`panel.num`	A number or letter to display in the upper left hand corner of the plot, used when the plot will be part of a multi-frame graphic (as in publications). Character.
`panel.num.inside.plot`	Whether to display panel.num inside the plot area itself (as opposed to the title area). T/F.
`hmap`	A named list of hull metric auxillary parameters, the name of each list element is the name of the variable.
`hmap.in.subtitle`	Include the hmap value(s) in the plot subtitle. T/F
`check.ap.value.in.hmparams`	Check to make sure that hull metrics have been computed for the hull metric auxillary parameter values passed (either as separate arguments or in `hmap`)
`...`	Other parameters, including any auxillary parameters required by certain hull metrics

This function has two main purposes. 1) To make scatterplot graphics either in a plot window or PNG file 2) To create a list of objects of class "locoh.hsp", which are basically a collection of the parameters that were used to create the scatterplot including any manually drawn regions created by the user (see regions).

Note that hull metrics must already have been computed. Several hull metrics are 'automatically' computed when the hullset is defined (e.g., hull area, number of enclosed points). Other hull metrics must be created separately with functions such as lhs.ellipses.add and lhs.visit.add. Auxillary parameters required for hull metrics can be passed either as individual parameters (e.g., ivg=3600*12) or as a list element (e.g., hmap=list(ivg=86400)).

filter, if passed, will create scatterplots for subsets of hulls. For this to work, filter must be a list whose elements are named lists with the following elements: idx = a vector of the indices of the hulls (in the hulls SpatialPolygonsDataFrame), label = a label for the subset, and col = a color value. lhs.filter.hsp can be used to create a filter list based on manually drawn regions of a hull scatterplot, and lhs.filter.anv can be used to create a filter based on ranges of values of an ancillary variable. The arguments filter.sampsize.in.subtitle, filter.col.use, and filter.axes.uniform control how the subsets are treated in the scatterplot(s).

If png.fn or png.dir is passed, the plots are exported to PNG file(s) and the function returns a list of file names and image dimensions (in pixels). Otherwise returns a named list whose element(s) are of class locoh.hsp. This list of locoh.hsp objects can then be 'permanently' saved in the LoCoH-hullset object using lhs.hsp.add, and/or fed into other functions such as plot.locoh.lhs (to symbolize hull points).

lhs.plot.scatter.auto, hm.expr, lhs.hsp.add, lhs.filter.hsp, lhs.filter.anv