Title
spmap -- Visualization of spatial data
spmap [attribute] [if] [in] using basemap [, basemap_options polygon(polygon_suboptions) line(line_suboptions) point(point_suboptions) diagram(diagram_suboptions) arrow(arrow_suboptions) label(label_suboptions) scalebar(scalebar_suboptions) graph_options]
basemap_options Description ------------------------------------------------------------------------- Main * id(idvar) base map polygon identifier
Cartogram area(areavar) draw base map polygons with area proportional to variable areavar split split multipart base map polygons map(backgroundmap) draw background map defined in Stata dataset backgroundmap mfcolor(colorstyle) fill color of the background map mocolor(colorstyle) outline color of the background map mosize(linewidthstyle) outline thickness of the background map mopattern(linepatternstyle) outline pattern of the background map
Choropleth map clmethod(method) attribute classification method, where method is one of the following: quantile, boxplot, eqint, stdev, kmeans, custom, unique clnumber(#) number of classes clbreaks(numlist) custom class breaks eirange(min max) attribute range for eqint classification method kmiter(#) number of iterations for kmeans classification method ndfcolor(colorstyle) fill color of empty (no data) base map polygons ndocolor(colorstyle) outline color of empty (no data) base map polygons ndsize(linewidthstyle) outline thickness of empty (no data) base map polygons ndlabel(string) legend label of empty (no data) base map polygons
Format fcolor(colorlist) fill color of base map polygons ocolor(colorlist) outline color of base map polygons osize(linewidthstyle_list) outline thickness of base map polygons
Legend legenda(on|off) display/hide base map legend legtitle(string) base map legend title leglabel(string) single-key base map legend label legorder(hilo|lohi) base map legend order legstyle(0|1|2|3) base map legend style legjunction(string) string connecting lower and upper class limits in base map legend labels when legstyle(2) legcount display number of base map polygons belonging to each class ------------------------------------------------------------------------- * Required option
polygon_suboptions Description ------------------------------------------------------------------------- Main * data(polygon) Stata dataset defining one or more supplementary polygons to be superimposed onto the base map select(command) keep/drop specified records of dataset polygon by(byvar_pl) group supplementary polygons by variable byvar_pl
Format fcolor(colorlist) fill color of supplementary polygons ocolor(colorlist) outline color of supplementary polygons osize(linewidthstyle_list) outline thickness of supplementary polygons
Legend legenda(on|off) display/hide supplementary-polygon legend legtitle(string) supplementary-polygon legend title leglabel(string) single-key supplementary-polygon legend label legshow(numlist) display only selected keys of supplementary-polygon legend legcount display number of supplementary polygons belonging to each group ------------------------------------------------------------------------- * Required when option polygon() is specified
line_suboptions Description ------------------------------------------------------------------------- Main * data(line) Stata dataset defining one or more polylines to be superimposed onto the base map select(command) keep/drop specified records of dataset line by(byvar_ln) group polylines by variable byvar_ln
Format color(colorlist) polyline color size(linewidthstyle_list) polyline thickness pattern(linepatternstyle_list) polyline pattern
Legend legenda(on|off) display/hide polyline legend legtitle(string) polyline legend title leglabel(string) single-key polyline legend label legshow(numlist) display only selected keys of polyline legend legcount display number of polylines belonging to each group ------------------------------------------------------------------------- * Required when option line() is specified
point_suboptions Description ------------------------------------------------------------------------- Main data(point) Stata dataset defining one or more points to be superimposed onto the base map select(command) keep/drop specified records of dataset point by(byvar_pn) group points by variable byvar_pn * xcoord(xvar_pn) variable containing the x-coordinate of points * ycoord(yvar_pn) variable containing the y-coordinate of points
Proportional size proportional(propvar_pn) draw point markers with size proportional to variable propvar_pn prange(min max) normalization range of variable propvar_pn psize(relative|absolute) reference system for drawing point markers
Deviation deviation(devvar_pn) draw point markers as deviations from given reference value of variable devvar_pn refval(mean|median|#) reference value of variable devvar_pn refweight(weightvar_pn) compute reference value of variable devvar_pn weighting observations by variable weightvar_pn dmax(#) absolute value of maximum deviation
Format size(markersizestyle_list) size of point markers shape(symbolstyle_list) shape of point markers fcolor(colorlist) fill color of point markers ocolor(colorlist) outline color of point markers osize(linewidthstyle_list) outline thickness of point markers
Legend legenda(on|off) display/hide point legend legtitle(string) point legend title leglabel(string) single-key point legend label legshow(numlist) display only selected keys of point legend legcount display number of points belonging to each group ------------------------------------------------------------------------- * Required when option point() is specified
diagram_suboptions Description ------------------------------------------------------------------------- Main data(diagram) Stata dataset defining one or more diagrams to be superimposed onto the base map at given reference points select(command) keep/drop specified records of dataset diagram by(byvar_dg) group diagrams by variable byvar_dg * xcoord(xvar_dg) variable containing the x-coordinate of diagram reference points * ycoord(yvar_dg) variable containing the y-coordinate of diagram reference points * variables(diagvar_dg) variable or variables to be represented by diagrams type(frect|pie) diagram type
Proportional size proportional(propvar_dg) draw diagrams with area proportional to variable propvar_dg prange(min max) reference range of variable propvar_dg
Framed-rectangle chart range(min max) reference range of variable diagvar_dg refval(mean|median|#) reference value of variable diagvar_dg refweight(weightvar_dg) compute the reference value of variable diagvar_dg weighting observations by variable weightvar_dg refcolor(colorstyle) color of the line representing the reference value of variable diagvar_dg refsize(linewidthstyle) thickness of the line representing the reference value of variable diagvar_dg
Format size(#) diagram size fcolor(colorlist) fill color of the diagrams ocolor(colorlist) outline color of the diagrams osize(linewidthstyle_list) outline thickness of the diagrams
Legend legenda(on|off) display/hide diagram legend legtitle(string) diagram legend title legshow(numlist) display only selected keys of diagram legend legcount display number of diagrams belonging to each group ------------------------------------------------------------------------- * Required when option diagram() is specified
arrow_suboptions Description ------------------------------------------------------------------------- Main * data(arrow) Stata dataset defining one or more arrows to be superimposed onto the base map select(command) keep/drop specified records of dataset arrow by(byvar_ar) group arrows by variable byvar_ar
Format direction(directionstyle_list) arrow direction, where directionstyle is one of the following: 1 (monodirectional arrow), 2 (bidirectional arrow) hsize(markersizestyle_list) arrowhead size hangle(anglestyle_list) arrowhead angle hbarbsize(markersizestyle_list) size of filled portion of arrowhead hfcolor(colorlist) arrowhead fill color hocolor(colorlist) arrowhead outline color hosize(linewidthstyle_list) arrowhead outline thickness lcolor(colorlist) arrow shaft line color lsize(linewidthstyle_list) arrow shaft line thickness lpattern(linepatternstyle_list) arrow shaft line pattern
Legend legenda(on|off) display/hide arrow legend legtitle(string) arrow legend title leglabel(string) single-key arrow legend label legshow(numlist) display only selected keys of arrow legend legcount display number of arrows belonging to each group ------------------------------------------------------------------------- * Required when option arrow() is specified
label_suboptions Description ------------------------------------------------------------------------- Main data(label) Stata dataset defining one or more labels to be superimposed onto the base map at given reference points select(command) keep/drop specified records of dataset label by(byvar_lb) group labels by variable byvar_lb * xcoord(xvar_lb) variable containing the x-coordinate of label reference points * ycoord(yvar_lb) variable containing the y-coordinate of label reference points * label(labvar_lb) variable containing the labels
Format length(lengthstyle_list) maximum number of label characters, where lengthstyle is any integer>0 size(textsizestyle_list) label size color(colorlist) label color position(clockpos_list) position of labels relative to their reference point gap(relativesize_list) gap between labels and their reference point angle(anglestyle_list) label angle ------------------------------------------------------------------------- * Required when option label() is specified
scalebar_suboptions Description ------------------------------------------------------------------------- Main * units(#) scale bar extent scale(#) ratio of scale bar units to map units xpos(#) scale bar horizontal position relative to plot region center ypos(#) scale bar vertical position relative to plot region center
Format size(#) scale bar height multiplier fcolor(colorstyle) fill color of scale bar ocolor(colorstyle) outline color of scale bar osize(linewidthstyle) outline thickness of scale bar label(string) scale bar label tcolor(colorstyle) color of scale bar text tsize(textsizestyle) size of scale bar text ------------------------------------------------------------------------- * Required when option scalebar() is specified
graph_options Description ------------------------------------------------------------------------- Main polyfirst draw supplementary polygons before the base map gsize(#) length of shortest side of available area (in inches) freestyle ignore built-in graph formatting presets and restrictions twoway_options any options documented in [G] twoway_options, except for aspect_option, scheme_option, by_option, and advanced_options -------------------------------------------------------------------------
spmap is aimed at visualizing several kinds of spatial data, and is particularly suited for drawing thematic maps and displaying the results of spatial data analyses.
spmap functioning rests on three basic principles:
o First, a base map representing a given study region R made up of N polygons is drawn.
o Second, at the user's choice, one or more types of additional spatial objects may be superimposed onto the base map. In the current version of spmap, six different types of spatial objects can be superimposed onto the base map: polygons (via option polygon()), polylines (via option line()), points (via option point()), diagrams (via option diagram()), arrows (via option arrow()), and labels (via option label()).
o Third, at the user's choice, one or more additional map elements may be added, such as a scale bar (via option scalebar()), a title, a subtitle, a note, and a caption (via title_options).
Proper specification of spmap options and suboptions, combined with the availability of properly formatted spatial data, allows the user to draw several kinds of maps, including choropleth maps, proportional symbol maps, pin maps, pie chart maps, and noncontiguous area cartograms.
While providing sensible defaults for most options and supoptions, spmap gives the user full control over the formatting of almost every map element, thus allowing the production of highly customized maps.
spmap requires that the spatial data to be visualized be arranged into properly formatted Stata datasets. Such datasets can be classified into nine categories: master, basemap, backgroundmap, polygon, line, point, diagram, arrow, label.
The master dataset is the dataset that resides in memory when spmap is invoked. At the minimum, it must contain variable idvar, a numeric variable that uniquely identifies the polygon or polygons making up the base map. If a choropleth map is to be drawn, then the master dataset should contain also variable attribute, a numeric variable expressing the values of the feature to be represented. Additionally, if a noncontiguous area cartogram is to be drawn - i.e., if the polygons making up the base map are to be drawn with area proportional to the values of a given numeric variable areavar - then the master dataset should contain also variable areavar.
A basemap dataset is a Stata dataset that contains the definition of the polygon or polygons making up the base map. A basemap dataset is required to have the following structure:
_ID _X _Y _EMBEDDED ------------------------------------- 1 . . 0 1 10 30 0 1 10 50 0 1 30 50 0 1 30 30 0 1 10 30 0 2 . . 0 2 10 10 0 2 10 30 0 2 18 30 0 2 18 10 0 2 10 10 0 2 . . 0 2 22 10 0 2 22 30 0 2 30 30 0 2 30 10 0 2 22 10 0 3 . . 1 3 15 35 1 3 15 45 1 3 25 45 1 3 25 35 1 3 15 35 1 -------------------------------------
_ID is required and is a numeric variable that uniquely identifies the polygons making up the base map. _X is required and is a numeric variable that contains the x-coordinate of the nodes of the base map polygons. _Y is required and is a numeric variable that contains the y-coordinate of the nodes of the base map polygons. Finally, _EMBEDDED is optional and is an indicator variable taking value 1 if the corresponding polygon is completely enclosed in another polygon, and value 0 otherwise. The following should be noticed:
o Both simple and multipart polygons are allowed. In the example above, polygons 1 and 3 are simple (i.e., they consist of a single area), while polygon 2 is multipart (i.e., it consists of two distinct areas).
o The first record of each simple polygon or of each part of a multipart polygon must contain missing x- and y-coordinates.
o The non-missing coordinates of each simple polygon or of each part of a multipart polygon must be ordered so as to correspond to consecutive nodes. o Each simple polygon or each part of a multipart polygon must be "closed", i.e., the last pair of non-missing coordinates must be equal to the first pair. o A basemap dataset is always required to be sorted by variable _ID.
A backgroundmap dataset is a Stata dataset that contains the definition of the polygon or polygons making up the background map - a map that can be optionally drawn as background of a noncontiguous area cartogram. A backgroundmap dataset has exactly the same structure as a basemap dataset, except for variable _EMBEDDED that is never used.
A polygon dataset is a Stata dataset that contains the definition of one or more supplementary polygons to be superimposed onto the base map. A polygon dataset is required to have the following structure:
_ID _X _Y byvar_pl ------------------------------------- 1 . . 1 1 20 40 1 1 20 42 1 1 25 42 1 1 25 40 1 1 20 40 1 2 . . 1 2 11 20 1 2 11 25 1 2 13 25 1 2 13 20 1 2 11 20 1 3 . . 2 3 25 25 2 3 25 35 2 3 30 35 2 3 30 25 2 3 25 25 2 -------------------------------------
Variables _ID, _X, and _Y are defined exactly in the same way as in a basemap dataset, with the sole exception that only simple polygons are allowed. In turn, byvar_pl is a placeholder denoting an optional variable that can be specified to distinguish different kinds of supplementary polygons.
A line dataset is a Stata dataset that contains the definition of one or more polylines to be superimposed onto the base map. A line dataset is required to have the following structure:
_ID _X _Y byvar_ln ------------------------------------- 1 . . 1 1 11 30 1 1 12 33 1 1 15 33 1 1 16 35 1 1 18 40 1 1 25 38 1 1 25 42 1 2 . . 2 2 12 20 2 2 18 15 2 3 . . 2 3 27 28 2 3 27 25 2 3 28 27 2 3 29 25 2 -------------------------------------
_ID is required and is a numeric variable that uniquely identifies the polylines. _X is required and is a numeric variable that contains the x-coordinate of the nodes of the polylines. _Y is required and is a numeric variable that contains the y-coordinate of the nodes of the polylines. Finally, byvar_ln is a placeholder denoting an optional variable that can be specified to distinguish different kinds of polylines. The following should be noticed:
o The first record of each polyline must contain missing x- and y-coordinates.
o The non-missing coordinates of each polyline must be ordered so as to correspond to consecutive nodes.
A point dataset is a Stata dataset that contains the definition of one or more points to be superimposed onto the base map. A point dataset is required to have the following structure:
xvar_pn yvar_pn byvar_pn propvar_pn devvar_pn weightvar_pn ----------------------------------------------------------------- 11 30 1 100 30 1000 20 34 1 110 25 1500 25 40 1 90 40 1230 25 45 2 200 10 950 15 20 2 50 70 600 -----------------------------------------------------------------
xvar_pn is a placeholder denoting a required numeric variable that contains the x-coordinate of the points. yvar_pn is a placeholder denoting a required numeric variable that contains the y-coordinate of the points. byvar_pn is a placeholder denoting an optional variable that can be specified to distinguish different kinds of points. propvar_pn is a placeholder denoting an optional variable that, when specified, requests that the point markers be drawn with size proportional to propvar_pn. devvar_pn is a placeholder denoting an optional variable that, when specified, requests that the point markers be drawn as deviations from a given reference value of devvar_pn. Finally, weightvar_pn is a placeholder denoting an optional variable that, when specified, requests that the reference value of devvar_pn be computed weighting observations by variable weightvar_pn. It is important to note that the required and optional variables making up a point dataset can either reside in an external dataset or be part of the master dataset.
A diagram dataset is a Stata dataset that contains the definition of one or more diagrams to be superimposed onto the base map at given reference points. A diagram dataset is required to have the following structure:
xvar_dg yvar_dg byvar_dg diagvar_dg propvar_dg weightvar_dg ------------------------------------------------------------------ 15 30 1 ... 30 1000 18 40 1 ... 25 1500 20 45 1 ... 40 1230 25 45 2 ... 10 950 15 20 2 ... 70 600 ------------------------------------------------------------------
xvar_dg is a placeholder denoting a required numeric variable that contains the x-coordinate of the diagram reference points. yvar_dg is a placeholder denoting a required numeric variable that contains the y-coordinate of the diagram reference points. byvar_dg is a placeholder denoting an optional variable that can be specified to distinguish different groups of diagrams. diagvar_dg is a placeholder denoting one or more variables to be represented by the diagrams. propvar_dg is a placeholder denoting an optional variable that, when specified, requests that the diagrams be drawn with area proportional to propvar_dg. Finally, weightvar_dg is a placeholder denoting an optional variable that, when specified, requests that the reference value of the diagrams be computed weighting observations by variable weightvar_dg (this applies only to framed-rectangle charts). It is important to note that the required and optional variables making up a diagram dataset can either reside in an external dataset or be part of the master dataset.
An arrow dataset is a Stata dataset that contains the definition of one or more arrows to be superimposed onto the base map. An arrow dataset is required to have the following structure:
_ID _X1 _Y1 _X2 _Y2 byvar_ar --------------------------------------------------------- 1 11 30 18 30 1 2 15 40 15 45 1 3 15 40 25 40 1 4 20 35 28 45 2 5 17 20 20 11 2 ---------------------------------------------------------
_ID is required and is a numeric variable that uniquely identifies the arrows. _X1 is required and is a numeric variable that contains the x-coordinate of the starting point of the arrows. _Y1 is required and is a numeric variable that contains the y-coordinate of the starting point of the arrows. _X2 is required and is a numeric variable that contains the x-coordinate of the ending point of the arrows. _Y2 is required and is a numeric variable that contains the y-coordinate of the ending point of the arrows. Finally, byvar_ar is a placeholder denoting an optional variable that can be specified to distinguish different kinds of arrows.
A label dataset is a Stata dataset that contains the definition of one or more labels to be superimposed onto the base map at given reference points. A label dataset is required to have the following structure:
xvar_lb yvar_lb byvar_lb labvar_lb --------------------------------------- 11 33 1 Abcde 20 37 1 Fgh 25 43 1 IJKL 25 48 2 Mnopqr 15 22 2 stu ---------------------------------------
xvar_lb is a placeholder denoting a required numeric variable that contains the x-coordinate of the label reference points. yvar_lb is a placeholder denoting a required numeric variable that contains the y-coordinate of the label reference points. byvar_lb is a placeholder denoting an optional variable that can be specified to distinguish different kinds of labels. Finally, labvar_lb is a placeholder denoting the variable that contains the labels. It is important to note that the required and optional variables making up a label dataset can either reside in an external dataset or be part of the master dataset.
Some spmap options and suboptions request the user to specify a list of one or more colors. When the list includes only one color, the user is required to specify a standard colorstyle. On the other hand, when the list includes two or more colors, the user can either specify a standard colorstyle list, or specify the name of a predefined color scheme.
The following table lists the predefined color schemes available in the current version of spmap, indicating the name of each scheme, the maximum number of different colors it allows, its type, and its source.
NAME MAXCOL TYPE SOURCE ------------------------------------------------ Blues 9 Sequential Brewer Blues2 99 Sequential Custom BuGn 9 Sequential Brewer BuPu 9 Sequential Brewer GnBu 9 Sequential Brewer Greens 9 Sequential Brewer Greens2 99 Sequential Custom Greys 9 Sequential Brewer Greys2 99 Sequential Brewer Heat 16 Sequential Custom OrRd 9 Sequential Brewer Oranges 9 Sequential Brewer PuBu 9 Sequential Brewer PuBuGn 9 Sequential Brewer PuRd 9 Sequential Brewer Purples 9 Sequential Brewer Rainbow 99 Sequential Custom RdPu 9 Sequential Brewer Reds 9 Sequential Brewer Reds2 99 Sequential Custom Terrain 16 Sequential Custom Topological 16 Sequential Custom YlGn 9 Sequential Brewer YlGnBu 9 Sequential Brewer YlOrBr 9 Sequential Brewer YlOrRd 9 Sequential Brewer BrBG 11 Diverging Brewer BuRd 11 Diverging Custom BuYlRd 11 Diverging Custom PRGn 11 Diverging Brewer PiYG 11 Diverging Brewer PuOr 11 Diverging Brewer RdBu 11 Diverging Brewer RdGy 11 Diverging Brewer RdYlBu 11 Diverging Brewer RdYlGn 11 Diverging Brewer Spectral 11 Diverging Brewer Accent 8 Qualitative Brewer Dark2 8 Qualitative Brewer Paired 12 Qualitative Brewer Pastel1 9 Qualitative Brewer Pastel2 8 Qualitative Brewer Set1 9 Qualitative Brewer Set2 8 Qualitative Brewer Set3 12 Qualitative Brewer ------------------------------------------------
Following Brewer (1999), sequential schemes are typically used to represent ordered data, so that higher data values are represented by darker colors; in turn, diverging schemes are used when there is a meaningful midpoint in the data, to emphasize progressive divergence from this midpoint in the two opposite directions; finally, qualitative schemes are generally used to represent unordered, categorical data.
The color schemes whose source is indicated as "Brewer" were designed by Dr. Cynthia A. Brewer, Department of Geography, The Pennsylvania State University, University Park, Pennsylvania, USA (Brewer et al. 2003). These color schemes are used with Dr. Brewers permission and are taken from the ColorBrewer map design tool available at ColorBrewer.org.
A choropleth map can be defined as a map in which each subarea (e.g., each census tract) of a given study region (e.g., a city) is colored or shaded with an intensity proportional to the value taken on by a given quantitative variable in that subarea (Slocum et al. 2005). Since choropleth maps are one of the most popular means for representing the spatial distribution of quantitative variables, it is worth noting the way spmap can be used to draw this kind of map.
In spmap, a choropleth map is a base map whose constituent polygons are colored according to the values taken on by attribute, a numeric variable that must be contained in the master dataset and specified immediately after the main command (see syntax diagram above). To draw the desired choropleth map, spmap first groups the values taken on by variable attribute into k classes defined by a given set of class breaks, and then assigns a different color to each class. The current version of spmap offers six methods for determining class breaks:
o Quantiles: class breaks correspond to quantiles of the distribution of variable attribute, so that each class includes approximately the same number of polygons.
o Boxplot: the distribution of variable attribute is divided into 6 classes defined as follows: [min, p25 - 1.5*iqr], (p25 - 1.5*iqr, p25], (p25, p50], (p50, p75], (p75, p75 + 1.5*iqr] and (p75 + 1.5*iqr, max], where iqr = interquartile range.
o Equal intervals: class breaks correspond to values that divide the distribution of variable attribute into k equal-width intervals.
o Standard deviates: the distribution of variable attribute is divided into k classes (2 <= k <= 9) whose width is defined as a fraction p of its standard deviation sd. Following the suggestions of Evans (1977), this proportion p varies with k as follows:
k p ------------ 2 inf 3 1.2 4 1.0 5 0.8 6 0.8 7 0.8 8 0.6 9 0.6 ------------
Class intervals are centered on the arithmetic mean m, which is a class midpoint if k is odd and a class boundary if k is even; the lowest and highest classes are open-ended (Evans 1977).
o k-means: the distribution of variable attribute is divided into k classes using k-means partition cluster analysis. The clustering procedure is applied several times to variable attribute, and the solution that maximizes the goodness-of-variance fit (Armstrong et al. 2003) is used.
o Custom: class breaks are specified by the user.
Alternatively, spmap allows the user to leave the values of variable attribute ungrouped. In this case, attribute is treated as a categorical variable and a different color is assigned to each of its values.
Options for drawing the base map
+------+ ----+ Main +-------------------------------------------------------------
id(idvar) specifies the name of a numeric variable that uniquely identifies the polygon or polygons making up the base map. idvar must be contained in the master dataset, and its values must correspond to the values taken on by variable _ID contained in the basemap dataset.
+-----------+ ----+ Cartogram +--------------------------------------------------------
area(areavar) requests that the polygons making up the base map be drawn with area proportional to the values taken on by numeric variable areavar, so that a noncontiguous area cartogram (Olson 1976) is obtained. areavar must be contained in the master dataset.
split requests that, before drawing a noncontiguous area cartogram, all multipart base map polygons be split into their constituent parts, each of which will then be treated as a distinct simple polygon.
map(backgroundmap) requests that, when drawing a noncontiguous area cartogram, the polygons making up the base map be superimposed onto a background map defined in Stata dataset backgroundmap.
mfcolor(colorstyle) specifies the fill color of the background map. The default is mfcolor(none).
mocolor(colorstyle) specifies the outline color of the background map. The default is mocolor(black).
mosize(linewidthstyle) specifies the outline thickness of the background map. The default is mosize(thin).
mopattern(linepatternstyle) specifies the outline pattern of the background map. The default is mopattern(solid).
+----------------+ ----+ Choropleth map +---------------------------------------------------
clmethod(method) specifies the method to be used for classifying variable attribute and representing its spatial distribution as a choropleth map.
clmethod(quantile) is the default and requests that the quantiles method be used.
clmethod(boxplot) requests that the boxplot method be used.
clmethod(eqint) requests that the equal intervals method be used.
clmethod(stdev) requests that the standard deviates method be used.
clmethod(kmeans) requests that the k-means method be used.
clmethod(custom) requests that class breaks be specified by the user with option clbreaks(numlist).
clmethod(unique) requests that each value of variable attribute be treated as a distinct class.
clnumber(#) specifies the number of classes k in which variable attribute is to be divided. When the quantiles, equal intervals, standard deviates, or k-means classification method is chosen, the default is clnumber(4). When the boxplot classification method is chosen, this option is inactive and k=6. When the custom classification method is chosen, this option is inactive and k equals the number of elements of numlist specified in option clbreaks(numlist) minus 1. When the unique classification method is chosen, this option is inactive and k equals the number of different values taken on by variable attribute.
clbreaks(numlist) is required when option clmethod(custom) is specified. It defines the custom class breaks to be used for classifying variable attribute. numlist should be specified so that the first element is the minimum value of variable attribute to be considered; the second to kth elements are the class breaks; and the last element is the maximum value of variable attribute to be considered. For example, suppose we want to group the values of variable attribute into the following four classes: [10,15], (15,20], (20,25] and (25,50]; for this we must specify clbreaks(10 15 20 25 50).
eirange(min max) 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(attribute), max(attribute)].
kmiter(#) specifies the number of times the clustering procedure is applied when option clmethod(kmeans) is specified. The default is kmiter(20).
ndfcolor(colorstyle) specifies the fill color of the empty (no data) polygons of the choropleth map. The default is ndfcolor(white).
ndocolor(colorstyle) specifies the outline color of the empty (no data) polygons of the choropleth map. The default is ndocolor(black).
ndsize(linewidthstyle) specifies the outline thickness of the empty (no data) polygons of the choropleth map. The default is ndsize(thin).
ndlabel(string) specifies the legend label to be attached to the empty (no data) polygons of the choropleth map. The default is ndlabel(No data).
+--------+ ----+ Format +-----------------------------------------------------------
fcolor(colorlist) specifies the list of fill colors of the base map polygons. When no choropleth map is drawn, the list should include only one element. On the other hand, when a choropleth map is drawn, the list should be either composed of k elements, or represented by the name of a predefined color scheme. The default fill color is none. When a choropleth map is drawn, the default argument is a color scheme that depends on the classification method specified in option clmethod(method):
Classification Default method color scheme ---------------------------------- quantile Greys boxplot BuRd eqint Greys stdev BuRd kmeans Greys custom Greys unique Paired ----------------------------------
ocolor(colorlist) specifies the list of outline colors of the base map polygons. When no choropleth map is drawn, the list should include only one element. On the other hand, when a choropleth map is drawn, the list should be either composed of k elements, or represented by the name of a predefined color scheme. The default outline color is black, the default specification is ocolor(black ...).
osize(linewidthstyle_list) specifies the list of outline thicknesses of the base map polygons. When no choropleth map is drawn, the list should include only one element. On the other hand, when a choropleth map is drawn, the list should be composed of k elements. The default outline thickness is thin, the default specification is osize(thin ...).
+--------+ ----+ Legend +-----------------------------------------------------------
legenda(on|off) specifies whether the base map legend should be displayed or hidden.
legenda(on) requests that the base map legend be displayed. This is the default when a choropleth map is drawn.
legenda(off) requests that the base map legend be hidden. This is the default when no choropleth map is drawn.
legtitle(string) specifies the title of the base map legend. When a choropleth map is drawn, option legtitle(varlab) requests that the label of variable attribute be used as the legend title.
leglabel(string) specifies the label to be attached to the single key of the base map legend when no choropleth map is drawn. This option is required when option legenda(on) is specified and no choropleth map is drawn.
legorder(hilo|lohi) specifies the display order of the keys of the base map legend when a choropleth map is drawn.
legorder(hilo) is the default and requests that the keys of the base map legend be displayed in descending order of variable attribute.
legorder(lohi) requests that the keys of the base map legend be displayed in ascending order of variable attribute. This is the default when option clmethod(unique) is specified.
legstyle(0|1|2|3) specifies the way the keys of the base map legend are labelled when a choropleth map is drawn.
legstyle(0) requests that the keys of the base map legend not be labelled.
legstyle(1) is the default and requests that the keys of the base map legend be labelled using the standard mathematical notation for value intervals (e.g.: (20,35]).
legstyle(2) requests that the keys of the base map legend be labelled using the notation ll&ul, where ll denotes the lower limit of the class interval, ul denotes the upper limit of the class interval, and & denotes a string that separates the two values. For example, if ll=20, ul=35, and &=" - ", then the resulting label will be "20 - 35".
legstyle(3) requests that only the first and last keys of the base map legend be labelled; the first key is labelled with the lower limit of the corresponding class interval, the last key is labelled with the upper limit of the corresponding class interval.
legjunction(string) specifies the string to be used as separator when option legstyle(2) is specified. The default is legjunction(" - ").
legcount requests that, when a choropleth map is drawn, the number of base map polygons belonging to each class of variable attribute be displayed in the legend.
+------+ ----+ Main +-------------------------------------------------------------
data(polygon) requests that one or more supplementary polygons defined in Stata dataset polygon be superimposed onto the base map.
select(command) requests that a given subset of records of dataset polygon be selected using Stata commands keep or drop.
by(byvar_pl) indicates that the supplementary polygons defined in dataset polygon belong to kpl different groups specified by variable byvar_pl.
+--------+ ----+ Format +-----------------------------------------------------------
fcolor(colorlist) specifies the list of fill colors of the supplementary polygons. When suboption by(byvar_pl) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pl) is specified, the list should be either composed of kpl elements, or represented by the name of a predefined color scheme. The default fill color is none, the default specification is fcolor(none ...).
ocolor(colorlist) specifies the list of outline colors of the supplementary polygons. When suboption by(byvar_pl) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pl) is specified, the list should be either composed of kpl elements, or represented by the name of a predefined color scheme. The default outline color is black, the default specification is ocolor(black ...).
osize(linewidthstyle_list) specifies the list of outline thicknesses of the supplementary polygons. When suboption by(byvar_pl) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pl) is specified, the list should be composed of kpl elements. The default outline thickness is thin, the default specification is osize(thin ...).
+--------+ ----+ Legend +-----------------------------------------------------------
legenda(on|off) specifies whether the supplementary-polygon legend should be displayed or hidden.
legenda(on) requests that the supplementary-polygon legend be displayed.
legenda(off) is the default and requests that the supplementary-polygon legend be hidden.
legtitle(string) specifies the title of the supplementary-polygon legend. When suboption by(byvar_pl) is specified, suboption legtitle(varlab) requests that the label of variable byvar_pl be used as the legend title.
leglabel(string) specifies the label to be attached to the single key of the supplementary-polygon legend when suboption by(byvar_pl) is not specified. This suboption is required when suboption legenda(on) is specified and suboption by(byvar_pl) is not specified.
legshow(numlist) requests that, when suboption by(byvar_pl) is specified, only the keys included in numlist be displayed in the supplementary-polygon legend.
legcount requests that the number of supplementary polygons be displayed in the legend.
+------+ ----+ Main +-------------------------------------------------------------
data(line) requests that one or more polylines defined in Stata dataset line be superimposed onto the base map.
select(command) requests that a given subset of records of dataset line be selected using Stata commands keep or drop.
by(byvar_ln) indicates that the polylines defined in dataset line belong to kln different groups specified by variable byvar_ln.
+--------+ ----+ Format +-----------------------------------------------------------
color(colorlist) specifies the list of polyline colors. When suboption by(byvar_ln) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ln) is specified, the list should be either composed of kln elements, or represented by the name of a predefined color scheme. The default color is black, the default specification is color(black ...).
size(linewidthstyle_list) specifies the list of polyline thicknesses. When suboption by(byvar_ln) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ln) is specified, the list should be composed of kln elements. The default thickness is thin, the default specification is size(thin ...).
pattern(linepatternstyle_list) specifies the list of polyline patterns. When suboption by(byvar_ln) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ln) is specified, the list should be composed of kln elements. The default pattern is solid, the default specification is pattern(solid ...).
+--------+ ----+ Legend +-----------------------------------------------------------
legenda(on|off) specifies whether the polyline legend should be displayed or hidden.
legenda(on) requests that the polyline legend be displayed.
legenda(off) is the default and requests that the polyline legend be hidden.
legtitle(string) specifies the title of the polyline legend. When suboption by(byvar_ln) is specified, suboption legtitle(varlab) requests that the label of variable byvar_ln be used as the legend title.
leglabel(string) specifies the label to be attached to the single key of the polyline legend when suboption by(byvar_ln) is not specified. This suboption is required when suboption legenda(on) is specified and suboption by(byvar_ln) is not specified.
legshow(numlist) requests that, when suboption by(byvar_ln) is specified, only the keys included in numlist be displayed in the polyline legend.
legcount requests that the number of polylines be displayed in the legend.
+------+ ----+ Main +-------------------------------------------------------------
data(point) requests that one or more points defined in Stata dataset point be superimposed onto the base map.
select(command) requests that a given subset of records of dataset point be selected using Stata commands keep or drop.
by(byvar_pn) indicates that the points defined in dataset point belong to kpn different groups specified by variable byvar_pn.
xcoord(xvar_pn) specifies the name of the variable containing the x-coordinate of each point.
ycoord(yvar_pn) specifies the name of the variable containing the y-coordinate of each point.
+-------------------+ ----+ Proportional size +------------------------------------------------
proportional(propvar_pn) requests that the point markers be drawn with size proportional to the values taken on by numeric variable propvar_pn.
prange(min max) requests that variable propvar_pn specified in suboption proportional(propvar_pn) be normalized based on range [min, max]. This suboption overrides the default normalization based on range [0, max(propvar_pn)].
psize(relative|absolute) specifies the reference system for drawing the point markers.
psize(relative) is the default and requests that the point markers be drawn using relative minimum and maximum reference values. This is the best choice when there is no need to compare the map at hand with other maps of the same kind.
psize(absolute) requests that the point markers be drawn using absolute minimum and maximum reference values. This is the best choice when the map at hand is to be compared with other maps of the same kind.
+-----------+ ----+ Deviation +--------------------------------------------------------
deviation(devvar_pn) requests that the point markers be drawn as deviations from a reference value of numeric variable devvar_pn specified in option refval(). When this suboption is specified, in the first place the values of variable devvar_pn are re-expressed as deviations from the chosen reference value. Then, points associated with positive deviations are represented by solid markers, whereas points associated with negative deviations are represented by hollow markers of the same shape; in both cases, markers are drawn with size proportional to the absolute value of the deviation. This suboption is incompatible with suboption proportional(propvar_pn).
refval(mean|median|#) specifies the reference value of variable devvar_pn for computing deviations.
refval(mean) is the default and requests that the arithmetic mean of variable devvar_pn be taken as the reference value.
refval(median) requests that the median of variable devvar_pn be taken as the reference value.
refval(#) requests that an arbitrary real value # be taken as the reference value.
refweight(weightvar_pn) requests that the reference value of variable devvar_pn be computed weighting observations by values of variable weightvar_pn.
dmax(#) requests that the point markers be drawn using value # as the maximum absolute deviation of reference.
+--------+ ----+ Format +-----------------------------------------------------------
size(markersizestyle_list) specifies the list of point marker sizes. When suboption by(byvar_pn) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pn) is specified, the list should be composed of kpn elements. The default size is *1, the default specification is size(*1 ...).
shape(symbolstyle_list) specifies the list of point marker shapes. When suboption by(byvar_pn) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pn) is specified, the list should be composed of kpn elements. The default shape is o, the default specification is shape(o ...). When suboption deviation(devvar_pn) is specified, this suboption accepts only solid symbolstyles written in short form: O D T S o d t s.
fcolor(colorlist) specifies the list of fill colors of the point markers. When suboption by(byvar_pn) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pn) is specified, the list should be either composed of kpn elements, or represented by the name of a predefined color scheme. The default fill color is black, the default specification is fcolor(black ...).
ocolor(colorlist) specifies the list of outline colors of the point markers. When suboption by(byvar_pn) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pn) is specified, the list should be either composed of kpn elements, or represented by the name of a predefined color scheme. The default outline color is none, the default specification is ocolor(none ...).
osize(linewidthstyle_list) specifies the list of outline thicknesses of the point markers. When suboption by(byvar_pn) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_pn) is specified, the list should be composed of kpl elements. The default outline thickness is thin, the default specification is osize(thin ...).
+--------+ ----+ Legend +-----------------------------------------------------------
legenda(on|off) specifies whether the point legend should be displayed or hidden.
legenda(on) requests that the point legend be displayed.
legenda(off) is the default and requests that the point legend be hidden.
legtitle(string) specifies the title of the point legend. When suboption by(byvar_pn) is specified, suboption legtitle(varlab) requests that the label of variable byvar_pn be used as the legend title.
leglabel(string) specifies the label to be attached to the single key of the point legend when suboption by(byvar_pn) is not specified. This suboption is required when suboption legenda(on) is specified and suboption by(byvar_pn) is not specified.
legshow(numlist) requests that, when suboption by(byvar_pn) is specified, only the keys included in numlist be displayed in the point legend.
legcount requests that the number of points be displayed in the legend.
+------+ ----+ Main +-------------------------------------------------------------
data(diagram) requests that one or more diagrams defined in Stata dataset diagram be superimposed onto the base map at given reference points.
select(command) requests that a given subset of records of dataset diagram be selected using Stata commands keep or drop.
by(byvar_dg) indicates that the diagrams defined in dataset diagram belong to kdg different groups specified by variable byvar_dg. This option is active only when just one variable is specified in suboption variables(diagvar_dg).
xcoord(xvar_dg) specifies the name of the variable containing the x-coordinate of each diagram reference point.
ycoord(yvar_dg) specifies the name of the variable containing the y-coordinate of each diagram reference point.
variables(diagvar_dg) specifies the list of variables to be represented by the diagrams.
type(frect|pie) specifies the type of diagram to be used.
type(frect) is the default when only one variable is specified in suboption variables(diagvar_dg) and requests that framed-rectangle charts (Cleveland and McGill 1984; Cleveland 1994) be used.
type(pie) is the default (and the only possibility) when two or more variables are specified in suboption variables(diagvar_dg) and requests that pie charts be used. When option type(pie) is specified, the variables specified in suboption variables(diagvar_dg) are rescaled so that they sum to 1 within each observation.
+-------------------+ ----+ Proportional size +------------------------------------------------
proportional(propvar_dg) requests that the diagrams be drawn with size proportional to the values taken on by numeric variable propvar_dg.
prange(min max) requests that variable propvar_dg specified in suboption proportional(propvar_dg) be normalized based on range [min, max]. This suboption overrides the default normalization based on range [0, max(propvar_dg)].
+------------------------+ ----+ Framed-rectangle chart +-------------------------------------------
range(min max) requests that variable diagvar_dg specified in suboption variables(diagvar_dg) be normalized based on range [min, max]. This suboption overrides the default normalization based on range [0, max(diagvar_dg)].
refval(mean|median|#) specifies the reference value of variable diagvar_dg for drawing the reference line.
refval(mean) is the default and requests that the arithmetic mean of variable diagvar_dg be taken as the reference value.
refval(median) requests that the median of variable diagvar_dg be taken as the reference value.
refval(#) requests that an arbitrary real value # be taken as the reference value.
refweight(weightvar_dg) requests that the reference value of variable diagvar_dg be computed weighting observations by values of variable weightvar_dg.
refcolor(colorstyle) specifies the color of the reference line. The default is refcolor(black).
refsize(linewidthstyle) specifies the thickness of the reference line. The default is refsize(medium).
+--------+ ----+ Format +-----------------------------------------------------------
size(#) specifies a multiplier that affects the size of the diagrams. For example, size(1.5) requests that the default size of all the diagrams be increased by 50%. The default is size(1).
fcolor(colorlist) specifies the list of fill colors of the diagrams. When just one variable is specified in suboption variables(diagvar_dg) and suboption by(byvar_dg) is not specified, the list should include only one element. When just one variable is specified in suboption variables(diagvar_dg) and suboption by(byvar_dg) is specified, the list should be either composed of kdg elements, or represented by the name of a predefined color scheme. Finally, when J>1 variables are specified in suboption variables(diagvar_dg), the list should be either composed of J elements, or represented by the name of a predefined color scheme. The default fill color is black, the default specification when J=1 is fcolor(black ...), and the default specification when J>1 is fcolor(red blue orange green lime navy sienna ltblue cranberry emerald eggshell magenta olive brown yellow dkgreen).
ocolor(colorlist) specifies the list of outline colors of the diagrams. When just one variable is specified in suboption variables(diagvar_dg) and suboption by(byvar_dg) is not specified, the list should include only one element. When just one variable is specified in suboption variables(diagvar_dg) and suboption by(byvar_dg) is specified, the list should be either composed of kdg elements, or represented by the name of a predefined color scheme. Finally, when J>1 variables are specified in suboption variables(diagvar_dg), the list should be either composed of J elements, or represented by the name of a predefined color scheme. The default fill color is black, the default specification is ocolor(black ...).
osize(linewidthstyle_list) specifies the list of outline thicknesses of the diagrams. When just one variable is specified in suboption variables(diagvar_dg) and suboption by(byvar_dg) is not specified, the list should include only one element. When just one variable is specified in suboption variables(diagvar_dg) and suboption by(byvar_dg) is specified, the list should be composed of kdg elements. Finally, when J>1 variables are specified in suboption variables(diagvar_dg), the list should be composed of J elements. The default outline thickness is thin, the default specification is osize(thin ...).
+--------+ ----+ Legend +-----------------------------------------------------------
legenda(on|off) specifies whether the diagram legend should be displayed or hidden.
legenda(on) requests that the diagram legend be displayed.
legenda(off) is the default and requests that the point diagram be hidden.
legtitle(string) specifies the title of the diagram legend. When just one variable is specified in suboption variables(diagvar_dg), suboption legtitle(varlab) requests that the label of variable diagvar_dg be used as the legend title.
legshow(numlist) requests that only the keys included in numlist be displayed in the diagram legend.
legcount requests that the number of diagrams be displayed in the legend.
+------+ ----+ Main +-------------------------------------------------------------
data(arrow) requests that one or more arrows defined in Stata dataset arrow be superimposed onto the base map.
select(command) requests that a given subset of records of dataset arrow be selected using Stata commands keep or drop.
by(byvar_ar) indicates that the arrows defined in dataset arrow belong to kar different groups specified by variable byvar_ar.
+--------+ ----+ Format +-----------------------------------------------------------
direction(directionstyle_list) specifies the list of arrow directions, where directionstyle is one of the following: 1 (monodirectional arrow), 2 (bidirectional arrow). When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be composed of kar elements. The default direction is 1, the default specification is direction(1 ...).
hsize(markersizestyle_list) specifies the list of arrowhead sizes. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be composed of kar elements. The default size is 1.5, the default specification is hsize(1.5 ...).
hangle(anglestyle_list) specifies the list of arrowhead angles. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be composed of kar elements. The default angle is 28.64, the default specification is hangle(28.64 ...).
hbarbsize(markersizestyle_list) specifies the list of sizes of the filled portion of arrowheads. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be composed of kar elements. The default size is 1.5, the default specification is hbarbsize(1.5 ...).
hfcolor(colorlist) specifies the list of arrowhead fill colors. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be either composed of kar elements, or represented by the name of a predefined color scheme. The default fill color is black, the default specification is hfcolor(black ...).
hocolor(colorlist) specifies the list of arrowhead outline colors. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be either composed of kar elements, or represented by the name of a predefined color scheme. The default outline color is black, the default specification is hocolor(black ...).
hosize(linewidthstyle_list) specifies the list of arrowhead outline thicknesses. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be composed of kar elements. The default outline thickness is thin, the default specification is hosize(thin ...).
lcolor(colorlist) specifies the list of arrow shaft line colors. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be either composed of kar elements, or represented by the name of a predefined color scheme. The default color is black, the default specification is lcolor(black ...).
lsize(linewidthstyle_list) specifies the list of arrow shaft line thicknesses. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be composed of kar elements. The default thickness is thin, the default specification is lsize(thin ...).
lpattern(linepatternstyle_list) specifies the list of arrow shaft line patterns. When suboption by(byvar_ar) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_ar) is specified, the list should be composed of kar elements. The default pattern is solid, the default specification is lpattern(solid ...).
+--------+ ----+ Legend +-----------------------------------------------------------
legenda(on|off) specifies whether the arrow legend should be displayed or hidden.
legenda(on) requests that the arrow legend be displayed.
legenda(off) is the default and requests that the arrow legend be hidden.
legtitle(string) specifies the title of the arrow legend. When suboption by(byvar_ar) is specified, suboption legtitle(varlab) requests that the label of variable byvar_ar be used as the legend title.
leglabel(string) specifies the label to be attached to the single key of the arrow legend when suboption by(byvar_ar) is not specified. This suboption is required when suboption legenda(on) is specified and suboption by(byvar_ar) is not specified.
legshow(numlist) requests that, when suboption by(byvar_ar) is specified, only the keys included in numlist be displayed in the arrow legend.
legcount requests that the number of arrows be displayed in the legend.
+------+ ----+ Main +-------------------------------------------------------------
data(label) requests that one or more labels defined in Stata dataset label be superimposed onto the base map at given reference points.
select(command) requests that a given subset of records of dataset label be selected using Stata commands keep or drop.
by(byvar_lb) indicates that the labels defined in dataset label belong to klb different groups specified by variable byvar_lb.
xcoord(xvar_lb) specifies the name of the variable containing the x-coordinate of each label reference point.
ycoord(yvar_lb) specifies the name of the variable containing the y-coordinate of each label reference point.
label(labvar_lb) specifies the name of the variable containing the labels.
+--------+ ----+ Format +-----------------------------------------------------------
length(lengthstyle_list) specifies the list of label lengths, where lengthstyle is any integer greater than 0 indicating the maximum number of characters of the labels. When suboption by(byvar_lb) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_lb) is specified, the list should be composed of klb elements. The default label lenght is 12, the default specification is length(12 ...).
size(textsizestyle_list) specifies the list of label sizes. When suboption by(byvar_lb) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_lb) is specified, the list should be composed of klb elements. The default label size is *1, the default specification is size(*1 ...).
color(colorlist) specifies the list of label colors. When suboption by(byvar_lb) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_lb) is specified, the list should be either composed of klb elements, or represented by the name of a predefined color scheme. The default label color is black, the default specification is color(black ...).
position(clockpos_list) specifies the list of label positions relative to their reference point. When suboption by(byvar_lb) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_lb) is specified, the list should be composed of klb elements. The default label position is 0, the default specification is position(0 ...).
gap(relativesize_list) specifies the list of gaps between labels and their reference point. When suboption by(byvar_lb) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_lb) is specified, the list should be composed of klb elements. The default label gap is *1, the default specification is gap(*1 ...).
angle(anglestyle_list) specifies the list of label angles. When suboption by(byvar_lb) is not specified, the list should include only one element. On the other hand, when suboption by(byvar_lb) is specified, the list should be composed of klb elements. The default label angle is horizontal, the default specification is angle(horizontal ...).
+------+ ----+ Main +-------------------------------------------------------------
units(#) specifies the length of the scale bar expressed in arbitrary units.
scale(#) specifies the ratio of scale bar units to map units. For example, suppose map coordinates are expressed in meters: if the scale bar length is to be expressed in meters too, then the ratio of scale bar units to map units will be 1; if, on the other hand, the scale bar length is to be expressed in kilometers, then the ratio of scale bar units to map units will be 1/1000. The default is scale(1).
xpos(#) specifies the distance of the scale bar from the center of the plot region on the horizontal axis, expressed as percentage of half the total width of the plot region. Positive values request that the distance be computed from the center to the right, whereas negative values request that the distance be computed from the center to the left. The default is xpos(0).
ypos(#) specifies the distance of the scale bar from the center of the plot region on the vertical axis, expressed as percentage of half the total height of the plot region. Positive values request that the distance be computed from the center to the top, whereas negative values request that the distance be computed from the center to the bottom. The default is ypos(-110).
+--------+ ----+ Format +-----------------------------------------------------------
size(#) specifies a multiplier that affects the height of the scale bar. For example, size(1.5) requests that the default height of the scale bar be increased by 50%. The default is size(1).
fcolor(colorstyle) specifies the fill color of the scale bar. The default is fcolor(black).
ocolor(colorstyle) specifies the outline color of the scale bar. The default is ocolor(black).
osize(linewidthstyle) specifies the outline thickness of the scale bar. The default is osize(vthin).
label(string) specifies the descriptive label of the scale bar. The default is label(Units).
tcolor(colorstyle) specifies the color of the scale bar text. The default is tcolor(black).
tsize(textsizestyle) specifies the size of the scale bar text. The default is tsize(*1).
+------+ ----+ Main +-------------------------------------------------------------
polyfirst requests that the supplementary polygons specified in option polygon() be drawn before the base map. By default, the base map is drawn before any other spatial object.
gsize(#) specifies the length (in inches) of the shortest side of the graph available area (the lenght of the longest side is set internally by spmap to minimize the amount of blank space around the map). The default ranges from 1 to 4, depending on the aspect ratio of the map. Alternatively, the height and width of the graph available area can be set using the standard xsize() and ysize() options.
freestyle requests that, when drawing the graph, all the formatting presets and restrictions built in spmap be ignored. By default, spmap presets the values of some graph options and restricts the use of some others, so as to produce a "nice" graph automatically. By specifying option freestyle, the user loses this feature but gains full control over most of the graph formatting options.
twoway_options include all the options documented in [G] twoway_options, except for aspect_option, scheme_option, by_option, and advanced_options. These include added_line_options, added_text_options, axis_options, title_options, legend_option, and region_options, as well as options nodraw, name(), and saving(). When option freestyle is specified, it is possible to control also aspect_option and scheme_option.
Examples 1: Choropleth maps
NOTE: All the examples illustrated in the present and in the following sections can be run by clicking on the blue hyperlinks only if Stata is called from the directory where the spmap ancillary datasets are located.
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(2) legend(region(lcolor(black))) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1m using "Italy-RegionsCoordinates.dta", id(id) /// ndfcolor(red) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(2) legend(region(lcolor(black))) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clmethod(eqint) clnumber(5) eirange(20 70) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(2) legend(region(lcolor(black))) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clnumber(20) fcolor(Reds2) ocolor(none ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(3) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clnumber(20) fcolor(Reds2) ocolor(none ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(3) legend(ring(1) position(3)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clnumber(20) fcolor(Reds2) ocolor(none ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(3) legend(ring(1) position(3)) /// plotregion(margin(vlarge)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clnumber(20) fcolor(Reds2) ocolor(none ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(3) legend(ring(1) position(3)) /// plotregion(icolor(stone)) graphregion(icolor(stone)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clnumber(20) fcolor(Greens2) ocolor(white ..) osize(medthin ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(3) legend(ring(1) position(3)) /// plotregion(icolor(stone)) graphregion(icolor(stone)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clnumber(20) fcolor(Greens2) ocolor(white ..) osize(thin ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(3) legend(ring(1) position(3)) /// plotregion(icolor(stone)) graphregion(icolor(stone)) /// polygon(data("Italy-Highlights.dta") ocolor(white) /// osize(medthick)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clnumber(20) fcolor(Greens2) ocolor(white ..) osize(medthin ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// legstyle(3) legend(ring(1) position(3)) /// plotregion(icolor(stone)) graphregion(icolor(stone)) /// scalebar(units(500) scale(1/1000) xpos(-100) label(Kilometers)) (click to run)
Examples 2: Proportional symbol maps
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// point(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) proportional(relig1) fcolor(red) size(*1.5)) (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// point(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) proportional(relig1) fcolor(red) size(*1.5) /// shape(s)) (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// point(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) proportional(relig1) fcolor(red) /// ocolor(white) size(*3)) /// label(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) label(relig1) color(white) size(*0.7)) (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// point(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) deviation(relig1) fcolor(red) dmax(30) /// legenda(on) leglabel(Deviation from the mean)) (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) fcolor(white) /// title("Catholics without reservations", size(*0.9) box bexpand /// span margin(medsmall) fcolor(sand)) subtitle(" ") /// point(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) proportional(relig1) prange(0 70) /// psize(absolute) fcolor(red) ocolor(white) size(*0.6)) /// plotregion(margin(medium) color(stone)) /// graphregion(fcolor(stone) lcolor(black)) /// name(g1, replace) nodraw . spmap using "Italy-OutlineCoordinates.dta", id(id) fcolor(white) /// title("Catholics with reservations", size(*0.9) box bexpand /// span margin(medsmall) fcolor(sand)) subtitle(" ") /// point(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) proportional(relig2) prange(0 70) /// psize(absolute) fcolor(green) ocolor(white) size(*0.6)) /// plotregion(margin(medium) color(stone)) /// graphregion(fcolor(stone) lcolor(black)) /// name(g2, replace) nodraw . spmap using "Italy-OutlineCoordinates.dta", id(id) fcolor(white) /// title("Other", size(*0.9) box bexpand /// span margin(medsmall) fcolor(sand)) subtitle(" ") /// point(data("Italy-RegionsData.dta") xcoord(xcoord) /// ycoord(ycoord) proportional(relig3) prange(0 70) /// psize(absolute) fcolor(blue) ocolor(white) size(*0.6)) /// plotregion(margin(medium) color(stone)) /// graphregion(fcolor(stone) lcolor(black)) /// name(g3, replace) nodraw . graph combine g1 g2 g3, rows(1) title("Religious orientation") /// subtitle("Italy, 1994-98" " ") xsize(5) ysize(2.6) /// plotregion(margin(medsmall) style(none)) /// graphregion(margin(zero) style(none)) /// scheme(s1mono) (click to run)
Examples 3: Other maps
. use "Italy-RegionsData.dta", clear . spmap using "Italy-RegionsCoordinates.dta", id(id) fcolor(stone) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) /// diagram(variable(relig1) range(0 100) refweight(pop98) /// xcoord(xcoord) ycoord(ycoord) fcolor(red)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap using "Italy-RegionsCoordinates.dta", id(id) fcolor(stone) /// diagram(variable(relig1 relig2 relig3) proportional(fortell) /// xcoord(xcoord) ycoord(ycoord) legenda(on)) /// legend(title("Religious orientation", size(*0.5) bexpand /// justification(left))) /// note(" " /// "NOTE: Chart size proportional to number of fortune tellers per million > population", /// size(*0.75)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clmethod(stdev) clnumber(5) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) area(pop98) /// note(" " /// "NOTE: Region size proportional to population", size(*0.75)) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta", id(id) /// clmethod(stdev) clnumber(5) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Italy, 1994-98" " ", size(*0.8)) area(pop98) /// map("Italy-OutlineCoordinates.dta") mfcolor(stone) /// note(" " /// "NOTE: Region size proportional to population", size(*0.75)) (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) fc(bluishgray) /// ocolor(none) /// title("Provincial capitals" " ", size(*0.9) color(white)) /// point(data("Italy-Capitals.dta") xcoord(xcoord) /// ycoord(ycoord) fcolor(emerald)) /// plotregion(margin(medium) icolor(dknavy) color(dknavy)) /// graphregion(icolor(dknavy) color(dknavy)) (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) fc(bluishgray) /// ocolor(none) /// title("Provincial capitals" " ", size(*0.9) color(white)) /// point(data("Italy-Capitals.dta") xcoord(xcoord) /// ycoord(ycoord) by(size) fcolor(orange red maroon) shape(s ..) /// legenda(on)) /// legend(title("Population 1998", size(*0.5) bexpand /// justification(left)) region(lcolor(black) fcolor(white)) /// position(2)) /// plotregion(margin(medium) icolor(dknavy) color(dknavy)) /// graphregion(icolor(dknavy) color(dknavy)) (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) fc(sand) /// title("Main lakes and rivers" " ", size(*0.9)) /// polygon(data("Italy-Lakes.dta") fcolor(blue) ocolor(blue)) /// line(data("Italy-Rivers.dta") color(blue) ) (click to run)
. use "Italy-RegionsData.dta", clear . spmap relig1 using "Italy-RegionsCoordinates.dta" if zone==1, /// id(id) fcolor(Blues2) ocolor(white ..) osize(medthin ..) /// title("Pct. Catholics without reservations", size(*0.8)) /// subtitle("Northern Italy, 1994-98" " ", size(*0.8)) /// polygon(data("Italy-OutlineCoordinates.dta") fcolor(gs12) /// ocolor(white) osize(medthin)) polyfirst (click to run)
. use "Italy-OutlineData.dta", clear . spmap using "Italy-OutlineCoordinates.dta", id(id) fc(sand) /// title("Main lakes and rivers" " ", size(*0.9)) /// polygon(data("Italy-Lakes.dta") fcolor(blue) ocolor(blue)) /// line(data("Italy-Rivers.dta") color(blue) ) /// freestyle aspect(1.4) xlab(400000 900000 1400000, grid) (click to run)
Acknowledgments
I wish to thank Nick Cox, Ian Evans, and Vince Wiggins for helping set up tmap (Pisati 2004), the predecessor of spmap. I also thank Kevin Crow, Bill Gould, Friedrich Huebler, and Scott Merryman for promoting tmap by making available to the Stata community several helpful resources related to the program. The development of spmap benefitted from suggestions by Joćo Pedro Azevedo, Kit Baum, Daniele Checchi, Kevin Crow, David Drukker, Friedrich Huebler, Laszlo Kardos, Ulrich Kohler, Mattia Landoni, Scott Merryman, Derek Wagner, the participants in the 1st Italian Stata Users Group Meeting, and the participants in the 3rd German Stata Users Group Meeting: many thanks to all of them.
Author
Maurizio Pisati Department of Sociology and Social Research University of Milano Bicocca - Italy maurizio.pisati@unimib.it
References
Armstrong, M.P., Xiao, N. and D.A. Bennett. 2003. Using genetic algorithms to create multicriteria class intervals for choropleth maps. Annals of the Association of American Geographers 93: 595-623.
Brewer, C.A. 1999. Color use guidelines for data representation. Proceedings of the Section on Statistical Graphics, American Statistical Association. Alexandria VA, 55-60.
Brewer, C.A., Hatchard, G.W. and M.A. Harrower. 2003. ColorBrewer in print: A catalog of color schemes for maps. Cartography and Geographic Information Science 52: 5-32.
Cleveland, W.S. 1994. The Elements of Graphing Data. Summit: Hobart Press.
Cleveland, W.S. and R. McGill. 1984. Graphical perception: Theory, experimentation, and application to the development of graphical methods. Journal of the American Statistical Association 79: 531-554.
Evans, I.S. 1977. The selection of class intervals. Transactions of the Institute of British Geographers 2: 98-124.
Olson, J.M. 1976. Noncontiguous area cartograms. The Professional Geographer 28: 371-380.
Pisati, M. 2004. Simple thematic mapping. The Stata Journal 4: 361-378.
Slocum, T.A., McMaster, R.B., Kessler, F.C and H.H. Howard. 2005. Thematic Cartography and Geographic Visualization. 2nd ed. Upper Saddle River: Pearson Prentice Hall.
Also see
Online: shp2dta (if installed), mif2dta (if installed)