createMap: Locate map, geocode data, then plot both.

In teradata-aster-field/toaster: Big Data in-Database Analytics that Scales with Teradata Aster Distributed Platform

Description

createMap is a smart function that places data artifact on the map. If necessary it geocodes the data, locates map that fits all data artifacts, and plots the map with the data shapes sized and colored using metrics.

Usage

createMap(data, maptype = "terrain", mapColor = c("color", "bw"),
  source = c("google", "osm", "stamen", "cloudmade"), location = NULL,
  locator = "center", boxBorderMargin = 10, zoom = NULL,
  locationName = NULL, lonName = "LONGITUDE", latName = "LATITUDE",
  metricName = NULL, metrics = metricName, labelName = NULL,
  scaleRange = c(1, 6), shape = 19, shapeColour = "red",
  shapeAlpha = 0.5, shapeStroke = 0.5, scaleSize = TRUE,
  textColour = "black", textFamily = "mono", textFace = "plain",
  textSize = 4, facet = NULL, ncol = 1, facetScales = "fixed",
  geocodeFun = memoise::memoise(geocode), getmapFun = get_map,
  urlonly = FALSE, api_key = NULL, baseSize = 12, baseFamily = "sans",
  title = NULL, legendPosition = "right", metricGuides = c("legend",
  "colorbar"), defaultTheme = theme_bw(base_size = baseSize),
  themeExtra = NULL)

Arguments

data	data frame with artifacts and their locations and metric(s) to be placed on the map. If location name is provided (with locationName) then it is used to gecode artifacts first. If not location then longitude and latitude must be provided. It is caller's responsibility adjust locations with value of zoom parameter to fit artifacts on the map.
maptype	map theme as defined in get_map. options available are 'terrain', 'satellite', 'roadmap', and 'hybrid'
mapColor	color ('color') or black-and-white ('bw')
source	Google Maps ('google'), OpenStreetMap ('osm'), Stamen Maps ('stamen'), or CloudMade maps ('cloudmade')
location	location of the map: longitude/latitude pair (in that order), or left/bottom/right/top bounding box: 'center' uses 2 value vector for the center of the map, while 'box' uses 4 value vector as left/bottom/right/top. If missing then function will derive map location using parameter locator and the data.
locator	in absence of location specifies how to use data to determine map location: when 'center' then function averages out data point longitude and latitude values to get approximate cneter for the map; when 'box' it will use min/max of longitude and latitude values to determine bounding box: left/bottom/right/top. If parameter locationName is specified then function will geocode values from this column first. If paramter locationName is missing then it assumes that data is already geocoded and stored in the columns with the names lonName and latName.
boxBorderMargin	margin size in percent of box sizes to increase box when computed from data locations.
zoom	map zoom as defined in get_map: an integer from 3 (continent) to 21 (building), default value 10 (city). Properly setting zoom for each map is responsibility of a caller. Zoom is optional when using bounding box location specification.
locationName	vector of the column names with address or name to geocode its location (find latitude and longitude) using geocode (see package ggmap). When locationName is specified then parameters lonName and latName are ignored. Multiple column names are used in order of appearance: geocoding tries 1st column's values first, then, for the data points that didn't get resolved, it tries the 2d column's values, and so on.
lonName	name of the column with longitude value. This value (in combination with value from column latName) is used to place each data point on the map. This parameter is ignored if locationName is defined.
latName	name of the column with latitude value. This value (in combination with value from column lonName) is used to place each data point on the map. This parameter is ignored if locationName is defined.
metricName	(deprecated) Use parameter metrics instead.
metrics	character vector of column names with metric values to scale shapes placed on map. First metric corresponds to the size (or area depending on scaleSize), second to the fill gradient. See also scaleSize and shapeStroke.
labelName	name of the column to use for the artifact label text when displaying data.
scaleRange	a numeric vector of lenght 2 that specifies the minimum and maximum size of the plotting symbol after transformation (see parameter range of scale_size).
shape	type of shape to use.
shapeColour	color of metric artifacts placed on map.
shapeAlpha	transparency of an artifact shape expressed as a fraction between 0 (complete transparency) and 1 (complete opacity).
shapeStroke	border width of an artifact shape. Remember, that in ggplot2 size and stroke are additive so a point with size = 5 and stroke = 5 will have a diameter of 10mm. createMap maps metrics[[1]] to shape size.
scaleSize	logical if TRUE then scale artifact shapes by size (radius), otherwise scale shape's area (artifact shapes scaling always uses metrics[[1]] values).
textColour	color of artifact labels on map.
textFamily	font family (when available) to use for artfiact labels.
textFace	font style to apply to artifact labels: 'plain' (default), 'bold', 'italic', or 'bold.italic'.
textSize	font size of artifact labels.
facet	name of a column to divide plot into facets for specificed parameter (defualt is NULL - no facets). If facet is single value then facet wrap applied (see facet_wrap), otherwise facet grid (see facet_grid with 1st 2 values of the vector.
ncol	number of facet columns (applies when single facet column supplied only - see parameter facet).
facetScales	Are scales shared across all facets: "fixed" - all are the same, "free_x" - vary across rows (x axis), "free_y" - vary across columns (Y axis) (default), "free" - both rows and columns (see in facet_wrap parameter scales).
geocodeFun	geocode function. Default is geocode but due to Google API restrictions use memoised version, e.g. memoise(geocode), instead (see package memoise).
getmapFun	get map function. Defayult is get_map but due to map APIs restrictions use memoised version, e.g. memose(get_map), instead (see package memoise).
urlonly	return url only.
api_key	an api key for cloudmade maps.
baseSize	base font size.
baseFamily	base font family.
title	plot title.
legendPosition	the position of metric guide ("left", "right", "bottom", "top", or two-element numeric vector; "none" is no legend).
metricGuides	list or vector with names of guide objects, or objects themselves, for up to 2 metrics. Typical guides are "legend" or "colorbar" names and guide_legend or guide_colorbar objects.
defaultTheme	plot theme to use, default is theme_bw.
themeExtra	any additional ggplot2 theme attributes to add.

Details

Geocoding: If parameter locationName is missing then no geocoding is possible. In that case parameters lonName and latName must contain names of columns with longitude and latitude information assigned to each data artifact (data point). If parameter locationName is defined then geocoding attempts to use values from the column with this name. Function geocodeFun specifies geocoding function (with default geocode from ggmap package). To speed up processing and avoid hitting global limit on Google Map API use memoised version of this function: memoise(geocode) (see memoise).

Map Locating: Function operates in 2 modes: explicit map location mode and implicit mode. In explicit mode value location locates the map using one of two supported formats. If it is a 2-value vector then it contains a center of the map. If it is 4-value vector then it contains bounding box coordinates: left/bottom/right/top. In implicit mode, when location is missing, fuction uses parameters locator and data to locate the map. If locator is equal to 'center' then it centers map by averaging longitude and latitude values of all data artifacts. If locator is equal to 'box' then it determines min/max values of longitutude and latitude of all data artifacts and locates the map by corresponding bounding box. Note that both modes support require explicit parameter zoom if applicable.

Map Types: variety of map avaiable are from several public sources: google, OpenStreetMap, Stamen, and CloudMade maps. The options and terms for each are different. For example, not all sources support both color and black-and-white options, or map types terrain, satellite, roadmap or hybrid. Note that in most cases by using Google source you are agreeing to the Google Maps API Terms of Service at https://developers.google.com/maps/terms.

Shapes: data artifacts are shapes placed over the map. Their size and fill are scaled using values in metrics columns and their location is determined either by geocoding values from locationName column or with longitude and latitude values stored in lonName and latName columns.

Labels: If labelName is specified then column with such name contains text labels to place on the map (using the same locations as for the shapes).

Value

a ggplot object

Examples

if(interactive()){
# initialize connection to Lahman baseball database in Aster 
conn = odbcDriverConnect(connection="driver={Aster ODBC Driver};
                         server=<dbhost>;port=2406;database=<dbname>;uid=<user>;pwd=<pw>")

data = computeAggregates(channel = conn, "teams_enh",
                aggregates = c("min(name) name", "min(park) park", "avg(rank) rank", 
                               "avg(attendance) attendance"),
                by = c("name || ', ' || park teamname", "lgid", "teamid", "decadeid"))
               
geocodeFun = memoise::memoise(ggmap::geocode)
getMapFun = memoise::memoise(ggmap::get_map)

createMap(data=data[data$decadeid>=2000,], 
          source = "stamen", maptype = "watercolor", zoom=4, 
          facet=c("lgid", "decadeid"),
          locationName=c('teamname','name'), 
          metrics=c('rank', 'attendance'), shape = 21,
          labelName='name', shapeColour="blue", scaleRange = c(2,12), textColour="black",
          title='Game Attendance by Decade and League (yearly, 2000-2012)',
          geocodeFun=geocodeFun, getmapFun = getMapFun)
}

teradata-aster-field/toaster documentation built on May 31, 2019, 8:36 a.m.