{smcl}
{* 23jan2004}{...}
{hline}
help for {hi:tmap}{right:(SJ4-4: gr0008)}
{hline}

{title:Simple thematic mapping}

{p 8 14 2} {cmd:tmap} {cmdab:cho:ropleth} {it:quantvar}
[{cmd:if} {it:exp}] [{cmd:in} {it:range}] {cmd:,}
{cmdab:i:d}{cmd:(}{it:varname}{cmd:)}
{cmdab:m:ap}{cmd:(}{it:filename}{cmd:)}
[
{cmdab:clm:ethod}{cmd:(quantile} | {cmd:eqint} | {cmd:stdev} | {cmd:custom} | {cmd:unique)}
{cmdab:cln:umber}{cmd:(}{it:#}{cmd:)}
{cmdab:clb:reaks}{cmd:(}{it:numlist}{cmd:)}
{cmdab:eir:ange}{cmd:(}{it:numlist}{cmd:)}
{cmdab:p:alette(}{it:colorscheme}{cmd:)}
{cmdab:c:olors}{cmd:(}{it:colorstyle_list}{cmd:)}
{cmdab:oc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:os:ize}{cmd:(}{it:linewidthtyle}{cmd:)}
{cmdab:legp:os}{cmd:(}{it:#}{cmd:)}
{cmdab:legt:itle}{cmd:(}{it:string}{cmd:)}
{cmdab:legf:ormat}{cmd:(}{it:format}{cmd:)}
{cmdab:legb:ox}
{cmdab:noleg:end}
]

{p 8 14} {cmd:tmap} {cmdab:pro:psymbol} {it:quantvar}
[{cmd:if} {it:exp}] [{cmd:in} {it:range}] {cmd:,}
{cmdab:x:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:y:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:m:ap}{cmd:(}{it:filename}{cmd:)}
[
{cmdab:sc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:ssh:ape}{cmd:(}{it:symbolstyle}{cmd:)}
{cmdab:ssi:ze}{cmd:(}{it:#}{cmd:)}
{cmdab:oc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:os:ize}{cmd:(}{it:linewidthstyle}{cmd:)}
{cmdab:fc:olor}{cmd:(}{it:colorstyle}{cmd:)}
]

{p 8 14} {cmd:tmap} {cmdab:dev:iation} {it:quantvar}
[{cmd:if} {it:exp}] [{cmd:in} {it:range}] {cmd:,}
{cmdab:x:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:y:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:m:ap}{cmd:(}{it:filename}{cmd:)}
[
{cmdab:c:enter}{cmd:(mean} | {cmd:median)}
{cmdab:sc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:ssh:ape}{cmd:(}{it:symbolstyle}{cmd:)}
{cmdab:ssi:ze}{cmd:(}{it:#}{cmd:)}
{cmdab:oc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:os:ize}{cmd:(}{it:linewidthstyle}{cmd:)}
{cmdab:fc:olor}{cmd:(}{it:colorstyle}{cmd:)}
]

{p 8 14} {cmd:tmap dot}
[{cmd:if} {it:exp}] [{cmd:in} {it:range}] {cmd:,}
{cmdab:x:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:y:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:m:ap}{cmd:(}{it:filename}{cmd:)}
[
{cmdab:by}{cmd:(}{it:varname}{cmd:)}
{cmdab:mar:ker}{cmd:(color} | {cmd:shape)}
{cmdab:sc:olor}{cmd:(}{it:colorstyle_list}{cmd:)}
{cmdab:ssh:ape}{cmd:(}{it:symbolstyle_list}{cmd:)}
{cmdab:ssi:ze}{cmd:(}{it:#}{cmd:)}
{cmdab:oc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:os:ize}{cmd:(}{it:linewidthstyle}{cmd:)}
{cmdab:fc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:legp:os}{cmd:(}{it:#}{cmd:)}
{cmdab:legt:itle}{cmd:(}{it:string}{cmd:)}
{cmdab:legb:ox}
{cmdab:noleg:end}
]

{p 8 14} {cmd:tmap} {cmdab:lab:el} {it:labvar}
[{cmd:if} {it:exp}] [{cmd:in} {it:range}] {cmd:,}
{cmdab:x:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:y:coord}{cmd:(}{it:varname}{cmd:)}
{cmdab:m:ap}{cmd:(}{it:filename}{cmd:)}
[
{cmdab:lc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:ls:ize}{cmd:(}{it:#}{cmd:)}
{cmdab:ll:ength}{cmd:(}{it:#}{cmd:)}
{cmdab:oc:olor}{cmd:(}{it:colorstyle}{cmd:)}
{cmdab:os:ize}{cmd:(}{it:linewidthstyle}{cmd:)}
{cmdab:fc:olor}{cmd:(}{it:colorstyle}{cmd:)}
]


{title:Description}

{p 4 4 2}{cmd:tmap choropleth} represents the spatial distribution of area data
by means of choropleth maps in which each of {it:n} subareas of the
geographical unit of interest, {it:R}, is colored (or shaded) according to a
discrete scale based on the value taken on by the variable of
interest, {it:quantvar}, in that subarea.

{p 4 4 2}{cmd:tmap 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, {it:quantvar}, in each of {it:n} subareas of the
geographical unit of interest, {it:R}, is represented by a symbol whose
size is proportional to the value itself.
 
{p 4 4 2}{cmd:tmap 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 {it:quantvar}
are re-expressed as deviations from the "center" of their distribution,
defined as the mean or the median of {it:quantvar}. The value taken on by the
transformed variable in each of {it:n} subareas of the geographical
unit of interest {it: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.

{p 4 4 2}{cmd:tmap dot} represents the spatial distribution of point data
by means of dot maps, i.e., maps where the {it:n} locations at which some
"events" of interest have occurred are indicated by symbols whose color or
shape can vary according to the type of "event".

{p 4 4 2}{cmd:tmap 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, {it:labvar}, at different locations. This program can be used, for
example, to plot subarea names or to represent the spatial distribution of a
given variable of interest in numeric form.


{title:Common options}

{p 4 8 2}{cmd:map(}{it:filename}{cmd:)} is required. It specifies the name of
the file containing the information needed to draw the base map. In 
{cmd:tmap choropleth}, {it:filename} must contain the coordinates of the
polygons representing the different subareas of the geographical unit of
interest {it:R}. In all the other cases, {it:filename} can contain either the
coordinates of the polygons representing the different subareas, or the
coordinates of the polygon(s) representing the whole geographical unit of
interest {it:R}.

{p 4 8 2}{cmd:ocolor(}{it:colorstyle}{cmd:)} specifies the outline color of the
polygons making up the base map (see {it:{help colorstyle}}). The default is
{cmd:ocolor(black)}.

{p 4 8 2}{cmd:osize(}{it:linewidthstyle}{cmd:)} specifies the outline thickness
of the polygons making up the base map (see {it:{help linewidthstyle}}). The
default is {cmd:osize(thin)}.

{p 4 8 2}{cmd:fcolor(}{it:colorstyle}{cmd:)} specifies the fill color of the
polygons making up the base map (see {it:{help colorstyle}}). The
default is {cmd:fcolor(white)}.


{title:Options for tmap choropleth}

{p 4 8 2}{cmd:id(}{it:varname}{cmd:)} is required. It specifies the name of
the numeric variable that uniquely identifies the different subareas of
the geographical unit of interest {it:R}. The values taken on by {it:varname}
must correspond to the values taken on by the identifier {cmd:_ID} contained
in the file specified with option {cmd:map(}{it:filename}{cmd:)}.

{p 4 8 2}{cmd:clmethod(quantile} | {cmd:eqint} | {cmd:stdev} | {cmd:custom} |
{cmd:unique)} specifies the method to be used for determining the class
breaks.

{p 8 8 2}{cmd:clmethod(quantile)} is the default and requests that the quantiles
method be used.

{p 8 8 2}{cmd:clmethod(eqint)} requests that the equal intervals
method be used.

{p 8 8 2}{cmd:clmethod(stdev)} requests that the standard deviates
method be used.

{p 8 8 2}{cmd:clmethod(custom)} requests that class breaks be specified by the
user with option {cmd:clbreaks(}{it:numlist}{cmd:)}.

{p 8 8 2}{cmd:clmethod(unique)} requests that the variable of interest
{it:quantvar} be treated as a categorical variable taking on a maximum of 9
different values.

{p 4 8 2}{cmd:clnumber(}{it:#}{cmd:)} specifies the number of classes {it:k}
in which the variable of interest {it:quantvar} should be divided. This option
accepts only numbers included between 2 and 9. The default is
{cmd:clnumber(4)}.

{p 4 8 2}{cmd:clbreaks(}{it:numlist}{cmd:)} is required if option
{cmd:clmethod(custom)} is specified. It specifies a list of numbers defined as
follows: the first element of the list is the minimum value of {it:quantvar}
to be considered; the second to {it:k}th elements of the list are the class
breaks; and the last element of the list is the maximum value of {it:quantvar}
to be considered.

{p 4 8 2}{cmd:eirange(}{it:numlist}{cmd:)} specifies the range of values
(minimum and maximum) to be considered in the calculation of class breaks when
option {cmd:clmethod(eqint)} is specified.  This option overrides the default
range, [min({it:quantvar}),max({it:quantvar})].

{p 4 8 2}{cmd:palette(}{it:colorscheme}{cmd:)} specifies the color scheme to
be used for representing the different classes in which {it:quantvar} has
been divided.  {it:colorscheme} is one of the following:

{p 12 12 2}{cmd:Blues} | {cmd:BrBG} | {cmd:Greens} | {cmd:Greys} |
{cmd:Paired} | {cmd:PuRd} | {cmd:Purples} | {cmd:RdBu} | {cmd:RdGy} |
{cmd:Reds} | {cmd:Set1} | {cmd:Set3} | {cmd:YlOrBr} | {cmd:Custom}

{p 8 8 2}
The default is {cmd:palette(Greys)} when {cmd:clmethod(quantile)} or
{cmd:clmethod(eqint)} is specified; {cmd:palette(RdBu)} when
{cmd:clmethod(stdev)} is specified; and {cmd:palette(Paired)} when
{cmd:clmethod(unique)} is specified.  If option {cmd:palette(Custom)} is
specified, option {cmd:colors(}{it:colorstyle_list}{cmd:)} must be specified
as well.  It specifies a custom list of colors to be used for representing the
different classes in which {it:quantvar} has been divided 
(see {it:{help colorstyle}}).  The number of elements of the list must equal
{it:k}, i.e., the desired number of classes.

{p 4 8 2}{cmd:legpos(}{it:#}{cmd:)} specifies the position of the map legend
(see {it:{help legend_option}}).  The default is {cmd:legpos(7)}.

{p 4 8 2}{cmd:legtitle(}{it:string}{cmd:)} specifies the title of the map
legend. By default, no title is used.

{p 4 8 2}{cmd:legformat(}{it:format}{cmd:)} specifies the format of the
numeric values appearing in the map legend. The default is
{cmd:legformat(%8.2f)}.

{p 4 8 2}{cmd:legbox} requests that a box be drawn around the map legend.

{p 4 8 2}{cmd:nolegend} requests that the map legend be suppressed.


{title:Options for tmap propsymbol}

{p 4 8 2}{cmd:xcoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:x}-coordinate of the centroid of each subarea
of the geographical unit of interest {it:R}.

{p 4 8 2}{cmd:ycoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:y}-coordinate of the centroid of each subarea
of the geographical unit of interest {it:R}.

{p 4 8 2}{cmd:scolor(}{it:colorstyle}{cmd:)} specifies the color of the
symbols (see {it:{help colorstyle}}). The default is {cmd:scolor(black)}.

{p 4 8 2}{cmd:sshape(}{it:symbolstyle}{cmd:)} specifies the shape of the
symbols (see {it:{help symbolstyle}}). The default is {cmd:sshape(Oh)}.

{p 4 8 2}{cmd:ssize(}{it:#}{cmd:)} specifies a multiplier that affects the
size of the symbols. The default is {cmd:ssize(1)}.


{title:Options for tmap deviation}

{p 4 8 2}{cmd:xcoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:x}-coordinate of the centroid of each subarea
of the geographical unit of interest {it:R}.

{p 4 8 2}{cmd:ycoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:y}-coordinate of the centroid of each subarea
of the geographical unit of interest {it:R}.

{p 4 8 2}{cmd:center(mean} | {cmd:median) } specifies the center of the
distribution of {it:quantvar} to be taken as the reference value.

{p 8 8 2}{cmd:center(mean)} is the default and requests that the reference value
be the arithmetic mean of the distribution of {it:quantvar}.

{p 8 8 2}{cmd:center(median)} requests that the reference value be the median
of the distribution of {it:quantvar}.

{p 4 8 2}{cmd:scolor(}{it:colorstyle}{cmd:)} specifies the color of the
symbols (see {it:{help colorstyle}}). The default is {cmd:scolor(black)}.

{p 4 8 2}{cmd:sshape(}{it:symbolstyle}{cmd:)} specifies the shape of the
symbols (see {it:{help symbolstyle}}). This option accepts only solid
symbolstyles, expressly: {cmd:O D T S o d t s}. The default is {cmd:sshape(O)}.

{p 4 8 2}{cmd:ssize(}{it:#}{cmd:)} specifies a multiplier that affects the
size of the symbols. The default is {cmd:ssize(1)}.


{title:Options for tmap dot}

{p 4 8 2}{cmd:xcoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:x}-coordinate of the locations at which the
events of interest have occurred.

{p 4 8 2}{cmd:ycoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:y}-coordinate of the locations at which the
"events" of interest have occurred.

{p 4 8 2}{cmd:by(}{it:varname}{cmd:)} specifies the name of a categorical
variable denoting the type of events that occurred at each location object of
analysis. Although the program does not impose any restriction, it is
advisable that {it:varname} take a maximum of 9 different values.

{p 4 8 2}{cmd:marker(color} | {cmd:shape)} when option
{cmd:by(}{it:varname}{cmd:)} is specified, it specifies whether the different
types of events should be indicated by symbols having the same shape but
different colors, or by symbols having the same color but different shapes.

{p 8 8 2}{cmd:marker(color)} is the default and requests that the different
types of events be indicated by symbols having the same shape but different
colors.

{p 8 8 2}{cmd:marker(shape)} is the default and requests that the different
types of events be indicated by symbols having the same color but different
shapes.

{p 4 8 2}{cmd:scolor(}{it:colorstyle_list}{cmd:)} specifies the colors of
the symbols. When option {cmd:by(}{it:varname}{cmd:)} is not specified or is
specified along with option {cmd:marker(shape)}, the default is
{cmd:scolor(black)}. When option {cmd:by(}{it:varname}{cmd:)} is specified
along with option {cmd:marker(color)}, the default is 
{cmd:scolor(black red blue green orange ltblue lime sienna yellow)}.

{p 4 8 2}{cmd:sshape(}{it:symbolstyle_list}{cmd:)} specifies the shapes of
the symbols. When option {cmd:by(}{it:varname}{cmd:)} is not specified or is
specified along with option {cmd:marker(color)}, the default is
{cmd:sshape(o)}. When option {cmd:by(}{it:varname}{cmd:)} is specified along
with option {cmd:marker(shape)}, the default is 
{cmd:sshape(o oh s sh t th d dh x)}.

{p 4 8 2}{cmd:ssize(}{it:#}{cmd:)} specifies a multiplier that affects the
size of the symbols. The default is {cmd:ssize(1)}.

{p 4 8 2}{cmd:legpos(}{it:#}{cmd:)} specifies the position of the map legend.
The default is {cmd:legpos(7)}.

{p 4 8 2}{cmd:legtitle(}{it:string}{cmd:)} specifies the title of the map
legend. By default, no title is used.

{p 4 8 2}{cmd:legbox} requests that a box be drawn around the map legend.

{p 4 8 2}{cmd:nolegend} requests that the map legend be suppressed.


{title:Options for tmap label}

{p 4 8 2}{cmd:xcoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:x}-coordinate of the locations at which the
labels of interest should be plotted.

{p 4 8 2}{cmd:ycoord(}{it:varname}{cmd:)} is required. It specifies the name of
the variable containing the {it:y}-coordinate of the locations at which the
labels of interest should be plotted.

{p 4 8 2}{cmd:lcolor(}{it:colorstyle}{cmd:)} specifies the color of the
labels. The default is {cmd:lcolor(black)}.

{p 4 8 2}{cmd:lsize(}{it:#}{cmd:)} specifies a multiplier that affects the size
of the labels. The default is {cmd:lsize(1)}.

{p 4 8 2}{cmd:llength(}{it:#}{cmd:)} specifies the maximum number of characters
of the labels to be displayed. The default is {cmd:llength(12)}.


{title:Examples}

{p 4 8 2}{cmd:. use "milano-areadata.dta"}{p_end}
{p 4 8 2}{cmd:. tmap choropleth foreign01, id(id) map("milano-areamap.dta")}{p_end}
{p 4 8 2}{cmd:. tmap cho foreign01, id(id) map("milano-areamap.dta") palette(Custom) colors(gs13 gs9 gs5 gs2) ocolor(white) osize(medium) legtitle("% foreign pop.") legformat("%4.1f")}{p_end}
{p 4 8 2}{cmd:. tmap propsymbol foreign01, x(x) y(y) map("milano-generalmap.dta")}{p_end}
{p 4 8 2}{cmd:. tmap deviation foreign01, x(x) y(y) map("milano-generalmap.dta")}{p_end}
{p 4 8 2}{cmd:. tmap label foreign01, x(x) y(y) map("milano-generalmap.dta")}{p_end}

{p 4 8 2}{cmd:. use "milano-pointdata.dta"}{p_end}
{p 4 8 2}{cmd:. tmap dot, x(x) y(y) map("milano-generalmap.dta") by(type) marker(shape)}


{title:Author}

{p 4 4 2} Maurizio Pisati {p_end}
{p 4 4 2} Department of Sociology and Social Research {p_end}
{p 4 4 2} University of Milano Bicocca - Italy {p_end}
{p 4 4 2} maurizio.pisati@unimib.it {p_end}


{title:Acknowledgments}

{p 4 4 2} The color schemes used in {cmd:tmap choropleth} were designed by 
{bind:Dr. Cynthia A. Brewer}, Department of Geography, The Pennsylvania State
University, University Park, Pennsylvania, USA. The color schemes are used
with {bind:Dr. Brewer's} permission and are from the ColorBrewer map design
tool available at {browse "http://www.ColorBrewer.org"}. I wish to thank an
anonymous reviewer and Nick Cox for their valuable suggestions and for helping
improve the {cmd:tmap} package. Any remaining errors are mine.  {p_end}