add note that layer.name is passed on as group. closes #264

R/mapView.R

@@ -23,44 +23,44 @@ if ( !isGeneric('mapView') ) {
 #'
 #' @param x a \code{Raster*} or \code{Spatial*} or \code{Satellite} or
 #' \code{sf} object or a list of any combination of those. Furthermore,
-#' this can also be a \code{data.frame}, a \code{numeric vector} or a
+#'   this can also be a \code{data.frame}, a \code{numeric vector} or a
 #' \code{character string} pointing to a tile image folder or file on disk.
-#' If missing, a blank map will be drawn.
+#'   If missing, a blank map will be drawn. A value of NULL will return NULL.
 #' @param map an optional existing map to be updated/added to.
 #' @param band for stars layers, the band number to be plotted.
 #' @param pane name of the map pane in which to render features. See
 #' \code{\link{addMapPane}} for details. Currently only supported for vector layers.
-#' Ignored if \code{canvas = TRUE}. The default \code{"auto"} will create different panes
-#' for points, lines and polygons such that points overlay lines overlay polygons.
-#' Set to \code{NULL} to get default leaflet behaviour where allfeatures
-#' are rendered in the same pane and layer order is determined automatically/sequentially.
+#'   Ignored if \code{canvas = TRUE}. The default \code{"auto"} will create different panes
+#'   for points, lines and polygons such that points overlay lines overlay polygons.
+#'   Set to \code{NULL} to get default leaflet behaviour where allfeatures
+#'   are rendered in the same pane and layer order is determined automatically/sequentially.
 #' @param canvas whether to use canvas rendering rather than svg. May help
-#' performance with larger data. See \url{http://leafletjs.com/reference-1.3.0.html#canvas}
-#' for more information. Only applicable for vector data. The default setting will
-#' decide automatically, based on feature complexity.
+#'   performance with larger data. See \url{http://leafletjs.com/reference-1.3.0.html#canvas}
+#'   for more information. Only applicable for vector data. The default setting will
+#'   decide automatically, based on feature complexity.
 #' @param viewer.suppress whether to render the map in the browser (\code{TRUE})
-#' or the RStudio viewer (\code{FALSE}). When not using RStudio, maps will open
-#' in the browser by default. This is passed to \link[htmlwidgets]{sizingPolicy}
-#' via \link[leaflet]{leafletSizingPolicy}. For raster data the default is \code{FALSE}.
-#' For vector data it depends on argument \code{canvas}.
+#'   or the RStudio viewer (\code{FALSE}). When not using RStudio, maps will open
+#'   in the browser by default. This is passed to \link[htmlwidgets]{sizingPolicy}
+#'   via \link[leaflet]{leafletSizingPolicy}. For raster data the default is \code{FALSE}.
+#'   For vector data it depends on argument \code{canvas}.
 #' @param maxpixels integer > 0. Maximum number of cells to use for the plot.
-#' If maxpixels < \code{ncell(x)}, sampleRegular is used before plotting.
+#'   If maxpixels < \code{ncell(x)}, sampleRegular is used before plotting.
 #' @param color color (palette) for points/polygons/lines
 #' @param col.regions color (palette) pixels.
-#' See \code{\link{levelplot}} for details.
+#'   See \code{\link{levelplot}} for details.
 #' @param at the breakpoints used for the visualisation.
-#' See \code{\link{levelplot}} for details.
+#'   See \code{\link{levelplot}} for details.
 #' @param na.color color for missing values
 #' @param use.layer.names should layer names of the Raster* object be used?
 #' @param map.types character spcifications for the base maps.
-#' see \url{http://leaflet-extras.github.io/leaflet-providers/preview/}
-#' for available options.
+#'   see \url{http://leaflet-extras.github.io/leaflet-providers/preview/}
+#'   for available options.
 #' @param burst whether to show all (TRUE) or only one (FALSE) layer(s).
-#' See also Details.
+#'   See also Details.
 #' @param zcol attribute name(s) or column number(s) in attribute table
-#' of the column(s) to be rendered. See also Details.
+#'   of the column(s) to be rendered. See also Details.
 #' @param cex attribute name(s) or column number(s) in attribute table
-#' of the column(s) to be used for defining the size of circles
+#'   of the column(s) to be used for defining the size of circles
 #' @param lwd line width
 #' @param alpha opacity of lines
 #' @param alpha.regions opacity of the fills of points, polygons or raster layer(s)
@@ -69,163 +69,167 @@ if ( !isGeneric('mapView') ) {
 #' @param legend.opacity opacity of the legend
 #' @param trim should the raster be trimmed in case there are NAs on the edges
 #' @param verbose should some details be printed during the process
-#' @param layer.name the name of the layer to be shown on the map
+#' @param layer.name the name of the layer to be shown on the map.
+#'   By default this is the character version of whatever is passed to \code{x}.
+#'   NOTE: This is being passed to underlying leaflet functions as the group argument.
+#'   So if you use mapview to set up a map and want to refer to a certain layer
+#'   later on, this is what you should refer to in \code{group}.
 #' @param homebutton logical, whether to add a zoom-to-layer button to the map.
-#' Defaults to TRUE
+#'   Defaults to TRUE
 #' @param popup a \code{list} of HTML strings with the popup contents, usually
-#' created from \code{\link[leafpop]{popupTable}}. See \code{\link{addControl}} for
-#' details.
+#'   created from \code{\link[leafpop]{popupTable}}. See \code{\link{addControl}} for
+#'   details.
 #' @param label For vector data (sf/sp) a character vector of labels to be
-#' shown on mouseover. See \code{\link{addControl}} for details. For raster
-#' data (Raster*/stars) a logical indicating whether to add image query.
+#'   shown on mouseover. See \code{\link{addControl}} for details. For raster
+#'   data (Raster*/stars) a logical indicating whether to add image query.
 #' @param native.crs logical whether to reproject to web map coordinate
-#' reference system (web mercator - epsg:3857) or render using native CRS of
-#' the supplied data (can also be NA). Default is FALSE which will render in
-#' web mercator. If set to TRUE now background maps will be drawn (but rendering
-#' may be much quicker as no reprojecting is necessary). Currently only works
-#' for simple features.
+#'   reference system (web mercator - epsg:3857) or render using native CRS of
+#'   the supplied data (can also be NA). Default is FALSE which will render in
+#'   web mercator. If set to TRUE now background maps will be drawn (but rendering
+#'   may be much quicker as no reprojecting is necessary). Currently only works
+#'   for simple features.
 #' @param method for raster data only (raster/stars). Method used to compute
-#' values for the resampled layer that is passed on to leaflet. mapview does
-#' projection on-the-fly to ensure correct display and therefore needs to know
-#' how to do this projection. The default is 'bilinear' (bilinear interpolation),
-#' which is appropriate for continuous variables. The other option, 'ngb'
-#' (nearest neighbor), is useful for categorical variables. Ignored if the raster
-#' layer is of class \code{factor} in which case "ngb" is used.
+#'   values for the resampled layer that is passed on to leaflet. mapview does
+#'   projection on-the-fly to ensure correct display and therefore needs to know
+#'   how to do this projection. The default is 'bilinear' (bilinear interpolation),
+#'   which is appropriate for continuous variables. The other option, 'ngb'
+#'   (nearest neighbor), is useful for categorical variables. Ignored if the raster
+#'   layer is of class \code{factor} in which case "ngb" is used.
 #' @param highlight either \code{FALSE}, \code{NULL} or a list of styling
-#' options for feature highlighting on mouse hover.
-#' See \code{\link{highlightOptions}} for details.
+#'   options for feature highlighting on mouse hover.
+#'   See \code{\link{highlightOptions}} for details.
 #' @param maxpoints the maximum number of points making up the geometry.
-#' In case of lines and polygons this refers to the number of vertices. See
-#' Details for more information.
+#'   In case of lines and polygons this refers to the number of vertices. See
+#'   Details for more information.
 #' @param query.type for raster methods only. Whether to show raster value query
-#' on \code{'mousemove'} or \code{'click'}. Ignored if \code{label = FALSE}.
+#'   on \code{'mousemove'} or \code{'click'}. Ignored if \code{label = FALSE}.
 #' @param query.digits for raster methods only. The amount of digits to be shown
-#' by raster value query. Ignored if \code{label = FALSE}.
+#'   by raster value query. Ignored if \code{label = FALSE}.
 #' @param query.position for raster methods only. The position of the raster
-#' value query info box. See \code{position} argument of \code{\link{addLegend}}
-#' for possible values. Ignored if \code{label = FALSE}.
+#'   value query info box. See \code{position} argument of \code{\link{addLegend}}
+#'   for possible values. Ignored if \code{label = FALSE}.
 #' @param query.prefix for raster methods only. a character string to be shown
-#' as prefix for the layerId. Ignored if \code{label = FALSE}.
+#'   as prefix for the layerId. Ignored if \code{label = FALSE}.
 #' @param ... additional arguments passed on to respective functions.
-#' See \code{\link{addRasterImage}}, \code{\link{addCircles}},
+#'   See \code{\link{addRasterImage}}, \code{\link{addCircles}},
 #' \code{\link{addPolygons}}, \code{\link{addPolylines}} for details
 #'
 #' @details
 #' \code{maxpoints} is taken to determine when to switch rendering from svg
-#' to canvas overlay for perfomance. The threshold calculation is done as follows: \cr
-#' if the number of points (in case of point data) or vertices (in case of
-#' polygon or line data) > \code{maxpoints} then render using special render
-#' function. Within this render function we approximate the complexity of
-#' features by \cr
+#'   to canvas overlay for perfomance. The threshold calculation is done as follows: \cr
+#'   if the number of points (in case of point data) or vertices (in case of
+#'   polygon or line data) > \code{maxpoints} then render using special render
+#'   function. Within this render function we approximate the complexity of
+#'   features by \cr
 #' \cr
 #' \code{maxFeatures <- maxfeatures / (npts(data) / length(data))} \cr
 #' \cr
-#' where \code{npts} determines the number of points/vertices and \code{length}
-#' the number of features (points, lines or polygons). When the number of
-#' features in the current view window is larger than \code{maxFeatures} then
-#' features are rendered on the canvas, otherwise they are rendered as svg objects
-#' and fully queriable.
+#'   where \code{npts} determines the number of points/vertices and \code{length}
+#'   the number of features (points, lines or polygons). When the number of
+#'   features in the current view window is larger than \code{maxFeatures} then
+#'   features are rendered on the canvas, otherwise they are rendered as svg objects
+#'   and fully queriable.
 #'
 #' @author
 #' Tim Appelhans
 #'
 #' @examples
 #' \dontrun{
-#' mapview()
+#'   mapview()
 #'
-#' ## simple features ====================================================
-#' library(sf)
+#'   ## simple features ====================================================
+#'   library(sf)
 #'
-#' # sf
-#' mapview(breweries)
-#' mapview(franconia)
+#'   # sf
+#'   mapview(breweries)
+#'   mapview(franconia)
 #'
-#' # sfc
-#' mapview(st_geometry(breweries)) # no popup
+#'   # sfc
+#'   mapview(st_geometry(breweries)) # no popup
 #'
-#' # sfg / XY - taken from ?sf::st_point
-#' outer = matrix(c(0,0,10,0,10,10,0,10,0,0),ncol=2, byrow=TRUE)
-#' hole1 = matrix(c(1,1,1,2,2,2,2,1,1,1),ncol=2, byrow=TRUE)
-#' hole2 = matrix(c(5,5,5,6,6,6,6,5,5,5),ncol=2, byrow=TRUE)
-#' pts = list(outer, hole1, hole2)
-#' (pl1 = st_polygon(pts))
-#' mapview(pl1)
+#'   # sfg / XY - taken from ?sf::st_point
+#'   outer = matrix(c(0,0,10,0,10,10,0,10,0,0),ncol=2, byrow=TRUE)
+#'   hole1 = matrix(c(1,1,1,2,2,2,2,1,1,1),ncol=2, byrow=TRUE)
+#'   hole2 = matrix(c(5,5,5,6,6,6,6,5,5,5),ncol=2, byrow=TRUE)
+#'   pts = list(outer, hole1, hole2)
+#'   (pl1 = st_polygon(pts))
+#'   mapview(pl1)
 #'
-#' ## raster ==============================================================
-#' if (interactive()) {
-#'   library(plainview)
+#'   ## raster ==============================================================
+#'   if (interactive()) {
+#'     library(plainview)
 #'
-#'   mapview(plainview::poppendorf[[5]])
-#' }
+#'     mapview(plainview::poppendorf[[5]])
+#'   }
 #'
-#' ## spatial objects =====================================================
-#' mapview(leaflet::gadmCHE)
-#' mapview(leaflet::atlStorms2005)
+#'   ## spatial objects =====================================================
+#'   mapview(leaflet::gadmCHE)
+#'   mapview(leaflet::atlStorms2005)
 #'
 #'
-#' ## styling options & legends ===========================================
-#' mapview(franconia, color = "white", col.regions = "red")
-#' mapview(franconia, color = "magenta", col.regions = "white")
+#'   ## styling options & legends ===========================================
+#'   mapview(franconia, color = "white", col.regions = "red")
+#'   mapview(franconia, color = "magenta", col.regions = "white")
 #'
-#' mapview(breweries, zcol = "founded")
-#' mapview(breweries, zcol = "founded", at = seq(1400, 2200, 200), legend = TRUE)
-#' mapview(franconia, zcol = "district", legend = TRUE)
+#'   mapview(breweries, zcol = "founded")
+#'   mapview(breweries, zcol = "founded", at = seq(1400, 2200, 200), legend = TRUE)
+#'   mapview(franconia, zcol = "district", legend = TRUE)
 #'
-#' clrs <- sf.colors
-#' mapview(franconia, zcol = "district", col.regions = clrs, legend = TRUE)
+#'   clrs <- sf.colors
+#'   mapview(franconia, zcol = "district", col.regions = clrs, legend = TRUE)
 #'
-#' ### multiple layers ====================================================
-#' mapview(franconia) + breweries
-#' mapview(list(breweries, franconia))
-#' mapview(franconia) + mapview(breweries) + trails
+#'   ### multiple layers ====================================================
+#'   mapview(franconia) + breweries
+#'   mapview(list(breweries, franconia))
+#'   mapview(franconia) + mapview(breweries) + trails
 #'
-#' mapview(franconia, zcol = "district") + mapview(breweries, zcol = "village")
-#' mapview(list(franconia, breweries),
-#'         zcol = list("district", NULL),
-#'         legend = list(TRUE, FALSE))
+#'   mapview(franconia, zcol = "district") + mapview(breweries, zcol = "village")
+#'   mapview(list(franconia, breweries),
+#'           zcol = list("district", NULL),
+#'           legend = list(TRUE, FALSE))
 #'
 #'
-#' ### burst ==============================================================
-#' mapview(franconia, burst = TRUE)
-#' mapview(franconia, burst = TRUE, hide = TRUE)
-#' mapview(franconia, zcol = "district", burst = TRUE)
+#'   ### burst ==============================================================
+#'   mapview(franconia, burst = TRUE)
+#'   mapview(franconia, burst = TRUE, hide = TRUE)
+#'   mapview(franconia, zcol = "district", burst = TRUE)
 #'
 #'
-#' ### ceci constitue la fin du pipe ======================================
-#' library(dplyr)
-#' library(sf)
+#'   ### ceci constitue la fin du pipe ======================================
+#'   library(dplyr)
+#'   library(sf)
 #'
-#' franconia %>%
-#'   sf::st_union() %>%
-#'   mapview()
+#'   franconia %>%
+#'     sf::st_union() %>%
+#'     mapview()
 #'
-#' franconia %>%
-#'   group_by(district) %>%
-#'   summarize() %>%
-#'   mapview(zcol = "district")
+#'   franconia %>%
+#'     group_by(district) %>%
+#'     summarize() %>%
+#'     mapview(zcol = "district")
 #'
-#' franconia %>%
-#'   group_by(district) %>%
-#'   summarize() %>%
-#'   mutate(area = st_area(.) / 1e6) %>%
-#'   mapview(zcol = "area")
+#'   franconia %>%
+#'     group_by(district) %>%
+#'     summarize() %>%
+#'     mutate(area = st_area(.) / 1e6) %>%
+#'     mapview(zcol = "area")
 #'
-#' franconia %>%
-#'   mutate(area = sf::st_area(.)) %>%
-#'   mapview(zcol = "area", legend = TRUE)
+#'   franconia %>%
+#'     mutate(area = sf::st_area(.)) %>%
+#'     mapview(zcol = "area", legend = TRUE)
 #'
-#' breweries %>%
-#'   st_intersection(franconia) %>%
-#'   mapview(zcol = "district")
+#'   breweries %>%
+#'     st_intersection(franconia) %>%
+#'     mapview(zcol = "district")
 #'
-#' franconia %>%
-#'   mutate(count = lengths(st_contains(., breweries))) %>%
-#'   mapview(zcol = "count")
+#'   franconia %>%
+#'     mutate(count = lengths(st_contains(., breweries))) %>%
+#'     mapview(zcol = "count")
 #'
-#' franconia %>%
-#'   mutate(count = lengths(st_contains(., breweries)),
-#'          density = count / st_area(.)) %>%
-#'   mapview(zcol = "density")
+#'   franconia %>%
+#'     mutate(count = lengths(st_contains(., breweries)),
+#'            density = count / st_area(.)) %>%
+#'     mapview(zcol = "density")
 #' }
 #'
 #' @export