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

Title

geoframe -- Command to prepare data for geoplot

Syntax

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

subcommand

Main
create load data into geoframe or declare
current frame as geoframe

use load geoframe from disk

save save geoframe to disk

describe describe geoframe

set update geoframe settings of current frame

get retrieve geoframe settings from current frame

Manage shapes
query obtain information on units and shapes in geoframe

generate generate helper variables related to shapes

select select units and shapes

Manipulate shapes
project apply projection

rescale rescale coordinates

clip clip shapes using convex window

rclip clip shapes using rectangular window

simplify simplify (generalize) shapes

refine add extra points to straight lines

Generate shapes
grid store grid lines in new frame

tissot store Tissot's indicatrices in new frame

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

bshare store shared borders in new frame

symbol generate symbol shapes and store in new frame

symboli symbol with immediate arguments

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

Merge and append
copy copy and merge variables from other frame

append append observations from other frame

stack combine multiple geoframes into one

Further utilities
rename rename geoframe

duplicate duplicate geoframe

link link shape frame to current frame

relink fix linkage variable after modifying data

unlink unlink shape frame from current frame

clean delete unmatched/empty shapes and units

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

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

Convert source
translate translate shapefile source to Stata format

convert synonym for translate

import translate and import shapefile source

Description

geoframe prepares data for use by geoplot.

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.

Subcommands

geoframe create

Syntax 1: Create geoframe from Stata source

Syntax 2: Create geoframe from ESRI or GeoJSON source

Syntax 3: Declare current frame as geoframe

Syntax 1: Create geoframe from Stata source

geoframe create [name] [using] filename
[, dta options ]

loads the data from filename into a new frame called
name, where filename is a Stata dataset, and declares the
created frame as a geoframe. If name is omitted, basename
is used as the name of the created frame, where basename is the base
name of filename. filename can be any valid Stata
dataset, but typically it is an attribute file created by
geoframe translate
(or, e.g., by command spshape2dta). Options are as follows.

dta enforces Syntax 1. Suffix .dta in filename implies
dta.

replace allows replacing existing frames.

noshp deactivates automatic loading of a shape file. By default,
if a file called basename_shp.dta is available in the
same folder as filename, it will be loaded into a secondary frame
called name_shp and the two frames will be linked. Type
noshp to suppress this behavior. Data types
shape and pc imply noshp; see option
type().

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

[[shpname] [using] shpfilename ] [, suboptions ]

where shpfilename specifies the file and shpname 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 shpname is
omitted, name_shp is used as the name for the shape
frame. suboptions are type(), id(), coordinates(),
centroids(), area(), sid(), pid(), and
plevel() as described below.

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

noclean is a synonym for nodrop.

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

current makes the created frame the current frame.

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

(1) If option type() is provided, use the specified type;

(2) else if option shp() is provided, impose type attribute;

(3) else if the type is already set in filename, use the set type;

(4) else if four names are provided in option coordinates(), impose type pc;

(5) else if a file called basename_shp.dta is available in the same folder as filemame, impose type attribute;

(6) else if a unit ID is available and the ID is nonunique, impose type shape;

(7) else impose type attribute.

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 attribute, 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 attribute, 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

Syntax 2: Create geoframe from ESRI or GeoJSON source

geoframe create [name] [using] source
[, dtype(dtype) options ]

imports an ESRI or GeoJSON shapefile source into an attribute
frame called name and a linked shape frame called
name_shp. source identifies the source to be imported. It
can be a filename with or without path (e.g. shapefiles/source/world.shp
or world.geojson), or it
can be a path without filename (e.g. shapefiles/source/), in which
case the topmost source in the specified folder will be imported. source
can also be a zip file, possibly including an internal path. For example, you can
specify shapefiles/source/world.zip to translate the source contained
in world.zip, shapefiles/source/world.zip/50m/ to translate the
source in folder 50m within world.zip, or
shapefiles/source/world.zip/50m/lakes.shp to translate lakes.shp
in folder 50m within world.zip. Options are as follows.

dtype(dtype) identifies the format of the source. dtype may be
esri (ESRI shapefile format), shp (synonym for esri),
json (GeoJSON format), or geojson (synonym for
json). Suffix .geojson or .json in source implies
dtype(geojson); else dtype(esri) is assumed.

allstring, gtype(), addmissing, and nodots as
as described for geoframe translate json, if the source
is in GeoJSON format.

replace, nodrop, noclean, nodescribe, current, and
feature() as described for Syntax 1.

Syntax 3: Declare current frame as geoframe

[frame frame:] geoframe create
[, options ]

declares the current frame as a geoframe. options are as follows.

noshp deactivates automatic linking of a shape frame. By default,
if a frame called frame_shp is in memory, it will be treated as
a shape frame to be linked to the current frame. Type
noshp to suppress this behavior. Data types
shape and pc imply noshp; see option
type().

shp(spec) specifies a custom shape frame to be linked to the current
frame. The syntax of spec is

[shpname] [, suboptions ]

where shpname is the name of the shape frame. The default for shpname
is frame_shp. suboptions are type(),
id(), coordinates(), centroids(),
area(), sid(), pid(), and plevel()
as described for Syntax 1.

nodrop, noclean, nodescribe, type(),
feature(), id(), coordinates(), centroids(),
area(), sid(), pid(), and plevel()
as described for Syntax 1.

geoframe use

geoframe use [name] [using] filename
[, options ]

loads the data from filename into a new frame called
name, where filename is a Stata dataset that has been saved by
geoframe save. If name is omitted, basename
is used as the name of the created frame, where basename is the base
name of filename. options are as follows.

replace allows replacing existing frames.

noshp deactivates automatic loading of the shape file. By default,
if filename is an attribute file and a file
called basename_shp.dta is available in the same folder,
it will be loaded into a secondary frame called name_shp and the
two frames will be linked. Type noshp to load the attribute file only.

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

current makes the created frame the current frame.

geoframe use is implemented as a wrapper for
geoframe create. Typing
geoframe use filename is equivalent to
geoframe create filename, dta noclean.

geoframe save

[frame frame:]
geoframe save [filename] [if] [in] [, options ]

saves the current frame on disk under the name filename (with
extension .dta). If filename is omitted, frame.dta is
used, where frame is the name of the current frame. Use the if and
in qualifiers to
restrict the observations of the current frame to be saved (and include only
the shapes of the selected units in the shape file). options are as follows.

replace allows replacing existing files.

noshp deactivates automatic saving of the shape frame. By default,
if the current frame is linked to a shape frame, the shape frame is stored
on disk under the same name with extension _shp.dta. Type noshp to store
the attribute frame only.

ifshp(exp) specifies an if condition to restrict
the observations of the shape frame to be saved (and, in the main file, include
only units with a nonzero selection in the shape frame). ifshp() is
not allowed together with noshp.

geoframe describe

[frame frame:] geoframe describe

displays the geoframe settings of the current frame. Alternatively, type

geoframe describe frame

to display the settings of frame frame.

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
attribute (attribute data), pc (paired-coordinates data),
or shape (shape data)

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 attribute and shape) or four (for data type pc) variable names; default is
_X _Y for data type shape, _CX _CY for data type attribute,
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
attribute, 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 macro called
lname instead of displaying it.

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 shape items; the default

items number of shape items by geometry type

gtype synonmy for items

direction orientation of shape items

orientation synonym for direction

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. The following scalars are returned in r().

r(units) number of units

r(items) number of shape items

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

Number of shape items by geometry type

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

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

r(items) total number of shape items

r(Polygon) number of polygon items (four or more points and first
point equal to last point)

r(LineString) number of line items (four or more points and
first point unequal last point, two points, or three points)

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

r(Empty) number of empty items (missing)

geoframe query gtype is a synonym for geoframe query items.

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)

Lines are trated like polygons. geoframe query orientation is a
synonym for geoframe query direction.

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 pading(), rotate, hull, circle,
n(), angle(), noadjust, and
noshp as described in geoframe bbox. The following
results are returned.

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 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 as follows.

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

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

direction generate direction indicator for shape items in shape frame

orientation synonym for geoframe generate direction

plevel generate enclave/exclaves identifier in shape frame

shpmatch generate indicator in current frame
for match of unit 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 the area in hectares, or type scale(1000)
to obtain the area 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 ID

geoframe generate pid [PID] [, replace noset ]

generates a variable identifying the different polygons or other shape items
within each unit. If the current frame is linked to a shape frame,
geoframe generate pid will be applied to the linked 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.

Geometry types of shape items

geoframe generate gtype [GTYPE] [, replace nolabel ]

generates a variable identifying the geometry type of each shape
item: 1 = Point, 2 = LineString, 3 = Polygon, 0 = Empty (item contains missing
only). If the current frame is linked to a shape frame,
geoframe generate gtype will be applied to the linked 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.

Orientation of shape items

geoframe generate direction [DIR] [, replace nolabel ]

generates a variable identifying the orientation of each shape
item: 1 = positive (counterclockwise), -1 = negative (clockwise), 0 = undetermined
(item has less than 3 unique points). If the current frame is linked to a shape frame,
geoframe generate direction will be applied to the linked 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.

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 shape
items. If the current frame is linked to a shape frame,
geoframe generate plevel will be applied to the linked 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 shape items
across all units in the data. Use option by() to stratify the search, for example,
if the data contains separate regions without overlap or if the data contains 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 items 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 items in this
order. The algorithm used by geoframe generate plevel assumes
that items do not overlap (i.e. no crossings). 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
item). 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 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 is linked to a
shape frame, a corresponding selection will also be applied to
the shape frame and the linkage between the frames will be
updated. 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 is linked 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 is linked 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 is linked to a 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.

geoframe project

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

transforms the coordinates of the selected shapes by applying the specified
projection. If the current frame is linked to a shape frame, the coordinates
in both the current frame and the shape frame will be translated. For a general
introduction to map projections
see en.wikipedia.org/wiki/Map_projection;
for an extensive list of projections see
en.wikipedia.org/wiki/List_of_map_projections).

The following projections are currently supported by geoframe project. Input
coordinates are assumed to represent latitude (Y) and
longitude (X) in degrees (typically WGS84); Y values outside +/- 90 will
clipped before applying the projection (unless noted otherwise). The names
of the projections can be abbreviated and typed in lower- or uppercase
letters (if abbreviation is ambiguous, the first match in the list will be
used).

Cylindrical

webmercator [zoom x0] Web Mercator
projection (the default), where
zoom sets the zoom level (default is 0, resulting in an equator
length of 256 pixels; set the zoom level to 1 for 512 pixels, 2
for 1024 pixels, etc.);
Y values outside +/- 85.051129 will be clipped before applying the
projection

mercator [r x0] Mercator
projection (spherical earth model)

emercator [r x0 m] Mercator
projection (ellipsoid earth model), where
m sets the inverse flattening parameter (default is 298.257223563,
corresponding to WGS 84)

miller [r x0] Miller cylindrical
projection

gallstereo [r x0] Gall stereographic
projection

lambert [r x0 S] Lambert cylindrical equal-area
projection, where S sets the stretch factor
(default is 1; see
en.wikipedia.org/wiki/Cylindrical_equal-area_projection)

behrmann [r x0] Behrmann
projection; equal to lambert with S = 0.75

hobodyer [r x0] Hobo–Dyer
projection; equal to lambert with S = cos(37.5 * _pi / 180)^2

gallpeters [r x0] Gall–Peters
projection; equal to lambert with S = 0.5

peters [r x0] synonym for gallpeters

equirectangular [y1 r x0 y0] Equirectangular
(equidistant cylindrical) projection; no clipping will be applied

Pseudocylindrical

robinson [r x0] Robinson
projection

equalearth [r x0] Equal Earth
projection

naturalearth [r x0] Natural Earth
projection

Pseudoazimuthal

winkeltripel [y1 r x0] Winkel tripel
projection; default for y1 is 180/_pi*acos(2/_pi)

hammer [r x0] Hammer
projection

Conic

conic [y1 y2 r x0 y0] Equidistant conic
(simple conic) projection

albers [y1 y2 r x0 y0] Albers equal-area conic
projection

lambertconic [y1 y2 r x0 y0] Lambert conformal conic
projection

Azimuthal

orthographic [r x0 y0] Orthographic
projection; Y values outside y0 +/- 90 and X values outside x0 +/- 90 will
be clipped before applying the projection (note that such clipping of individual
coordinates can lead to artifacts at the edges of the displayed hemisphere; preferably,
use geoframe rclip to clip the shapes to the relevant
range before applying geoframe project orthographic)

Legend:

y1 the (first) standard parallel (in degrees); default is 0 (unless noted otherwise)

y2 the second standard parallel (in degrees); default is 60

r the scale of the projection (earth radius); default is 1

x0 the central meridian (in degrees); default is 0

y0 the central parallel (in degrees); default is 0

options are as follows.

radian indicates that the input coordinates (and arguments x0,
y0, y1, y1) are in radians, not in degrees.

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 the
current frame is linked to a 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.

replace allows into() to overwrite existing frames.

fast does not restore the original data should the user press
Break. fast is intended for use by programmers. fast has
no effect if into() is specified.

current makes the created frame the current frame.

geoframe rescale

[frame frame:] geoframe rescale
[sx [sy]] [if] [in]
[, x0(x0)
y0(y0) options ]

transforms the coordinates of the selected shapes as follows:

X' = (X - x0) * sx
Y' = (Y - y0) * sy

The default for sx is 1; sy is set to sx if omitted;
the default for x0 and y0 is 0. If the current frame is
linked to a shape frame, the coordinates in both the current frame and
the shape frame will be transformed. options are xy(),
ifshp(), noshp, into(), replace, fast,
and current as described for geoframe project.

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
polygon (or a set of polygons). Specify line, to clip a polygon in
such a way that the result is a line (or a set of lines), unless the
polygon lies entirely within the clipping window. 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.

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 entirely within the window.

nosplit changes the behavior of noclip. By default, noclip
selects or excludes each shape item individually. Specify nosplit to treat shape
items that belong to the same unit 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.

ifshp(exp) specifies an if condition to be applied to
the linked shape frame. ifshp() is only allowed
if the current frame is linked to a shape frame.

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 the selected shapes will be copied.

replace allows into() to overwrite existing frames.

fast does not restore the original data should the user press
Break. fast is intended for use by programmers. fast has
no effect if into() is specified.

current makes the created frame the current 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 is a numlist
providing the minimum and maximum of X and Y in the following order:

xmin xmax ymin ymax

Element in limits that are omitted or specified as . (missing) are
treated as (minus) infinity. 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. Rectangular
clipping is a special case of convex clipping.

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; see option
absolute below. 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. 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.

[no]refine[([delta] [, absolute])]
omits refinement or sets the degree of refinement. The simplification algorithm removes
points on long straight lines, which may lead to undesired artifacts
when applying projections. Therefore, by default, geoframe simplify calls
geoframe refine after simplifying the shapes so that extra points
are added back in on long edges. Use option refine() to determine the degree of
refinement, with argument delta and suboption absolute
as described for geoframe refine. Type norefine
to omit refinement after simplification.

nodrop, nodots, ifshp(), into(), replace,
fast, and current as described for geoframe clip.

Note that geoframe simplify drops all point items
(unless the threshold is zero). Line items that are simplified to two points will
be dropped unless their length is at least 2*sqrt(2*d), where d is the
threshold. Polygon items that are simplified to two points will be dropped.

geoframe simplify cannot be used with paired-coordinates data.

geoframe refine

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

refines the selected shapes by adding extra points within edges 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 in such a way that a diagonal
across the map has 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, ifshp(), into(), replace,
fast, and current as described for geoframe clip.

geoframe refine cannot be used with paired-coordinates data.

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 is 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. The default
depends on option y(); if x() is omitted, the number of
vertical lines is determined in a way such that the spacing between vertical lines
is similar to the spacing between horizontal lines. Specify x(#0)
to omit vertical lines.

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(#7) (unless x() is specified, in which case the default number of
horizontal lines is determined in a way such that the spacing between horizontal lines
is similar to the spacing between vertical lines). Specify y(#0)
to omit horizontal lines.

tight omits rounding of the position of the grid lines. This is only
relevant for positions that are determined automatically, not for custom
positions. By default, geoframe grid determines the range and spacing
of the grid lines in a way such that each grid line is placed at a nice (rounded)
value. This implies that the grid will typically be somewhat larger than the
range of the data. Type tight to omit the rounding and generate a grid
that tightly fits the data.

padding(marginexp) adds padding to the range of the grid. This is
only relevant for positions that are determined automatically, not for
custom positions. The values in marginexp are in percent of the size
of the map in each direction. For example, type padding(5) to
increase the range of the grid 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). padding() implies tight.

radian indicates that coordinates are in radians. This is only
relevant for positions that are determined automatically, not for custom
positions. If radian is specified, rounding is performed on a
transformed scale such that the grid lines are placed at nice values in
degrees. radian has no effect if tight is specified.

noextend omits extending the length of lines to cover the data
range (including padding; negative padding will reduce the length of the
lines). If noextend is specified, the lines will
only be drawn within the limits of the requested grid.

mesh omits the first and last line on each axis (if there are 3 or more
lines).

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 existing frames.

current makes the created frame the current frame.

geoframe tissot

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

generates Tissot's indicatrices covering the range of the selected shapes
(whose coordinates are assumed to be unprojected and in
degrees) 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 is linked to a
shape frame. options are as follows.

r(#), with #>0, to set a custom radius for the indicatrices. The default
radius depends on the spacing of the indicatrices.

x(), y(), tight, padding(), n(),
noshp, replace, and current as described for
geoframe grid, with the following differences. Default
for y() is #5 rather than #7; y(#0) and
y(#0) are not allowed; the values in y(numlist) must
be in [-90,90] or, if radian has been specified, in [-pi/2,pi/2];
option radian, apart of affecting automatic positioning, makes sure
that the indicatrices are generated in a way that is consistent with data
in radians.

Tissot's indicatrices are used to illustrate characteristics of
projections; see
en.wikipedia.org/wiki/Tissot's_indicatrix.

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 is linked to a
shape frame. options are as follows.

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.

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

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.

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

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

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.

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

replace allows overwriting existing frames.

current makes the created frame the current frame.

geoframe bshare

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

extracts shared borders from 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. A shared border is defined as a
sequence of vertices that exists in two shape items (irrespective of
direction). The current frame may be a shape frame or an attribute frame
that is linked to a shape frame. options are as follows.

unique omits duplicates. By default, each shared border is included
twice (possibly with different orientation), once for each of the two shape
items that share the border. Specify unique to keep only one of the two
copies. Only one of unique, endpoints, and
not is allowed.

endpoints extracts start and end points of shared
borders only. Only one of unique, endpoints, and
not is allowed.

not extracts non-shared borders rather than shared borders. That is,
from each shape item all sequences of vertices are extracted that do not
exist in any other item. Only one of unique, endpoints, and
not is allowed.

nodots suppresses the progress dots that are displayed by default.

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

replace allows overwriting existing frames.

current makes the created frame the current frame.

geoframe bshare cannot be used with paired-coordinates data.

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 existing frames.

current makes the created frame the current frame.

geoframe symboli

geoframe symboli newname [newshpname]
immediate_values [, options ]

creates symbol shapes at specified positions
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.

immediate_values is one or more of

#_x #_y [[[*]size]]

where #_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. options
are as follows.

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

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

replace allows overwriting existing frames.

current makes the created frame the current frame.

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 units 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 data from the current frame to be
considered. The default is to use all data. Specify
select(exp) to consider only data 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 unit 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 as 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 reverse logic of the syntax compared to
geoframe collapse) and stores the unit 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 data from frame2 that will be
considered in the spatial join. The default is to use all data. Specify
select(exp) to consider only data 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 spjoin cannot be used with paired-coordinates data.

geoframe copy

[frame frame:] geoframe copy frame2
varlist [if] [in] [, options ]

copies variables from frame2 (source frame) into the current
frame (target frame), where varlist specifies the variables to be
copied and the if and in qualifiers select the observations
to be considered from frame2 (all obervations by default).

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). 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 suitable geoframe link exists between the two frames (and neither
if nor in is specified), 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.

relax causes variables that already exist in the current frame to be
skipped. The default is to abort with error if a variable already exists.

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.

unique aborts with error if frame2 is not unique.

The number of copied variables is returned in scalar r(k). The (target)
names of the copied variables are returned in r(varlist).

geoframe append

[frame frame:] geoframe append frame2
[varlist] [if] [in] [, options ]

appends the selected 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. options are as follows.

raw appends raw data only, without copying labels or display
formats. By default, geoframe append complements variable labels
for variables that do not yet have a label, merges value label definitions
for variables that have value labels, and copies display formats for new
variables. Specify raw to copy only the data, ignoring labels and
display formats.

force allows string variables to be appended to numeric variables and
vice versa, applying functions real() or strofreal()
to transform data, respectively.

target(namelist) specifies alternative variable names to be used
in the current frame. 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.

touse(varname) 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. touse() is intended for use by programmers.

fast does not restore the original data should the user press
Break. fast is intended for use by programmers.

geoframe stack

geoframe stack framelist [, options ]

stacks the data of the specified frames and also creates
a stacked shape frame if any of the specified frames is linked to a
shape frame. framelist must contain at least two names. A new
_ID variable will be generated to identify the units in the stacked frame
(replacing the existing IDs; other geoframe settings will be taken from
the first frame). Furthermore, variable _FRAME will be
added, containing the name of the source frame for each
observation. options are as follows.

force allows string variables to be appended to numeric variables and
vice versa, applying functions real() or strofreal()
to transform data, respectively.

noshp causes linked shape frames to be ignored. That is, if noshp
is specified, no stacked shape frame will be created even if the frames in
framelist contain links to shape frames.

into(newname [newshpname]) specifies a custom name for the frame
containing the stacked data (and a custom name for the stacked shape data;
newname_shp is used if newshpname is omitted). By default,
newname is set to the first name in framelist.

replace allows replacing existing frames. replace is required
if into() is omitted.

current makes the created frame the current frame.

drop drops the source frames from memory after appending them.

geoframe rename

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

renames the current frame to newname and, if the current frame is linked
to a shape frame, renames the shape frame to newshpname; newname_shp
is used as name for the shape frame if newshpname is omitted.

noshp renames the current frame only even if the current frame is
linked to a shape frame.

replace allows overwriting existing frames.

Renaming geoframes using official Stata's frame rename is discouraged
as this will break links created by geoframe. Use
geoframe rename to make sure that the links will be preserved.

geoframe duplicate

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

copies the current frame to a new frame called newname and, if the
current frame is linked to a shape frame, copies the shape frame to a new
frame called newshpname; newname_shp is used as name for
the shape frame if newshpname is omitted. options are as follows.

noshp copies the current frame only even if the current frame is
linked to a shape frame. A link to the original shape frame will be
established in the copied frame.

unlink does not establish a link to a shape frame in the copied
frame. unlink implies noshp.

replace allows overwriting existing frames.

current makes the created frame the current frame.

Copying geoframes using official Stata's frame copy is discouraged
as this will break links created by created by geoframe. Use
geoframe duplicate to make sure that the links will be preserved.

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 a single
shape frame may contain incoming links from multiple attribute frames.)

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

geoframe relink

[frame frame:] geoframe relink

rebuilds an existing link to a shape frame that has been created in the
current frame by geoframe. 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. If the current frame does not contain
a link to a shape frame, geoframe unlink has no effect.

geoframe clean

[frame frame:] geoframe clean
[, options ]

removes unmatched shapes and units if applied to an attribute frame that
is linked 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 delete 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 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.

geoframe translate

geoframe translate [translator] ...

translates shapefile source data to Stata format, where translator specifies
the type of translation. Available translators are:

esri translate ESRI shapefile (the default)

shp synonym for geoframe translate esri

json translate GeoJSON shapefile

geojson synonym for geoframe translate json

wkt translate WKT (well-known text) geometries

geoframe convert is a synonym for geoframe translate.

ESRI shapefile

geoframe translate [esri] [path][name] [using]
source [, options ]

translates an ESRI format shapefile to Stata format (using commands
import_shp and import_dbase). Translator esri
is implied unless source contains a .geojson or .json
suffix. Arguments and options are as follows.

path specifies an optional destination path for the translated data
(e.g. shapefiles/dta/). The working directory is used if path is
omitted. Argument path is not allowed if option
toframe is specified.

name provides a custom name for the translated
data. The base name of the source file will be used if name is
omitted. If option toframe is specified, frames
name and name_shp will be created. If option toframe
is omitted files name.dta and
name_shp.dta will be created in the directory identified by
path.

source identifies the source to be translated. It can be
a filename with or without path (e.g. countries.shp
or shapefiles/source/countries; the file suffix is optional),
or it can be a path without filename (e.g. shapefiles/source/). If the
specified directory contains multiple source files,
the topmost source will be translated.

source can also be a zip file. For example, you can
specify shapefiles/source/countries.zip to translate the source
contained in countries.zip. If the zip file contains multiple source
files, the topmost source will be translated. Alternatively, you can specify an internal path
(e.g. world.zip/50m/) and/or name pointing to the source to be translated
(e.g. world.zip/countries.shp or world.zip/50m/countries; again, the
file suffix is optional).

replace allows overwriting existing files or frames.

toframe writes the translated data into frames instead of saving them in
files on disk. This is equivalent to translating the data and then
loading them using geoframe create, but without
generating any files.

nodescribe, current, feature(), nodrop, and
noclean as described for geoframe create. These
options are only allowed if option toframe is specified.

GeoJSON shapefile

geoframe translate [json] [path][name] [using]
source [, options ]

translates a GeoJSON format shapefile to Stata format (see
https://en.wikipedia.org/wiki/GeoJSON). Arguments
path, name, and source are as described for
geoframe translate esri (apart from file
suffix). Translator json
is implied if source contains file suffix .geojson or
.json. options are as follows.

allstring imports all attributes as string variables.

gtype(newvar) adds a variable to the attribute file that contains
the geometry type of each unit (1 = Point, 2 = LineString, 3 = Polygon, 4 =
MultiPoint, 5 = MultiLineString, 6 = MultiPolygon, 7 = GeometryCollection).

addmissing adds missing rows between point geometries. In the
translated data, each line or polygon will start with a row of missing values
so that the different shape items can be distinguished by geoplot. By
default, such missing rows are omitted for items obtained from a Point or
MultiPoint object (unless the objects are part of a GeometryCollection). Specify
addmissing to treat points in the same way as lines and polygons.

nodots suppresses the progress dots that are displayed by default.

replace, toframe, nodescribe, current,
feature(), nodrop, and noclean as for
geoframe translate esri.

WKT geometries

geoframe translate wkt [path]name geomvar
[if] [in] [, options ]

where arguments path and name are as described for
geoframe translate esri (except that name
is not optional) and geomvar is the name of a string variable
containing WKT geometry
definitions. That is, the source data is assumed to be in memory (e.g.
imported from a CSV or Excel file), with one of the variables containing
the WKT geometry definitions. An attribute file or frame and a shape file
or frame is then created from this data. Units that do not satisfy the
if and in qualifiers will not be considered. Options
are as described for geoframe translate json (except
addmissing, which is not allowed).

geoframe import

geoframe import [translator] ...

translates shapefile source data to Stata format and loads it into
frames. This is equivalent to translating the data using
geoframe translate and then
loading the translated data using
geoframe create, but without generating any files.

geoframe import is implemented by calling
geoframe translate with option
toframe. Syntax and options are identical to
geoframe translate (with option
toframe assumed)

Examples

Load attribute data and associated shape file:

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)

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).

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.