help bimapbimap v1.81 (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 spmap.
Therefore it assumes that geographic boundaries are available, and you are familar with making maps in Stata.
Note that bimap only works if you have processed the shapefiles using Stata's spshape2dta command.

Syntax

bimap vary varx [if] [in], [ 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) textlabsize(num) textsize(num) formatx(str) formaty(str) xscale(num) yscale(num)
polygon(options) line(options) point(options) label(options) arrow(options) diagram(options) scalebar(options)
title(str) subtitle(str) note(str) name(str) scheme(str) ]

The options are described as follows:

Map options

bimap vary varx The command requires numeric vary and varx variables.

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 can be used if the variables are assumed categorical, for example, binary variables, 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 is also to prevent accidentally declaring a regular variable as discrete.

palette(option) In version v1.6 and above, 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. 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. Same as in spmap. Default value is 0.02. Also applied to polygons with no data.

ocolor(str) Outline color of polygons with data. Same as in spmap. Default value is white.

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

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

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

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

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

showlegend If this option is specified, then the following spmap options are enabled: legend(), legenda(), legstyle(), legjunction(), legcount(), legorder(),
legttitle(), plus additional options that can be specified for supplementary layers: polygon(), line(), point(), label().
showlegend can be used for describing additional layers, like boundaries, points, lines etc.
It is also highly recommended to turn off the base layer legend by using legenda(off) since this shows up in the bimap legend on the right.
This option is still beta, so suggestions for improvement are appreciated.

title(), subtitle(), note(), name() These are standard twoway graph 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.

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

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

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

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

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

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

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

bimap requires spmap (Pisati 2018) and palettes (Jann 2018, 2022):

ssc install spmap, replace
ssc install palettes, replace
ssc install colrspace, replace

Even if you have the packages installed, please check for updates: ado update, update.

Examples

Please see GitHub for examples.

Package details

Version : bimap v1.81
This release : 22 Aug 2023
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

Acknowledgements

Steve Johnson found a bug with missing data getting dropped (v1.81). ndsize() passthru fixed.
Paul Hufe requested changes to custom cut-offs (v1.8).
Several requests for allowing categorical variables (v1.7)
Kit Baum, Fayssal Ayad, and Paul reported bug in the bimap v1.6 legends (v1.62, v1.61).
Tyson King-Meadows and Vishakha Agarwal requested a greyscale palette (v1.5).
Souradet Shaw requested scalebar and arrow passthrus (v1.5).
Paul Frissard Martínez requested spmap legend options (v1.4).
Ruth Watkinson found an error in the grouping code (v1.3).
Pierre-Henri Bono suggested core passthrus for additional spmap layers (v1.3).
Kit Baum requested the percent option and fixes to label colors (v1.3).
Mattias Öhman found an error in cut-offs and color assignments with missing groups (v1.3).
Cristian Jordan Diaz found and error in variable name comparisons (v1.2).

Feedback

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

References

Pisati, B. (2018). spmap v1.3.2.

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.

Other visualization packages

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