help geoplothttps://github.com/benjann/geoplot/

Title

geoplot -- Command to draw maps

Syntax

geoplot (layer) [(layer) ...]
[,
global_options
]

or

geoplot layer || [ layer || ...]
[,
global_options
]

where layer is

layertype [frame] [...] [,
zvar_options
other_options ]

and frame is the name of a frame containing data prepared by
geoframe. frame may be omitted if
there are no subsequent arguments (apart from if,
in, weight, or options); in this case, the
current (working) frame will be used. To use the current (working) frame
you can also type . (missing).

layertype

area shapes, potentially filled

line shapes, line only

point single-coordinate markers

scatter synonym for point

label single-coordinate labels

symbol single-coordinate symbols (circles,
hexagons, stars, etc.)

* pie pie charts

* bar stacked (or unstacked) bar charts

* areai area with immediate arguments

* linei line with immediate arguments

* pointi point with immediate arguments

* scatteri synonym for pointi

* labeli label with immediate arguments

* symboli symbol with immediate arguments

pcspike etc. paired-coordinate spikes, arrows, or markers

* pci etc. paired-coordinate plot with immediate arguments

* Unstarred zvar_options not supported.

zvar_options

Main
discrete treat
zvar as discrete instead of continuous

levels(spec) number of levels and
method to determine cuts

cuts(numlist) use levels defined by
specified cuts

colorvar([i.]zvar) alternative to
specifying zvar as argument

Styling
* color(palette) colors

* lwidth(list) line widths

* lpattern(list) line patterns

* fintensity(list) fill intensities

* msymbol(list) marker symbols

* msize(list) marker sizes

* msangle(list) marker angles

* mlwidth(list) marker outline widths

* mlabsize(list) marker label sizes

* mlabangle(list) marker label angles

* mlabcolor(palette) marker label colors

Legend keys
* label(spec) set labels of legend
keys and related settings

* gloptions(options) override options
for the symbols created by glegend()

* nolegend do not consider the layer for the default
legend

Missing
missing(options) styling of elements
for which zvar is missing

* These options are also effective if zvar is not
specified, possibly with different interpretation and syntax. See the
descriptions of the options below.

global_options

Main
background[(opts)] draw a
background frame behind the map

grid[(options)] draw grid lines on
top of the map (can be repeated)

tissot[(options)] draw Tissot's
indicatrices on top of the map

project[(spec)] apply
projection (coordinates in degrees assumed)

angle(angle) rotate map by angle

rotate(angle) synonym for angle()

Legends
legend[(options)] add
standard legend

glegend[(options)] add
geoplot legend (can be repeated)

slegend(spec) add
size legend (can be repeated)

clegend[(options)] add
contour plot legend (requires Stata 18)

sbar[(options)] add scale bar

compass[(options)] add
compass

Zoom / Inset
zoom(spec) zoom in on specific layers
(can be repeated)

inset(spec) create inset from additional map
(can be repeated)

Overall appearance
tight adjust graph size to dimension of map

margin(spec) specify (minimum) margin
around map

refdim(spec) select reference
dimension

aspectratio(spec) adjust aspect
ratio of map

axes turn display of Stata's coordinate system on

twoway_options twoway options, other than by()

Data
frame(spec) store ploted data in new frame

nograph do not generate a graph

Description

geoplot draws maps from shape files and other datasets prepared by
geoframe. The procedure is to first create one or several frames
containing the source data using geoframe and then apply
geoplot to plot the data from these frames.

Multiple layers of elements such as regions, borders, lakes, roads, labels,
etc., can be freely combined, and the look of the elements can be varied
depending on the values of variables.

Some of the functions used by geoplot and geoframe are provided
in Mata library lgeoplot.mlib. See lgeoplot_source for source and
minimal documentation of these functions.

geoplot requires colorpalette, colrspace, and
moremata. To install these packages type

. ssc install palettes
. ssc install colrspace
. ssc install moremata

Layer types

shapes, potentially filled

area frame [[i.]zvar] [if] [in] [weight]
[, options ]

where frame is the frame containing the shapes to be
plotted (see geoframe; frame can be a shape frame or an
attribute frame that is linked to a shape frame), zvar
is an optional variable to determine styling, and weight, specified as
[weight=exp] or
[iweight=exp], rescales the coordinates of
the shapes by the absolute (and normalized) values of exp. options
are as follows.

zvar_options determine the look of
the shapes (e.g. color) depending on the values of
zvar as described
below.

wmax[(#)] specifies a custom upper bound for
normalization of weights. This is only relevant if weight has
been specified. The default is to normalize by max(1,wmax), where
wmax is the observed maximum of the (absolute) weights (within
layer). Specify wmax(#) to normalize by #. Specify wmax
without argument to normalize by wmax even if wmax<1.

size(exp[, scale(#) dmax(#)])
resizes the shapes such that their sizes are proportional to exp
(typically, exp is a varname; the size of a shape is equal to the
area covered by the shape). Default normalization is such that the shape
with the highest density (within layer), defined as abs(exp) divided
by the area of the shape, will keep its original size. Negative values in
exp will be treated as positive; shapes for which exp is missing
will keep their original size.

Suboption scale() multiplies all sizes by # (after
normalization). Suboption dmax() specifies a custom maximum density
for normalization; use this option to make sizes comparable across layers.

select(exp) selects the shapes to be included in the
plot. select() is applied after determining the cuts for zvar
and after processing weights and size(). Specify if or
in if you want to select observations upfront.

ifshp(exp) specifies an additional if condition to be applied to
the shape frame. This is relevant if frame is an attribute frame is
linked to a shape frame. Observations in the shape frame that do not
satisfy the specified condition (i.e., observations for which exp evaluates
to zero), as well as units in the attribute frame for which the condition
leads to an empty selection in the shape frame, will be excluded. If frame
is a shape frame (i.e. not an attribute frame linked to a shape frame), ifshp()
is treated in the same way as the if qualifier.

ecolor(colorspec)
sets the fill color used for enclaves. colorspec is a (single) color
specification as described in
colorpalette. Default is
ecolor(white). The color of an enclave will only be visible if not
covered by a corresponding exclave.

area_options affect the look of areas as
described in twoway area. For example, use option lcolor() to
set the outline color. Color options support colorspec as described in
colorpalette.

lock causes the shapes to be unaffected by global
options project() and
angle(), apart from location. For example,
if lock is specified, angle() will rotate
only the positions of the shapes, but not their orientation.

box[(suboptions)] draws a bounding box around the
plotted shapes. suboptions are as follows.

padding(), rotate, hull, circle, n(), angle(),
and noadjust as described in help geoframe bbox.

refine adds extra points to the edges of the box. Specify this
suboption to avoid undesired artifacts when applying global option
project().

line plots the bounding box using plot type line. The
default is to plot the bounding box using plot type area. Note
that, by default, the bounding box does not have a fill color even if option
line is omitted. Specify color(colorspec) or
fcolor(colorspec) to set a
fill color.

area_options or line_options, depending on whether
option line has been specified, are regular graph options to affect
the look of the bounding box. Color options support colorspec as described in
colorpalette.

feature(string) specifies the type of feature represented in the
layer. The default is to use the setting returned by
geoframe get feature.

coordinates(X Y) specifies custom coordinate variables. The default
is to use the variables returned by
geoframe get coordinates.

plevel(PLEVEL) specifies a custom plot level variable. The default is
to use the variable returned by geoframe get plevel.

id(ID) specifies a custom ID variable. The default is
to use the variable returned by geoframe get id. An ID
variable is not strictly needed, but if available it will be taken into
account when categorizing zvar.

centroids(X Y) specifies custom centroid variables. The default is
to use the variables returned by
geoframe get centroids. If centroids are needed and
no centroid variables are found, the centroids are computed on the fly using
geoframe generate centroids. The centroids are
needed if weights, option size(), or option lock is specified.

area(AREA) specifies a custom shape size variable. The default is to
use the variable returned by
geoframe get area. If shape sizes are needed and no
shape size variable is found, the sizes are computed on the fly using
geoframe generate area. Shape sizes
are only needed if option size() is specified.

By default, the shapes do not have a fill color. Specify
zvar to color the shapes depending on the values
of zvar. Specify
fcolor(colorspec) to set a
single fill color for all shapes.

shapes, line only

line frame [[i.]zvar] [if] [in] [weight]
[,
options ]

where frame is the frame containing the shapes to be
plotted (see geoframe; frame can be a shape frame or an
attribute frame that is linked to a shape frame), zvar
is an optional variable to determine styling, and weight, specified as
[weight=exp] or
[iweight=exp], rescales the coordinates of
the shapes by the absolute (and normalized) values of exp. options are as follows.

zvar_options, wmax(), size(), select(),
ifshp(), lock, box(), feature(), coordinates(), id(),
centroids(), and area() are
options as described for layer type area.

line_options affect the look of lines as
described in twoway line. For example, use option lwidth() to
set the width of lines. Color options support colorspec as described in
colorpalette.

single-coordinate markers

point frame [[i.]zvar] [if] [in] [weight]
[,
options ]

where frame is the frame containing the points to be
plotted (see geoframe), zvar is an optional
variable to determine styling, and weight, specified as
[weight=exp] or
[iweight=exp], scales the size of the
markers by the absolute (and normalized) values of exp (also see
Weighted markers in twoway scatter). options
are as follows.

zvar_options, wmax(), select(),
ifshp(), lock, box(), coordinates(), id(),
and centroids() are
options as described for layer type area.

marker_options, marker_label_options,
connect_options, and jitter_options affect
the look of markers as described in twoway scatter. For example,
use option msymbol() to set the marker symbol. Color options
support colorspec as described in colorpalette.

shp causes points to be plotted at the coordinates from the
linked shape frame. By default, layer type point uses the coordinates
from frame even if frame is linked to a shape frame. Option shp has
no effect if frame is not linked to a shape frame.

scatter may be used as a synonym for point.

single-coordinate labels

label frame labelspec [[i.]zvar] [if] [in]
[,
options ]

where frame is the frame containing the coordinates of the labels to be
plotted (see geoframe), labelspec provides the labels,
and zvar is an optional
variable to determine styling.

The syntax of labelspec is as follows. To print labels from a variable, type

label frame labelvar [[i.]zvar]
[if] [in] [, options ]

where labelvar may be a numeric variable or a string variable. To print
custom labels, type

label frame ("text" ["text" ...])
[[i.]zvar] [if] [in] [, options ]

If zvar is omitted, the first "text" element
will be assigned to all selected observations. Othewise
the elements will be assigned one-by-one to the levels determined by
zvar (using the first element for missing, if there
are missing values; elements will be recycled if there are fewer elements than
levels). SMCL markup directives can be used in text; see
[G-4] text. Finally, to print labels
as defined by options label() and
missing(label()), type

label frame . [[i.]zvar] [if] [in] [, options ]

options are as follows.

zvar_options, select(), ifshp(),
lock, box(), coordinates(), id(),
and centroids() are
options as described for layer type area; option shp
is as described for layer type point.

size(textsizestyle),
color(colorspec),
angle(anglestyle),
tstyle(textstyle),
format(%fmt),
gap(size),
position(clockposstyle), and
vposition(varname)
are marker label options equivalent to the corresponding options
described in help marker_label_options. Color options
support colorspec as described in colorpalette.

If zvar is specified, options size(),
color(), and angle() are interpreted in the way as described
below for mlabsize(), mlabcolor(),
and mlabangle().

Layer type label is implemented as a wrapper for point.

single-coordinate symbols

symbol frame [[i.]zvar] [if] [in] [weight]
[,
options ]

where frame is the frame containing the positions of
the symbols (see geoframe), zvar is an optional
variable to determine styling, and weight, specified as
[weight=exp] or
[iweight=exp], scales the symbols by the
absolute (and normalized) values of exp. options are as follows.

shape(spec) selects or defines the shape of the symbols. shape may be

circle circle (or oval)

triangle triangle

square square (or rectangle)

pentagon pentagon

hexagon hexagon

heptagon heptagon

octagon octagon

arc [angle] section of circle; angle in [-360,360]

slice [angle] slice of circle; angle in [-360,360]

line horizontal line

pipe vertical line

plus upright cross

x diagonal cross

diamond diamond

v V symbol

arrow arrow with open head

farrow arrow with closed head

star 5-pointed star

star6 6-pointed star

pentagram pentagram (5-pointed star with crossing lines)

hexagram hexagram (6-pointed star with crossing lines)

pin [headsize] pin (needle); headsize in [0,1]

pin2 [headsize] alternative pin; headsize in [0,1]

numlist manual shape coordinates

matname matrix containing shape coordinates

name [arg] mata function _geo_symbol_name() returning shape coordinates

The default is circle. For arc and
slice, argument angle in [-360,360] specifies the size of the
segment in degrees; default is 180 (half circle). In case of
arc you may want to specify option line (see below) to prevent
connecting the first and the last point. For pin and pin2, argument
headsize in [0,1] specifies the size of the head; default is one third for
pin and 0.6 for pin2.

Use shape(numlist) or shape(matname) to
create a custom symbol. numlist is a list of shape coordinates specified
as

x1 y1 [x2 y2 ...]

matname is the name of a matrix containing the shape coordinates. The matrix may
contain a single row or column of consecutive points or it may contain two
rows or two columns, one for X and one for Y. For example, to create a
kite symbol, you could type

shape(0 -1 .5 0 0 .5 -.5 0 0 -1)

or you could define a matrix such as

matrix KITE = (0, -1, .5, 0, 0, .5, -.5, 0, 0, -1)

or

matrix KITE = (0, .5, 0, -.5, 0)', (-1, 0, .5, 0, -1)'

and then type shape(KITE). Furthermore, you may create a custom symbol
by defining a Mata function
_geo_symbol_name() and then call the function
as shape(name [arg]). Two arguments will be submitted to
the function, real scalar n and string scalar arg. The function must
return a numeric r x 2 matrix containing the (X,Y)
coordinates of the symbol (or a r x 3 matrix containing the
coordinates in the first two columns and a plot level indicator in the
third column; use the plot level indicator in multi-part symbols
to create white space by setting the plot level to 0 for
regular parts and to 1 for white-space parts; more precisely, the parts
of the symbol will be printed in ascending order of the plot level with
even-level parts treated as regular parts and odd-level parts treated as
white space). For example, to create a kite symbol, define function

real matrix _geo_symbol_Kite(real scalar n, string scalar arg)
{
pragma unused n
pragma unused arg

return(((0, .5, 0, -.5, 0)',(-1, 0, .5, 0, -1)'))
}

and then type shape(Kite). Multipart symbols can be
created by introducing a missing point between parts.

n(n) sets the number of points used to draw a circle. Technically,
a circle is drawn as a polygon with n edges; if n is large enough,
the polygon appears as a smooth circle. This also means that you can use shape(circle)
with low n to create regular polygons. In fact, symbols
triangle, square, ..., octagon are implemented as
shape(circle) with n set to 3, 4, ..., 8, respectively. For shape(circle),
the default is n = 100. For shape(arc angle) and
shape(slice angle) the default is n =
max(2, ceil(abs(angle)/360 * 100)). For shape(pin) and shape(pin2), the default
is n = max(4, ceil(headsize * 100)).

align(align) changes the zero point of the selected symbol shape, which
determines how the shape is aligned to the coordinate of its position. align()
is applied to the raw symbol shape, before applying options such as ratio(),
size(), angle(), or offset().

align can contain one of left and right, one of
bottom and top, as well as center. For example,
type align(bottom) to move the zero point to the bottom, or type
align(top left) to move it to the top left corner. The default is to
leave the zero point unchanged, which is at the center for most shapes; type
align(center) if you want to recenter shapes that do not have their
zero point at the center. left, right, bottom, and top
take precedence over center.

ratio(#) adjusts the ratio between the height and the width of the symbols. The default
is ratio(1). For example, type ratio(2) to double the height.

angle(angle) rotates the symbols by angle degrees (counterclockwise). Global
option angle() has no effect on the orientation of the symbols.

size([*]exp) sets or adjusts the size of the symbols. For
the predefined symbols, size() sets the length of the
radius of the circle enclosing the symbol (i.e. the distance between the center
and the outermost point). For custom symbols, size() sets
the unit length of the specified coordinates. Type size(exp) to specify
an absolute size (i.e. in units of the underlying
map). Alternatively, specify size(*exp) to multiply the default
size by exp. The default size is set to 3% of the minimum of the horizontal
and vertical size of the underlying map (as it exists at the point when the
symbols are added, including the positions of the symbols; the smallest possible
default size is 1).

offset(offset [angle]) offsets the positions of the
symbols by offset percent of size() in the direction of angle. The
default angle is 0 (east). For example, set angle to 90 for north, 180
for west, or -45 for south-east.

line plots the symbols using plot type line. The
default is to plot the symbols using plot type area. Note
that, by default, the symbols do not have a fill color even if option
line is omitted. Specify zvar to color the
symbols depending on the values of zvar. Specify
color(colorspec) or
fcolor(colorspec) to set a
single fill color for all symbols.

area_options or line_options, depending on whether
option line has been specified, are regular graph options to affect
the look of the symbols. Color options support colorspec as described in
colorpalette.

marker_label_options to add marker labels.

zvar_options, wmax(), select(), ecolor(), box(),
feature(), and coordinates() are options as described for layer type
area.

pie charts

pie frame varlist [if] [in] [weight]
[,
options ]

where frame is the frame containing the positions and data of
the pie charts (see geoframe), varlist specifies the variables
determining the slice sizes (a separate pie chart will be created for each
unit/row in the data), and
weight, specified as [weight=exp] or
[iweight=exp], scales the pie charts by the
absolute (and normalized) values of exp. options
are as follows.

asis omits normalization of the values provided by varlist. By
default, the values will be normalized such they sum to 100 across varlist
in each row of the data. Option asis may be useful if the provided
values are percentages and you want to leave part of the pie blank
if the percentages do not sum up to 100.

explode(spec) displays exploded pie charts. An exploded pie
chart is a pie chart in which one or more slices are moved out from the
center. spec may be # to move all slices out by # percent of
the radius of the pie. Alternatively, spec may be

index = # [index = # ...]

where index is the index of the slice to be moved out (1 for the
slice corresponding to the first variable, 2 for the second, etc.)
and # is the value of the shift in percent of the radius of the pie.

polar causes polar area diagrams to be displayed rather than regular
pie charts. A polar area diagram is a pie chart in which each slice has the
same angle and the values from varlist determine how far the
slices extend from the center of the pie. In a regular pie chart the values of
varlist determine the angles of the slices and all slices extend from the
center by the same amount.

reverse travels in counterclockwise direction around the circle. The
default is to arrange the slices in clockwise order.

mid shifts the start of the first slice by half its angle. By default,
the edge of the first slice starts at 90 degrees (north). Specify mid
to center the first slice at 90 degrees.

angle(angle) rotates the pies by angle degrees
(counterclockwise). The default is angle(90) such that the first
slice of a pie starts at an angle of 90 degrees (north). For example, type
angle(0) place the first slice at 0 degrees (east). Global
option angle() has no effect on the orientation of the pies.

size([*]exp) sets or adjusts the size of the
pies. Type size(exp) to specify an absolute size (i.e. in units of the underlying
map) for the radius of the pie. Alternatively, specify size(*exp)
to multiply the default radius by exp. The default radius is set to 3% of the minimum
of the horizontal and vertical size of the underlying map (as it exists at the point when the
pies are added, including the positions of the pies; the smallest possible
default radius is 1).

offset(offset [angle]) offsets the positions of the
pies by offset percent of their radius in the direction of angle. The
default angle is 0 (east). For example, set angle to 90 for north, 180
for west, or -45 for south-east.

outline[(options]) adds an outline circle to each pie
by calling layertype symbol. This may
be useful, for example, to complete the circle for the part of a pie that may be
left empty if asis is specified, to draw a reference outline in
case of polar, or to create doughnut charts. options are as follows.

below plots the outlines below the pie charts. The the default is
to plot the outlines on top.

noweight requests that the specified weights be ignored when
determining the sizes of the outlines.

size(), ratio(), n(), offset(), line,
and area_options or line_options are
options as described for layertype symbol. Several
of these options will be set automatically, which can be overridden by specifying
the options explicitly. size(*#) will be interpreted
as # times the size used for the pies.

n(n) sets the number of points used to draw a circle. Default is
n(100). Each slice will use a fraction of points corresponding to the
angle of the slice (with an imposed minimum of 2 points).

nolabel uses variable names rather variable labels in the legend.

zvar_options, wmax(), select(),
area_options, box(), and coordinates() are options as described
for layer type area. Unstarred zvar_options
will be ignored.

bar charts

bar frame varlist [if] [in] [weight]
[,
options ]

where frame is the frame containing the positions and data of
the bar charts (see geoframe), varlist specifies the variables determining
the bar segments (a separate bar chart will be created for each unit/row in the data), and
weight, specified as [weight=exp] or
[iweight=exp], scales the bar charts by the
absolute (and normalized) values of exp. options
are as follows.

nostack unstacks the bars. The default is to display stacked bar
charts. Specify nostack if you want to display regular (unstacked) bar charts.

asis omits normalization of the values provided by varlist. By
default, the values will be normalized such they sum to 100 across varlist
in each row of the data. Option asis may be useful if the provided
values are percentages and you want to leave part of the bar chart blank
if the percentages do not sum up to 100.

reverse arranges the bars in reverse order.

angle(angle) rotates the bar charts by angle degrees
(counterclockwise). The default is to display upright bar charts. For
example, Type angle(-90) for horizontal bar charts (west to east). Global
option angle() has no effect on the orientation of the bars.

size([*]exp) sets or adjusts the size of the
bar charts. Type size(exp) to specify an absolute size (i.e. in units of
the underlying map) for the width of the charts. Alternatively, specify size(*exp) to
multiply the default width by exp. The default width is set to 3% of the minimum
of the horizontal and vertical size of the underlying map (as it exists at the
point when the bar charts are added, including the positions of the bar charts;
the smallest possible default width is 1).

ratio(#) adjusts the ratio between the height and the width of the
bars charts. The default is ratio(2).

offset(offset [angle]) offsets the positions of the
bar charts by offset percent of their width in the direction of angle. The
default angle is 0 (east). For example, set angle to 90 for north, 180
for west, or -45 for south-east.

outline[(options]) adds an outline frame to each bar
chart by calling layertype symbol. This may
be useful, for example, to illustrate the part of the bar chart
that may be left empty if asis is specified. options are as follows.

below plots the outlines below the bar charts. The the default is
to plot the outlines on top.

noweight requests that the specified weights be ignored when
determining the sizes of the outlines.

size(), ratio(), angle(), offset(), line,
and area_options or line_options are
options as described for layertype symbol. Several
of these options will be set automatically, which can be overridden by specifying
the options explicitly. size(*#) will be interpreted
as # times the size used for the bar charts.

nolabel uses variable names rather variable labels in the legend.

zvar_options, wmax(), select(),
area_options, box(), and coordinates() are options as described
for layer type area. Unstarred zvar_options
will be ignored.

area with immediate arguments

areai x1 y1 [ x2 y2 ... ] [, options ]

where arguments x and y specify the coordinates defining an
area; separate areas are delimited by setting x and y equal to
. (missing). options are as follows.

label(label) sets a key label for the legend, where label is
"text" ["text" ...]. Multiple lines
are created if multiple "text" elements are specified.

Rendering options as described for layertype area.

line with immediate arguments

linei x1 y1 [ x2 y2 ... ] [, options ]

where arguments x and y specify the coordinates defining a
line; separate lines are delimited by setting x and y equal to
. (missing). options are as follows.

label(label) sets a key label for the legend, where label is
"text" ["text" ...]. Multiple lines
are created if multiple "text" elements are specified.

Rendering options as described for layertype line.

point with immediate arguments

pointi immediate_values [, options ]

where immediate_values is one or more of

#_x #_y [(clockpos)] ["text"]

Arguments #_x and #_y specify the position of the point,
"text" specifies an optional marker label, and
clockpos specifies the location of the label
(see clockposstyle). options are as follows.

label(label) sets a key label for the legend, where label is
"text" ["text" ...]. Multiple lines
are created if multiple "text" elements are specified.

Rendering options as described for layertype point.

scatteri may be used as a synonym for pointi.

label with immediate arguments

labeli immediate_values [, options ]

and where immediate_values is one or more of

#_x #_y [(clockpos)] "text"

Arguments #_x and #_y specify the anchor point of the label,
"text" specifies the text of the label, and
clockpos specifies the location of the label
(see clockposstyle; default is 0). options are as follows.

label(label) sets a key label for the legend, where label is
"text" ["text" ...]. Multiple lines
are created if multiple "text" elements are specified.

Rendering options as described for layertype label.

symbol with immediate arguments

symboli immediate_values [, options ]

where immediate_values is one or more of

#_x #_y [[[*]size]] [(clockpos)] ["text"]

Arguments #_x and #_y specify the position of the symbol and optional argument
size specifies a custom size for the symbol (size must be enclosed in
square brackets). Specify *size to multiply the default size by
size; specify size without * for an absolute size. Furthermore,
"text" specifies an optional label and clockpos
specifies the location of the label (see clockposstyle). Options
are as follows.

size([*]size) sets the size argument for those
symbols for which no custom size has been specified.

label(label) sets a key label for the legend, where label is
"text" ["text" ...]. Multiple lines
are created if multiple "text" elements are specified.

Rendering options as described for layertype symbol.

paired-coordinate spikes, arrows, or markers

pctype frame [zvar] [if] [in]
[, options ]

where pctype is

pcspike paired-coordinate spikes

pccapsym paired-coordinate spikes capped with
symbols

pcarrow paired-coordinate arrows

pcbarrow paired-coordinate arrows with two
heads

pcpoint paired-coordinate markers

pcscatter synonym for pcpoint

and frame is the frame containing the paired coordinates (see
geoframe) and zvar is an optional
variable to determine styling. Type
i.zvar to treat zvar as a categorical
variable. options are as follows.

zvar_options, select(), and box() are
options as described for layer type area.

Options to affect the rendering of the spike
lines, arrows, and markers as described in twoway pcspike,
twoway pccapsym, twoway pcarrow, and
twoway pcscatter, respectively. Color options support
colorspec as described in colorpalette.

coordinates(X1 Y1 X2 Y2) specifies custom coordinate variables. The
default is to use the variables returned by
geoframe get coordinates.

noshp uses the coordinates found in frame even if frame is
linked to a shape frame. By default, the coordinates are taken from the
linked shape frame. Option noshp has no effect if frame is not linked to a shape frame.

paired-coordinate spikes, arrows, or markers with immediate arguments

pcitype immediate_values [, options ]

where pcitype is

pci pcspike with immediate arguments

pccapsymi pccapsym with immediate arguments

pcarrowi pcarrow with immediate arguments

pcbarrowi pcbarrow with immediate arguments

pcpointi pcpoint with immediate arguments

pcscatteri synonym for pcpointi

and where immediate_values is one or more of

#_x1 #_y1 #_x2 #_y2 [(clockpos)] ["text"]

Arguments #_x1, #_y1, #_x2, and #_y2 specify the
coordinates of the start point and the end point,
"text" specifies an optional marker label, and
clockpos specifies the location of the label (see
clockposstyle). options are as follows.

label(label) sets a key label for the legend, where label is
"text" ["text" ...]. Multiple lines
are created if multiple "text" elements are specified.

Rendering options as described for layertype pcspike.

Options

zvar options

Many layer types support variable zvar (or
i.zvar) as an argument. Specify zvar
to determine the colors and other aspects of the
units displayed in the layer by the values of zvar. The
range of values of zvar will be divided into levels and each
level will be represented by a different style. Use the options below to
determine how zvar is divided into levels, how the levels will be
styled, and how the levels will be represented in the legend. Type
i.zvar to treat zvar as a categorical
variable. Each value of zvar will then be treated as a separate
level. Likewise, if zvar is a string variable, each unique value of
zvar will be treated as a separate level.

discrete treats zvar as a discrete
variable. Each unique value of zvar will be treated as a
separate level. Typing i.zvar implies discrete. Note that
i.zvar only allows positive and integer values, while
discrete does not impose such a restriction. If zvar is a string
variable, discrete is implied.

levels([#][, method weight(varname)]) specifies the number of
levels to be formed by zvar. By default, a regular grid
(equidistant cuts) of 5 intervals from the observed minimum to the observed
maximum of zvar will be used (first interval closed, remaining intervals
left-open). Specify levels(#) to create # intervals. Specify suboption method
to use a non-regular grid, where method can be one of the following.

quantile use quantiles as cuts

kmeans use cuts determined by cluster kmeans

The number of resulting levels may be less than # with these methods, depending on the
distribution of zvar. In case of quantile, weights to be taken
into account when computing the quantiles can be specified in suboption weight(). Option
levels() has no effect if i.zvar or
discrete is specified, or if zvar is a string variable.

cuts(numlist) is an alternative to levels() and
provides custom breaks for the levels to be formed by
zvar. For continuous zvar,
specify #+1 breaks to form # intervals (first interval closed, remaining
intervals left-open). Observations with values below the first break or above
the last break will be ignored.

If i.zvar or discrete
is specified, numlist is interpreted as the distinct values of
zvar to be selected. In this case, numlist
also affects the order in which the levels are printed in the legend. Behavior
is similar if zvar is a string variable, except that the
values in numlist are interpreted as indices of alphabetically sorted
values.

colorvar([i.]zvar) is an alternative to specifying
[i.]zvar as an argument. If both are specified,
colorvar() will take precedence.

color([palette] [,
palette_options])
selects the colors to be used for the levels. palette is any
palette allowed by colorpalette (which can also be a simple list of colors, see
help colorlist) and palette_options are
corresponding options. For example, type colors(hcl bluered, reverse) for a
red to blue HCL color scheme. The default is color(st) if
i.zvar or discrete is specified or if
zvar is a string variable; in all other cases the default is
color(viridis). An appropriate number of colors will automatically
be retrieved from palette (applying interpolation or recycling, if necessary,
depending on type of palette). Specify a single color if you do not want
the color to depend on the values of zvar.

If zvar is omitted, color()
is interpreted as a standard graph option; in this case, the syntax is
color(colorspec).

lwidth(list),
lpattern(list),
fintensity(list),
msymbol(list),
msize(list),
msangle(list),
mlwidth(list),
mlabsize(list), and
mlabangle(list) specify lists of line widths, line pattern, fill
intensities, markers symbols, marker sizes, marker angles, marker outline
widths, marker label sizes, and marker label angles to be used for the
levels. The availability of these options depends on layer type; for example,
marker options will be available with point, but not
with area or line.

list can be a numlist or an appropriate
stylelist (linewidthstylelist,
linepatternstylelist,
intensitystylelist,
symbolstylelist,
markersizestylelist,
anglestylelist, or
textsizestylelist). Specify numlist with exactly two
elements, e.g. lwidth(0.5 1), to use a regular grid of values
between the two numbers. In all other cases, the specified
elements will be recycled if the number of levels is larger than the
number of elements in list. Omit an option or specify a single
element, e.g. lwidth(thin), if you want to keep a property
constant across levels.

If zvar is omitted, the options are
interpreted as a standard graph options with their regular syntax.

mlabcolor([palette] [,
palette_options]) is like
color() but affects marker labels
only.

label([labelinfo] [, options]) determines how
the levels formed by zvar will be labeled in
the legend. labelinfo is

[value [=]] label [ value [=] label ... ]

where value is the index (continuous or string zvar) or
value (categorical zvar) of the level to be affected and label is

"text" ["text" ...]

(a multiline label will be created if label contains multiple
"text" elements).

value may be # to select a specific level
(e.g., 1 for the 1st level,
2 for 2nd level, etc.) or it may be a specification including
wildcard characters * and ? to select multiple levels
(e.g. ? for levels 1-9, 1? for levels 10-19, * for all
levels). In any case, the label of the first matching
specification will be assigned. You may also type label(label)
rather than label(* = label) to assign the
same (type of) label to all levels.

text may include the following placeholders:

@lb lower bound of the interval

@mid middle of the interval

@ub upper bound of the interval

@lab value label in case of categorical zvar, @lb - @ub in case of continuous zvar

@n number of units

In case of i.zvar or discrete, or if zvar is a string variable,
the default is label("@lab"). For example, type label("@lab (@n)") to
include the number of units in the label. For continuous zvar,
the default is equivalent to label(1 = "[@lb,@ub]" * = "(@lb,@ub]"). For example,
type label("@lb - @ub") or label("@lab") to create labels
formatted as "lb - ub", where lb and ub are the lower
and upper bounds of the intervals.

options are as follows.

nolabel omits the use of value labels in case of i.zvar or
discrete.

format(%fmt) selects the display format to be applied to numeric
values. The default is to use the display format of zvar.

reverse reverses the order of the legend keys.

If zvar is omitted in a layer (such that, technically,
the layer only contains a single level), type label(label) to
set the label of the layer's legend key (the default is to use the name of
the plotted frame as label). The above options and placeholders are ineffective in this case.

gloptions(options) provides override options to be applied to
the symbols created by glegend(). Depending on layer
type, these are area_options,
line_options, or marker_options.

nolegend requests that the current layer not be considered for the
legend that is displayed by default if there are layers containing a
zvar. nolegend only affects the default
behavior; you can still include the layer manually in the legend using the
legend's layer() suboption.

missing(options) specifies the styling of elements for which zvar
is missing, where options are as follows.

Standard rendering options depending on layer type, such as color(),
lwidth(), lpattern(), etc. In case of area,
the default is to use color gs14 for areas for which zvar is missing.

label("text" ["text" ...])
sets a label for missing in the legend. The default is
"no data". Multiple lines are created if multiple
"text" elements are specified. @n can be used in
text as a placeholder for the number of missing units.

nolabel omits missing from the legend.

first places missing at the top (or leftmost) rather than at
the bottom (or rightmost) of the legend.

nogap omits the gap between missing and the other keys in the legend.

gloptions(options) provides override options to be applied to
the missing symbol created by glegend().

Global options

background[(options)] draws a (rectangular)
background frame behind the map, where options are as follows.

water sets the feature type of the background to water, affecting
how the background will be rendered by default.

limits(limits) specifies custom limits for the size of the
background frame, where limits is

xmin xmax ymin ymax

The default is to use the observed limits of the coordinates included in the
map. Elements in limits that are omitted
or specified as . (missing) are set to the default.

padding(marginexp) adds padding to limits of the background frame. This is
only relevant for limits that are determined automatically, not for custom
limits. The values in marginexp are in percent of the size of the map
in each direction. For example, type padding(5) to increase the frame
by 5% on each side; type padding(-5) decrease by 5%. Provide multiple
values in marginexp to use different padding on the left, right,
bottom, and top (in this order; values will be recycled). Alternatively,
specify one or more elements of the form
{l|r|b|t} [=] #, such as
padding(l=5) (add 5% padding on the left; no padding on other sides)
or padding(r=5 t=10) (add 5% padding on the right and 10% padding at the top;
no padding on other sides).

n(#) specifies number of points used to draw each edge of the
background frame. Default is n(1) or, if project()
is specified, n(100).

area_options affect the look of the background
frame as described in twoway area. By default, only the outline will be
displayed (unless option water is specified). Specify option
color() to display a filled frame (without
outline); use options fcolor() and lcolor() to set the colors
of fill and outline separately. Color options support
colorspec as described in colorpalette.

grid[(options)] draws grid lines on top of the
map. grid() can be repeated to draw multiple grids. options are
as follows.

x(), y(), tight, padding(), radian,
noextend, mesh, and n() define the lines as described in
geoframe grid. If grid() is repeated, shapes
created by earlier calls to grid() will be included in the
computations.

line_options affect the look of lines as
described in twoway line. For example, use option lwidth() to
set the width of lines. Color options support colorspec as described in
colorpalette.

labels[(options)] adds axis labels,
where options are as follows.

positions(list) selects the sides to be labeled and fine-tunes the
positioning of the labels. Argument list is one or more elements of the form

{l|r|b|t} [[=] clockpos]

where l prints labels on the left, r on the right, b at the
bottom, and t at the top, and clockpos fine-tunes the
positioning. Default clockpos is 9 for l, 3 for
r, 6 for b, and 12 for t.

The default is positions(l b) or, more precisely,
positions(l=9 b=6) or positions(l 9 b 6). Type, for example,
positions(l r b t) to print labels on all four sides.

format(%fmt) or format(exp) formats the labels. Use
format(%fmt) to apply a numerical format as
described in format; use format(exp) for more involved
formatting, where exp is a string expression. Within exp, use
X for the numerical value and axis for the axis
to which a label belongs (1 = X axis, 2 = Y axis). For example,

format(string(X,"%9.1f") + "{&degree}")

displays the labels with one decimal place and a degree symbol. Likewise,

format(string(abs(X)) + "{&degree}" + cond(X>0, cond(axis==1,"E","N"), cond(X<0, cond(axis==1,"W","S"), "")))

displays the labels in absolute degrees including compass direction.

size(), color(), angle(), tstyle(), and gap()
affect the rendering of the labels as described for layertype
label.

tissot[(options)] draws Tissot's
indicatrices on top of the map, where options are as follows.

r(), x(), y(), tight, padding(), radian,
and n() define the indicatrices as described in
geoframe tissot.

area_options affect the look of the indicatrices as described
in twoway area. By default, only the outline will be
displayed. Specify option color() to display a filled frame (without
outline); use options fcolor() and lcolor() to set the colors
of fill and outline separately. Color options support
colorspec as described in colorpalette.

markers[(marker_options)] displays a marker at the
center of each indicatrix, where marker_options affect
the look of markers as described in twoway scatter. For example,
use option msymbol() to set the marker symbol. Color options
support colorspec as described in colorpalette.

project[([projection [args]] [, radian])]
applies the specified projection, where projection and args are
as described in geoframe project. Original
coordinates are assumed to represent latitude (Y) and longitude (X) in
degrees (typically WGS84); specify suboption radian if the
coordinates are in radians. If project is specified without
arguments, the webmercator projection is applied.

angle(angle) rotates the map by angle degrees
(counterclockwise). rotate() is a synonym for angle().

legend[(options)] prints a legend for one or several
layers, employing official Stata's legend option. options are as follows:

layout(layout) selects and arranges the layers to be included in the
legend. layout is

el [ el ... ]

where el is one of

# include the legend keys of layer #

. add a gap

| start a new column (or a new row)

- title add a subtitle, where title is
"text" ["text" ...]

Series of # elements can be specified using shorthand notation as described
in numlist. layers() can be used as a synonym for layout().

bottom aligns the legend keys at the bottom (rightmost) if there are multiple
columns (rows) in the legend. The default is to align the keys at the top (leftmost).

horizontal arranges the legend horizontally (i.e., in rows). The default is to
arrange the legend vertically (in columns).

reverse reverses the order of the legend keys within layers.

position(compassdirstyle) overrides the default location of the legend,
which is in the upper right corner.

outside places the legend outside of the plot region. The default is
to place the legend inside the plot region.

contents and location options are further options to affect the
rendering of the legend as documented in legend_option. Be
careful with options order(), rows(), cols(), and
colfirst, as these options are set automatically by geoplot and
you may not want to override these settings. Option
bplacement() will be ignored.

Type legend(off) or nolegend to suppress the legend that is printed by default if
zvar has been specified in at least one layer.

glegend[(options)] prints a legend for one or several
layers, employing a custom procedure that does not make use of
official Stata's legend option. Unlike the standard legend() option,
glegend() supports the inclusion of symbols created by layertype
symbol. Furthermore, glegend() can be repeated to
create multiple legends. options are as follows:

layout(layout) selects and arranges the layers to be included in the
legend. layout is

el [ el ... ]

where el is one of

layers include the legend keys of the specified layers

. add a gap between layers

| start a new column

- title add a subtitle, where title is
"text" ["text" ...]

and layers is a single # to include the keys of layer #, a
numlist to include the keys from multiple layers (one after
the other), or

#1 & #2 [ & #3 ... ]

to include legend keys with composite symbols from two or more
layers (i.e., symbols from multiple layers printed on top of each
other; labels will be determined in such as way that for
each key the last non-empty label is printed). layers()
can be used as a synonym for layout().

bottom aligns the legend keys at the bottom if there are multiple
columns in the legend. The default is to align the keys at the top.

reverse reverses the order of the legend keys within layers.

position(compassdirstyle) overrides the default location of the legend,
which is in the upper right corner. Default is position(ne). The
legend will always be placed inside the plot region; use global option
margin() to make space for the legend if needed.

box[(area_options)] prints a frame around the
the legend. Color options in area_options support colorspec as
described in colorpalette.

symysize(#) and symxsize(#) specify the height and width of the
space used for the keys' symbols, in percent
of the map's reference size. Defaults are
symysize(3) and symxsize(3).

symscale(#) specifies the relative size of symbols from layertype
symbol, in proportion to the height set by
symysize(). Default is symscale(0.8).

rowgap(#) specifies the vertical gap between legend keys, in percent
of the map's reference size. Default is
rowgap(0).

colgap(#) specifies the horizontal gap between legend columns, in percent
of the map's reference size. Default is
colgap(3).

keygap(#) specifies the horizontal gap between the symbol
and the label of a key, in percent
of the map's reference size. Default is
keygap(1).

textfirst places labels before symbols. The default
is to place symbols before labels.

textwidth(numlist) specifies the width of the space used for the keys' labels,
in percent of the map's reference size. Default is
textwidth(12). Unlike the standard legend()
option, glegend() uses a fixed width and does not adjust the size
to the content of the labels; use option textwidth() to adjust the
space if it is too wide or too narrow. Specify multiple values to use
different widths across columns (values will be recycled).

talign(align) specifies the alignment of the labels, where
align can be left, center, or right. Default is
talign(left) or, if textfirst is specified,
talign(right).

tsize(textsizestyle),
tcolor(colorspec),
and tangle(anglestyle) specify the size, color, and angle of the
labels. Defaults are tsize(vsmall) and tcolor(black).

lineskip(#) specifies the size of the lineskip in multiline
labels, in percent of the map's
reference size. Default is lineskip(2).

headskip(before after) specifies extra vertical gaps to be added
before and after subtitles. Default is headskip(1 0.5).

halign(align) specifies the alignment of subtitles, where
align can be left, center, or right. Default is
halign(left).

hsize(textsizestyle),
hcolor(colorspec),
and hangle(anglestyle) specify the size, color, and angle of the
subtitles. Default is the same setting as for labels.

nospan restricts the space of subtitles to the space used for labels. By default,
the subtitles span the combined space of symbols and labels.

title(), margin(), xmargin(), and ymargin() as
described for the inset() option.

slegend(values [, options]) prints a legend
for symbol sizes created by applying weights in layertype
symbol. slegend() can be repeated to
create multiple legends. Argument values specifies the sizes
(values of the weighting variable) to be included in the legend. The syntax
of values is

numlist ["label" [numlist ["label"] ... ]]

where label specifies a custom label for the preceding value. The
default is to use numeric values as labels. options are as follows:

layer(#) selects the layer for which the legend be created. The default
is to use the first symbol layer to which weights have
been applied. No legend will be created if there is no such layer.

overlay[(offset)] creates a legend with overlayed
symbols. Use optional argument offset to stagger the positions of the
symbols, where offset specifies the proportion of each symbol's width
that is used to shift the symbols.

tfloat makes the horizontal positions of labels dependent on the
sizes of the symbols. The default is to align the labels at a fixed position.

salign(align) specifies the alignment of the symbols, where
align can be left, center, or right. Default is
salign(center).

heading("text" ["text" ...])
specifies a heading (subtitle) for the legend. Multiple lines are
created if multiple "text" elements are specified. Use
options such as halign(), hsize(), and hcolor() to format
the heading (see below).

format(fmt) selects the display format to be applied to numeric
labels.

reverse, position(), box(), symysize(),
symxsize(), rowgap(), keygap(), textfirst,
textwidth(), talign(), tsize(), tcolor(),
tangle(), lineskip(), headskip(), halign(),
hsize(), hcolor(), hangle(), nospan,
title(), margin(), xmargin(), and ymargin() as
described for option glegend(), with the following
differences: default for position() is sw; default for
symysize() and symxsize() is 2; default for
rowgap() is 1; headskip() only has a single argument
specifying the extra gap after the subtitle.

line and area_options or line_options affect
the rendering of the symbols as described for layertype
symbol. By default, slegend() displays
raw symbols without applying rendering options. For
example, use option color() to add color.

clegend[(options)] prints a contour plot legend
of the colors used in one of the layers that include
zvar with a color gradient
(requires Stata 18). options are as follows.

layer(#) selects the layer for which the legend be created. The default
is to use the first layer containing a color gradient. For example, if layers
3 and 4 in a graph contain zvar with a
color gradient, type layer(4) to create a legend
for layer 4.

format(%fmt) select the display format to be applied to the values
in the legend labels. The default is to use the display format of
zvar.

cuts(keyword) determines how ticks and labels are used to indicated
the cuts between the color levels. keyword may be none (do not
indicate the cuts), label (major ticks plus labels), tick
(major ticks only), mlabel (minor ticks plus labels), and mtick
(minor ticks only). Default is cuts(label). You may use options
zlabel(), ztick(),
zmlabel(), and zmtick()
outside of clegend() to add further ticks and labels or to override the
ticks and labels added by cuts(). cuts() has no effect if
zvar is discrete

nolabel omits the use of value labels. This is only relevant
if zvar is discrete.

missing requests that missing value is
included in the legend. Use option missing() to
set the label for missing.

position(compassdirstyle) overrides the default location of the legend,
which is in the lower right corner.

outside places the legend outside of the plot region. The default is
to place the legend inside the plot region.

clegend_suboption are further options to affect the rendering of the
legend as documented in clegend_option. For example, use options
width(size) and height(size) to set the size of the legend. Option
bplacement() will be ignored.

The rendering of the axis included in the contour legend is controlled by
options specified outside of clegend(). In particular, use
option ztitle() to set the axis title, options
zlabel() and ztick()
to affect the axis labels and ticks, and option
zscale() to control further aspects of the axis.

sbar[(options)] adds a scale bar to the map. options
are as follows.

scale(#), #>0, determines the size of units of the scale bar. Default is
scale(1000). That is, by default, if coordinates are in meters, the
scale bar will be in kilometers.

length(#), #>0, sets the length of the scale bar in units of
the scale bar. geoplot will abort with error
if the resulting scale bar is too large (i.e., has
coordinates outside of the plotregion). An appropriate
length is determined automatically if length() is omitted.

n(#) sets the number of segments in the scale bar. Default is
n(5).

even causes even segments to be filled. The default is to fill
odd segments.

height(#), #>=0, sets the height of the bar in percent of
the map's reference size; see refdim(). Default is
height(1). geoplot
will abort with error if the resulting scale bar is too large (i.e., has
coordinates outside of the plotregion).

label(options) affects the rendering of the numeric labels, where
options are textbox_options such as color() or size()
(defaults are color(black) and size(vsmall)), minmax to label
only the minimum and maximum, above to place the labels above the
scale bar (rather than below), and format(fmt) to set the display
format; default is format(%8.0g). Type nolabel to omit the numeric
labels.

units(text) specifies text to be appended to the rightmost label. Use
this to denote units, e.g., units(km).

title("text" ["text" ...][, suboptions])
adds a title to the scale bar. Multiple lines are created if multiple
"text" elements are specified. suboptions are
position(compassdirstyle) to set the position
of the title (default is at the top) as well as textbox_options such
as color() or size() to affect the rendering of the title; color
options support colorspec as described in
colorpalette. Option
title() can be repeated to create multiple titles.

position(compassdirstyle) overrides the default location
of the scale bar, which is in the lower left corner.

xmargin(#) and ymargin(#) specify how much the
scale bar will be moved away from the edge of the plotregion, in percent of the map's
reference size; see refdim(). Defaults are xmargin(1)
and ymargin(3).

area_options are general options to affect the rendering of the
scale bar, such as color() or lwidth(). Defaults are
color(black), fintensity(100), and lwidth(vthin).

compass[(options)] adds a compass to the map. options
are as follows.

type(type) selects the type of compass. Argument type may be
1 (the default), 2, or 3.

angle(angle) rotates the compass by angle degrees
(counterclockwise).

size(#), #>=0, sets the size (or half-size) of the compass
in percent of the map's reference size; see refdim(). The default
is size(5). For compass type 1, size() sets the half-size; for compass types
2 and 3, size() sets the size. geoplot will abort with error if the resulting
compass is too large (i.e., has coordinates outside of the plotregion).

label[(options)] affects the contents and
rendering of the compass labels, where options
are: text(labels) to override the default labels, which are
text("N" "S" "E" "W") for compass type 1 and text("N")
for compass types 2 and 3; gap(#) to determine how far the
labels will be moved out from the edge of the compass, where argument
#, with default value 30, is in percent of the size (or half-size)
of the compass; as well as textbox_options such as
color() or size(). Default settings are
color(black) and size(vsmall). By default, labels are turned on
for compass types 1 and 2 and off for compass type 3. Type nolabel
to omit the labels in compass types 1 and 2; type label to turn labels
on in compass type 3.

nocircle omits the circle in compass types 1 and 3.

nomspikes omits the minor spikes in compass type 1.

position(compassdirstyle) overrides the default location
of the compass, which is in the lower right corner.

xmargin(#) and ymargin(#) specify how much the
compass will be moved away from the edge of the plotregion, in percent of the map's
reference size; see refdim(). Defaults are xmargin(2)
and ymargin(2).

area_options are general options to affect the rendering of the
compass, such as color() or lwidth(). Defaults are
color(black), fintensity(100), and lwidth(vthin).

zoom(spec) magnifies the objects from selected layers. Option zoom()
can be repeated to magnify multiple sets of objects. The syntax of
spec is

layers: scale [offset [angle]] [, options]

where layers is a list of layer numbers and scale is a scaling
factor. For example, type zoom(2/4: 2.5) to magnify the objects in layers 2 through 4
by factor 2.5. Argument offset specifies the distance by which the objects be moved
and angle specifies the direction of the move in degrees. The default offset
is 0 (no move) and the default angle is 0 (east). For example, type
zoom(2/4: 2.5 100 90) to move the objects by 100 percent (1 radius)
in northward direction. options are as follows.

otype(type) sets the scaling of the offset argument, where
type may be one of the following.

zoom offset is in percent of the radius (half-diagonal)
of the zoom's bounding box (or minimum enclosing circle), including padding
and magnification; this is the default

map offset is in percent of the map's
reference size, before processing any zoom() option and
before processing margin()

absolute offset is in absolute units of the map

position(x y [compassdirstyle]) moves
the objects to the absolute position provided by coordinates x and
y. Optional argument compassdirstyle determines where the
objects will be located relative to point (x,y). The default is
0 (or center) which means that the objects will be centered
at (x,y). For example, specify left to place the objects to the left of
(x,y), or specify se to place the objects in south-east direction
of (x,y). Main arguments offset and angle, if specified, will
be applied after position() has taken effect.

title("text" ["text" ...][, suboptions])
adds a title to the zoom. Multiple lines are created if multiple
"text" elements are specified. suboptions are
position(compassdirstyle) to set the position
of the title (default is at the top) as well as textbox_options such
as color() or size() to affect the rendering of the title; color
options support colorspec as described in
colorpalette. Option
title() can be repeated to create multiple titles.

box[(which)] displays the origin bounding box and
the destination bounding box of the objects. Argument which can be
destination (print destination box only) or
origin (print origin box only). Only one of box and
circle is allowed.

circle[(which)] displays the origin MEC (minimum
enclosing circle) and the destination MEC of the objects. Argument
which can be destination (print destination circle only) or
origin (print origin circle only). Only
one of circle and box is allowed.

By default, the positioning of the magnified objects is
based on the midpoint and radius of the (rectangular)
bounding box. However, if circle() is specified, the positioning is based on the
midpoint and radius of the MEC. To use the MEC as basis without displaying
the circles, you can type circle(none).

padding(#) adds padding to the bounding box or MEC so that it does
not touch the objects. Argument #
is in percent of the radius of the (unpadded) bounding box or MEC. For example,
type padding(5) to add 5% padding. Default is padding(0).

noconnect suppresses the connecting lines between origin and destination
bounding boxes or MECs that are typically printed if box
or circle is specified.

connect[(options)] enforces printing the
connecting lines even if no bounding boxes or MECs are displayed and affects
the rendering of the lines. options are as follows.

all requests that all four corners of the bounding
boxes be connected; by default only the two outer corners are connected
(i.e., the corners for which the connecting lines do not cross either the
origin box or the destination box)

line_options affect the rendering of the connecting lines; for
example, type connect(lpattern(dash)) to use dashed lines

area_options affect the look of the bounding boxes
or MECs. For example, type lcolor(cranberry) to use red lines. The specified
options also affect the connecting lines unless the options are overridden by options
specified in connect().

Note that bounding boxes and MECs generated by zoom()
are printed on top of the map (i.e. in front of the existing
objects). Adding fill to a bounding box or MEC will cover the
objects lying behind it. To include a filled box or MEC that does not
cover the objects, you may use geoframe bbox to
generate a frame containing the coordinates of the box or MEC and then
add it to the graph as regular layer using layertype
area.

inset(spec) creates an inset containing an additional
map. Option inset() can be repeated to create multiple insets. The
syntax of spec is

(layer) [(layer) ...] [, options ]

or

layer || [ layer || ...] [, options ]

where layer is as described above and options
are as follows.

below prints the inset behind the main map. The default is to print the
inset on top.

title("text" ["text" ...][, suboptions])
adds a title to the inset. Multiple lines are created if multiple
"text" elements are specified. suboptions are
position(compassdirstyle) to set the position
of the title (default is at the top) as well as textbox_options such
as color() or size() to affect the rendering of the title; color
options support colorspec as described in
colorpalette. Option
title() can be repeated to create multiple titles.

box(area_options) affects the rendering of frame around the
inset. Color options in area_options support colorspec as
described in colorpalette. Type nobox
to omit the frame.

margin(marginexp) sets the (inner) margin of the inset
(i.e., the margin between the inset and its frame) in percent
of the map's reference size, where marginexp is
as described for global option margin(). Default
is margin(1) unless nobox is specified, in which case the default
is margin(0).

position(compassdirstyle) determines the location of the inset in
the plotregion of the graph. Default is position(0) (in the
center). For example, type position(ne) to place the inset in the
upper right corner.

size(#) sets the size of the inset (excluding margin) in percent
of the map's reference size. Default
is size(30) which means that the width (or height) of the inset will
be 30% of the width (or height) of the plotregion. You may also type
size(.) to omit rescaling and print the
inset in its original size. In any case, however, the size of the inset will
be restricted in such a way that it fits into the plotregion of the main map.

xmargin(#) and ymargin(#) specify how much the
inset will be moved away from the edge of the plotregion, in percent
of the map's reference size. The default
for is xmargin(0) and ymargin(0) unless title() is specified,
in which case the default is xmargin(3) and ymargin(3).

background[(options)] adds a background to the
inset map; see global option background().

grid[(options)] adds gridlines to the inset map;
see global option grid().

project[(spec)] applies the specified projection
to the inset map; see global option project(). The
default is to apply the same projection as for the main map. Type
noproject to omit projection for the inset map.

angle(angle) rotates the inset map by angle
degrees (counterclockwise). rotate() is a synonym for
angle(). The default is to apply rotation as set by
global option angle(); type angle(0) to omit
rotation for the inset map.

tight adjusts the size of the overall graph such that it tightly fits
the map. If tight is not specified, the size of the graph is as set by
the chosen graph scheme. Specify tight to remove
possible white space. By default, tight preserves the vertical size
of the graph and adjust the horizontal size such that the graph has the
same aspect ratio as the map. However, if xsize()
is specified, the vertical size is adjusted. If xsize()
and ysize() are both specified, tight has no effect.

Note that tight may not remove all white space if elements outside the
plot region, e.g. a title(), are added to the
graph (in this case the available space for the map may have a different
aspect ratio than the overall graph, which means that the map will not use up
all available space). Also note that, by default, geoplot includes a small margin around
the plotregion such that the map will not touch the edges of the
graph. Specify graphregion(margin(zero)) to remove
this outer margin.

margin(marginexp) sets the margin by which
the plotregion extends the size of the map, where marginexp is
# [# # #] or one or more elements of the form

{l|r|b|t} [=] #

such as l=5 or t=10. Default is margin(0),
which means that the plotregion will tightly fit the map. Specify, for example,
margin(1) to increase the plotregion by 1 percent on each side of the
map. Specify margin(# # # #) to use different
margins on the left, right, bottom, and top (numbers will be recycled if
less than four numbers are specified). For example, margin(10 5 0 7)
will increase the plotregion by 10 percent on the left, 5 percent on the
right, 0 percent at the bottom, and 7 percent at the top. Alternatively, use
the {l|r|b|t}=#
syntax. For example, margin(r=5 t=10) will increase the plotregion
by 5 percent on the right and by 10 at the top (and by 0 percent on the other
sides). The default reference for computing the margins is the minimum of the horizontal
and vertical size of the map; also see option refdim().

margin() may be useful, for example, if you need to make space for a
legend, such that it does not cover parts of the map. Note that, by default,
geoplot also includes a small margin around the plotregion. Specify option
graphregion(margin(zero)) to remove this outer margin.

refdim(spec) selects the reference dimension for size
calculations by margin(), inset(),
glegend(),
compass(), and
sbar(). spec may be y or
vertical for the vertical dimension, or x or horizontal
for the horizontal dimension. If refdim() is omitted, the
minimum of the horizontal and vertical size of the map is used as the
reference size.

aspectratio([#] [, pos_option]) may be used to
adjust the aspect ratio of the map and to determine the placement of the
plotregion in the graph. By default, geoplot sets the aspect ratio
in a way such that horizontal and vertical distances are proportional to
the numeric values of the coordinates. Specify aspectratio(#) to multiply
the aspect ratio determined by geoplot by # (values between 0 and 1
will compress the map vertically, values larger than 1 will compress the map
horizontally). For pos_option see help aspect_option.

axes turns the display of Stata's default coordinate system on
(axes and axis labels, plot and graph region styles as set by the current
scheme). By default, axes are suppressed, region styles are set to none, and
bgcolor() (an apparently undocumented option to set the color of the
canvas that becomes visible if the graph region has no color) is set to
white.

twoway_options are general twoway options, other than by(), as
documented in help twoway_options.

frame(name[, replace nocurrent])
stores the compiled data of the plot in a frame called
name. Applying the command in r(graph) to the frame
will reproduce the map. Option replace allows overwriting
an existing frame. Option nocurrent does not make the created frame
the current frame.

nograph suppresses the graph. The graph command will still be
returned in r(graph), but the command will not be executed. Use option
nograph if you are only interested in obtaining the compiled data
using option frame() and do not want to waste
computer time on rendering the graph.

Examples

Load data

local url http://fmwww.bc.edu/repec/bocode/i/

geoframe create regions `url'Italy-RegionsData.dta, id(id) coord(xcoord ycoord) shp(Italy-RegionsCoordinates.dta)

geoframe create country `url'Italy-OutlineCoordinates.dta

geoframe create capitals `url'Italy-Capitals.dta, coord(xcoord ycoord)

geoframe create lakes `url'Italy-Lakes.dta, feature(water)

geoframe create rivers `url'Italy-Rivers.dta, feature(water)

Basic map of Italian regions

geoplot (area regions) (line country, lwidth(medthick)), tight

Basic map with lakes and rivers

geoplot (area regions) (area lakes) (line rivers), tight

Regions colored by number of fortune tellers (per million population)

geoplot (area regions fortell) (area regions), tight

Different formatting of legend labels

geoplot (area regions fortell, label("@lb-@ub (N=@n)")) (area regions), tight

Similar graph with more colors and alternative type of legend (requires Stata 18)

geoplot (area regions fortell, levels(20) lcolor(gray)), tight clegend(position(ne)) zlabel(4(3)28)

Map with provincial capitals

local layer1 (area regions)

local layer2 (point capitals i.size [w=pop98], color(Set1, opacity(50)) mlcolor(%0))

local layer3 (label capitals city if pop98>250000, color(black))

geoplot `layer1' `layer2' `layer3', tight legend(position(sw))

Map with composite legend

local layer1 (area regions fortell)

local layer2 (point capitals i.size [w=pop98], color(Set1, reverse opacity(50)) mlcolor(white))

geoplot `layer1' `layer2', tight legend(layout(- "FORTELL" 1 | - "CITY SIZE" 2) position(sw))

Map with pie charts

geoplot (area regions) (pie regions relig?, label(, reverse)), tight

Map with bar charts

geoplot (area regions) (bar regions relig1, asis outline), tight

Stored results

Scalars:

r(layers) number of layers in the graph

r(hasz_#) 1 if layer # has zvar; 0 else

r(z_hascol_#) 1 if a color gradient has been used for
zvar in layer #; 0 else (if relevant)

r(z_discrete_#) 1 if zvar in layer #
is discrete or categorical; 0 else (if relevant)

r(z_hasmis_#) 1 if levels of zvar in layer #
include a missing category; 0 else (if relevant)

Macros:

r(graph) copy of the called graph command

r(legend) copy of the legend option in r(graph) (so
that the legend can be restored when modifying the graph using command
addplot; see ssc describe addplot).

r(keys_#) legend keys of layer #

r(labels_#) labels of legend keys of layer #

r(z_colors_#) colors used for the levels of
zvar in layer # (if relevant)

Matrices:

r(z_levels_#) cut points or levels of zvar
in layer # (if relevant)

r(z_nobs_#) number of units per level of zvar
in layer # (if relevant)

If the levels of zvar in layer # include
a missing category, the first element in
r(keys_#),
r(labels_#),
r(z_colors_#), or
r(z_nobs_#) corresponds to the missing category.

Author

Ben Jann, University of Bern, ben.jann@unibe.ch

Thanks for citing this software as follows:

Jann, B. (2023). geoplot: Stata module to draw maps. Available from
https://ideas.repec.org/c/boc/bocode/s459211.html.

Various features of geoplot have been inspired by corresponding
features in spmap by Maurizio Pisati.

I am grateful to Asjad Naqvi for extensive testing and many valuable
suggestions.