help bimapbimap v2.1 (GitHub)

bimap

: A Stata package for bi-variate maps.

The package is based on the Bi-variate maps guide on Medium. The bimap command is a wrapper
for geoplot (v17+) and spmap (v16-).
The command will auto-detect the Stata version and execute the right code. Each code block comes with its own set of input requirements.
The older version can still be used by specifying the old option. The older version that relies on spmap will eventually be phased out.

The command assumes that data on geographic boundaries is available and it is set up or ready for setup. Familiarity with making maps in Stata is also assumed.
Note that bimap only works if you have processed the shapefiles using Stata's spshape2dta or the geoplot command.

The two command versions have different input requirements that are defined in the first two lines in the syntax below. The remaining code block, that determines
the cuts and how the legend is drawn, is common across the two versions. Therefore porting basic maps is fairly easy. For more advance features,
such as drawing multiple layers in geoplot, can be added by using the geo() option. Additional features such as arrows, scalebars, zooms etc can be passed on
using the geopost() options. For spmap, the old syntax just passes on individual options. This has been maintained to avoid the breaking the old code completely.

Syntax (version 17 or newer)

bimap vary varx [if] [in], frame(name)
[ geo(options) geopost(options)
palette(name) reverse clr0(str) clrx(str) clry(str) clrsaturate(num)
cut(pctile|equal) cutx(numlist) cuty(numlist) binsproper bins(num >=2) binx(num >=2) biny(num >=2) values count
percent showlegend ocolor(str) osize(str) ndocolor(str) ndfcolor(str) ndfsize(str) xdiscrete ydiscrete
labxgap(num) labygap(num) textx(str) texty(str) formatx(str) formaty(str) detail wrap(num)
textsize(str) textlabsize(str) vallabsize(str) textcolor(str) textlabcolor(str) vallabcolor(str)
xscale(num) yscale(num) * ]

Syntax (version 16 or earlier)

bimap vary varx [if] [in], shp(shapefile)
[ old polygon(str) line(str) point(str) label(str) arrow(str) diagram(str) scalebar(str)
palette(name) reverse clr0(str) clrx(str) clry(str) clrsaturate(num)
cut(pctile|equal) cutx(numlist) cuty(numlist) binsproper bins(num >=2) binx(num >=2) biny(num >=2) values count
percent showlegend ocolor(str) osize(str) ndocolor(str) ndfcolor(str) ndfsize(str) xdiscrete ydiscrete
labxgap(num) labygap(num) textx(str) texty(str) formatx(str) formaty(str) detail wrap(num)
textsize(str) textlabsize(str) vallabsize(str) textcolor(str) textlabcolor(str) vallabcolor(str)
xscale(num) yscale(num) * ]

The options are described as follows:

Map syntax

bimap vary varx, options The command requires numeric vary and varx variables. See options below for additional info.

Version 17 or newer

frame(name) The geoplot frames need to be defined before executing the bimap command. The frame() therefore
ask users to define the frame name with the plot data. This is to ensure that the command still executes regardless of which frame is active.

geo(string) This option can be used to define addition area, line or point layers. It is assumed that each layer has a frame
defined (see help geoplot) and is ready to be plotted. This can be any number of layers. Make sure that each layer is enclosed in round brackets,
for example, geo((area ..., ...) (area ..., ...) (line ..., ...)) etc.

geopost(string) Similar to geo(), geopost() can be used to pass on additional commands in geoplot.
This for example, can include zooms, legend options, arrows, scalebars etc.

Version 16 or older

old If this option is specified, the command switches to the options below regardless of the Stata version. This is to
ensure consistency and backward compatibility when using running dofiles that are setup for older command versions.

shp(shapefile) The spmap requires defining a shapefile using the shp() options. NOTE: This is a slight change from the
older bimap versions where the users previously specified bimap vary varx using shpfile. The new version requires bimap vary varx, shp(shpfile).
While this might cause some incovinience to vetran bimap users, it has been implemented to ensure syntax consistency.
The users are assumed to have the attributes file with the required data already loaded that can be merged with the shp() file
on the _ID variable. The shapefile file usually has *_shp.dta name and is automatically created while using the spshape2dta
command.

polygon(), line(), point(), label() These are spmap passthru options to draw additional layers. See help spmap for details.

arrow(), diagram(), scalebar() These are spmap passthru options for additional map options. See help spmap for details.

Map cuts and colors

cut(option) Here cut take on three options: cut(pctile) for percentiles, or cut(equal) for equally-spaced intervals. If either
cutx(), or cuty(), or are specified, then they overwrite the defined cut() options. Default is cut(pctile).

cutx(numlist), cuty(numlist) Define a custom set of cut-offs using numlist to add more control to your legend.
At least three numbers need to be specified to generate the map.

xdiscrete, ydiscrete These can be used if the variables are categorical, for example, binary or ordinally ranked variables.
These options overwrite other binning options and legend axes markers will use value labels and will be centered to bin width/height. More than 10 categories will throw an error.
Hence the maximum combination of discrete variables allowed is 10x10 or 100 bins. This also prevents accidentally declaring a regular variable as discrete which
can get computationally messy very fast.

palette(option) Palettes are dynamically generated for any number of bins(). Named palettes are:
pinkgreen, bluered, greenblue, purpleyellow, yellowblue, orangeblue. The original (legacy) palettes are still available with the following names:
pinkgreen0, bluered0, greenblue0, purpleyellow0, yellowblue0, orangeblue0, brew1, brew2, brew3,
census, rgb, viridis, gscale.
If legacy palettes are defined, the number of bins will default to 3x3 and any other custom binning options will be ignored.
See GitHub for examples of legacy palettes. Default option is palette(pinkgreen).
Users can also over-write the palettes using the clr...() options described below.

clr0(), clrx(), clry() Users can overwrite the colors end-points using one or more of these options. Option clr0() is the starting
bottom-left color. Similarly, clrx(), clry() are x-axis bottom-right and y-axis top-left colors respectively. One can either define a "named" Stata color (e.g.
named colors from s2 scheme), or they need to provide Hex values. DO NOT specify RBG values! For example, true Red has an RGB value
of "255 0 0", while its Hex code is #ff0000. In order to convert or select Hex colors, a good option is the Google Color Picker.
Otherwise, colorpalette, other softwares (including MS Paint), and websites can be used as well.

clrsaturate(num) Change the saturation of the colors. Higher values are for brighter colors. Default is clrsat(6).

reverse Swap the x- and y-axis colors. This option does not work for legacy palettes.

bins(num), binx(num), biny(num) Users can either defined nxn bins by using the option bins(n). Otherwise custom bins can
also be defined using binx() and/or biny(). The default is bin(3). Bins are constrained to a minimum dimension of 2.

osize(string) Line width of polygons. Default value is osize(0.02). Also applied to polygons with no data.

ocolor(str) Outline color of polygons with data. Default value is ocolor(white).

ndocolor(str) Outline color of polygons with no data. Default value is ndocolor(gs12).

ndfcolor(str) Fill color of polygons with no data. Default value is ndfcolor(gs8).

ndsize(str) Line width of missing observations. If no value is specified, it defaults to the osize(0.02) value.

nolegend Hide the legend. Useful if you are generating several maps with a controlled legend where one map with a legend is sufficient if combining graphs.

showlegend If this option is specified, then the geoplot and spmap options are enabled. Both commands have
fairly complex syntaxes for generating legends so please see individual helpfiles for details.

detail Show which Stata version is detected and which program is called.

* All other standard twoway options.

Legend options

count or percent Display the count or percent of categories in each box in the map legend.

values Display the cut-off values on the legend axes.

textx(str), texty(str) The axes labels of the legend. The default values are the variable names.

wrap(num) Wrap the legend title after a number of characters. Word boundaries are respected.

textsize(str) The text size of the legend axes labels. The default value is texts(3).

textlabsize(str) The text size of the axes cut-off values. The default value is textlabs(2.2).

vallabsize(str) The size of the box values. The default value is vallabs(2.2).

textcolor(str) The text color of the legend axis labels. The default value is textc(black).

textlabcolor(str) The text color of the axes cut-off values. The default value is textlabc(black).

vallabcolor(str) The text color of the box values. The default value is vallabc(black).

formatval(fmt) Format of the box values. Default format is formatval(%5.1f).

formatx(fmt), formaty(fmt) Format the values on the legend axes. Default format is formatx(%5.1f), formaty(%5.1f).

labxgap(num) The gap of the x-axis title from the default position. The default value is labxgap(0). Use in very minor increments, e.g. labxgap(0.02).

labygap(num) The gap of the y-axis title from the default position. The default value is labygap(0). Use in very minor increments, e.g. labygap(0.02).

binsproper Show actual cut-off on the axes in the legend. Otherwise equally spaced boxes are shown. The option binsproper will look
squished especially if the categories are bunched together. This will most likely cause labels to overlap.

xscale(num) The scale of the legend on the x-axis. Default value is xscale(35). This option can be used to change the legend dimensions.

yscale(num) The scale of the legend on the y-axis. Default value is yscale(100). This is an advanced option so use it with caution.

Dependencies

Stata version 17 or newer requires the following packages:
ssc install geoplot, replace
ssc install moremata, replace
ssc install palettes, replace
ssc install colrspace, replace
ssc install graphfunctions, replace

Stata version 16 or earlier requires the following packages:
ssc install spmap, replace
ssc install palettes, replace
ssc install colrspace, replace
ssc install graphfunctions, replace

Even if you have these packages installed, please reguarly check for their updates.

Examples

Please see GitHub for examples.

Package details

Version : bimap v2.1
This release : 18 Oct 2024
First release: 08 Apr 2022
Repository : GitHub
Keywords : Stata, map, bimap, bi-variate
License : MIT

Author : Asjad Naqvi
E-mail : asjadnaqvi@gmail.com
Twitter : @AsjadNaqvi

Feedback

If you find bugs and/or have feature requests, then please open an issue on GitHub.

Citation guidelines

Suggested citation guidlines for this package:

Naqvi, A. (2024). Stata package "bimap" version 2.1. Release date 18 October 2024. https://github.com/asjadnaqvi/stata-bimap.

@software{bimap,
author = {Naqvi, Asjad},
title = {Stata package ``bimap''},
url = //github.com/asjadnaqvi/stata-bimap,
version = {2.1},
date = {2024-10-18}
}

References

Pisati, B. (2007). spmap: Stata module to visualize spatial data. Available from https://ideas.repec.org/c/boc/bocode/s456812.html.

Jann, B. (2005). moremata: Stata module (Mata) to provide various functions. Available from https://ideas.repec.org/c/boc/bocode/s455001.html.

Jann, B. (2018). Color palettes for Stata graphics. The Stata Journal 18(4): 765-785.

Jann, B. (2022). Color palettes for Stata graphics: An update. University of Bern Social Sciences Working Papers No. 43.

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

Other visualization packages

arcplot, alluvial, bimap, bumparea, bumpline, circlebar, circlepack, clipgeo, delaunay, joyplot,
marimekko, polarspike, sankey, schemepack, spider, splinefit, streamplot, sunburst, treecluster, treemap, waffle

or visit GitHub for detailed documentation and examples.