v1.5 update

README.md

@@ -1,7 +1,7 @@
 
 ![StataMin](https://img.shields.io/badge/stata-2015-blue) ![issues](https://img.shields.io/github/issues/asjadnaqvi/stata-bimap) ![license](https://img.shields.io/github/license/asjadnaqvi/stata-bimap) ![Stars](https://img.shields.io/github/stars/asjadnaqvi/stata-bimap) ![version](https://img.shields.io/github/v/release/asjadnaqvi/stata-bimap) ![release](https://img.shields.io/github/release-date/asjadnaqvi/stata-bimap)
 
-# bimap v1.4
+# bimap v1.5
 
 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).
 
@@ -15,7 +15,7 @@ The package can be installed from SSC (**v1.32**):
 ssc install bimap, replace
 ```
 
-Or it can be installed from GitHub (**v1.4**):
+Or it can be installed from GitHub (**v1.5**):
 
 ```
 net install bimap, from("https://raw.githubusercontent.com/asjadnaqvi/stata-bimap/main/installation/") replace
@@ -52,14 +52,15 @@ This command is a wrapper for `spmap` and assumes that you have shapefiles in St
 
 ## Syntax
 
-The syntax for **v1.4** is as follows:
+The syntax for **v1.5** is as follows:
 
 ```
 
 bimap vary varx [if] [in],  palette(option) cut(option) 
 		[ count percent values formatx(str) formaty(str) cutx(val1 val2) cuty(val1 val2) 
 		ocolor(str) osize(str) ndocolor(str) ndsize(str) ndocolor(str) showlegend
 		polygon(str) line(str) point(str) label(str) formatx(str) formaty(str)
+		arrow(str) diagram(str) scalebar(str) 
 		textx(string) texty(str) TEXTLABSize(num) TEXTSize(num) TEXGap(num) BOXsize(num) xscale(num) yscale(num) 
 		title(str) subtitle(str) note(str) name(srt) scheme(str) ]
 ```
@@ -156,24 +157,27 @@ bimap share_hisp share_afam using usa_county_shp_clean, cut(equal) palette(pinkg
 ```
 local i = 1
 
-foreach x in pinkgreen bluered greenblue purpleyellow yellowblue orangeblue brew1 brew2 brew3 census {
+foreach x in pinkgreen bluered greenblue purpleyellow yellowblue orangeblue brew1 brew2 brew3 census rgb viridis gscale {
+
 		bimap share_hisp share_afam using usa_county_shp_clean, cut(pctile) palette(`x') percent title("Scheme: `x'") 
 		graph export bimap3_`i'.png, replace wid(2000)	
-			local i = `i' + 1
+
+		local i = `i' + 1
 }
 ```
 
 <img src="/figures/bimap3_1.png" height="250"><img src="/figures/bimap3_2.png" height="250"><img src="/figures/bimap3_3.png" height="250">
 <img src="/figures/bimap3_4.png" height="250"><img src="/figures/bimap3_5.png" height="250"><img src="/figures/bimap3_6.png" height="250">
 <img src="/figures/bimap3_7.png" height="250"><img src="/figures/bimap3_8.png" height="250"><img src="/figures/bimap3_9.png" height="250">
-<img src="/figures/bimap3_10.png" height="250">
+<img src="/figures/bimap3_10.png" height="250"><img src="/figures/bimap3_11.png" height="250"><img src="/figures/bimap3_12.png" height="250">
+<img src="/figures/bimap3_13.png" height="250">
 
 
 ### Advanced examples
 
 ```
 bimap share_asian share_afam using usa_county_shp_clean, cut(pctile) palette(bluered)  ///
-	title("{fontface Arial Bold:My first bivariate map}") subtitle("Made with Stata") note("Data from the US Census Bureau.") ///	
+	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("usa_state_shp_clean") ocolor(white) osize(0.3))
@@ -184,18 +188,18 @@ bimap share_asian share_afam using usa_county_shp_clean, cut(pctile) palette(blu
 
 ```
 bimap share_asian share_afam using usa_county_shp_clean, cut(pctile) palette(yellowblue)  ///
-	title("{fontface Arial Bold:My first bivariate map}") subtitle("Made with Stata") note("Data from the US Census Bureau.") ///	
+	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("usa_state_shp_clean") ocolor(black) osize(0.2)) 
+		 polygon(data("usa_state_shp_clean") ocolor(black) osize(0.2))
 ```
 
 <img src="/figures/bimap6.png" height="500">
 
 
 ```
 bimap share_asian share_hisp  using usa_county_shp_clean, cut(pctile) palette(orangeblue)  ///
-	title("{fontface Arial Bold:My first bivariate map}") subtitle("Made with Stata") note("Data from the US Census Bureau.") ///	
+	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("usa_state_shp_clean") ocolor(black) osize(0.2)) 
@@ -209,12 +213,12 @@ Since `bimap` is a wrapper of `spmap`, we can pass information for other layers
 
 ```
 bimap share_hisp share_afam using usa_county_shp_clean, cut(pctile) palette(pinkgreen) percent  ///
-	title("{fontface Arial Bold:My first bivariate map}") subtitle("Made with Stata") ///
+	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) ///
+		 ocolor() osize(none) ///
 		 polygon(data("usa_state_shp_clean") ocolor(white) osize(0.3)) ///
-		 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))
+		 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) )  
 ```
 
 <img src="/figures/bimap8.png" height="500">
@@ -299,7 +303,11 @@ Please open an [issue](https://github.com/asjadnaqvi/stata-bimap/issues) to repo
 
 ## Versions
 
-**v1.4  (04 Oct 2022)**
+**v1.5 (05 Nov 2022)**
+- Three new palettes added: `rgb`, `viridis`, `gscale`.
+- Added `spmap` passthru options for `arrow`, `diagram`, and `scalebar`.
+
+**v1.4 (04 Oct 2022)**
 - Added the option to add custom cut-offs.
 - Added the option to format cut-offs,
 - Added the option to show default `spmap` legends.
@@ -339,6 +347,3 @@ Please open an [issue](https://github.com/asjadnaqvi/stata-bimap/issues) to repo
 
 
 
-
-
-

installation/bimap.ado

@@ -1,6 +1,7 @@
-*! bimap v1.4 (4 Oct 2022)
+*! bimap v1.5 (5 Nov 2022)
 *! Asjad Naqvi ([email protected])
-*
+
+* v1.5  (05 Nov 2022): 3 new colors: rgb, gscale, viridis. arrow, scalebar, diagram passthrus added.
 * v1.4  (02 Oct 2022): custom cut-off points added. cut'offs can be formatted. spmap legend passthru.
 * v1.33 (29 Sep 2022): Passthru options fixed.
 * v1.32 (19 Aug 2022): Fixed a bug in variable comparisons
@@ -28,14 +29,14 @@ version 15
 
 	syntax varlist(min=2 max=2 numeric) [if] [in] using/ , ///
 		cut(string) palette(string)  ///
-		[ count percent BOXsize(real 8) textx(string) texty(string) formatx(string) formaty(string) TEXTGap(real 2) xscale(real 30) yscale(real 100) TEXTLABSize(real 2)  TEXTSize(real 2.5) values ] ///
+		[ count percent BOXsize(real 8) textx(string) texty(string) formatx(string) formaty(string) TEXTGap(real 2) xscale(real 30) yscale(real 100) TEXTLABSize(real 2) TEXTSize(real 2.5) values ] ///
 		[ polygon(passthru) line(passthru) point(passthru) label(passthru) ] ///
 		[ ocolor(string) osize(string) ]   ///
 		[ ndocolor(string) ndsize(string) ndfcolor(string) ]   ///
 		[ title(passthru) subtitle(passthru) note(passthru) name(passthru)  ] ///
 		[ cutx(numlist min=2 max=2)  cuty(numlist min=2 max=2) SHOWLEGend  ] ///  // 1.4 updates
-		[ LEGend(passthru) legenda(passthru) LEGStyle(passthru) LEGJunction(passthru) LEGCount(passthru) LEGOrder(passthru) LEGTitle(passthru)  ]   // 1.4 legend controls as passthru
-
+		[ 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
 
 		if (substr(reverse("`using'"),1,4) != "atd.") local using "`using'.dta"  // from spmap to check for extension
 
@@ -178,8 +179,8 @@ qui {
 
 		***** store the cut-offs for labels	
 
-		if "`formatx'" =="" local formatx = "%05.1f"
-		if "`formaty'" =="" local formaty = "%05.1f"
+		if "`formatx'" =="" local formatx "%5.1f"
+		if "`formaty'" =="" local formaty "%5.1f"
 
 
 		summ `var1' if `cat_`var1'' == 1
@@ -248,7 +249,7 @@ qui {
 		// from spmap
 
 		if "`palette'" != "" {
-			local LIST "pinkgreen bluered greenblue purpleyellow yellowblue orangeblue brew1 brew2 brew3 census"
+			local LIST "pinkgreen bluered greenblue purpleyellow yellowblue orangeblue brew1 brew2 brew3 census rgb viridis gscale"
 			local LEN = length("`palette'")
 			local check = 0
 			foreach z of local LIST { 
@@ -258,12 +259,13 @@ qui {
 			}
 
 			if !`check' {
-				di in yellow "Wrong palette specified. The supported palettes are {ul:pinkgreen}, {ul:bluered}, {ul:greenblue}, {ul:purpleyellow}, {ul:yellowblue}, {ul:orangeblue}, {ul:brew1}, {ul:brew2}, {ul:brew3}, {ul:census}. See {stata help bimap:help file}."
+				di in yellow "Wrong palette specified. The supported palettes are {it:pinkgreen}, {it:bluered}, {it:greenblue}, {it:purpleyellow}, {it:yellowblue}, {it:orangeblue}, {it:brew1}, {it:brew2}, {it:brew3}, {it:census}, {it:rgb}, {it:viridis}, {it:gscale}."
+				di in yellow "See {stata help bimap:help file}."
 				exit 198
 			}
 		}
 
-		** bottom left to bottom top, bottom middle to top middle, bottom right to top right
+		** bottom left > top left, bottom middle > top middle, bottom right > top right
 
 		if "`palette'" == "pinkgreen" {
 			local color #e8e8e8 #dfb0d6 #be64ac #ace4e4 #a5add3 #8c62aa #5ac8c8 #5698b9 #3b4994
@@ -305,7 +307,20 @@ qui {
 			local color #fffdef #e6f1df #d2e4f6 #fef3a9 #bedebc #a1c8ea #efd100 #4eb87b #007fc4
 		}
 
-
+		if "`palette'" == "rgb" {   
+			local color #F5F402 #8EBA13 #2A8F25 #FE870D #B8A5D2 #3092FA #FF4343 #D052EB #5148BA
+		}
+
+
+		if "`palette'" == "gscale" {   
+			local color #e5e5e5 #d4d4d4 #bbbbbb #a2a2a2 #8a8a8a #727272 #5b5b5b #444444 #262626
+		}				
+
+		if "`palette'" == "viridis" {   
+			local color #FDE724 #D2E11B #A5DA35 #35B778 #29788E #38568B #462F7C #48196B #440154
+		}
+
+
 		if "`polygon'" == "" {
 			local polyadd 
 		}
@@ -335,6 +350,7 @@ qui {
 				ndocolor(`ndo' ..) ndsize(`lw' ..) 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
 
 

installation/bimap.pkg

@@ -1,4 +1,4 @@
-v 1.4
+v 1.5
 d {bf:BIMAP}: Bi-variate maps
 d
 d
@@ -8,9 +8,9 @@ d KW: Stata
 d KW: graphs
 d KW: map
 d KW: bivariate map
-d Distribution-Date: 20221004
+d Distribution-Date: 20221105
 d
-d This  version: 04 Oct 2022
+d This  version: 05 Nov 2022
 d First version: 08 Apr 2022
 d License: MIT
 d

installation/bimap.sthlp

@@ -1,7 +1,7 @@
 {smcl}
-{* 02Oct2022}{...}
+{* 05Nov2022}{...}
 {hi:help bimap}{...}
-{right:{browse "https://github.com/asjadnaqvi/stata-bimap":bimap v1.4 (GitHub)}}
+{right:{browse "https://github.com/asjadnaqvi/stata-bimap":bimap v1.5 (GitHub)}}
 
 {hline}
 
@@ -17,7 +17,8 @@ Note that {cmd:bimap} only works if you have processed the shapefiles using Stat
 
 {cmd:bimap} {it:vary varx} {ifin}, {cmd:palette}({it:option}) {cmd:cut}({it:option}) 
 		{cmd:[} {cmd:cutx}({it:val1 val2}) {cmd:cuty}({it:val1 val2}) {cmd:values} {cmd:count} {cmd:percent}  {cmd:ocolor}({it:str}) {cmd:osize}({it:str}) {cmd:ndocolor}({it:str}) {cmd:ndfcolor}({it:str}) 
-		{cmd:polygon}({it:options}) {cmd:line}({it:options}) {cmd:point}({it:options}) {cmd:label}({it:options}) {cmdab:showleg:end} {cmd:formatx}({it:str}) {cmd:formaty}({it:str}) 
+		{cmdab:showleg:end} {cmd:formatx}({it:str}) {cmd:formaty}({it:str}) 
+		{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:textx}({it:str}) {cmd:texty}({it:str}) {cmdab:textg:ap}({it:num}) {cmdab:textlabs:ize}({it:num}) {cmdab:texts:ize}({it:num}) {cmdab:box:size}({it:num}) {cmd:xscale}({it:num}) {cmd:yscale}({it:num}) 
 		{cmd:title}({it:str}) {cmd:subtitle}({it:str}) {cmd:note}({it:str}) {cmd:name}({it:str}) {cmd:scheme}({it:str}) {cmd:]}
 
@@ -31,17 +32,17 @@ The options are described as follows:
 
 {p2coldent : {opt bimap} {it:vary varx}}The command requires numeric {it:vary} and {it:varx} variables.{p_end}
 
-{p2coldent : {opt cut(option)}}Here {cmd:cut} take on three options: {cmd:cutcut({it:pctile})} for percentiles or terciles in this case, 
-OR {cmd:cut({it:equal})} for equal intervals, OR {cmd:cut({{it:custom})} for custom cut-offs.
-If {ul:{it:custom}} is specified, then either {cmd:cutx()} or {cmd:cuty()}, or both need to be defined.{p_end}
+{p2coldent : {opt cut(option)}}Here {cmd:cut} take on three options: {cmd:cut({it:pctile})} for terciles, 
+{cmd:cut({it:equal})} for equal intervals, or {cmd:cut({it:custom})} for custom cut-offs.
+{cmd:cut({it:custom})} is specified, then either {cmd:cutx()}, or {cmd:cuty()}, or both need to be defined.{p_end}
 
 {p2coldent : {opt cutx(val1 val2)}, {opt cuty(val1 val2)}}Define the middle two cut-off points for the x and y variables. Either one of the two, or both options need to be specified.
 If only one option is specified, then the other will automatically take the {it:pctile} cut-offs. The minimum and maximum cut-offs will be estimated directly by the program.
 If values are outside of the variable range, then the program will throw an error.{p_end}
 
-{p2coldent : {opt palette(option)}}Palette options for bi-variate maps are: {ul:{it:pinkgreen}}, {ul:{it:bluered}}, {ul:{it:greenblue}}, {ul:{it:purpleyellow}}, {ul:{it:yellowblue}}, {ul:{it:orangeblue}},
-{ul:{it:brew1}}, {ul:{it:brew2}}, {ul:{it:brew3}}, {ul:{it:census}}.
-See {stata help bimap:help file} for details and {browse "https://github.com/asjadnaqvi/stata-bimap":GitHub} for palette examples.{p_end}
+{p2coldent : {opt palette(option)}}Palette options for bi-variate maps are: {it:pinkgreen}, {it:bluered}, {it:greenblue}, {it:purpleyellow}, {it:yellowblue}, {it:orangeblue},
+{it:brew1}, {it:brew2}, {it:brew3}, {it:census}, {it:rgb}, {it:viridis}, {it:gscale}.
+See {browse "https://github.com/asjadnaqvi/stata-bimap":GitHub} for palette examples.{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}
 
@@ -53,6 +54,8 @@ See {stata help bimap:help file} for details and {browse "https://github.com/asj
 
 {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 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.
@@ -141,8 +144,8 @@ Additional examples on {browse "https://github.com/asjadnaqvi/stata-bimap":GitHu
 
 {title:Package details}
 
-Version      : {bf:bimap} v1.4
-This release : 04 Oct 2022
+Version      : {bf:bimap} v1.5
+This release : 04 Nov 2022
 First release: 08 Apr 2022
 Repository   : {browse "https://github.com/asjadnaqvi/stata-bimap":GitHub}
 Keywords     : Stata, graph, bi-variate, map
@@ -157,10 +160,14 @@ Twitter      : {browse "https://twitter.com/AsjadNaqvi":@AsjadNaqvi}
 {title:Acknowledgements}
 
 {p 4 4 2}
-Ruth Watkinson found an error in the grouping code. Pierre-Henri Bono suggested {it:passthru} options for {cmd:spmap}. 
-Kit Baum requested the {it:percent} option and fixes to label colors. 
-Mattias Öhman found an error in cut-offs and color assignments with missing groups.
-Cristian Jordan Diaz found and error in variable name comparisons.
+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 {stata help spmap:spmap} layers (v1.3). 
+Kit Baum requested the {it: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).
 
 {title:Feedback}