toaster (version 0.2.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, labelName = NULL,
    scaleRange = c(1, 6), shapeColour = "red",
    textColour = "black", textFamily = "mono",
    textFace = "plain", textSize = 4, facet = NULL,
    ncol = 1, facetScales = "fixed",
    geocodeFun = memoise(geocode), getmapFun = get_map,
    urlonly = FALSE, api_key = NULL, baseSize = 12,
    baseFamily = "sans", title = NULL,
    legendPosition = "right",
    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 p

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 wil

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

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 optio

locationName

name of the column with strings to be geocoded to determine longitude and latitude for each data point. If this value is specified then parameters lonName and latName are ignored.

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

name of the column to use for the artifact metric 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).

labelName

name of the column to use for the artifact label text when displaying data.

shapeColour

color of of artifact placed on map.

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

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 legends. ("left", "right", "bottom", "top", or two-element numeric vector. "none" is no legend.)

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 is scaled using values in metricName column 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

data = computeAggregates(asterConn, "pitching",
               columns = c("name || ', ' || park teamname", "lgid", "teamid", "decadeid"),
               aggregates = c("min(name) name", "min(park) park", "avg(rank) rank",
                              "avg(attendance) attendance")
               )

geocodeMem = memoise(geocode)

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