Simple thematic mapping
tmap choropleth quantvar [if exp] [in range] , id(varname) map(filename) [ clmethod(quantile | eqint | stdev | custom | unique) clnumber(#) clbreaks(numlist) eirange(numlist) palette(colorscheme) colors(colorstyle_list) ocolor(colorstyle) osize(linewidthstyle) bcolor(colorstyle) title(tinfo) subtitle(tinfo) note(tinfo) caption(tinfo) legpos(#) legcolor(colorstyle) legsize(#) legformat(format) legtitle(tinfo) legbox(roptions) legcount nolegend addplot(command) ]
tmap propsymbol quantvar [if exp] [in range] , xcoord(varname) ycoord(varname) map(filename) [ scolor(colorstyle) sshape(symbolstyle) ssize(#) soutline ocolor(colorstyle) osize(linewidthstyle) fcolor(colorstyle) bcolor(colorstyle) title(tinfo) subtitle(tinfo) note(tinfo) caption(tinfo) ]
tmap deviation quantvar [if exp] [in range] , xcoord(varname) ycoord(varname) map(filename) [ center(mean | median) scolor(colorstyle) sshape(symbolstyle) ssize(#) ocolor(colorstyle) osize(linewidthstyle) fcolor(colorstyle) bcolor(colorstyle) title(tinfo) subtitle(tinfo) note(tinfo) caption(tinfo) ]
tmap dot [if exp] [in range] , xcoord(varname) ycoord(varname) map(filename) [ by(varname) marker(color | shape | both) scolor(colorstyle_list) sshape(symbolstyle_list) ssize(#) soutline ocolor(colorstyle) osize(linewidthstyle) fcolor(colorstyle) bcolor(colorstyle) title(tinfo) subtitle(tinfo) note(tinfo) caption(tinfo) legpos(#) legcolor(colorstyle) legsize(#) legtitle(tinfo) legbox(roptions) legcount nolegend ]
tmap label labvar [if exp] [in range] , xcoord(varname) ycoord(varname) map(filename) [ lcolor(colorstyle) lsize(#) llength(#) ocolor(colorstyle) osize(linewidthstyle) fcolor(colorstyle) bcolor(colorstyle) title(tinfo) subtitle(tinfo) note(tinfo) caption(tinfo) ]
Description
map choropleth represents the spatial distribution of area data by means of choropleth maps, i.e., maps where each of n sub-areas of the geographical unit of interest R is colored (or shaded) according to a discrete scale based on the value taken on by the variable of interest quantvar in that sub-area. Optionally, a propsymbol, deviation, dot, or label plot can be superimposed onto the current choropleth map.
map propsymbol represents the spatial distribution of area data by means of proportional symbol maps, i.e., maps where the value taken on by the variable of interest quantvar in each of n sub-areas of the geographical unit of interest R is represented by a symbol whose size is proportional to the value itself.
map deviation represents the spatial distribution of area data by means of deviation maps, a particular kind of proportional symbol maps. In the first place, the values taken on by the variable of interest quantvar are re-expressed as deviations from the "center" of their distribution, defined as the mean or the median of quantvar. The value taken on by the transformed variable in each of n sub-areas of the geographical unit of interest R is then represented by a symbol whose size is proportional to the value itself expressed in absolute terms, and whose filling reflects the sign of the value: positive values are represented by solid symbols, while negative values are represented by hollow symbols of the same shape.
map dot represents the spatial distribution of point data by means of dot maps, i.e., maps where the n locations at which some "events" of interest have occurred are indicated by symbols whose color and/or shape can vary according to the type of event.
map label is an auxiliary program that allows the user to superimpose onto a base map the values taken on by a numeric or string variable labvar at different locations. This program can be used, for example, to plot sub-area names or to represent the spatial distribution of a given variable of interest in numeric form.
Common options
map(filename) is required. It specifies the name of the file containing the information needed to draw the base map. In tmap choropleth, filename must contain the coordinates of the polygons representing the different sub-areas of the geographical unit of interest R. In all the other cases, filename can contain either the coordinates of the polygons representing the different sub-areas, or the coordinates of the polygons representing the whole geographical unit of interest R.
ocolor(colorstyle) specifies the outline color of the polygons making up the base map. The default is ocolor(black).
osize(linewidthstyle) specifies the outline thickness of the polygons making up the base map. The default is osize(thin).
fcolor(colorstyle) specifies the fill color of the polygons making up the base map. The default is fcolor(white).
bcolor(colorstyle) specifies the background color of the graph. The default is bcolor(white).
title(tinfo) specifies the overall title of the graph.
subtitle(tinfo) specifies the subtitle of the graph.
note(tinfo) specifies notes to be displayed with the graph.
caption(tinfo) specifies an explanation to accompany the graph.
Options for tmap choropleth
id(varname) is required. It specifies the name of the numeric variable that uniquely identifies the different sub-areas of the geographical unit of interest R. The values taken on by varname must correspond to the values taken on by the identifier _ID contained in the file specified with option map(filename).
clmethod(quantile | eqint | stdev | custom | unique) specifies the method to be used for determining the class breaks.
clmethod(quantile) is the default and requests that the quantiles method be used.
clmethod(eqint) requests that the equal intervals method be used.
clmethod(stdev) requests that the standard deviates method be used.
clmethod(custom) requests that class breaks be specified by the user with option clbreaks(numlist).
clmethod(unique) requests that the variable of interest quantvar be treated as a categorical variable taking on a maximum of nine different values.
clnumber(#) specifies the number of classes k in which the variable of interest quantvar should be divided. This option accepts only numbers between 2 and 9. The default is clnumber(4).
clbreaks(numlist) is required if option clmethod(custom) is specified. It specifies a list of numbers defined as follows: the first element of the list is the minimum value of quantvar to be considered; the second to kth elements of the list are the class breaks; the last element of the list is the maximum value of quantvar to be considered.
eirange(numlist) specifies the range of values (minimum and maximum) to be considered in the calculation of class breaks when option clmethod(eqint) is specified. This option overrides the default range [min(quantvar),max(quantvar)].
palette(colorscheme) specifies the color scheme to be used for representing the different classes in which quantvar has been divided. colorscheme is one of the following: Blues BrBG Greens Greys Paired PuRd Purples RdBu RdGy Reds Set1 Set3 YlOrBr Custom The default is palette(Greys) when clmethod(quantile) or clmethod(eqint) is specified; palette(RdBu) when clmethod(stdev) is specified; and palette(Paired) when clmethod(unique) is specified. If option palette(Custom) is specified, option colors(colorstyle_list) must be specified as well.
colors(colorstyle_list) specifies a custom list of colors to be used for representing the different classes in which quantvar has been divided. The number of elements of the list must equal k, i.e., the desired number of classes.
legpos(clockpos) specifies the position of the map legend. The default is legpos(7).
legcolor(colorstyle) specifies the color of the main text of the map legend. The default is legcolor(black).
legsize(#) specifies a multiplier that affects the size of the main text of the map legend. For example, to increase the default size of the text by 50%, specify legsize(1.5). The default is legsize(1).
legformat(format) specifies the format of the numeric values appearing in the map legend. The default is legformat(%8.2f).
legtitle(tinfo) specifies the title of the map legend. By default, no title is used.
legbox(roptions) requests that a box be drawn around the map legend and specifies its appearance.
legcount requests that the number of sub-areas belonging to each class k in which quantvar has been divided be displayed in the map legend.
nolegend requests that the map legend be suppressed.
addplot(command) requests that a propsymbol, deviation, dot or label plot be superimposed onto the current choropleth map. command is one of the following:
propsymbol quantvar [if exp] [in range] , xcoord(varname) ycoord(varname) [ scolor(colorstyle) sshape(symbolstyle) ssize(#) soutline ]
deviation quantvar [if exp] [in range] , xcoord(varname) ycoord(varname) [ center(mean | median) scolor(colorstyle) sshape(symbolstyle) ssize(#) ]
dot [if exp] [in range] , xcoord(varname) ycoord(varname) [ by(varname) marker(color | shape | both) scolor(colorstyle_list) sshape(symbolstyle_list) ssize(#) soutline ]
label labvar [if exp] [in range] , xcoord(varname) ycoord(varname) [ lcolor(colorstyle) lsize(#) llength(#) ]
Options for tmap propsymbol
xcoord(varname) is required. It specifies the name of the variable containing the x-coordinate of the centroid of each sub-area of the geographical unit of interest R.
ycoord(varname) is required. It specifies the name of the variable containing the y-coordinate of the centroid of each sub-area of the geographical unit of interest R.
scolor(colorstyle) specifies the color of the symbols. The default is scolor(black).
sshape(symbolstyle) specifies the shape of the symbols. The default is sshape(Oh).
ssize(#) specifies a multiplier that affects the size of the symbols. For example, to increase the size of all the symbols by 50%, specify ssize(1.5). The default is ssize(1).
soutline requests that the symbols be drawn with a black outline.
Options for tmap deviation
xcoord(varname) is required. It specifies the name of the variable containing the x-coordinate of the centroid of each sub-area of the geographical unit of interest R.
ycoord(varname) is required. It specifies the name of the variable containing the y-coordinate of the centroid of each sub-area of the geographical unit of interest R.
center(mean | median) specifies the center of the distribution of quantvar to be taken as the reference value.
center(mean) is the default requesting that the reference value be the arithmetic mean of quantvar.
center(median) requests that the reference value be the median of quantvar.
scolor(colorstyle) specifies the color of the symbols. The default is scolor(black).
sshape(symbolstyle) specifies the shape of the symbols. This option accepts only solid symbolstyles expressed in short form, namely O D T S o d t s. The default is sshape(O).
ssize(#) specifies a multiplier that affects the size of the symbols. For example, to increase the size of all the symbols by 50%, specify ssize(1.5). The default is ssize(1).
Options for tmap dot
xcoord(varname) is required. It specifies the name of the variable containing the x-coordinate of the locations at which the events of interest have occurred.
ycoord(varname) is required. It specifies the name of the variable containing the y-coordinate of the locations at which the events of interest have occurred.
by(varname) specifies the name of a categorical variable denoting the type of event that occurred at each location. Although the program does not impose any restriction, it is advisable that varname take a maximum of nine different values.
marker(color | shape | both) when by(varname) is specified, specifies whether the different types of event should be indicated by symbols having the same shape but different colors, by symbols having the same color but different shapes, or by symbols having both different colors and different shapes.
marker(color) is the default and requests that the different types of event be indicated by symbols having the same shape but different colors.
marker(shape) requests that the different types of event be indicated by symbols having the same color but different shapes.
marker(both) requests that the different types of event be indicated by symbols having both different colors and different shapes.
scolor(colorstyle_list) specifies the colors of the symbols. When by(varname) is not specified or is specified along with marker(shape), the default is scolor(black). When by(varname) is specified along with marker(color) or marker(both), the default is scolor(black red blue green orange ltblue lime sienna yellow).
sshape(symbolstyle_list) specifies the shapes of the symbols. When by(varname) is not specified or is specified along with marker(color), the default is sshape(o). When by(varname) is specified along with marker(shape) or marker(both), the default is sshape(o oh s sh t th d dh x).
ssize(#) specifies a multiplier that affects the size of the symbols. For example, to increase the size of all the symbols by 50%, specify ssize(1.5). The default is ssize(1).
soutline requests that the symbols be drawn with a black outline.
legpos(clockpos) specifies the position of the map legend. The default is legpos(7).
legcolor(colorstyle) specifies the color of the main text of the map legend. The default is legcolor(black).
legsize(#) specifies a multiplier that affects the size of the main text of the map legend. For example, to increase the default size of the text by 50%, specify legsize(1.5). The default is legsize(1).
legtitle(tinfo) specifies the title of the map legend. By default, no title is used.
legbox(roptions) requests that a box be drawn around the map legend and specifies its appearance.
legcount requests that the number of locations belonging to each possible type of event be displayed in the map legend.
nolegend requests that the map legend be suppressed.
Options for tmap label
xcoord(varname) is required. It specifies the name of the variable containing the x-coordinate of the locations at which the labels of interest should be plotted.
ycoord(varname) is required. It specifies the name of the variable containing the y-coordinate of the locations at which the labels of interest should be plotted.
lcolor(colorstyle) specifies the color of the labels. The default is lcolor(black).
lsize(#) specifies a multiplier that affects the size of the labels. For example, to increase the size of all the labels by 50%, specify lsize(1.5). The default is lsize(1).
llength(#) specifies the maximum number of characters of the labels to be displayed. The default is llength(12).
Examples
. use Us-Database.dta, clear . tmap choropleth murder, id(id) map(Us-Coordinates.dta) . tmap cho murder if conterminous, id(id) map(Us-Coordinates.dta) . tmap cho murder if conterminous, id(id) map(Us-Coordinates.dta) palette(Blues) ocolor(white) title(`"`"Murders per 100,000 population"'"') subtitle("United States 1994") . tmap propsymbol murder if conterminous, x(x_coord) y(y_coord) map(Us48-Coordinates.dta) sshape(o) scolor(edkblue) fcolor(eltblue) title(`"`"Murders per 100,000 population"'"') subtitle("United States 1994") . tmap deviation murder if conterminous, x(x_coord) y(y_coord) map(Us48-Coordinates.dta) sshape(s) scolor(sienna) fcolor(eggshell) title(`"`"Murders per 100,000 population"'"') subtitle("United States 1994") . tmap label label if conterminous, x(x) y(y) map(Us48-Coordinates.dta) lc(white) ls(0.9) fc(emerald)
. use MilanoPolice-Database.dta, clear . tmap dot, x(x) y(y) map(MilanoOutline-Coordinates.dta) by(type) marker(both) sshape(s d) title("Location of police stations") subtitle("Milano 2004") legtitle("Police force", size(*0.7)) legbox(lc(black))
Author
Maurizio Pisati Department of Sociology and Social Research University of Milano Bicocca - Italy maurizio.pisati@unimib.it
Aknowledgments
The color schemes used in tmap choropleth were designed by Dr. Cynthia A. Brewer, Department of Geography, The Pennsylvania State University, University Park, Pennsylvania, USA. The color schemes are used with Dr. Brewer's permission and are from the ColorBrewer map design tool available at http://www.ColorBrewer.org. I wish to thank an anonymous reviewer, Nick Cox and Vince Wiggins for their valuable suggestions and for helping improve the tmap package. Any remaining errors are mine.