toaster (version 0.5.5)

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

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.

Value

a ggplot object

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).

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)
}