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

Title

geoframe -- Command to prepare data for geoplot

Syntax

[frame frame:] geoframe subcommand [...]

subcommand

Main
translate translate shapefile source to Stata format (without loading)

convert synonym for geoframe translate

create load data into geoframe or declare
current frame as geoframe

link link shape frame to current frame

clean delete unmatched/empty shapes and units

query obtain information on shapes in geoframe

describe describe geoframe

Manipulation
project apply projection

select select units and shapes

clip clip shapes using convex window

rclip clip shapes using rectangular window

simplify simplify (generalize) shapes

refine add extra points to straight lines

bshare select shared borders

generate generate special-purpose variables

copy copy variables between frames

append append observations between frames

Spatial join
collapse collapse points from other frame into current frame

contract contract points from other frame into current frame

spjoin match points in current frame to shapes from other frame

Generate shapes
grid store grid lines in new frame

bbox store bounding box, enclosing circle, or convex hull in new frame

symbol generate symbol shapes and store in new frame

symboli geoframe symbol with immediate arguments

Settings
set update geoframe settings of current frame

get retrieve geoframe settings from current frame

Utilities
rename rename a geoframe

duplicate duplicate a geoframe

relink fix linkage variable after modifying data

unlink unlink shape frame from current frame

attach attach attribute frame to current frame using aliases (Stata 18 required)

detach detach attribute frame from current frame (Stata 18 required)

Description

geoframe prepares data for geoplot.

Subcommands

geoframe translate

geoframe translate [translator] [destination] [using]
source [, replace user ]

translates shapefile source data to Stata format, where translator specifies
the type of translation. Currently, the only available translator is esri, which
translates ESRI shapefile data to Stata format using official Stata's
spshape2dta command or, if option user is specified, the
user command shp2dta (see ssc describe shp2dta). Omitting
translator is equivalent to specifying esri.

Optional argument destination specifies a destination for the translated
data. The syntax for destination is

[path][basename]

where path is an absolute or relative path to an (existing) directory
(e.g. mydata/shapfiles/ on Mac OS or mydata\shapfiles\
on Windows) and basename provides a custom base name for the created files. If
path is omitted, the files are stored in the working directory. If
basename is omitted, the name of the source will be used. Two files
will be created, basename.dta and
basename_shp.dta. Option replace allows overwriting
existing files.

Argument source identifies the source data to be translated. The syntax
for source is

sourcepath[sourcename]

where sourcepath is an absolute or relative path to the directory containing
the source (e.g. mydata/shapfiles/source/world/ on Mac OS or
mydata\shapfiles\source\world\ on Windows) and sourcename specifies the
base name of the source to be translated (in case of an ESRI shape file,
the source consists of sourcename.shp, sourcename.dbf,
and possibly some additional files with the same base name). If sourcepath
contains multiple sources and sourcename is omitted, the first source
will be translated. Alternatively, source can be

zipfile[separator[location][sourcename]]

where zipfile is the (path and) name of a zip file containing the source
(e.g. mydata/shapfiles/source/world.zip on Mac OS or mydata\shapfiles\source\world.zip
on Windows), separator is the operating system's directory separator (i.e. / on Mac OS, \ on Windows),
location specifies the directory of the source within the zip file, and
sourcename specifies the name of the source to be translated. For example, you could
type world.zip/50m/ to translate the first source found in folder 50m within
zip file world.zip, or you could type world.zip/50m/country_borders to translate
the source called country_borders in folder 50m within zip file world.zip.

geoframe convert is a synonym for geoframe translate.

geoframe create

geoframe create [frame] [using] filename
[, options ]

loads the data from filename into a new frame called
frame, where filename is a valid Stata dataset, and declares the
created frame as a geoframe. If frame is omitted, the base name of filename
is used as the name of the created frame. Typically, filename is
an attribute file created by geoframe translate
(or spshape2dta). If a shape file belonging
to filename is available in the same folder (that is, if there is
a file called basename_shp.dta in the folder, where basename is the base
name of filename), the shape file will automatically
be loaded into a second frame called frame_shp and a link between
the two frames will be established. Alternatively,
filename may also be a shape file or any other valid Stata dataset.

You may also type

[frame frame:] geoframe create
[, options ]

to declare the current frame as a geoframe.

Options are as follows.

replace allows replacing existing frames.

nodescribe suppresses the description of the frame that is displayed
by default.

nocurrent does not make the created frame the current frame. The default
is to make the created frame the current frame.

type(type) declares the type of data included in the
frame. type may be unit (attribute data), pc
(paired-coordinate data), or shape (shape data). If type() is omitted,
geoframe create infers the type from context.

feature(string) declares the type of feature represented by the
units in the frame. For example, type feature(water) if the frame
contains data on lakes or rivers. string can be any text.

id(varname) specifies the name of the unit ID. Default is _ID.

coordinates(X Y [X2 Y2]) specifies the names of the variables containing
the coordinates. The default depends on data type. It is _X _Y for data type shape,
_CX _CY for data type unit, and _X1 _Y1 _X2 _Y2 for data type pc.

centroids(CX CY) specifies the names of the variables containing
the centroids of the units. The default is _CX _CY
for data types shape and pc; for data type unit, centroids()
is a synonym for coordinates().

area(AREA) specifies the name of the variable containing the sizes
of the units (i.e. the areas of the shapes). The default is _AREA.

sid(varname) specifies the name of the within-unit sort ID. Default is
shape_order. This is only relevant for data of type shape

pid(varname) specifies the name of the within-unit polygon ID. Default is
_PID. This is only relevant for data of type shape

plevel(varname) specifies the name of the plot level ID (enclaves and exclaves). Default is
_PLEVEL. This is only relevant for data of type shape

noshpfile deactivates automatic loading of the shape file. By default,
as described above, geoframe create loads the shape file belonging to
filename if such a file is found on disk. Specify
noshpfile to suppress this behavior. Data types shape and pc
imply noshpfile.

shpfile(spec) specifies a custom shape file to be loaded along with the main
file. The syntax of spec is

[[shpframe] [using] shpfilename ] [, suboptions ]

where shpfilename is the name of the shape file on disk and shpframe
provides a name for the shape frame. If shpfilename is specified without
path, geoframe looks for the file in the same folder as the main file. If
shpframe is omitted, frame_shp
is used as the name for the shape frame. suboptions are feature(),
id(), coordinates(), sid(), pid(), and plevel()
as described above.

nodrop prevents dropping unmatched units and empty shapes
when linking the attribute file and the shape file (i.e., do not apply
geoframe clean).

geoframe link

[frame frame:] geoframe link shpframe
[, clean[(options)] ]

establishes a link between the current frame and shpframe. geoframe link
is an alternative to linking frames automatically when loading them
using geoframe create.

The current frame must be an attribute frame (one row per unit) and
shpframe is typically a frame containing shape information on the units
represented in the current frame. For each frame only one link to a
shape frame can be registered; calling geoframe link will
remove any existing link to another shape frame. (But note that a single
shape frame may contain links from multiple attribute frames.)

Option clean() calls geoframe clean after
linking the frames. See below for a description of options.

geoframe clean

[frame frame:] geoframe clean
[, options ]

removes unmatched shapes and units if applied to an attribute frame that
has a link to a shape frame. options are as
follows.

shapes deletes unmatched and empty shapes in the linked shape frame.

units deletes unmatched units and units linked to empty
shapes in the current frame.

If neither shapes nor units is specified, the default is to deletes both,
unmatched or empty shapes in the linked shape frame as well as unmatched units or
units linked to empty shapes in the current frame.

noempty does not delete empty shapes or units linked to empty shapes.

emptyonly deletes empty shapes and units linked to empty shapes
only. Unmatched shapes and units will be retained.

A shape is considered empty if it contains only missing coordinates.

geoframe query

[frame frame:] geoframe query [function] [...]

provides functions to obtain information about the units and shapes in the
current frame. Available functions are:

n number of units and shapes; the default

direction orientation of shape items

orientation synonym for direction

gtype geometry type of shape items

bbox bounding box of shapes

Number of units and shapes

[frame frame:] geoframe query [n] [if] [in]

obtains information about the number of selected units and corresponding
shape items (depending on context, a shape item can be a polygon, a line,
or a point). The following scalars are returned in r().

r(units) number of units

r(items) number of shape items (polygons, lines, or points)

r(min) minimum number of shape items per unit

r(avg) average number of shape items per unit

r(max) maximum number of shape items per unit

Orientation of shape items

[frame frame:] geoframe query direction [if] [in]

obtains information about the orientation of the shape items of the
selected units. The following scalars are returned in r().

r(items) total number of shape items

r(neg) number of items with negative orientation (clockwise)

r(pos) number of items with positive orientation (counterclockwise)

r(null) number of items with undefined orientation (items
with less than 3 unique points)

geoframe query orientation is a synonym for geoframe query direction.

Geometry type of shape items

[frame frame:] geoframe query gtype [if] [in]

obtains information about the type of geometry of the shape items of the
selected units. The following scalars are returned in r().

r(items) total number of shape items

r(polygons) number of polygon items (three or more points; first
point equal to last point)

r(lines) number of line items (two or more points; first point
unequal last point, unless there are only two points)

r(points) number of point items (one point)

r(empty) number of empty items (missing)

Bounding box of shapes

[frame frame:] geoframe query bbox [if] [in] [, options ]

obtains the bounding box of the selected shapes and returns
it in r(). options are rotate, circle, hull,
pading(#), n(#), angle(#), noadjust, and
noshp as described in geoframe bbox. The following
results are returned in r().

Scalars:

r(xmin) lower X limit of the bounding box

r(xmax) upper X limit of the bounding box

r(xmid) midpoint between r(xmin) and r(xmax)

r(ymin) lower Y limit of the bounding box

r(ymax) upper Y limit of the bounding box

r(ymid) midpoint between r(ymin) and r(ymax)

Matrix:

r(bbox) (X,Y) coordinates of the bounding box

r(limits) row vector containing limits of the bounding box (xmin, xmax, ymin, ymax)

geoframe describe

[frame frame:] geoframe describe

displays the geoframe settings of the current frame. You may also type

geoframe describe frame

to display the settings of frame frame.

geoframe project

[frame frame:] geoframe project [projection [args]] [if] [in]
[, options ]

applies the specified projection to the coordinates of the selected
shapes. X coordinates are assumed to be within -180 and 180, Y coordinates
within -90 and 90; values outside these ranges will be
clipped before applying the projection. If the current frame is linked to a
shape frame, the coordinates in the shape frame will also be translated. The
following projections are currently available:

robinson [#] Robinson projection; argument # sets the scale (earth radius;
default is 1; for example, set # to 6371 if you want the
resulting coordinates to be in km)

web_mercator [args] Web Mercator projection (spherical model); the default

mercator_sphere [args] Mercator projection (spherical model)

mercator [args] Mercator projection (ellipsoid model)

equidistant_cylindrical [args] Equidistant cylindrical projection (spherical model)

albers_sphere [args] Albers equal-area conic projection (spherical model)

albers [args] Albers equal-area conic projection (ellipsoid model)

lambert_sphere [args] Lambert conformal conic projection (spherical model)

Except for robinson, the projections are computed by user command
geo2xy, which must be installed on the system (see
ssc describe geo2xy); args are documented as
proj_opts in geo2xy. options are as follows

xy(varlist) specifies additional variables in the current
frame to be translated. By default, only the variables returned by
geoframe get coordinates will be affected. varlist
must provide an even number of variables (i.e., pairs of X and Y
coordinates).

ifshp(exp) specifies an if condition to be applied to
the linked shape frame. Observations in the
linked shape frame that do not satisfy the specified condition (i.e.,
observations for which exp evaluates to zero), as well as units in the
current frame for which ifshp() leads to an empty selection in the
shape frame, will not be transformed. ifshp() is only allowed
if the current frame is linked to a shape frame. ifshp() and
noshp are not both allowed.

noshp applies the projection to the current frame only, even if there
is a linked shape frame.

into(newname [newshpname]) copies the transformed data into a new frame
called newname and leaves the current frame unchanged. If the current
frame has a linked shape frame, into() also creates a new shape
frame and leaves the original shape frame unchanged. The
default name for the new shape frame is newname_shp; specify
newshpname to provide an alternative name. into() and noshp
are not both allowed.

replace allows into() to overwrite existing frames.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

geoframe select

[frame frame:] geoframe select [if] [in]
[, options ]

selects the observations satisfying the if and in qualifiers in
the current frame. By default, if the current frame has been linked to a
shape frame by geoframe create or
geoframe link, the selection will also be applied to
the shape frame and the linkage will be rebuilt. options are as
follows.

ifshp(exp) specifies an if condition to be applied to
the linked shape frame when selecting observations. Observations in the
linked shape frame that do not satisfy the specified condition (i.e.,
observations for which exp evaluates to zero) will be removed from
the (copy of the) linked shape frame, and units for which no observations
remain in the linked shape frame after applying ifshp() will be
dropped from the (copy of the) current frame. ifshp() is only allowed
if the current frame is linked to a shape frame. ifshp() is not
allowed together with noshp or unlink.

nodrop retains units in the (copy of the) current frame for which
ifshp() removed all shape-frame observations. The default
is to keep only those units for which at least one observation remains
after applying ifshp(). nodrop is only relevant if
ifshp() has been specified.

noshp modifies the (copy of the) current frame
only, even if the current frame contains a link to a shape frame. That is,
the linked shape frame will remain unchanged (apart from updating the
linkage). noshp also implies that into() will make no copy of
the shape frame.

unlink does not establish a link to a shape frame in the modified
frame, even if the current frame contains a link to a shape
frame. unlink implies noshp.

into(newname [newshpname]) copies the selection in a new frame
called newname and leaves the current frame unchanged. If the current
frame has a linked shape frame, into() also creates a new shape
frame and leaves the original shape frame unchanged. The
default name for the new shape frame is newname_shp; specify
newshpname to provide an alternative name.

replace allows into() to overwrite existing frames.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

geoframe clip

[frame frame:] geoframe clip matname [if] [in]
[, options ]

clips the selected shapes by a convex mask, where matname
is a matrix containing the (X,Y) coordinates of the clipping mask. For example,
you could type geoframe rclip r(bbox) to apply clipping by the bounding box
returned by geoframe query bbox. options are as
follows.

line enforces line clipping for polygons. By default,
a polygon is clipped in such a way that the result is a
(closed) polygon (or a set of closed polygons) again. Specify line, to clip a polygon
to a set of one or more (unclosed) lines. Polygons that lie completely within
the clipping window remain intact in any case. line has no effect
if noclip is specified.

noclip applies selection rather than clipping. Shape items that
are at least partially inside the clipping window will be selected. noclip
is implied when processing point data or paired-coordinate data. For
paired-coordinate data, an item is considered inside if the origin coordinate
is within the clipping window.

strict changes the behavior of noclip. By default, noclip
selects shape items that are at least partially inside the clipping
window. Specify strict to restrict the selection
to items that are completely within the window.

nosplit changes the behavior of noclip. By default, noclip
selects or excludes each shape item (i.e. each polygon, line, or point)
individually. Specify nosplit to treat shape
items that belong to the same unit (e.g. main territory and exclaves) as a
group of items to be included or excluded together.

nodrop retains empty-shape units in the data. The default is to keep only
those units that remain non-empty after the modification.

nodots suppresses the progress dots that are displayed by default.

into(newname [newshpname]) copies the processed shapes
into a frame called newname (and possibly a linked shape
frame called newshpname) and leaves the current frame (and its linked
shape frame) unchanged. The default for newshpname is
newname_shp. Only observations that satisfy the if and in
qualifiers will be copied.

replace allows into() to overwrite existing frames.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

geoframe rclip

[frame frame:] geoframe rclip limits [if] [in]
[, options ]

clips the selected shapes by a rectangular window, where limits
specifies the boundaries of the window. limits can be specified as a
numlist providing the minimum and maximum
of X and Y in the following order:

xmin xmax ymin ymax

Specify . (missing) to set a boundary to (minus)
infinity (or omit the boundary). For example, you could type
geoframe rclip . . ymin to clip from below. Alternatively,
specify limits as matname where
matname is the name of a matrix (row or column vector)
containing the limits (in the same order as above). For example, you
could type geoframe rclip r(limits) to apply clipping by the
(limits of the) bounding box returned by
geoframe query bbox. options are as
described for geoframe clip.

You can also use geoframe clip for rectangular clipping, but
geoframe rclip may be more convenient (and, in some situations, faster).

geoframe simplify

[frame frame:] geoframe simplify [delta] [if] [in]
[, options ]

simplifies (generalizes) the selected shapes (using a Visvalingam–Whyatt
algorithm), where delta specifies the degree of simplification. The
larger delta, the stronger the simplification. The default value for
delta is one. options are as follows.

jointly causes the selected shapes to be simplified
jointly, taking into account shared borders. By default, each
shape item is simplified individually, which may lead to inconsistencies
in shared borders (i.e., different points may be selected for each
item). Such inconsistencies are visually insignificant with moderate
degrees of simplification, and this is why jointly is turned off
by default. Specify jointly if you want to enforce shared borders
to be simplified in the same way for all involved shape items. This may be
time consuming in large datasets.

absolute causes delta to be interpreted as an absolute
threshold (minimum triangle area by which points are dropped). absolute
only has an effect if delta is specified.

By default, delta is interpreted as a multiplier for the base threshold, which
is determined from the coordinates of the selected shapes as
0.5 * (Xmax-Xmin)/2000 * (Ymax-Ymin)/2000 (corresponding to half a pixel
in a four megapixel image). This default is chosen so
that the simplification will be barely visible when plotting the shapes, but
thousands of data points may still be removed depending on the complexity of
the original data. Shape files often come with a great amount of
detail that will only be visible when zooming in on selected areas of
the map. Use geoframe simplify to reduce the amount of data in these
cases, yielding faster screen rendering and smaller graph files, without
loosing much accuracy of the display. Specify, for example,
geoframe simplify 100 if you want to simplify the shapes with a clear
visual effect.

Specify delta with option absolute if you want to provide a
custom threshold rather than a multiplier for the default threshold.

nodrop retains empty-shape units in the data. The default is to keep only
those units that remain non-empty after the modification.

nodots suppresses the progress dots that are displayed by default.

into(newname [newshpname]) copies the processed shapes
into a frame called newname (and possibly a linked shape
frame called newshpname) and leaves the current frame (and its linked
shape frame) unchanged. The default for newshpname is
newname_shp. Only observations that satisfy the if and in
qualifiers will be copied.

replace allows into() to overwrite existing frames.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

geoframe refine

[frame frame:] geoframe refine [delta] [if] [in]
[, options ]

refines the selected shapes by adding extra points within segments that are
longer than a given threshold. That is, if the distance between two
neighboring points in a polygon or line is larger than the threshold,
additional points will be added such that the maximum distance between
points is smaller than or equal to the threshold. Argument delta
affects the degree of refinement; see option absolute
below. geoframe refine may be useful if you want to apply
projections. options are as follows.

absolute causes delta to be interpreted as an absolute value
for the threshold (maximum distance between neighboring points). By
default, delta is interpreted as a factor by which the base threshold
will be divided. The base threshold is determined such that a diagonal
across the map would have at least 200 points. Specify, for example,
geoframe refine 2 to use a threshold that is half the size of the
default threshold (at least 400 points on the diagonal). Alternatively, specify
delta with option absolute if you want to provide a custom
threshold rather than a divisor for the default threshold. absolute
only has an effect if delta is specified.

nodots, into(), replace, and current as described for
geoframe simplify.

geoframe bshare

[frame frame:] geoframe bshare [if] [in]
[, not options ]

modifies the selected shapes so that only shared borders remain. Specify option
not to remove shared borders and retain the other parts of the shape
items. The default is to retain shared borders and remove the other
parts. Further options are nodrop, nodots, into(),
replace, and current as described for
geoframe simplify.

geoframe generate

[frame frame:] geoframe generate function ...

provides functions to generate specific variables in the current frame or in a
linked shape frame. Available functions are:

centroids generate centroid variables in current frame

area generate shape size variable in current frame

pid generate within-unit polygon ID (shape item ID) in shape frame

direction generate direction indicator for shape items in shape frame

orientation synonym for geoframe generate direction

gtype generate geometry-type indicator for shape items in shape frame

plevel generate enclave/exclaves identifier in shape frame

shpmatch generate indicator in current frame
whether unit has match in the linked shape frame

Centroids

geoframe generate centroids [CX CY] [, replace noset ]

generates variables containing the coordinates of the centroid of each shape
(across all shape items belonging to the same unit). The command can be
applied both to a shape frame (in which case the centroids
will be stored in the shape frame) or to an attribute frame that has a linked shape
frame (in which case the centroids will be stored in the attribute frame). CX
and CY specify the names of the generated
variables; _CX and _CY are used as default variable names. Option
replace allows overwriting existing variables. The created variables
will be registered using geoframe set centroids
unless option noset is specified.

Shape sizes

geoframe generate area [AREA] [, scale(exp) replace noset ]

generates a variable containing the size of the area enclosed in each
shape (including all shape items belonging to the same unit). The command
can be applied both to a shape frame (in which case the variable
will be stored in the shape frame) or to an attribute frame that has a linked shape
frame (in which case the variable will be stored in the attribute frame). AREA
specifies a name for the generated variable; _AREA
is used as default variable name. Option scale(exp) determines
the scale of the resulting areas; for example, if the coordinates are in meters,
type scale(100) to obtain areas in hectares, or type scale(1000)
to obtain areas in square kilometers. Option replace allows overwriting
an existing variable. The created variable will be registered using
geoframe set area unless option noset is
specified.

Shape item IDs

geoframe generate pid [PID] [, replace noset ]

generates a variable identifying the different polygons or other shape items
(lines, points) within each unit
represented in the frame. If geoframe generate pid is applied to an
attribute frame that has a linked shape frame, the variable will be added to
the shape frame (considering all observations of the shape frame). PID
specifies a name for the generated variable; _PID is used as default
variable name. Option replace allows overwriting an existing
variable. The created variable will be registered in the shape frame using
geoframe set pid unless option noset is
specified.

Shape items are assumed to be separated by rows of missing
coordinates. If a unit contains no missing rows, each observation in the
unit is assumed to be a separate point item.

Orientation of shape items

geoframe generate direction [DIR] [, replace nolabel ]

generates a variable identifying the orientation of each shape item in the
frame: 1 = positive (counterclockwise), -1 = negative (clockwise), 0 = undetermined
(item has less than 3 unique points). If geoframe generate direction is applied to an
attribute frame that has a linked shape frame, the variable will be added to
the shape frame (considering all observations of the shape frame). DIR
specifies a name for the generated variable; _DIR is used as default
variable name. Option replace allows overwriting an existing
variable. Option nolabel omits creating and assigning value labels.

geoframe generate orientation is a synonym for geoframe generate direction.

Geometry types of shape items

geoframe generate gtype [GTYPE] [, replace nolabel ]

generates a variable identifying the geometry type of each shape item in the
frame: 1 = polygon, 2 = (poly)line, 3 = point, 0 = empty (item contains missing
only). If geoframe generate gtype is applied to an
attribute frame that has a linked shape frame, the variable will be added to
the shape frame (considering all observations of the shape frame). GTYPE
specifies a name for the generated variable; _GTYPE is used as default
variable name. Option replace allows overwriting an existing
variable. Option nolabel omits creating and assigning value labels.

Enclaves and exclaves

geoframe generate plevel [PLEVEL] [if] [in]
[, by(byvar) replace noset
nodots ]

generates (or updates) a variable identifying the plot order of the different polygons
represented in the frame. If geoframe generate plevel is applied to an
attribute frame that has a linked shape frame, the variable will be added to
or updated in the shape frame.

PLEVEL specifies a name for the generated variable; _PLEVEL is used as default
variable name. If variable PLEVEL already exists and is numeric, the
values of the selected observations will be updated; the existing values of
the other observations will not be changed. If variable PLEVEL does not
exist, a new variable will be created, which will be set to missing for all
other observations. If variable PLEVEL already exists and is not
numeric, an error will be displayed. Specify option replace to allow
overwriting the variable in this case. You can also use replace
to replace an existing numeric variable rather then updating it. Variable
PLEVEL will be registered in the shape frame using
geoframe set plevel unless option noset is
specified. Option nodots suppresses the progress dots that are displayed
by default.

By default, geoframe generate plevel will do a search for nested polygons
across all units in the data. Use option by() to stratify the search, for example,
if the data contain separate regions without overlap or if the data contain units
from different aggregation levels that should not be compared. If by()
is specified, a separate search will be done within each group of units defined by the
levels of byvar.

geoframe generate plevel is useful to identify enclaves and exclaves
so that they do not get covered when plotting filled areas. The generated
variable will be set to 0 for polygons that are neither enclaves nor exclaves,
1 for enclaves, 2 for exclaves, 3 for enclaves within exclaves, 4 for exclaves
within enclaves, etc. geoplot will then print the polygons in this
order. The algorithm used by geoframe generate plevel assumes
that polygons do not overlap (i.e. that a polygon is always either completely
inside or completely outside of another polygon; technically, a polygon is classified
as outside as soon as at least one coordinate lies outside). It also assumes that
enclaves are explicitly included in the data (that is, if unit A has
an exclave in unit B, then unit B must contain a corresponding enclave
polygon). Results will be invalid if these assumptions are not met.

geoframe generate plevel can be slow in larger datasets. Make sure to
apply geoframe generate plevel only to shapes at the same
level of aggregation (e.g. regions or countries, but not regions and countries
simultaneously); if relevant, use option by() to stratify by level. Furthermore,
it is generally a good idea to restrict the
data to the geographic region you want to include in your
graph (e.g. using geoframe select) before applying
geoframe generate plevel.

Match in shape frame

geoframe generate shpmatch [SHPMATCH] [, replace ]

generates a variable indicating whether a unit has a match in the linked
shape frame (i.e., whether shape information is available for a unit). The command
can only be applied to a frame that has a link to a shape frame. SHPMATCH
specifies a name for the generated variable; _SHPMATCH is used as default
variable name. Option replace allows overwriting an existing variable.

geoframe copy

[frame frame:] geoframe copy frame2
varlist [, target(namelist) exclude(varlist)
id(id [id2]) ]

copies variables from frame2 (source frame) into the current
frame (target frame), where varlist specifies the variables to be copied. Both
frames can be unique (one row per unit; e.g.,
an attribute frame) or non-unique (multiple rows per unit; e.g., a shape
frame) and the operation performed by geoframe copy depends on the specific
combination.

o Both frames unique: The variables will be
copied from frame2 into the current frame using a one-to-one merge.

o Current frame non-unique, frame2 unique: The variables will be
copied using a many-to-one merge.

o Current frame unique, frame2 non-unique: The variables will be
copied by selecting the first observation from each unit in
frame2 (assuming the variables are constant within units).

o Both frames non-unique: The variables will be
copied by selecting the first observation from each unit in
frame2 and duplicating values within units in the
current frame.

If a link from geoframe create or
geoframe link exists between the two frames, the
existing link will be employed. Otherwise, an appropriate
link will be established on the fly. Options are as follows.

target(namelist) specifies alternative variable names to be used
in the current frame. varlist and target(), after applying exclude(),
will be matched one by one. If target() contains fewer
elements than varlist, the remaining names will be taken
from varlist.

exclude(varlist) excludes the specified variables from the main
varlist. These variables will not be copied.

id(id [id2]) specifies custom ID variables for the
merging. The default is to use the ID variables returned by
geoframe get id (and to abort with error if
geoframe get id fails in any of the two frames). Use
option id() to override this default behavior. Argument id provides
the name of the ID in the current frame, optional id2 provides
the name of the ID in frame2; the same name will be used in
both frames if id2 is omitted.

Results stored by the internal call to frget are passed through in
r().

geoframe append

[frame frame:] geoframe append frame2
[varlist] [if] [in]
[, target(varlist) touse(varname) ]

appends observations from frame2 to the current frame. By default, all variables
from frame2 will be included, creating new variables in the current
frame if necessary. Specify varlist to include a selection of variables only.

Option target() specifies the names of the target variables
to which the observations be appended. Use this option to append a variable
from frame2 to a variable that has a different name in the current
frame; varlist and target() are matched one by one; if target()
contains fewer elements than varlist, the remaining names will be taken
from varlist. The resulting list of target variable must be unique.

Option touse() specifies a variable identifying the observations to be
appended (i.e. observations for which the specified variable is unequal
zero). Use this option as an alternative to if and in.

geoframe collapse

[frame frame:] geoframe collapse frame2
clist [if] [in] [weight] [, options ]

finds the positions of the points provided by frame2 in the shapes
defined by the current frame using geoframe spjoin,
computes summary statistics such as means,
sums, or counts by shapes using collapse, and then adds the results
as additional variables to the current frame (which can be
a shape frame or an attribute frame that is linked to a shape frame). Argument
clist specifies the statistics to be computed; see collapse. Only
points from frame2 that satisfy the if and in
qualifiers will be considered. aweights, iweights, fweights,
and pweights are allowed; see weight, and see Weights
in collapse. options are as follows.

cw specifies casewise deletion. If cw is not specified, all
possible observations are used for each calculated statistic.

select(exp) restricts the shapes from the current frame to be
considered. The default is to use all shapes. Specify
select(exp) to consider only shapes for which exp is unequal 0.

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

generate[(spec)] causes the IDs of the matched
shapes to be left behind as a new variable in frame2. spec is

[ID] [, nosort noset replace ]

where ID is the variable name to be used, nosort omits sorting the data in
frame2 by the generated ID variable, noset omits registering the
generated ID variable in frame2 using geoframe set id, and
replace allows overwriting an existing variable. The default for ID is _ID.

nodots suppresses the progress dots of the spatial join that are displayed by default.

id(ID) indicates that an ID variable matching the points in
frame2 to the shapes in the current frame already exists, e.g. from an
earlier call to geoframe collapse with option generate() or from
a call to geoframe spjoin. In this case,
geoframe collapse will base its computations on existing variable
ID rather than computing a new ID variable. Options select(),
coordinates(), and generate() are not allowed if id() is specified.

geoframe contract

[frame frame:] geoframe contract frame2
[if] [in] [weight] [, options ]

is analogous to geoframe collapse but uses
contract to summarize the data. fweights are allowed; see
weight. options are options described in contract
as well as select(), coordinates(), generate(), and
id() as described in geoframe collapse.

geoframe spjoin

[frame frame:] geoframe spjoin frame2 [ID]
[if] [in] [, options ]

finds the positions of the points provided by the current frame in the shapes
defined by frame2 (note the reversed logic of the syntax compared to
geoframe collapse) and stores the IDs of the matched shapes
in variable ID in the current frame; _ID is used as default
variable name. Only points satisfying the if and in
qualifiers will be considered; for all other points ID will be set to
missing. frame2 can be a shape frame or an attribute frame
that is linked to a shape frame. The spacial join algorithm assumes that
shapes do not overlap (no crossings). It also assumes that nested shapes in
frame2 (or its linked shape frame) have been tagged using
geoframe generate plevel
(if there are nested shapes). options are as follows.

select(exp) restricts the shapes from frame2 that will be
considered in the spatial join. The default is to use all shapes. Specify
select(exp) to consider only shapes for which exp is unequal 0.

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

nosort does not sort the data. The default is to sort the data in the
current frame by the created ID variable (preserving the original sort order
within ID).

noset does not register the created ID variable. By default,
the created variable will be registered in the current frame using
geoframe set id.

replace allows overwriting an existing variable.

nodots suppresses the progress dots that are displayed by default.

geoframe grid

[frame frame:] geoframe grid newname [newshpname]
[if] [in] [, options ]

generates grid lines covering the range of the selected shapes and stores
them in a new frame called newname and an associated shape frame
called newshpname; newname_shp is
used as name for the shape frame if newshpname is omitted. The current
frame may be a shape frame or an attribute frame that has been linked to a
shape frame. options are as follows.

x(##) or x(numlist) determines the
positions of the vertical grid lines. Use x(##),
where # is the desired number of lines, to
determine the positions automatically based on the range of the coordinates of
the selected shapes. Use x(numlist) to specify custom positions. Default
is x(#10).

y(##) or y(numlist) determines the
positions of the horizontal grid lines. Use y(##),
where # is the desired number of lines, to
determine the positions automatically based on the range of the coordinates of
the selected shapes. Use y(numlist) to specify custom positions. Default
is y(#10).

padding(#) adds padding to the range of the grid (only relevant for
positions that are determined automatically, not for custom
positions). Argument # is in percent of the size in each dimension. For
example, type padding(5) to add 5% padding. Default is padding(0).

mesh omits the first and last line on each axis
so that the grid has no frame.

n(n) sets the number of points used to construct a line. The
default is n(100).

noshp uses information on coordinates from the current frame even
if the current frame is linked to a shape frame.

replace allows overwriting an existing frame.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

geoframe bbox

[frame frame:] geoframe bbox newname [newshpname]
[if] [in] [, options ]

computes the bounding box of the selected shapes in the current
frame and stores it in a new frame called newname and an associated shape frame
called newshpname; newname_shp is used as name for the shape
frame if newshpname is omitted. The current
frame may be a shape frame or an attribute frame that has been linked to a
shape frame. options are as follows.

noshp obtains the bounding box from the coordinates found in the
current frame even if the current frame is linked to a shape frame. The default
is to base the bounding box on the coordinates in the shape frame.

by(byvar) computes a separate bounding box
for each group of units defined by the levels of byvar. In the new
frame, the levels of byvar will be used as values of the ID variable.

rotate allows rotation of the bounding box such that the minimum-area
bounding box will be found. rotate has no effect if circle or
hull is specified.

circle computes the minimum enclosing circle (MEC) rather than a
rectangular bounding box. Only one of circle and hull is allowed.

hull computes the convex hull rather than a rectangular bounding
box. Only one of hull and circle is allowed.

padding(#) adds padding to the bounding box. Argument #
is in percent of the size in each dimension. For example,
type padding(5) to add 5% padding. Default is padding(0).

n(n) sets the number of points used to construct a circle. This is only
relevant if circle has been specified. The default is n(100).

angle(angle) rotates the coordinates of the minimum enclosing circle
by angle degrees (counterclockwise). This may be useful when using
circle with a small value for n().

noadjust omits radius adjustment for the minimum enclosing circle. By
default, the radius is adjusted so that the true circle is enclosed in
the n-gram used to form the circle. Specify noadjust if, conversely,
you want the n-gram to be enclosed within the true circle. noadjust is only
relevant if circle has been specified.

replace allows overwriting an existing frame.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

geoframe symbol

[frame frame:] geoframe symbol newname [newshpname]
[if] [in] [, options ]

creates symbol shapes at the positions of the points in the current frame
and stores them in a new frame called newname and an associated shape frame
called newshpname; newname_shp is
used as name for the shape frame if newshpname is omitted. options
are as follows.

shape(), n(), ratio(), angle(), size(), and
offset() are options as described for
layertype symbol in geoplot.

replace allows overwriting an existing frame.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

geoframe symboli

geoframe symboli newname [newshpname]
x1 y1 size1 [x2 y2 size2 ...] [, options ]

creates symbol shapes of the specified sizes at the specified
positions and stores stores them in a new frame called newname and an
associated shape frame called newshpname; newname_shp is
used as name for the shape frame if newshpname is omitted. options
are as describes for geoframe symbol; option size()
will be ignored.

geoframe set

[frame frame:] geoframe set key [value]

defines or adjusts the settings of the current frame. The settings, for example, contain
information on the names of the coordinate variables. Such information will be
retrieved by geoframe or geoplot when processing a frame. key can
be as follows.

key Description

type the type of data in the frame; value may be
unit (attribute file), pc (paired-coordinates file),
or shape (shape file)

feature the type of features represented by the units in the frame;
value can be any text

id the name of the variable containing the unit ID; value is a single
variable name; default is _ID

coordinates the names of the variables containing the coordinates; value is a list of
two (for data types unit and shape) or four (for data type pc) variable names; default is
_X _Y for data type shape, _CX _CY for data type unit,
and _X1 _Y1 _X2 _Y2 for data type pc

centroids the names of the variables containing the centroids; value is a list of
two variable names; default is _CX _CY for data types shape and pc; for data type
unit, centroids is a synonym for coordinates

area the name of the variable containing the shape sizes;
value is a single variable name; default is _AREA

sid the name of the variable containing the within-unit sort ID;
value is a single variable name; default is shape_order; the setting
is only relevant for data of type shape

pid the name of the variable containing the within-unit polygon ID;
value is a single variable name; default is _PID; the setting
is only relevant for data of type shape

plevel the name of the variable containing the plot level ID (enclaves and exclaves);
value is a single variable name; default is _PLEVEL; the setting
is only relevant for data of type shape

shpframe the name of the linked shape frame; only allowed with
geoframe get

linkname the name of the linking variable in the linked shape frame; only
allowed with geoframe get

key is case insensitive; you may type key in lowercase
(as above) or in uppercase.

geoframe get

[frame frame:] geoframe get key [, local(lname) ]

retrieves the value of a geoframe setting, where key is the name of the
setting to be retrieved. Available keys are as listed
above.

Option local() stores the value of the setting in a local called
lname instead of displaying it.

geoframe rename

[frame frame:] geoframe rename newname
[, replace ]

renames the current frame to newname. If the current frame has been linked
to a shape frame by geoframe create or
geoframe link, the link will
be updated. If the current frame is a shape
frame containing links from attribute frames created by
geoframe create or geoframe link,
these links will be updated. Option
relplace allows overwriting an existing frame.

Renaming geoframes using official Stata's frame rename is discouraged
as this will break links created by
geoframe create or geoframe link.

geoframe duplicate

[frame frame:] geoframe duplicate newname
[newshpname] [, options]

copies the current frame to a new frame called newname. By default,
if the current frame has been linked to a shape frame by
geoframe create or
geoframe link, the shape frame will also be copied
and a link between the new frames will be established. The
default name for the new shape frame is newname_shp; specify
newshpname to provide an alternative name. options are as follows.

noshp makes a copy of the current frame only, even if the
current frame contains a link to a shape frame. Instead of copying the
shape frame, a link to the original shape frame will be established in the
new frame.

unlink does not establish a link to a shape frame in the new frame
even if the current frame contains a link to a shape frame. unlink
implies noshp.

replace allows overwriting existing frames.

current makes the created frame the current frame. (current has
no effect if the frame prefix is applied, as Stata will immediately switch back
to the prior frame.)

Copying geoframes using official Stata's frame copy is discouraged
as this will break links created by
geoframe create or geoframe link.

geoframe relink

[frame frame:] geoframe relink

rebuilds an existing link to a shape frame that has been created in the
current frame by geoframe create or
geoframe link. For example, use geoframe relink
to fix a broken linkage after dropping or adding observations. If the current frame
does not contain a link to a shape frame, geoframe relink has no effect.

Alternatively, type geoframe link shpframe to fix a broken link.

geoframe unlink

[frame frame:] geoframe unlink

removes the link to a shape frame that has been created in the
current frame by geoframe create or
geoframe link. If the current frame does not contain
a link to a shape frame, geoframe unlink has no effect.

geoframe attach

[frame frame:] geoframe attach frame2
[varlist] [, exclude(varlist) ]

attaches frame2 to the current frame using an m:1 merge. That is, a
link to frame2 is established and all variables from frame2
that do not already exist in the current frame (except for the ID) are added
as aliases to the current frame. frame2 must be an attribute frame
(one row per unit) and the current frame is typically a frame containing
shape information on the units represented in frame2. After attaching
frame2 to the current frame, the variables
from frame2 will be available in the current frame like any other variables
in the current frame.

By default, all relevant variables from frame2 will be added as aliases
to the current frame. Specify varlist to select the variables
to be added; use option exlcude() to exclude variables from being added.

geoframe attach requires Stata 18.

geoframe detach

[frame frame:] geoframe detach frame2

detaches frame2 from the current frame. All alias variables related to
frame2 will be removed and the link to frame2
will be deleted from the current frame.

geoframe detach requires Stata 18.

Examples

Load attribute data and associated shape file in one call:

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

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

geoplot (area regions fortell), tight

Options id() and coord() have been specified because
Italy-RegionsData.dta uses custom names for the unit ID and the
coordinate variables (the default variable names for an attribute file are _ID,
_CX and _CY). No such options were specified for the shape file
because the variables in Italy-RegionsCoordinates.dta comply with the
default naming conventions for shape files (_ID,
_X and _Y).

Load attribute data and associated shape file in two steps and then link them
manually using geoframe link:

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

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

geoframe create regions_shp `url'Italy-RegionsCoordinates.dta, replace

frame regions: geoframe link regions_shp

frame regions: geoframe describe

geoplot (area regions fortell), tight

Option replace has been specified so that the existing frames from the
first examples can be overwritten.

Load shape file and attribute data in two steps and then link them using
geoframe attach: An alternative to the above linking
approach is to load the shape file and the
attribute file separately and then use geoframe attach
to make the attribute data accessible directly from within the
shape frame (this requires Stata 18). Conceptually, the shape file is then
the main working frame and the attribute data is kept in an
auxiliary frame.

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

geoframe create regions `url'Italy-RegionsCoordinates.dta, replace

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

frame regions: geoframe attach regions_data

frame regions: describe

geoplot (area regions fortell), tight

An advantage of such a reversed approach is that multiple attribute frames
can be attached to the same shape frame.

Yet another approach is to load the shape file and the attribute data
separately and then use geoframe copy to copy selected
variables from the attribute data into the shape frame (not shown).

Use of option feature() for lakes and rivers:

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

geoframe create regions `url'Italy-RegionsCoordinates.dta, replace

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

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

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

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.

Also see

Online: help for
geoplot, frames, spshape2dta