plot.locoh.lhs: Plot a LoCoH-hullset object
In tlocoh: Constructs homeranges and explores time use patterns from location data

Multi-purpose plotting function for a LoCoH-hullset object

## S3 method for class 'locoh.lhs'
plot(x, lhs, id = NULL, k = NULL, r = NULL,
  a = NULL, s = NULL, hs.names = NULL, iso = FALSE, rast = FALSE,
  hulls = FALSE, hpp = FALSE, dr = FALSE, nn = FALSE,
  ellipses = FALSE, allpts = FALSE, ptid = NULL,
  ptid.highlight = TRUE, add = FALSE, aoi = NULL, iso.idx = NULL,
  iso.sort.metric = NULL, iso.legend = TRUE, legend.space = 0.25,
  dr.metric = NULL, dr.thresh.val = NULL, dr.thresh.type = NULL,
  dr.smooth = NULL, lwd.dr = 2, pch.allpts = 16, cex.nn = 2,
  cex.hpp = 0.6, cex.allpts = 0.5, cex.pp = 2, cex.axis = 0.8,
  cex.legend = 0.8, col.hpp = "gray50", col.hpp.na = "yellow",
  col.hulls.border = "gray50", col.hulls.fill = NA,
  col.ellipses = "red", col.allpts = c("auto", "gray")[1],
  col.nn = "black", col.nn.pp = "blue", col.iso.fill = 1,
  col.iso.opacity = 1, col.iso.border = NA, col.iso.scale = TRUE,
  col.dr = "red", hpp.classify = c("none", "hsp", hm.expr(names.only =
  TRUE, print = FALSE, desc = FALSE))[1], hpp.classify.bins = 10,
  hpp.classify.chop = 0.01, hpp.classify.legend = TRUE,
  hpp.classify.common.scale.discrete = TRUE,
  col.ramp = c("gray10,gray90", "rainbow")[1], col.ramp.bins = 10,
  hsp = NULL, record = FALSE, figs.per.page = 1,
  same.axes.4all = NULL, overlay = FALSE,
  col.overlay.byhullset = FALSE, ufat = TRUE, ufipt = TRUE,
  axes.show = TRUE, axes.ticks = axes.show, axes.titles = axes.show,
  title = NULL, title.show = TRUE, title.inc = c("title", "hs.name",
  "id", "kar", "features", "hpp.classify", "hmap", "ptid")[if
  (is.null(title)) 3:4 else 1], subtitle.inc = c("title", "hs.name",
  "id", "kar", "features", "hpp.classify", "hmap", "ptid")[if
  (is.null(title)) 5:8 else 0], mar = c(if (axes.titles || axes.ticks)
  3.3 else 0.5, if (axes.titles || axes.ticks) 3.2 else 0.5, if
  (title.show) 3.2 else 0.5, 0.5), mgp = c(2, 0.7, 0), lo.save = TRUE,
  lo.margins.set = TRUE, desc = c(NONE <- 0, BOTTOM <- 1, TOP <-
  3)[ifelse(figs.per.page == 1, 2, 1)], cex.desc = 0.8,
  col.desc = "darkgreen", gmap = c("none", "roadmap", "satellite",
  "hybrid", "terrain")[1], gmap.one4all = TRUE, google_apikey = NULL,
  tiff.fn = NULL, tiff.pct = FALSE, tiff.bands = c(4, 3, 2),
  tiff.col = gray(0:255/255), tiff.buff = 0, tiff.fill.plot = TRUE,
  shp.csv = NULL, layers = NULL, png.fn = NULL, png.dir = NULL,
  png.dir.make = TRUE, png.fn.pre = NULL, png.fn.mid = NULL,
  png.fn.suf = NULL, png.fn.incld.hs.name = TRUE,
  png.each.plot.separate = TRUE, png.width = 800,
  png.height = png.width, png.pointsize = 12 + (png.width - 480)/80,
  png.overwrite = TRUE, status = TRUE, panel.num = NULL,
  panel.num.inside.plot = !title.show, hmap = NULL, iso.level = NULL,
  xlim = NULL, ylim = NULL, check.ap.value.in.hmparams = TRUE,
  hme = hm.expr(names.only = FALSE), ...)

`x`	A LoCoH-hullset object
`lhs`	Deprecated, use `x` instead
`id`	The names of the individual(s) to include in the plot.
`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
`iso`	Whether to display isopleths. T/F.
`rast`	Whether to display rasterized isopleths. T/F.
`hulls`	Whether to display hulls. T/F.
`hpp`	Whether to display hull parent-points. T/F.
`dr`	Whether to display directional routes. T/F.
`nn`	Whether to display nearest neighbors (requires that a value for ptid is passed and nearest neighbors were saved when creating the hullset object). T/F.
`ellipses`	Whether to display bounding ellipses (requires that ellipses were saved when computing ellipses for the hullset). T/F.
`allpts`	Whether to display all points. T/F.
`ptid`	One or more ptid (point id) values. A separate plot will be drawn 'zoomed in' to each point indicated. Can also be "auto", in which case ptid will be selected at random. Used primarily to inspect the hull, nearest neighbors, and/or ellipse for specific hulls.
`ptid.highlight`	Whether to highlight the point specified by ptid. T/F.
`add`	Whether to add to the existing plot. T/F.
`aoi`	An area-of-interest object (e.g., box), used to 'zoom in' to specific parts of the plot. aoi objects may be created by the function `aoi()`.
`iso.idx`	The index(s) of the isopleths to plot. Use the summary() function to see the indices of the isopleths.
`iso.sort.metric`	The sort metric(s) of the isopleths that will be displayed. Character.
`iso.legend`	Whether to include a legend for the isopleths.
`legend.space`	An expansion factor for the x-axis that will be used to make room for the legend.
`dr.metric`	The name of the metric for the directional routes to be displayed (acts to filter on which directional routes are displayed). See `lhs.dr.add`
`dr.thresh.val`	The threshhold value for the directional routes to be displayed (acts to filter on which directional routes are displayed). See `lhs.dr.add`
`dr.thresh.type`	The threshhold type for the directional routes to be displayed (acts to filter on which directional routes are displayed). See `lhs.dr.add`
`dr.smooth`	The smoothing factor for the directional routes to be displayed (acts to filter on which directional routes are displayed). See `lhs.dr.add`
`lwd.dr`	The line width of directional routes.
`pch.allpts`	The plot character for all points
`cex.nn`	The expansion factor for nearest neighbor points.
`cex.hpp`	The expansion factor for hull parent-points.
`cex.allpts`	The expansion factor for all points.
`cex.pp`	The expansion factor for the parent point.
`cex.axis`	The expansion factor for axis labels.
`cex.legend`	The expansion factor for the legend.
`col.hpp`	The color of hull parent points. Either a single color value or a vector of color values of the same length as the number of hulls.
`col.hpp.na`	The color of hull parent points that have no value of the metric specified by `hpp.classify`. Single color value.
`col.hulls.border`	The outline color of hulls. Either a single color value or a vector of color values of the same length as the number of hulls.
`col.hulls.fill`	The fill color of hulls.
`col.ellipses`	The outline color of bounding ellipses. Either a single color value or a vector of color values of the same length as the number of hulls.
`col.allpts`	The color of all points. Single color value.
`col.nn`	The color of nearest neighbors. Single color value.
`col.nn.pp`	The color of parent-points. Used only when ptid is passed. Single color value.
`col.iso.fill`	A number corresponding to a preset color ramp that will be used to display the isopleths. 1=red to blue, 2=yellow to red, 3=blue to red, 4=red to yellow. Alternately, a character vector of color values of the same length as the number of isopleth levels.
`col.iso.opacity`	A number 0..1 for the opacity of isopleth fill color, where 1 is opaque and 0 is transparent
`col.iso.border`	Color value of the isopleth border. Color value (use NA for no border).
`col.iso.scale`	When plotting a subset of isopleths (by ecc or par), whether to scale the isopleth colors to the values of the subset. Not being used.
`col.dr`	The color of directional routes.
`hpp.classify`	How to classify hull parent points. May be "none", the name of a hull metric, or "hsp" (hull scatterplot)
`hpp.classify.bins`	The number of equal-interval bins of the hull metric value to create when classifying hull parent-points by a hull metric.
`hpp.classify.chop`	The proportion of hull parent-points at the tails of the distribution to remove when calculating the bins.
`hpp.classify.legend`	Whether to include a legend for the classification of hull parent-points. T/F.
`hpp.classify.common.scale.discrete`	Whether to classify hull parent points using a common scale when there are multiple maps produced. Ignored if hpp.classify is 'none' or 'hsp'. T/F.
`col.ramp`	The first and last values of the color ramp to use when classifying hull parent-points by a hull metric. Two-item vector with color values.
`col.ramp.bins`	The number of bins in the color ramp when classifying hull parent-points by a hull-metric
`hsp`	The hull scatterplot object to use when displaying hull parent points by a hull scatterplot. May be a hull scatterplot object or the index of a hull scatterplot saved in the hullset.
`record`	Whether to open a new plot window and turn on recording. T/F.
`figs.per.page`	The number of plots per page.
`same.axes.4all`	Whether to use the same axes ranges for all plots. T/F.
`overlay`	Whether to overlay the plots. T/F.
`col.overlay.byhullset`	Whether to use a different color for each hullset when overlay=TRUE. Affects only isopleths, hulls and ellipses. T/F.
`ufat`	Whether to use user-friendly-axis-titles. T/F.
`ufipt`	Whether to use user-friendly-isopleth-plot-titles. T/F.
`axes.show`	Whether to show the axes. T/F.
`axes.ticks`	Whether to show the tick marks and labels on the axes. T/F.
`axes.titles`	Whether to show axes titles. 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.inc`	The element(s) to include in the title (ignored if `title` is passed or `overlay=TRUE`)
`subtitle.inc`	The element(s) to include in the subtitle (ignored if `title` is passed or `overlay=TRUE`)
`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.
`desc`	Which side to display automatically generated desciptive text (e.g. caption). 0=none, 1=bottom, 3=top. Ignored if `overlay=TRUE`.
`cex.desc`	The expansion factor for the descriptive text. Numeric value.
`col.desc`	The color of the descriptive text. Color value.
`gmap`	The name of a background image that will be downloaded from Google: `"none"`, `"roadmap"`, `"satellite"`, `"hybrid"`, or `"terrain"`. May also be a object of type `locoh.gmap`, see Notes.
`gmap.one4all`	Whether to download a single background image for all ids. T/F
`google_apikey`	API key for the Google Static Map API service. See https://developers.google.com/maps/documentation/maps-static/get-api-key for details.
`tiff.fn`	The path and name of a GeoTIFF file (e.g., satellite image) that will be displayed in the background. See notes.
`tiff.pct`	Whether or to convert the GeoTIFF to an indexed 256 color RGB image, which may speed up drawing. T/F.
`tiff.bands`	A vector of exactly one (for a single band image) or exactly three integers corresponding to the bands of the GeoTIFF image that will be mapped to the red, green and blue color guns respectively,. Ignored if `tiff.fn` only contains one band.
`tiff.col`	A vector of color values for plotting single-band images in the background. Ignored if using three bands.
`tiff.buff`	A numeric buffer distance that the range of the plot will be expanded so the points are not right on the edge of the GeoTIFF.
`tiff.fill.plot`	Whether to fill the entire plot area with the GeoTIFF. T/F.
`shp.csv`	The path and filename of a csv file that contains information about shapefiles, including layer names, file, and symbology.
`layers`	The name(s) of layers in shp.csv to display in the background. Will be displayed using the symbology in shp.csv. Character vector or comma delimited string
`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.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.fn.incld.hs.name`	Whether to include the hullset name as part of the PNG filename. (T/F). Ignored if png.fn is passed
`png.each.plot.separate`	Whether to make each plot in a separate plot / PNG. T/F. Ignored if png.fn is passed
`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.overwrite`	Whether to overwrite an existing PNG file if it exists. T/F
`status`	Whether to show messages. T/F
`panel.num`	A number or letter to display in the upper left hand corner of the plot when the plot will be used as 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
`hmap`	A named list of hull metric auxillary parameters, the name of each list element is the name of the variable
`iso.level`	The isopleth levels to plot, numeric vector
`xlim`	The lower and upper limit of the x-axis, two-element numeric vector
`ylim`	The lower and upper limit of the y-axis, two-element numeric vector
`check.ap.value.in.hmparams`	Whether to check if hull metrics exist for the auxillary parameters passed. T/F
`hme`	A list of hull metric expressions
`...`	Other parameters, including any auxillary parameters required by certain hull metrics

If png.fn or png.dir is passed, a list object where each element is a three-element list of the properties of the PNG file(s) created: $fn, $dim, $desc. Otherwise, returns a vector of desc

This is a multi-purpose plotting function for LoCoH-hullset objects. You specify which objects in the hullset to include on the plot by passing parameters.

All hullsets have hulls and hull parent points that can be plotted (e.g., codehulls=TRUE, hpp=TRUE. All hullsets also have the original locations saved and these can be added to the plot by setting allpts=TRUE. Depending how the hullset was created (see lxy.lhs), some hullsets may also have the nearest neighbors for each parent point saved, which can also be plotted (nn=TRUE).

Hullsets for which have bounding ellipses (lhs.ellipses.add) or directional routes (lhs.dr.add) have been computed can have these elements plotted by setting ellipses=TRUE and dr=TRUE respectively. If isopleths have been constructed (lhs.iso.add), these can be plotted by setting iso=TRUE. If you only want to plot some of the isopleths, you can specify which one(s) to plot with the parameters iso.idx (the index(s) of the isopleths to plot, see summary.locoh.lhs) or iso.sort.metric.

The plot title can be manually set with the title parameter. If no value for title is passed, a title will be constructed. You can define what elements will go in the title and subtitle (i.e., the second line of the title) with the title.inc and subtitle.inc parameters. To omit the plot title completely, set title.show=FALSE.

To display an image from Google in the background, set gmap to "roadmap", "satellite", "hybrid", or "terrain". This requires an internet connection. When creating plots of hullsets from multiple individuals, gmap.one4all determines whether a single background image is used for all individuals (faster to download but could result in blurry backgrounds if the individuals occupy different parts of the landscape), or a separate image is used for each individual. In the later case, You may also set gmap to an object of type locoh.gmap, so the image(s) don't have to be downloaded each time. See lhs.gmap (in the tlocoh.dev package). tiff.fn, tiff.pct, tiff.buff, tiff.bands, tiff.col, and tiff.fill.plot control the display of a GeoTIFF image in the plot background. The GeoTIFF image must be georeferenced in the same coordinate system as the locoh-hullset object, and the pixel values must be 'prestretched' for display. tiff.bands controls which bands in the TIFF file will be displayed using the red, green, and blue color guns if using three bands. In a Landsat TM image, for example, the first four bands are blue, green, red, and infrared. To display a TM GeoTIFF image as 'natural colors', you would set tiff.bands=c(3,2,1). If tiff.pct=T, the script will create a indexed 256-color version of the image, which may result in quicker drawing time particularly if several plots are being drawn. If using a single-band, for example a DEM or classified image, the colors are set by tiff.col. tiff.buff can be used to expand the range of values on the x and y axis so that you see a bit of the background image beyond the extent of the points.