diff --git a/CITATION.cff b/CITATION.cff index f3b7faf..f9c1b15 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -3,6 +3,6 @@ authors: - family-names: "Naqvi" given-names: "Asjad" title: "Stata package ``bimap''" -version: 1.9 -date-released: 2024-06-19 +version: 2.0 +date-released: 2024-08-22 url: "https://github.com/asjadnaqvi/stata-bimap" diff --git a/README.md b/README.md index f8d3b36..0d6d5c9 100644 --- a/README.md +++ b/README.md @@ -9,31 +9,45 @@ -# bimap v1.9 -(19 Jun 2024) +# bimap v2.0 +(22 Aug 2024) This package provides the ability to draw bi-variate maps in Stata. It is based on the [Bi-variate maps Guide](https://medium.com/the-stata-guide/stata-graphs-bi-variate-maps-b1e96dd4c2be). +As of version 2.0 (released on 22nd August 2024), **bimap** uses **geoplot** for Stata versions 17 or newer, and **spmap** for Stata versions 16 or earlier. Users with newer versions can still opt to use the original **spmap** implementation by defining the original code (with minor changes, see below) and using the option `old`. Information on which version is detected and which map package is used can be displayed by using the `detail` option. + +As more and more users switch to newer Stata versions, the **spmap** implementation will eventually be phased out. As of v2.0 it will no longer be developed further. + ## Installation The package can be installed via SSC or GitHub. The GitHub version, *might* be more recent due to bug fixes, feature updates etc, and *may* contain syntax improvements and changes in *default* values. See version numbers below. Eventually the GitHub version is published on SSC. All examples are updated to the latest version and might not be compatible with the old ones. Please check the documentation and change logs. -The package can be installed from SSC (**v1.82**): +The package can be installed from SSC (**v1.9**): ``` ssc install bimap, replace ``` -Or it can be installed from GitHub (**v1.9**): +Or it can be installed from GitHub (**v2.0**): ``` net install bimap, from("https://raw.githubusercontent.com/asjadnaqvi/stata-bimap/main/installation/") replace ``` +For using the command with `geoplot` the following packages are required: -The `spmap` and `palettes` package is required to run this command: +```stata +ssc install geoplot, replace +ssc install moremata, replace +ssc install palettes, replace +ssc install colrspace, replace -``` +``` + + +For using the command with `spmap` the following packages are required: + +```stata ssc install spmap, replace ssc install palettes, replace ssc install colrspace, replace @@ -41,14 +55,21 @@ ssc install colrspace, replace Even if you have these packages installed, please check for updates: `ado update, update`. -If you want to make a clean figure, then it is advisable to load a clean scheme. I personally use the following: +*Optional*: Users can also install the `geo2xy` package for projection transformations, even though `geoplot` supports projects internally as well: + +```stata +ssc install geo2xy, replace +``` + + +*Optional*: If you want to make a clean figure, then it is advisable to load a clean scheme. I personally use the following: ``` ssc install schemepack, replace set scheme white_tableau ``` -You can also push the scheme directly into the graph using the `scheme(schemename)` option. See the help file for details or the example below. +You can also push the scheme directly into the graph using the `scheme(schemename)` option. I also prefer narrow fonts in figures with long labels. You can change this as follows: @@ -56,32 +77,53 @@ I also prefer narrow fonts in figures with long labels. You can change this as f graph set window fontface "Arial Narrow" ``` -This command is a wrapper for `spmap` and assumes that you have shapefiles in Stata and are comfortable with making maps. - -## Syntax +## Syntax for Stata versions 17 or newer The syntax for the latest version is as follows: ```stata -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) formatx(str) formaty(str) - textsize(str) textlabsize(str) vallabsize(str) textcolor(str) textlabcolor(str) vallabcolor(str) - xscale(num) yscale(num) polygon(options) line(options) point(options) label(options) arrow(options) - diagram(options) scalebar(options) * ] +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) + textsize(str) textlabsize(str) vallabsize(str) textcolor(str) textlabcolor(str) vallabcolor(str) + xscale(num) yscale(num) * ] ``` -See the help file `help bimap` for details. +with the following minimal syntax requirement: -The most basic use is as follows: +``` +bimap vary varx, frame(framename) +``` + + +## Syntax for Stata versions 16 or older + +```stata +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) + textsize(str) textlabsize(str) vallabsize(str) textcolor(str) textlabcolor(str) vallabcolor(str) + xscale(num) yscale(num) * ] ``` -bimap vary varx using *shapefile* + +with the following minimal syntax requirement: + +``` +bimap vary varx, shp(shapefile) ``` -See helpfile for further details +Note that v2.0 changes the use of the shapefile syntax. This might be a minor inconvinience for older users of bimap. + +See `help bimap` for details. + ## Citation guidelines @@ -94,15 +136,15 @@ Software packages take countless hours of programming, testing, and bug fixing. author = {Naqvi, Asjad}, title = {Stata package ``bimap''}, url = {https://github.com/asjadnaqvi/stata-bimap}, - version = {1.9}, - date = {2024-06-19} + version = {2.0}, + date = {2024-08-22} } ``` *or simple text* ``` -Naqvi, A. (2024). Stata package "bimap" version 1.9. Release date 19 June 2024. https://github.com/asjadnaqvi/stata-bimap. +Naqvi, A. (2024). Stata package "bimap" version 2.0. Release date 22 August 2024. https://github.com/asjadnaqvi/stata-bimap. ``` @@ -113,27 +155,53 @@ Naqvi, A. (2024). Stata package "bimap" version 1.9. Release date 19 June 2024. ## Examples +The examples showcase both the syntax for the use with `geoplot` (first syntax) and `spmap` (second syntax). The map outputs have been aligned to the extent possible but very minor differences in outputs might remain. Additionally, as `geoplot` is still in active development, output might break with latest updates or syntax might change. Please report these as soon as possible. + +Since I am using Stata 18 or newer versions, I have to specify `old` option to pass the syntax to use `spmap`. This might be uncessary if you have older Stata versions. + Download the files from [GIS](./GIS/) and dump them in a folder. Set up the data: +```stata +COPY THE FILES FROM THE DIRECTORY IN YOUR FOLDER + +ADD CODE FOR THE FOLLOWING FILES +county // baseline attributes file +county_shp2 // projected shape file +state // baseline state file +state_shp2 // projected shape file +usa_county2 // additional data + ``` -clear -set scheme white_tableau -graph set window fontface "Arial Narrow" -// set the directory to the GIS folder -// cd +Test whether the `geoplot` is working properly. First set up the layer frames: + + +```stata + +// create the geoframes +geoframe create county, replace shp(county_shp2) +geoframe create state, replace shp(state_shp2) +geoframe create cities usa_county2, replace shp(county_shp2) // minor example of pairing with point location data. + +// make the country frame active +frames change county + -use county, clear destring _all, replace merge 1:1 STATEFP COUNTYFP using county_race keep if _m==3 drop _m +``` -save usa_county2.dta, replace ``` +geoplot (area county share_afam) (line state) +``` + + + Test whether the `spmap` is working properly: @@ -145,38 +213,63 @@ spmap share_afam using county_shp2, id(_ID) clm(custom) clb(0(10)100) fcolor(Hea +## Basic bimap + +Let's test the `bimap` command: + +``` +bimap share_hisp share_afam, frame(county) cut(pctile) palette(pinkgreen) +``` + ``` -spmap share_hisp using county_shp2, id(_ID) clm(custom) clb(0(10)100) fcolor(Heat) +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(pinkgreen) ``` - + + -Let's test the `bimap` command: ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(pinkgreen) +bimap share_hisp share_afam , frame(county) cut(pctile) palette(pinkgreen) count values ``` - - ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(pinkgreen) count values +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(pinkgreen) count values ``` + + + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(pinkgreen) percent values +bimap share_hisp share_afam , cut(pctile) palette(pinkgreen) percent values frame(county). ``` + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(pinkgreen) percent values +``` + + + + +``` +bimap share_hisp share_afam, frame(county) cut(equal) palette(pinkgreen) count values +``` + + ``` -bimap share_hisp share_afam using county_shp2, cut(equal) palette(pinkgreen) count values +bimap share_hisp share_afam, shp(county_shp2) old cut(equal) palette(pinkgreen) count values ``` + + @@ -184,16 +277,26 @@ bimap share_hisp share_afam using county_shp2, cut(equal) palette(pinkgreen) cou These old palettes can still be used and will default to 3x3 bins. -``` + +```stata local i = 1 foreach x in pinkgreen0 bluered0 greenblue0 purpleyellow0 yellowblue0 orangeblue0 brew1 brew2 brew3 census rgb viridis gscale { - bimap share_hisp share_afam using county_shp2, cut(pctile) palette(`x') percent title("Legacy scheme: `x'") - graph export bimap3_`i'.png, replace wid(2000) + bimap share_hisp share_afam, frame(county) cut(pctile) palette(`x') percent title("Legacy scheme: `x'") + + local ++i +} +``` + +```stata +local i = 1 + +foreach x in pinkgreen0 bluered0 greenblue0 purpleyellow0 yellowblue0 orangeblue0 brew1 brew2 brew3 census rgb viridis gscale { - local i = `i' + 1 + bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(`x') percent title("Legacy scheme: `x'") + local ++i } ``` @@ -207,43 +310,88 @@ foreach x in pinkgreen0 bluered0 greenblue0 purpleyellow0 yellowblue0 orangeblue ### Advanced examples ``` -bimap share_asian share_afam using county_shp2, cut(pctile) palette(bluered) /// +bimap share_asian share_afam, cut(pctile) palette(bluered) frame(county) /// + title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// + textx("Share of African Americans") texty("Share of Asians") texts(3.5) textlabs(3) values count /// + osize(none) geo((line state)) +``` + + +``` +bimap share_asian share_afam, shp(county_shp2) old cut(pctile) palette(bluered) /// title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// textx("Share of African Americans") texty("Share of Asians") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(white) osize(0.3)) ``` + + ``` -bimap share_asian share_afam using county_shp2, cut(pctile) palette(yellowblue) /// +bimap share_asian share_afam, cut(pctile) palette(orangeblue) frame(county) /// + title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// + textx("Share of African Americans") texty("Share of Asians") texts(3.5) textlabs(3) values count /// + osize(none) geo((line state, lc(white) lw(0.2))) +``` + + + +``` +bimap share_asian share_afam, shp(county_shp2) old cut(pctile) palette(yellowblue) /// title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// textx("Share of African Americans") texty("Share of Asians") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + ``` -bimap share_asian share_hisp using county_shp2, cut(pctile) palette(orangeblue) /// +bimap share_asian share_hisp, cut(pctile) palette(orangeblue) frame(county) /// + title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// + textx("Share of Hispanics") texty("Share of Asians") texts(3.5) textlabs(3) values count /// + osize(none) geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_asian share_hisp, shp(county_shp2) old cut(pctile) palette(orangeblue) /// title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// textx("Share of Hispanics") texty("Share of Asians") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + -Since `bimap` is a wrapper of `spmap`, we can pass information for other layers as well including dots. Below we use the file we saved in the first step to plot the population of counties: +### Passing advanced options + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(pinkgreen) percent /// + +bimap share_hisp share_afam, cut(pctile) palette(pinkgreen) percent frame(county) /// + title("{fontface Arial Bold:A Stata bivariate map}") /// + note("Data from the US Census Bureau. Counties with population > 100k plotted as proportional dots.", size(1.8)) /// + textx("Share of African Americans") texty("Share of Hispanics") texts(3.5) textlabs(3) values /// + osize(none) /// + geo( (line state, lc(black) lw(0.2)) (point cities [w = tot_pop] if tot_pop>1e5, mc(lime%80) msize(0.8) lc(black)) ) +``` + + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(pinkgreen) percent /// title("{fontface Arial Bold:A Stata bivariate map}") /// note("Data from the US Census Bureau. Counties with population > 100k plotted as proportional dots.", size(1.8)) /// textx("Share of African Americans") texty("Share of Hispanics") texts(3.5) textlabs(3) values /// @@ -252,6 +400,9 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(pinkgreen) pe point(data("usa_county2") x(_CX) y(_CY) select(keep if tot_pop>100000) proportional(tot_pop) psize(absolute) fcolor(lime%85) ocolor(black) osize(0.12) size(0.9) ) ``` + + + @@ -261,13 +412,23 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(pinkgreen) pe Let's make a `bimap` with percentiles as cut-offs and percentages shown in boxes: ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values percent /// + osize(none) geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values percent /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + @@ -275,50 +436,97 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) we can now modify the cut-offs as follows: + ``` -bimap share_hisp share_afam using county_shp2, cuty(0(20)100) cutx(0(20)100) palette(orangeblue) /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values percent /// + osize(none) geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cuty(0(20)100) cutx(0(20)100) palette(orangeblue) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values percent /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + Cut-offs can be formatted as follows: + ``` -bimap share_hisp share_afam using county_shp2, cuty(0(25)100) cutx(0(25)100) formatx(%3.0f) formaty(%3.0f) palette(orangeblue) /// +bimap share_hisp share_afam, cuty(0(25)100) cutx(0(25)100) formatx(%3.0f) formaty(%3.0f) palette(orangeblue) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// + osize(none) geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cuty(0(25)100) cutx(0(25)100) formatx(%3.0f) formaty(%3.0f) palette(orangeblue) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + If we define only one custom cut-off, the other will automatically take on the pctile values: + ``` -bimap share_hisp share_afam using county_shp2, cutx(0 2 6 100) formatx(%5.0f) palette(orangeblue) /// +bimap share_hisp share_afam, cutx(0 2 6 100) formatx(%5.0f) palette(orangeblue) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values percent /// + osize(none) geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cutx(0 2 6 100) formatx(%5.0f) palette(orangeblue) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values percent /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + ### legend checks + offset (v1.8) -`spmap` legend options can be passed to `bimap` to describe additional layers: ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(census) /// +bimap share_hisp share_afam, cut(pctile) palette(census) frame(county) /// + note("Data from the US Census Bureau.", size(small)) /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.2) textlabs(3) values percent labxgap(0.05) labygap(0.05) /// + ocolor(black) osize(0.03) /// + geo((line state, lc(black) lw(0.2))) showlegend /// + geopost( /// + compass /// + sbar(length(1000) units(km) position(sw)) /// + ) +``` + + + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(census) /// note("Data from the US Census Bureau.", size(small)) /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.2) textlabs(3) values percent /// ocolor(black) osize(0.03) /// @@ -327,11 +535,14 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(census) /// showleg legenda(off) legend(pos(7) size(5)) legstyle(2) ``` + + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(census) /// +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(census) /// note("Data from the US Census Bureau.", size(small)) /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.2) textlabs(3) values percent labxgap(0.05) labygap(0.05) /// ocolor(black) osize(0.03) /// @@ -340,6 +551,8 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(census) /// showleg legenda(off) legend(pos(7) size(5)) legstyle(2) ``` + + @@ -348,38 +561,71 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(census) /// Check for legend color options: ``` -bimap share_asian share_afam using county_shp2, cut(pctile) /// +bimap share_asian share_afam, cut(pctile) frame(county) /// title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// textx("Share of African Americans") texty("Share of Asians") values count textcolor(lime) textlabcolor(blue) vallabc(red) /// - ocolor() osize(none) /// + osize(none) /// + geo((line state, lc(white) lw(0.3))) +``` + + +``` +bimap share_asian share_afam, shp(county_shp2) old cut(pctile) /// + title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// + textx("Share of African Americans") texty("Share of Asians") values count textcolor(lime) textlabcolor(blue) vallabc(red) /// + osize(none) /// polygon(data("state_shp2") ocolor(white) osize(0.3)) ``` + + Check for label wrapping in the legend: + ``` -bimap share_asian share_afam using county_shp2, cut(pctile) /// +bimap share_asian share_afam, cut(pctile) frame(county) /// title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// textx("Share of African Americans") texty("Share of Asians") wrap(16) values count /// - ocolor() osize(none) /// + osize(none) /// + geo((line state, lc(white) lw(0.3))) +``` + +``` +bimap share_asian share_afam, shp(county_shp2) old cut(pctile) /// + title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// + textx("Share of African Americans") texty("Share of Asians") wrap(16) values count /// + osize(none) /// polygon(data("state_shp2") ocolor(white) osize(0.3)) ``` + + + Check for hiding the legend: +``` +bimap share_asian share_afam, cut(pctile) frame(county) /// + title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// + osize(none) /// + geo((line state, lc(white) lw(0.3))) nolegend +``` + ``` -bimap share_asian share_afam using county_shp2, cut(pctile) /// +bimap share_asian share_afam, shp(county_shp2) old cut(pctile) /// title("{fontface Arial Bold:A Stata bivariate map}") note("Data from the US Census Bureau.") /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(white) osize(0.3)) nolegend ``` + + + @@ -388,7 +634,17 @@ bimap share_asian share_afam using county_shp2, cut(pctile) /// If condition checks with legends ``` -bimap share_hisp share_afam using county_shp2 if STATEFP==36, cut(pctile) palette(census) /// +bimap share_hisp share_afam if STATEFP==36, cut(pctile) palette(census) frame(county) /// + title("New York") /// + note("Data from the US Census Bureau.", size(small)) /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.2) textlabs(3) values percent /// + ocolor(black) osize(0.03) /// + geo((line state if _ID==19, lc(black) lw(0.2))) nolegend +``` + + +``` +bimap share_hisp share_afam if STATEFP==36, shp(county_shp2) old cut(pctile) palette(census) /// title("New York") /// note("Data from the US Census Bureau.", size(small)) /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.2) textlabs(3) values percent /// @@ -397,79 +653,161 @@ bimap share_hisp share_afam using county_shp2 if STATEFP==36, cut(pctile) palett showleg legenda(off) legend(pos(7) size(5)) legstyle(2) ``` + + ### v1.6 updates ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) bins(5) /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) bins(5) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) bins(5) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) binx(4) biny(5) /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) binx(4) biny(5) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) binx(4) biny(5) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) binx(3) biny(8) /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) binx(3) biny(8) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) binx(3) biny(8) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) bins(8) /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) bins(8) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) bins(8) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.1)) ``` + + + +``` +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) bins(8) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) reverse bins(8) /// +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) reverse bins(8) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) clr0(white) clrx(red) bins(6) clrsat(10) /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) clr0(white) clrx(red) bins(6) clrsat(10) frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) clr0(white) clrx(red) bins(6) clrsat(10) /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + ``` -bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) bins(4) percent /// +bimap share_hisp share_afam, cut(pctile) palette(orangeblue) bins(4) percent frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old cut(pctile) palette(orangeblue) bins(4) percent /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + @@ -477,14 +815,26 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(orangeblue) b Bins can be scaled to show actual division. Use this cautiously especially if the data distribution is highly skewed. + +``` +bimap share_hisp share_afam, cuty(0 20 60 100) cutx(0 30 50 75 100) palette(orangeblue) formatx(%5.0f) formaty(%5.0f) binsproper frame(county) /// + note("Data from the US Census Bureau.") /// + texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// + osize(none) /// + geo((line state, lc(black) lw(0.2))) +``` + + ``` -bimap share_hisp share_afam using county_shp2, cuty(0 20 60 100) cutx(0 30 50 75 100) palette(orangeblue) formatx(%5.0f) formaty(%5.0f) binsproper /// +bimap share_hisp share_afam, shp(county_shp2) old cuty(0 20 60 100) cutx(0 30 50 75 100) palette(orangeblue) formatx(%5.0f) formaty(%5.0f) binsproper /// note("Data from the US Census Bureau.") /// texty("Share of Hispanics") textx("Share of African Americans") texts(3.5) textlabs(3) values count /// ocolor() osize(none) /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + @@ -510,42 +860,69 @@ tab discy discx, m We can also now declare these variables as discrete while using `bimap` in any combination: ``` -bimap discy share_afam using county_shp2, palette(yellowblue) values count ydisc +bimap discy share_afam, palette(yellowblue) values count ydisc frame(county) +``` + + +``` +bimap discy share_afam, shp(county_shp2) old palette(yellowblue) values count ydisc ``` + + + + +``` +bimap share_hisp discx, palette(yellowblue) values count xdisc frame(county) +``` ``` -bimap share_hisp discx using county_shp2, palette(yellowblue) values count xdisc +bimap share_hisp discx, shp(county_shp2) old palette(yellowblue) values count xdisc ``` + + ``` -bimap discy discx using county_shp2, palette(yellowblue) values count xdisc ydisc +bimap discy discx, palette(yellowblue) values count xdisc ydisc frame(county) +``` + + +``` +bimap discy discx, shp(county_shp2) old palette(yellowblue) values count xdisc ydisc ``` + + -### missing data fixed (v1.81) +### missing data (v1.81) ``` -use county, clear -destring _all, replace -merge 1:1 STATEFP COUNTYFP using county_race -keep if _m==3 -drop _m - replace share_hisp = . if stname=="Texas" +``` -bimap share_hisp share_afam using county_shp2, palette(orangeblue) /// +``` +bimap share_hisp share_afam, palette(orangeblue) frame(county) /// + ndfcolor(pink) ndocolor(lime) ndsize(0.2) /// + values count /// + geo((line state, lc(black) lw(0.2))) +``` + + +``` +bimap share_hisp share_afam, shp(county_shp2) old palette(orangeblue) /// ndfcolor(pink) ndocolor(lime) ndsize(0.3) /// values count /// polygon(data("state_shp2") ocolor(black) osize(0.2)) ``` + + ## Feedback @@ -555,6 +932,12 @@ Please open an [issue](https://github.com/asjadnaqvi/stata-bimap/issues) to repo ## Change log +**v2.0 (22 August 2024)** +- Major update. Support for `geoplot` for Stata versions 17 or newer. Support for `spmap` for Stata versions 16 or older. Versions are auto detected. +- Minor change in syntax for `spmap` versions from `bimap y x using shapefile` to `bimap y x, shp(shapefile)`. This is to ensure consistency for upcoming releases. +- Stata 17 or newer users can use the option `old` to call in the `spmap` version. This ensures that the code of seasoned `bimap` users does not break. +- Option `detail` added to show which Stata version is detected and which map program is used. This might be useful in case you want to have more information. + **v1.9 (19 June 2024)** - Fixed and added several options to control legends: `textcolor()`, `textlabcolor()`, `vallabcolor()`. - Better options for `textsize()`, `textlabsize()`, `vallabsize()`. diff --git a/figures/bimap10.png b/figures/bimap10.png index ab866dd..5979b21 100644 Binary files a/figures/bimap10.png and b/figures/bimap10.png differ diff --git a/figures/bimap10_geo.png b/figures/bimap10_geo.png new file mode 100644 index 0000000..838b787 Binary files /dev/null and b/figures/bimap10_geo.png differ diff --git a/figures/bimap11.png b/figures/bimap11.png index 827a848..0075d2a 100644 Binary files a/figures/bimap11.png and b/figures/bimap11.png differ diff --git a/figures/bimap11_geo.png b/figures/bimap11_geo.png new file mode 100644 index 0000000..288bd25 Binary files /dev/null and b/figures/bimap11_geo.png differ diff --git a/figures/bimap12.png b/figures/bimap12.png index e57e50f..ba09d61 100644 Binary files a/figures/bimap12.png and b/figures/bimap12.png differ diff --git a/figures/bimap12_1.png b/figures/bimap12_1.png index f89b972..38a6cb7 100644 Binary files a/figures/bimap12_1.png and b/figures/bimap12_1.png differ diff --git a/figures/bimap12_2.png b/figures/bimap12_2.png index e79d9a0..5a0b118 100644 Binary files a/figures/bimap12_2.png and b/figures/bimap12_2.png differ diff --git a/figures/bimap12_2_geoplot.png b/figures/bimap12_2_geoplot.png new file mode 100644 index 0000000..8cf3007 Binary files /dev/null and b/figures/bimap12_2_geoplot.png differ diff --git a/figures/bimap12_3.png b/figures/bimap12_3.png index 80be7df..6259cf6 100644 Binary files a/figures/bimap12_3.png and b/figures/bimap12_3.png differ diff --git a/figures/bimap12_3_geoplot.png b/figures/bimap12_3_geoplot.png new file mode 100644 index 0000000..a91cda4 Binary files /dev/null and b/figures/bimap12_3_geoplot.png differ diff --git a/figures/bimap12_4.png b/figures/bimap12_4.png index 102f074..656f55e 100644 Binary files a/figures/bimap12_4.png and b/figures/bimap12_4.png differ diff --git a/figures/bimap12_4_geoplot.png b/figures/bimap12_4_geoplot.png new file mode 100644 index 0000000..cf86efd Binary files /dev/null and b/figures/bimap12_4_geoplot.png differ diff --git a/figures/bimap12_geoplot.png b/figures/bimap12_geoplot.png new file mode 100644 index 0000000..eb256bb Binary files /dev/null and b/figures/bimap12_geoplot.png differ diff --git a/figures/bimap13.png b/figures/bimap13.png index 9911897..a8b4b3b 100644 Binary files a/figures/bimap13.png and b/figures/bimap13.png differ diff --git a/figures/bimap13_geoplot.png b/figures/bimap13_geoplot.png new file mode 100644 index 0000000..4d423e2 Binary files /dev/null and b/figures/bimap13_geoplot.png differ diff --git a/figures/bimap14.png b/figures/bimap14.png new file mode 100644 index 0000000..dff1d24 Binary files /dev/null and b/figures/bimap14.png differ diff --git a/figures/bimap15.png b/figures/bimap15.png index 813bbfd..2448d58 100644 Binary files a/figures/bimap15.png and b/figures/bimap15.png differ diff --git a/figures/bimap15_geoplot.png b/figures/bimap15_geoplot.png new file mode 100644 index 0000000..466d924 Binary files /dev/null and b/figures/bimap15_geoplot.png differ diff --git a/figures/bimap16.png b/figures/bimap16.png index d05547e..b937fb7 100644 Binary files a/figures/bimap16.png and b/figures/bimap16.png differ diff --git a/figures/bimap16_geoplot.png b/figures/bimap16_geoplot.png new file mode 100644 index 0000000..72e0e5b Binary files /dev/null and b/figures/bimap16_geoplot.png differ diff --git a/figures/bimap17.png b/figures/bimap17.png index 204f391..625f8ee 100644 Binary files a/figures/bimap17.png and b/figures/bimap17.png differ diff --git a/figures/bimap17_geoplot.png b/figures/bimap17_geoplot.png new file mode 100644 index 0000000..d619fdc Binary files /dev/null and b/figures/bimap17_geoplot.png differ diff --git a/figures/bimap18.png b/figures/bimap18.png index c63c413..b3106fd 100644 Binary files a/figures/bimap18.png and b/figures/bimap18.png differ diff --git a/figures/bimap18_geoplot.png b/figures/bimap18_geoplot.png new file mode 100644 index 0000000..4e1660c Binary files /dev/null and b/figures/bimap18_geoplot.png differ diff --git a/figures/bimap19.png b/figures/bimap19.png index 5a8ed40..7013ed7 100644 Binary files a/figures/bimap19.png and b/figures/bimap19.png differ diff --git a/figures/bimap19_geoplot.png b/figures/bimap19_geoplot.png new file mode 100644 index 0000000..4e1660c Binary files /dev/null and b/figures/bimap19_geoplot.png differ diff --git a/figures/bimap1_1.png b/figures/bimap1_1.png index 5bdcfd0..b149ca0 100644 Binary files a/figures/bimap1_1.png and b/figures/bimap1_1.png differ diff --git a/figures/bimap1_2.png b/figures/bimap1_2.png index a3fcd5a..c8d0048 100644 Binary files a/figures/bimap1_2.png and b/figures/bimap1_2.png differ diff --git a/figures/bimap2.png b/figures/bimap2.png index a4af906..01ce9d0 100644 Binary files a/figures/bimap2.png and b/figures/bimap2.png differ diff --git a/figures/bimap20.png b/figures/bimap20.png index 599a148..dd1865a 100644 Binary files a/figures/bimap20.png and b/figures/bimap20.png differ diff --git a/figures/bimap20_geoplot.png b/figures/bimap20_geoplot.png new file mode 100644 index 0000000..d651e2a Binary files /dev/null and b/figures/bimap20_geoplot.png differ diff --git a/figures/bimap21.png b/figures/bimap21.png index 59f5407..0ea9379 100644 Binary files a/figures/bimap21.png and b/figures/bimap21.png differ diff --git a/figures/bimap21_geoplot.png b/figures/bimap21_geoplot.png new file mode 100644 index 0000000..834b36b Binary files /dev/null and b/figures/bimap21_geoplot.png differ diff --git a/figures/bimap22.png b/figures/bimap22.png index cc52532..a1b25e1 100644 Binary files a/figures/bimap22.png and b/figures/bimap22.png differ diff --git a/figures/bimap22_geoplot.png b/figures/bimap22_geoplot.png new file mode 100644 index 0000000..77447db Binary files /dev/null and b/figures/bimap22_geoplot.png differ diff --git a/figures/bimap23_1.png b/figures/bimap23_1.png index 15f65bd..b61a328 100644 Binary files a/figures/bimap23_1.png and b/figures/bimap23_1.png differ diff --git a/figures/bimap23_1_geoplot.png b/figures/bimap23_1_geoplot.png new file mode 100644 index 0000000..7fdaf7b Binary files /dev/null and b/figures/bimap23_1_geoplot.png differ diff --git a/figures/bimap23_2.png b/figures/bimap23_2.png index ef4e694..bb0a11b 100644 Binary files a/figures/bimap23_2.png and b/figures/bimap23_2.png differ diff --git a/figures/bimap23_2_geoplot.png b/figures/bimap23_2_geoplot.png new file mode 100644 index 0000000..d474c2b Binary files /dev/null and b/figures/bimap23_2_geoplot.png differ diff --git a/figures/bimap23_3.png b/figures/bimap23_3.png index 4755906..008eeeb 100644 Binary files a/figures/bimap23_3.png and b/figures/bimap23_3.png differ diff --git a/figures/bimap23_3_geoplot.png b/figures/bimap23_3_geoplot.png new file mode 100644 index 0000000..19b49ef Binary files /dev/null and b/figures/bimap23_3_geoplot.png differ diff --git a/figures/bimap24.png b/figures/bimap24.png index 54b1bee..270f86b 100644 Binary files a/figures/bimap24.png and b/figures/bimap24.png differ diff --git a/figures/bimap24_geoplot.png b/figures/bimap24_geoplot.png new file mode 100644 index 0000000..270f86b Binary files /dev/null and b/figures/bimap24_geoplot.png differ diff --git a/figures/bimap2_1.png b/figures/bimap2_1.png index 8d73adb..4cf63d9 100644 Binary files a/figures/bimap2_1.png and b/figures/bimap2_1.png differ diff --git a/figures/bimap2_1_1.png b/figures/bimap2_1_1.png index e28960e..f6a7a77 100644 Binary files a/figures/bimap2_1_1.png and b/figures/bimap2_1_1.png differ diff --git a/figures/bimap2_1_1_geo.png b/figures/bimap2_1_1_geo.png new file mode 100644 index 0000000..4eea041 Binary files /dev/null and b/figures/bimap2_1_1_geo.png differ diff --git a/figures/bimap2_1_geo.png b/figures/bimap2_1_geo.png new file mode 100644 index 0000000..de88aaa Binary files /dev/null and b/figures/bimap2_1_geo.png differ diff --git a/figures/bimap2_2.png b/figures/bimap2_2.png index 22e72ee..f079842 100644 Binary files a/figures/bimap2_2.png and b/figures/bimap2_2.png differ diff --git a/figures/bimap2_2_geo.png b/figures/bimap2_2_geo.png new file mode 100644 index 0000000..5791b62 Binary files /dev/null and b/figures/bimap2_2_geo.png differ diff --git a/figures/bimap2_geo.png b/figures/bimap2_geo.png new file mode 100644 index 0000000..2ab3263 Binary files /dev/null and b/figures/bimap2_geo.png differ diff --git a/figures/bimap3_1.png b/figures/bimap3_1.png index 8a9b0db..4332516 100644 Binary files a/figures/bimap3_1.png and b/figures/bimap3_1.png differ diff --git a/figures/bimap3_10.png b/figures/bimap3_10.png index 0dd7bf9..93facd8 100644 Binary files a/figures/bimap3_10.png and b/figures/bimap3_10.png differ diff --git a/figures/bimap3_10_geo.png b/figures/bimap3_10_geo.png new file mode 100644 index 0000000..029b458 Binary files /dev/null and b/figures/bimap3_10_geo.png differ diff --git a/figures/bimap3_11.png b/figures/bimap3_11.png index 9d39f5e..d58eba7 100644 Binary files a/figures/bimap3_11.png and b/figures/bimap3_11.png differ diff --git a/figures/bimap3_11_geo.png b/figures/bimap3_11_geo.png new file mode 100644 index 0000000..e8605f1 Binary files /dev/null and b/figures/bimap3_11_geo.png differ diff --git a/figures/bimap3_12.png b/figures/bimap3_12.png index be3502b..c9442f2 100644 Binary files a/figures/bimap3_12.png and b/figures/bimap3_12.png differ diff --git a/figures/bimap3_12_geo.png b/figures/bimap3_12_geo.png new file mode 100644 index 0000000..469990d Binary files /dev/null and b/figures/bimap3_12_geo.png differ diff --git a/figures/bimap3_13.png b/figures/bimap3_13.png index 8eed407..e79fb43 100644 Binary files a/figures/bimap3_13.png and b/figures/bimap3_13.png differ diff --git a/figures/bimap3_13_geo.png b/figures/bimap3_13_geo.png new file mode 100644 index 0000000..f8ac74e Binary files /dev/null and b/figures/bimap3_13_geo.png differ diff --git a/figures/bimap3_1_geo.png b/figures/bimap3_1_geo.png new file mode 100644 index 0000000..37a39a3 Binary files /dev/null and b/figures/bimap3_1_geo.png differ diff --git a/figures/bimap3_2.png b/figures/bimap3_2.png index 96e611d..f8e5e28 100644 Binary files a/figures/bimap3_2.png and b/figures/bimap3_2.png differ diff --git a/figures/bimap3_2_geo.png b/figures/bimap3_2_geo.png new file mode 100644 index 0000000..9cbda02 Binary files /dev/null and b/figures/bimap3_2_geo.png differ diff --git a/figures/bimap3_3.png b/figures/bimap3_3.png index b4c664e..f0fec11 100644 Binary files a/figures/bimap3_3.png and b/figures/bimap3_3.png differ diff --git a/figures/bimap3_3_geo.png b/figures/bimap3_3_geo.png new file mode 100644 index 0000000..a5d7ce5 Binary files /dev/null and b/figures/bimap3_3_geo.png differ diff --git a/figures/bimap3_4.png b/figures/bimap3_4.png index cbf1a82..dc4fd85 100644 Binary files a/figures/bimap3_4.png and b/figures/bimap3_4.png differ diff --git a/figures/bimap3_4_geo.png b/figures/bimap3_4_geo.png new file mode 100644 index 0000000..f885888 Binary files /dev/null and b/figures/bimap3_4_geo.png differ diff --git a/figures/bimap3_5.png b/figures/bimap3_5.png index c5886cc..89e58cd 100644 Binary files a/figures/bimap3_5.png and b/figures/bimap3_5.png differ diff --git a/figures/bimap3_5_geo.png b/figures/bimap3_5_geo.png new file mode 100644 index 0000000..a4b6fa7 Binary files /dev/null and b/figures/bimap3_5_geo.png differ diff --git a/figures/bimap3_6.png b/figures/bimap3_6.png index a2b17d3..f261428 100644 Binary files a/figures/bimap3_6.png and b/figures/bimap3_6.png differ diff --git a/figures/bimap3_6_geo.png b/figures/bimap3_6_geo.png new file mode 100644 index 0000000..c8f0308 Binary files /dev/null and b/figures/bimap3_6_geo.png differ diff --git a/figures/bimap3_7.png b/figures/bimap3_7.png index d425ac5..2447691 100644 Binary files a/figures/bimap3_7.png and b/figures/bimap3_7.png differ diff --git a/figures/bimap3_7_geo.png b/figures/bimap3_7_geo.png new file mode 100644 index 0000000..d26c2ba Binary files /dev/null and b/figures/bimap3_7_geo.png differ diff --git a/figures/bimap3_8.png b/figures/bimap3_8.png index 193bff2..9917dcb 100644 Binary files a/figures/bimap3_8.png and b/figures/bimap3_8.png differ diff --git a/figures/bimap3_8_geo.png b/figures/bimap3_8_geo.png new file mode 100644 index 0000000..123737e Binary files /dev/null and b/figures/bimap3_8_geo.png differ diff --git a/figures/bimap3_9.png b/figures/bimap3_9.png index 6ff8775..8a387e4 100644 Binary files a/figures/bimap3_9.png and b/figures/bimap3_9.png differ diff --git a/figures/bimap3_9_geo.png b/figures/bimap3_9_geo.png new file mode 100644 index 0000000..27ecc14 Binary files /dev/null and b/figures/bimap3_9_geo.png differ diff --git a/figures/bimap4.png b/figures/bimap4.png index d6c1d53..140461b 100644 Binary files a/figures/bimap4.png and b/figures/bimap4.png differ diff --git a/figures/bimap4_geo.png b/figures/bimap4_geo.png new file mode 100644 index 0000000..34b6a83 Binary files /dev/null and b/figures/bimap4_geo.png differ diff --git a/figures/bimap6.png b/figures/bimap6.png index 098cd09..64db798 100644 Binary files a/figures/bimap6.png and b/figures/bimap6.png differ diff --git a/figures/bimap6_geo.png b/figures/bimap6_geo.png new file mode 100644 index 0000000..9291e89 Binary files /dev/null and b/figures/bimap6_geo.png differ diff --git a/figures/bimap7.png b/figures/bimap7.png index f6b19b1..25ea8bd 100644 Binary files a/figures/bimap7.png and b/figures/bimap7.png differ diff --git a/figures/bimap7_geo.png b/figures/bimap7_geo.png new file mode 100644 index 0000000..1eb6223 Binary files /dev/null and b/figures/bimap7_geo.png differ diff --git a/figures/bimap8.png b/figures/bimap8.png index d40cbd4..e7212ff 100644 Binary files a/figures/bimap8.png and b/figures/bimap8.png differ diff --git a/figures/bimap8_geo.png b/figures/bimap8_geo.png new file mode 100644 index 0000000..9c44f6a Binary files /dev/null and b/figures/bimap8_geo.png differ diff --git a/figures/bimap9.png b/figures/bimap9.png index 071d942..21e49e1 100644 Binary files a/figures/bimap9.png and b/figures/bimap9.png differ diff --git a/figures/bimap9_0.png b/figures/bimap9_0.png index b469fb9..5cd360b 100644 Binary files a/figures/bimap9_0.png and b/figures/bimap9_0.png differ diff --git a/figures/bimap9_0_geo.png b/figures/bimap9_0_geo.png new file mode 100644 index 0000000..a844ab1 Binary files /dev/null and b/figures/bimap9_0_geo.png differ diff --git a/figures/bimap9_geo.png b/figures/bimap9_geo.png new file mode 100644 index 0000000..fdf495d Binary files /dev/null and b/figures/bimap9_geo.png differ diff --git a/installation/bimap.ado b/installation/bimap.ado index 02ed41f..9db16f8 100644 --- a/installation/bimap.ado +++ b/installation/bimap.ado @@ -1,6 +1,7 @@ -*! bimap v1.9 (19 Jun 2024) +*! bimap v2.0 (22 Aug 2024) *! Asjad Naqvi (asjadnaqvi@gmail.com) +* v2.0 (22 Aug 2024): Port to geoplot for newer stata versions. frame() geo() geopost() added for geoplot. /using swapped with shp() for spmap. * v1.9 (19 Jun 2024): Fixed some minor bugs. Nolegend option added. wrap() added for label wrapping. * v1.82 (04 May 2024): textcolor() added for legend labels. updates to various defaults * v1.81 (22 Aug 2023): Fixed a bug where missing data was getting dropped. ndsize() passthru fixed. @@ -29,42 +30,74 @@ * https://medium.com/the-stata-guide/stata-graphs-bi-variate-maps-b1e96dd4c2be -// add checks for number of bins in xdisc, ydisc -// pass on values labels correctly - cap program drop bimap program bimap, sortpreserve -version 15 +*version 15 - syntax varlist(min=2 max=2 numeric) [if] [in] using/ /// - [ , cut(string) palette(string) ] /// + syntax varlist(min=2 max=2 numeric) [if] [in] /// + [ , cut(string) palette(string) ] /// [ count percent BOXsize(real 8) textx(string) texty(string) formatx(string) formaty(string) xscale(real 35) yscale(real 100) TEXTLABSize(string) TEXTSize(string) values ] /// [ polygon(passthru) line(passthru) point(passthru) label(passthru) ] /// - [ ocolor(string) osize(string) ] /// - [ ndocolor(string) ndsize(string) ndfcolor(string) ] /// + [ ocolor(string) osize(string) ndocolor(string) ndsize(string) ndfcolor(string) ] /// [ cutx(numlist min=1) cuty(numlist min=1) SHOWLEGend ] /// // 1.4 updates [ LEGend(passthru) legenda(passthru) LEGStyle(passthru) LEGJunction(passthru) LEGCount(passthru) LEGOrder(passthru) LEGTitle(passthru) ] /// // 1.4 legend controls as passthru [ arrow(passthru) diagram(passthru) scalebar(passthru) ] /// // 1.5 [ bins(numlist min=1 >=2) binx(numlist min=1 >=2) biny(numlist min=1 >=2) reverse clr0(string) clrx(string) clry(string) CLRSATurate(real 6) binsproper FORMATVal(string) VALLABSize(string) ] /// // 1.6 [ XDISCrete YDISCrete ] /// // v1.7 options [ labxgap(real 0) labygap(real 0) ] /// // v1.8 options - [ TEXTColor(string) TEXTLABColor(string) VALLABColor(string) NOLEGend wrap(numlist >=0 max=1) * ] // v1.82, v1.9 - + [ TEXTColor(string) TEXTLABColor(string) VALLABColor(string) NOLEGend wrap(numlist >=0 max=1) * ] /// // v1.82, v1.9 + [ geo(string) geopost(string) frame(string) old shp(string) details ] // v2.0 -- stata 18+ options for geoplot - if (substr(reverse("`using'"),1,4) != "atd.") local using "`using'.dta" // from spmap to check for extension - capture confirm file "`using'" - if _rc { - di as err "{p}File {bf:`using'} not found{p_end}" - exit 601 - } + local myver = `c(version)' // check dependencies + + if `myver' >= 17 & "`old'"=="" { + + if "`details'" != "" { + noi display in yellow "Stata `myver' detected. Using {stata help geoplot:geoplot} package." + } + + if "`frame'" == "" { + display as error "For calling geoplot, option {it:frame()} is required. See {stata help bimap:help}." + exit + } + + capture findfile geoplot.ado + if _rc != 0 { + di as error "geoplot package is missing. Click here to install {stata ssc install geoplot, replace:geoplot}." + exit + } + + capture findfile colorpalette.ado + if _rc != 0 { + di as error "The {bf:palettes} package is missing. Click here to install {stata ssc install palettes, replace:palettes} and {stata ssc install colrspace, replace:colrspace}." + exit + } + + /* + capture findfile moremata.ado + if _rc != 0 { + di as error "The {bf:moremata} package is missing. Click here to install {stata ssc install moremata, replace:moremata}." + exit + } + */ + + } + else { + + if "`old'" != "" local oldtxt (but option old specified) + + if "`details'" != "" { + noi display in yellow "Stata `myver' detected `oldtxt'. Using {stata help spmap:spmap} package." + } + capture findfile spmap.ado if _rc != 0 { di as error "spmap package is missing. Click here to install {stata ssc install spmap, replace:spmap}." @@ -76,6 +109,24 @@ version 15 di as error "The {bf:palettes} package is missing. Click here to install {stata ssc install palettes, replace:palettes} and {stata ssc install colrspace, replace:colrspace}." exit } + + + if "`shp'" == "" { + display as error "For calling spmap, option {it:shp()} is required. See {stata help bimap:help} file." + exit + } + + if (substr(reverse("`shp'"),1,4) != "atd.") local shp "`shp'.dta" // from spmap to check for extension + + capture confirm file "`shp'" + if _rc { + di as err "{p}File {bf:`shp'} not found{p_end}" + exit 601 + } + + } + + marksample touse, strok novarlist gettoken var2 var1 : varlist // var1 = x, var2 = y @@ -88,6 +139,7 @@ version 15 exit } + if "`count'" != "" & "`percent'" != "" { di as error "Please specify either {it:count} or {it:percent}. See {stata help bimap:help file}." exit @@ -105,15 +157,13 @@ version 15 ***** Get the cuts -qui { +quietly { preserve keep if `touse' keep `varlist' _ID tempvar cat_`var1' cat_`var2' - - summ `var1', meanonly local xmin = r(min) local xmax = r(max) @@ -245,7 +295,7 @@ qui { levelsof `cat_`var1'' if r(r) > 10 { - di as err "Maximum categories allowed are 10. `var1' has `r(r)' categories." + di as err "Maximum 10 categories allowed. `var1' has `r(r)' categories." exit 198 } @@ -264,7 +314,7 @@ qui { levelsof `cat_`var2'' if r(r) > 10 { - di as err "Maximum categories allowed are 10. `var2' has `r(r)' categories." + di as err "Maximum 10 categories allowed. `var2' has `r(r)' categories." exit 198 } @@ -441,7 +491,8 @@ qui { ***** store the cut-offs for labels - + + if "`count'" != "" { forval i = 1/`binx' { @@ -466,7 +517,8 @@ qui { } } } - + + if "`polygon'" == "" { local polyadd @@ -486,7 +538,7 @@ qui { local nds = cond("`ndsize'" == "", "`lw'", "`ndsize'") - local leg = cond("`showlegend'"=="", "legend(off)", "`legend'") + local leg = cond("`showlegend'"=="", "legend(off)", "") if "`clr0'" != "" local cl0 `clr0' @@ -502,8 +554,10 @@ qui { local cly `tempx' } + gen cuts = `grp_cut' - // finally the map! + + // finally the map if `check'==0 { local cutst = `binx' * `biny' @@ -522,27 +576,52 @@ qui { local cutst = 9 } - if "`nolegend'" != "" { - spmap `grp_cut' using "`using'", /// - id(_ID) clm(custom) clb(0(1)`cutst') fcolor("`colors'") /// - ocolor(`lc' ..) osize(`lw' ..) /// - ndocolor(`ndo' ..) ndsize(`nds' ..) ndfcolor(`ndf' ..) /// - `polygon' `line' `point' `label' /// - `leg' `legstyle' `legenda' `legendstyle' `legjunction' `legcount' `legorder' `legtitle' /// // v1.4 legend passthrus - `arrow' `diagram' `scalebar' `options' + + if `myver' >= 17 & "`old'"=="" { + + + if "`nolegend'" != "" { + geoplot /// + (area `frame' `grp_cut', discrete cuts(1(1)`cutst') color("`colors'") lcolor(`lc') lwidth(`lw') missing(color(`ndf') lc(`ndo') lw(`nds')) nolegend ) /// + `geo' /// + , `leg' tight `geopost' `options' + + exit + + } + else { + + geoplot /// + (area `frame' `grp_cut', discrete cuts(1(1)`cutst') color("`colors'") lcolor(`lc') lwidth(`lw') missing(color(`ndf') lc(`ndo') lw(`nds')) nolegend ) /// + `geo' /// + , `leg' tight `geopost' name(_map, replace) nodraw + } - exit } else { + + if "`nolegend'" != "" { + spmap `grp_cut' using "`shp'", /// + id(_ID) clm(custom) clb(0(1)`cutst') fcolor("`colors'") /// + ocolor(`lc' ..) osize(`lw' ..) /// + ndocolor(`ndo' ..) ndsize(`nds' ..) ndfcolor(`ndf' ..) /// + `polygon' `line' `point' `label' /// + `leg' `legstyle' `legenda' `legendstyle' `legjunction' `legcount' `legorder' `legtitle' /// // v1.4 legend passthrus + `arrow' `diagram' `scalebar' `options' + + exit + } + else { - spmap `grp_cut' using "`using'", /// - id(_ID) clm(custom) clb(0(1)`cutst') fcolor("`colors'") /// - ocolor(`lc' ..) osize(`lw' ..) /// - ndocolor(`ndo' ..) ndsize(`nds' ..) ndfcolor(`ndf' ..) /// - `polygon' `line' `point' `label' /// - `leg' `legstyle' `legenda' `legendstyle' `legjunction' `legcount' `legorder' `legtitle' /// // v1.4 legend passthrus - `arrow' `diagram' `scalebar' /// // v1.5 passthrus + spmap `grp_cut' using "`shp'", /// + id(_ID) clm(custom) clb(0(1)`cutst') fcolor("`colors'") /// + ocolor(`lc' ..) osize(`lw' ..) /// + ndocolor(`ndo' ..) ndsize(`nds' ..) ndfcolor(`ndf' ..) /// + `polygon' `line' `point' `label' /// + `leg' `legstyle' `legenda' `legendstyle' `legjunction' `legcount' `legorder' `legtitle' /// // v1.4 legend passthrus + `arrow' `diagram' `scalebar' /// // v1.5 passthrus name(_map, replace) nodraw + } } */ @@ -663,7 +742,6 @@ qui { replace x_mid = . if tag!=1 replace y_mid = . if tag!=1 - if "`count'" != "" | "`percent'" != "" { gen mycount = . @@ -675,19 +753,17 @@ qui { } } - local marksym mycount - + local marksym mycount } - if "`formatval'" =="" local formatval "%5.1f" - if "`percent'" != "" { + if "`percent'" != "" { gen mycount2 = string(mycount, "`formatval'") + "%" if mycount!=. - local marksym mycount2 } + // markers @@ -701,7 +777,7 @@ qui { local z = 1 forval i0 = 1/`xlen' { replace x_mark = `: word `i0' of `xcats'' in `z' - replace x_val = `: word `i0' of `xlist'' in `z' + replace x_val = `: word `i0' of `xlist'' in `z' local z = `z' + 1 } } @@ -710,7 +786,7 @@ qui { local z = 1 forval i0 = 1/`xlen' { - replace x_mark = `: word `i0' of `xcats'' in `z' + replace x_mark = `: word `i0' of `xcats'' in `z' replace x_val = `: word `i0' of `xdiscli'' in `z' local z = `z' + 1 } @@ -744,9 +820,6 @@ qui { } - - - // rescale x and y (0-1) summ x, meanonly @@ -839,19 +912,19 @@ qui { foreach x of local lvls { - local boxes `boxes' (area y x if box==`x', nodropbase cmissing(n) fi(100) fc("`r(p`x')'") lc(white) lw(none) ) /// + local boxes `boxes' (area y x if box==`x', nodropbase cmissing(n) fi(100) fc("`r(p`x')'") lc(white) lw(none) ) } if "`count'" != "" | "`percent'" != "" { - local mylabels (scatter y_mid x_mid, mlabel(`marksym') mlabpos(0) mcolor(none) mlabsize(`vallabsize') mlabcolor(`vallabcolor') ) /// // labels + local mylabels (scatter y_mid x_mid, mlabel(`marksym') mlabpos(0) mcolor(none) mlabsize(`vallabsize') mlabcolor(`vallabcolor') ) // labels } if "`values'" != "" { - local xvals (scatter y0 x_mark, mcolor(none) mlabel(x_val) mlabpos(6) mcolor(gs6) msize(0.2) mlabsize(`textlabsize') mlabcolor(`textlabcolor') ) /// + local xvals (scatter y0 x_mark, mcolor(none) mlabel(x_val) mlabpos(6) mcolor(gs6) msize(0.2) mlabsize(`textlabsize') mlabcolor(`textlabcolor') ) - local yvals (scatter y_mark x0, mcolor(none) mlabel(y_val) mlabpos(9) mcolor(gs6) msize(0.2) mlabsize(`textlabsize') mlabcolor(`textlabcolor') ) /// + local yvals (scatter y_mark x0, mcolor(none) mlabel(y_val) mlabpos(9) mcolor(gs6) msize(0.2) mlabsize(`textlabsize') mlabcolor(`textlabcolor') ) } @@ -883,10 +956,10 @@ qui { graph combine _map _legend, /// imargin(zero) `options' +*/ -} -*/ +} end diff --git a/installation/bimap.pkg b/installation/bimap.pkg index 6bbce9b..0462b8c 100644 --- a/installation/bimap.pkg +++ b/installation/bimap.pkg @@ -1,4 +1,4 @@ -v 1.82 +v 2.0 d {bf:BIMAP}: Bi-variate maps d Requires: Stata version 15 or higher. @@ -7,9 +7,9 @@ d KW: Stata d KW: graphs d KW: map d KW: bivariate map -d Distribution-Date: 20240504 +d Distribution-Date: 20240822 d -d This version: 04 May 2024 +d This version: 22 Aug 2024 d First version: 08 Apr 2022 d License: MIT d diff --git a/installation/bimap.sthlp b/installation/bimap.sthlp index fdcbd47..fd3d307 100644 --- a/installation/bimap.sthlp +++ b/installation/bimap.sthlp @@ -1,27 +1,56 @@ {smcl} -{* 19Jun2024}{...} +{* 22Aug2024}{...} {hi:help bimap}{...} -{right:{browse "https://github.com/asjadnaqvi/stata-bimap":bimap v1.9 (GitHub)}} +{right:{browse "https://github.com/asjadnaqvi/stata-bimap":bimap v2.0 (GitHub)}} {hline} {title:bimap}: A Stata package for bi-variate maps. {p 4 4 2} -The package is based on the {browse "https://medium.com/the-stata-guide/stata-graphs-bi-variate-maps-b1e96dd4c2be":Bi-variate maps} guide on Medium. The {cmd:bimap} command is a wrapper for {stata help spmap:spmap}. -Therefore it assumes that data on geographic boundaries is available, and you are familar with making maps in Stata. -Note that {cmd:bimap} only works if you have processed the shapefiles using Stata's {stata help spshape2dta:spshape2dta} command. +The package is based on the {browse "https://medium.com/the-stata-guide/stata-graphs-bi-variate-maps-b1e96dd4c2be":Bi-variate maps} guide on Medium. The {cmd:bimap} command is a wrapper +for {stata help spmap:geoplot} (v17+) and {stata help spmap: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 {it:old} option. The older version that relies on {stata help spmap:spmap} will eventually be phased out. + +{p 4 4 2} +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 {cmd:bimap} only works if you have processed the shapefiles using Stata's {stata help spshape2dta:spshape2dta} or the {stata help geoplot:geoplot} command. + +{p 4 4 2} +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 {cmd:geoplot}, can be added by using the {cmd:geo()} option. Additional features such as arrows, scalebars, zooms etc can be passed on +using the {cmd:geopost()} options. For {cmd:spmap}, the old syntax just passes on individual options. This has been maintained to avoid the breaking the old code completely. + + +{marker syntax}{title:Syntax (version 17 or newer)} -{marker syntax}{title:Syntax} {p 8 15 2} -{cmd:bimap} {it:vary varx} {ifin}, {cmd:[} {cmd:palette}({it:name}) reverse {cmd:clr0}({it:str}) {cmd:clrx}({it:str}) {cmd:clry}({it:str}) {cmdab:clrsat:urate}({it:num}) - {cmd:cut}({it:pctile}|{it:equal}) {cmd:cutx}({it:numlist}) {cmd:cuty}({it:numlist}) {cmd:binsproper} {cmd:bins}({it:num >=2}) {cmd:binx}({it:num >=2}) {cmd:biny}({it:num >=2}) {cmd:values} {cmd:count} - {cmd:percent} {cmdab:showleg:end} {cmd:ocolor}({it:str}) {cmd:osize}({it:str}) {cmd:ndocolor}({it:str}) {cmd:ndfcolor}({it:str}) {cmd:ndfsize}({it:str}) {cmdab:xdisc:rete} {cmdab:ydisc:rete} - {cmd:labxgap}({it:num}) {cmd:labygap}({it:num}) {cmd:textx}({it:str}) {cmd:texty}({it:str}) {cmd:formatx}({it:str}) {cmd:formaty}({it:str}) - {cmdab:texts:ize}({it:str}) {cmdab:textlabs:ize}({it:str}) {cmdab:vallabs:ize}({it:str}) {cmdab:textc:olor}({it:str}) {cmdab:textlabc:olor}({it:str}) {cmdab:vallabc:olor}({it:str}) - {cmd:xscale}({it:num}) {cmd:yscale}({it:num}) {cmd:polygon}({it:options}) {cmd:line}({it:options}) {cmd:point}({it:options}) {cmd:label}({it:options}) {cmd:arrow}({it:options}) - {cmd:diagram}({it:options}) {cmd:scalebar}({it:options}) * {cmd:]} +{cmd:bimap} {it:vary varx} {ifin}, {cmd:frame}({it:name}) + {cmd:[} {cmd:geo}({it:options}) {cmd:geopost}({it:options}) + {cmd:palette}({it:name}) {cmd:reverse} {cmd:clr0}({it:str}) {cmd:clrx}({it:str}) {cmd:clry}({it:str}) {cmdab:clrsat:urate}({it:num}) + {cmd:cut}({it:pctile}|{it:equal}) {cmd:cutx}({it:numlist}) {cmd:cuty}({it:numlist}) {cmd:binsproper} {cmd:bins}({it:num >=2}) {cmd:binx}({it:num >=2}) {cmd:biny}({it:num >=2}) {cmd:values} {cmd:count} + {cmd:percent} {cmdab:showleg:end} {cmd:ocolor}({it:str}) {cmd:osize}({it:str}) {cmd:ndocolor}({it:str}) {cmd:ndfcolor}({it:str}) {cmd:ndfsize}({it:str}) {cmdab:xdisc:rete} {cmdab:ydisc:rete} + {cmd:labxgap}({it:num}) {cmd:labygap}({it:num}) {cmd:textx}({it:str}) {cmd:texty}({it:str}) {cmd:formatx}({it:str}) {cmd:formaty}({it:str}) + {cmdab:texts:ize}({it:str}) {cmdab:textlabs:ize}({it:str}) {cmdab:vallabs:ize}({it:str}) {cmdab:textc:olor}({it:str}) {cmdab:textlabc:olor}({it:str}) {cmdab:vallabc:olor}({it:str}) + {cmd:xscale}({it:num}) {cmd:yscale}({it:num}) * {cmd:]} + + +{marker syntax}{title:Syntax (version 16 or earlier)} + +{p 8 15 2} + +{cmd:bimap} {it:vary varx} {ifin}, {cmd:shp}({it:shapefile}) + {cmd:[} {cmd:old} {cmd:polygon}({it:str}) {cmd:line}({it:str}) {cmd:point}({it:str}) {cmd:label}({it:str}) {cmd:arrow}({it:str}) {cmd:diagram}({it:str}) {cmd:scalebar}({it:str}) + {cmd:palette}({it:name}) {cmd:reverse} {cmd:clr0}({it:str}) {cmd:clrx}({it:str}) {cmd:clry}({it:str}) {cmdab:clrsat:urate}({it:num}) + {cmd:cut}({it:pctile}|{it:equal}) {cmd:cutx}({it:numlist}) {cmd:cuty}({it:numlist}) {cmd:binsproper} {cmd:bins}({it:num >=2}) {cmd:binx}({it:num >=2}) {cmd:biny}({it:num >=2}) {cmd:values} {cmd:count} + {cmd:percent} {cmdab:showleg:end} {cmd:ocolor}({it:str}) {cmd:osize}({it:str}) {cmd:ndocolor}({it:str}) {cmd:ndfcolor}({it:str}) {cmd:ndfsize}({it:str}) {cmdab:xdisc:rete} {cmdab:ydisc:rete} + {cmd:labxgap}({it:num}) {cmd:labygap}({it:num}) {cmd:textx}({it:str}) {cmd:texty}({it:str}) {cmd:formatx}({it:str}) {cmd:formaty}({it:str}) + {cmdab:texts:ize}({it:str}) {cmdab:textlabs:ize}({it:str}) {cmdab:vallabs:ize}({it:str}) {cmdab:textc:olor}({it:str}) {cmdab:textlabc:olor}({it:str}) {cmdab:vallabc:olor}({it:str}) + {cmd:xscale}({it:num}) {cmd:yscale}({it:num}) * {cmd:]} + {p 4 4 2} @@ -32,9 +61,44 @@ The options are described as follows: {synoptline} {p 4 4 2} -{it:{ul:Map options}} +{it:{ul:Map syntax}} + +{p2coldent : {opt bimap} {it:vary varx, options}}The command requires numeric {it:vary} and {it:varx} variables. See options below for additional info.{p_end} + +{p 4 4 2} +{it:{ul:Version 17 or newer options}} + +{p2coldent : {opt frame(name)}}The geoplot frames need to be defined before executing the bimap command. The {opt 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.{p_end} + +{p2coldent : {opt 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, {opt geo((area ..., ...) (area ..., ...) (line ..., ...))} etc.{p_end} + +{p2coldent : {opt geopost(string)}}Similar to {opt geo()}, {opt geopost()} can be used to pass on additional commands in {cmd:geoplot}. +This for example, can include zooms, legend options, arrows, scalebars etc.{p_end} + + +{p 4 4 2} +{it:{ul:Version 16 or older options}} + +{p2coldent : {opt old}}If this option is specified, the command switches to the {cmd spmap} 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.{p_end} -{p2coldent : {opt bimap} {it:vary varx}}The command requires numeric {it:vary} and {it:varx} variables.{p_end} +{p2coldent : {opt shp(shapefile)}}The spmap requires defining a shapefile using the {opt shp()} options. {bf: NOTE:} This is a slight change from the +older {cmd:bimap} versions where the users previously specified {opt bimap vary varx using shpfile}. The new version requires {opt bimap vary varx, shp(shpfile)}. +While this might cause some incovinience to vetran {cmd: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 {opt shp()} file +on the {it:_ID} variable. The shapefile file usually has {it:*_shp.dta} name and is automatically created while using the {stata help spshape2dta:spshape2dta} +command.{p_end} + +{p2coldent : {opt polygon}(), {opt line}(), {opt point}(), {opt label}()}These are {cmd:spmap} passthru options to draw additional layers. See {stata help spmap} for details.{p_end} + +{p2coldent : {opt arrow}(), {opt diagram}(), {opt scalebar}()}These are {cmd:spmap} passthru options for additional map options. See {stata help spmap} for details.{p_end} + + +{p 4 4 2} +{it:{ul:Map cuts and colors}} {p2coldent : {opt cut(option)}}Here {opt cut} take on three options: {opt cut(pctile)} for percentiles, or {opt cut(equal)} for equally-spaced intervals. If either {opt cutx()}, or {opt cuty()}, or are specified, then they overwrite the defined {opt cut()} options. Default is {opt cut(pctile)}.{p_end} @@ -42,20 +106,21 @@ The options are described as follows: {p2coldent : {opt cutx(numlist)}, {opt cuty(numlist)}}Define a custom set of cut-offs using {stata help numlist:numlist} to add more control to your legend. At least three numbers need to be specified to generate the map.{p_end} -{p2coldent : {opt xdisc:rete}, {opt ydisc:rete}} can be used if the variables are assumed categorical, for example, binary variables, or ordinally ranked variables. +{p2coldent : {opt xdisc:rete}, {opt ydisc:rete}} 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 is also to prevent accidentally declaring a regular variable as discrete.{p_end} +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.{p_end} -{p2coldent : {opt palette(option)}}In version v1.6 and above, palettes are dynamically generated for any number of {opt bins()}. Named palettes are: +{p2coldent : {opt palette(option)}}Palettes are dynamically generated for any number of {opt bins()}. Named palettes are: {it:pinkgreen}, {it:bluered}, {it:greenblue}, {it:purpleyellow}, {it:yellowblue}, {it:orangeblue}. The original (legacy) palettes are still available with the following names: {it:pinkgreen0}, {it:bluered0}, {it:greenblue0}, {it:purpleyellow0}, {it:yellowblue0}, {it:orangeblue0}, {it:brew1}, {it:brew2}, {it:brew3}, {it:census}, {it:rgb}, {it:viridis}, {it:gscale}. If legacy palettes are defined, the number of bins will default to 3x3 and any other custom binning options will be ignored. See {browse "https://github.com/asjadnaqvi/stata-bimap":GitHub} for examples of legacy palettes. Default option is {opt palette(pinkgreen)}. -Users can also over-write the palettes using the {opt clr.()} options described below.{p_end} +Users can also over-write the palettes using the {opt clr...()} options described below.{p_end} -{p2coldent : {opt clr0()}, {opt clrx()}, {opt clry()}}Users can overwrite the colors end-points using one or more of these options. Option {opt clr0()} is the -starting bottom-left color. Similarly, {opt clrx()}, {opt clry()} are x-axis bottom-right and y-axis top-left colors. One can either define a "named" Stata color (e.g. +{p2coldent : {opt clr0()}, {opt clrx()}, {opt clry()}}Users can overwrite the colors end-points using one or more of these options. Option {opt clr0()} is the starting +bottom-left color. Similarly, {opt clrx()}, {opt 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 {stata colorpalette s2: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 {browse "https://g.co/kgs/iKAHGF":Google Color Picker}. Otherwise, {stata help colorpalette:colorpalette}, other softwares (including MS Paint), and websites can be used as well.{p_end} @@ -67,27 +132,20 @@ Otherwise, {stata help colorpalette:colorpalette}, other softwares (including MS {p2coldent : {opt bins(num)}, {opt binx(num)}, {opt biny(num)}}Users can either defined {it:n}x{it:n} bins by using the option {opt bins(n)}. Otherwise custom bins can also be defined using {opt binx()} and/or {opt biny()}. The default is {opt bin(3)}. Bins are constrained to a minimum dimension of 2.{p_end} -{p2coldent : {opt osize(string)}}Line width of polygons. Same as in {cmd:spmap}. Default value is {it:0.02}. Also applied to polygons with no data.{p_end} +{p2coldent : {opt osize(string)}}Line width of polygons. Default value is {opt osize(0.02)}. Also applied to polygons with no data.{p_end} -{p2coldent : {opt ocolor(str)}}Outline color of polygons with data. Same as in {cmd:spmap}. Default value is {it:white}.{p_end} +{p2coldent : {opt ocolor(str)}}Outline color of polygons with data. Default value is {opt ocolor(white)}.{p_end} -{p2coldent : {opt ndocolor(str)}}Outline color of polygons with no data. Same as in {cmd:spmap}. Default value is {it:gs12}.{p_end} +{p2coldent : {opt ndocolor(str)}}Outline color of polygons with no data. Default value is {opt ndocolor(gs12)}.{p_end} -{p2coldent : {opt ndfcolor(str)}}Fill color of polygons with no data. Same as in {cmd:spmap}. Default value is {it:gs8}.{p_end} +{p2coldent : {opt ndfcolor(str)}}Fill color of polygons with no data. Default value is {opt ndfcolor(gs8)}.{p_end} {p2coldent : {opt ndsize(str)}}Line width of missing observations. If no value is specified, it defaults to the {opt osize(0.02)} value.{p_end} -{p2coldent : {opt polygon}(), {opt line}(), {opt point}(), {opt label}()}These are {cmd:spmap} passthru options for additional layers. See {stata help spmap} for details.{p_end} - -{p2coldent : {opt arrow}(), {opt diagram}(), {opt scalebar}()}These are {cmd:spmap} passthru options for additional layers. See {stata help spmap} for details.{p_end} - {p2coldent : {opt noleg:end}}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.{p_end} -{p2coldent : {opt showleg:end}}If this option is specified, then the following {stata help spmap:spmap} options are enabled: {cmd:legend}(), {cmd:legenda}(), {cmdab:legs:tyle}(), -{cmdab:legj:unction}(), {cmdab:legc:ount}(), {cmdab:lego:rder()}, {cmdab:legt:title}(), plus additional options that can be specified for supplementary layers: {cmd:polygon}(), -{cmd:line}(), {cmd:point}(), {cmd:label}(). {cmdab:showleg:end} 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 {cmd:legenda}(off) since this shows up in the bimap legend on the right. -This option is still {it:beta}, so suggestions for improvement are appreciated.{p_end} +{p2coldent : {opt showleg:end}}If this option is specified, then the {stata help geoplot:geoplot} and {stata help spmap:spmap} options are enabled. Both commands have +fairly complex syntaxes for generating legends so please see individual helpfiles for details.{p_end} {p2coldent : {opt *}}All other standard twoway options.{p_end} @@ -134,13 +192,20 @@ squished especially if the categories are bunched together. This will most likel {title:Dependencies} -{cmd:bimap} requires {stata help spmap:spmap} (Pisati 2018) and {browse "http://repec.sowi.unibe.ch/stata/palettes/index.html":palettes} (Jann 2018, 2022): +Stata version 17 or newer requires the following packages: +{stata ssc install geoplot, replace} +{stata ssc install moremata, replace} +{stata ssc install palettes, replace} +{stata ssc install colrspace, replace} + + +Stata version 16 or earlier requires the following packages: {stata ssc install spmap, replace} {stata ssc install palettes, replace} {stata ssc install colrspace, replace} -Even if you have the packages installed, please check for updates: {stata ado update, update}. +Even if you have these packages installed, please reguarly check for their updates. {title:Examples} @@ -150,8 +215,8 @@ Please see {browse "https://github.com/asjadnaqvi/stata-bimap":GitHub} for examp {title:Package details} -Version : {bf:bimap} v1.9 -This release : 19 Jun 2024 +Version : {bf:bimap} v2.0 +This release : 20 Aug 2024 First release: 08 Apr 2022 Repository : {browse "https://github.com/asjadnaqvi/stata-bimap":GitHub} Keywords : Stata, map, bimap, bi-variate @@ -173,19 +238,21 @@ If you find bugs and/or have feature requests, then please open an {browse "http Suggested citation guidlines for this package: -Naqvi, A. (2024). Stata package "bimap" version 1.9. Release date 19 June 2024. https://github.com/asjadnaqvi/stata-bimap. +Naqvi, A. (2024). Stata package "bimap" version 2.0. Release date 20 August 2024. https://github.com/asjadnaqvi/stata-bimap. @software{bimap, author = {Naqvi, Asjad}, title = {Stata package ``bimap''}, url = {https://github.com/asjadnaqvi/stata-bimap}, - version = {1.9}, - date = {2024-06-19} + version = {2.0}, + date = {2024-08-20} } {title:References} -{p 4 8 2}Pisati, B. (2018). {browse "help spmap":spmap} v1.3.2. +ADD GEOPLOT AND MOREMATA + +{p 4 8 2}Pisati, B. (2018). {stata help spmap:spmap} v1.3.2. {p 4 8 2}Jann, B. (2018). {browse "https://www.stata-journal.com/article.html?article=gr0075":Color palettes for Stata graphics}. The Stata Journal 18(4): 765-785. diff --git a/installation/stata.toc b/installation/stata.toc index e17b88c..e442e4b 100644 --- a/installation/stata.toc +++ b/installation/stata.toc @@ -1,7 +1,7 @@ -v 1.82 +v 2.0 d BIMAP: A package for creating bi-variate maps. d -d Distribution-Date: 20240504 +d Distribution-Date: 20240822 d d Asjad Naqvi d asjadnaqvi@gmail.com