v1.9

CITATION.cff

@@ -3,6 +3,6 @@ authors:
 - family-names: "Naqvi"
   given-names: "Asjad"
 title: "Stata package ``bimap''"
-version: 1.82
-date-released: 2024-05-04
+version: 1.9
+date-released: 2024-06-19
 url: "https://github.com/asjadnaqvi/stata-bimap"

README.md

@@ -9,8 +9,8 @@
 
 
 
-# bimap v1.82
-(04 May 2024)
+# bimap v1.9
+(19 Jun 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).
 
@@ -24,7 +24,7 @@ The package can be installed from SSC (**v1.82**):
 ssc install bimap, replace
 ```
 
-Or it can be installed from GitHub (**v1.82**):
+Or it can be installed from GitHub (**v1.9**):
 
 ```
 net install bimap, from("https://raw.githubusercontent.com/asjadnaqvi/stata-bimap/main/installation/") replace
@@ -66,10 +66,11 @@ 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) ndsize(str) xdiscrete ydiscrete labxgap(num) labygap(num)
-                textx(str) texty(str) textlabsize(str) textsize(str) textcolor(str) formatx(str) formaty(str) xscale(num) yscale(num) 
-                polygon(options) line(options) point(options) label(options) arrow(options) diagram(options) scalebar(options) 
-                title(str) subtitle(str) note(str) name(str) scheme(str) ]
+                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) * ]
 ```
 
 See the help file `help bimap` for details.
@@ -83,6 +84,32 @@ bimap vary varx using *shapefile*
 See helpfile for further details
 
 
+## Citation guidelines
+Software packages take countless hours of programming, testing, and bug fixing. If you use this package, then a citation would be highly appreciated. Suggested citations:
+
+*in BibTeX*
+
+```
+@software{bimap,
+   author = {Naqvi, Asjad},
+   title = {Stata package ``bimap''},
+   url = {https://github.com/asjadnaqvi/stata-bimap},
+   version = {1.9},
+   date = {2024-06-19}
+}
+```
+
+*or simple text*
+
+```
+Naqvi, A. (2024). Stata package "bimap" version 1.9. Release date 19 June 2024. https://github.com/asjadnaqvi/stata-bimap.
+```
+
+
+*or see [SSC citation](https://ideas.repec.org/c/boc/bocode/s459196.html) (updated once a new version is submitted)*
+
+
+
 
 ## Examples
 
@@ -316,6 +343,46 @@ bimap share_hisp share_afam using county_shp2, cut(pctile) palette(census)  ///
 <img src="/figures/bimap12_1.png" width="100%">
 
 
+### new legend checks (v1.9)
+
+Check for legend color options:
+
+```
+bimap share_asian share_afam using county_shp2, 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) ///
+		 ocolor() osize(none) ///
+		 polygon(data("state_shp2") ocolor(white) osize(0.3))
+```
+
+<img src="/figures/bimap12_2.png" width="100%">
+
+
+Check for label wrapping in the legend:
+
+```
+bimap share_asian share_afam using county_shp2, 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  ///
+		 ocolor() osize(none) ///
+		 polygon(data("state_shp2") ocolor(white) osize(0.3))
+```
+
+<img src="/figures/bimap12_3.png" width="100%">
+
+Check for hiding the legend:
+
+
+```
+bimap share_asian share_afam using county_shp2, 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
+```
+
+<img src="/figures/bimap12_4.png" width="100%">
+
+
 ### v1.5 updates
 
 If condition checks with legends
@@ -332,18 +399,6 @@ bimap share_hisp share_afam using county_shp2 if STATEFP==36, cut(pctile) palett
 
 <img src="/figures/bimap13.png" width="100%">
 
-```
-bimap share_hisp share_afam using county_shp2 if STATEFP==36, cut(pctile) palette(census)  ///
-		 title("New York") ///
-		 note("Data from the US Census Bureau.", size(small)) ///	
-		 texty("Share of Hispanics") textx("Share of`=char(10)'African Americans") texts(3.2) textlabs(3) values percent ///
-		 ocolor(black) osize(0.03)  ///
-		 polygon(data("state_shp2") select(keep if _ID==19) ocolor(black) osize(0.2) legenda(on) leglabel(State boundaries))  ///
-		 showleg legenda(off) legend(pos(7) size(5)) legstyle(2) 
-```
-
-<img src="/figures/bimap14.png" width="100%">
-
 
 ### v1.6 updates
 
@@ -500,6 +555,13 @@ Please open an [issue](https://github.com/asjadnaqvi/stata-bimap/issues) to repo
 
 ## Change log
 
+**v1.9 (19 June 2024)**
+- Fixed and added several options to control legends: `textcolor()`, `textlabcolor()`, `vallabcolor()`. 
+- Better options for `textsize()`, `textlabsize()`, `vallabsize()`.
+- Added `wrap()` to wrap labels in legends.
+- Added `nolegend` option to generate maps without a bi-variate legend. This is useful is several maps are being generated with a controlled legend and need to be combined in one figure.
+- Several improvements to graph passthru options.
+
 **v1.82 (04 May 2024)**
 - Added `textcolor()` to control random colors appearing in legend labels under some schemes.
 - Backend improvements to some defaults.

installation/bimap.ado

@@ -1,6 +1,7 @@
-*! bimap v1.82 (04 May 2024)
+*! bimap v1.9 (19 Jun 2024)
 *! Asjad Naqvi ([email protected])
 
+* 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.
 * v1.8  (26 Jun 2023): custom cuts now take on values given in list, textgap() removed, labxgap(), labygap() added. Legend label positions optimized.
@@ -45,14 +46,13 @@ version 15
 		[ 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) saving(passthru)  ] ///
 		[ 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) ]			// v1.82
+		[ TEXTColor(string) TEXTLABColor(string) VALLABColor(string) NOLEGend wrap(numlist >=0 max=1)  * ]			// v1.82, v1.9
 
 
 		if (substr(reverse("`using'"),1,4) != "atd.") local using "`using'.dta"  // from spmap to check for extension
@@ -522,6 +522,18 @@ 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'
+
+		exit	
+		}
+		else {
 
 		spmap `grp_cut' using "`using'", ///
 			id(_ID) clm(custom) clb(0(1)`cutst') fcolor("`colors'") ///
@@ -531,7 +543,7 @@ qui {
 				`leg' `legstyle' `legenda' `legendstyle' `legjunction' `legcount' `legorder' `legtitle'  ///  // v1.4 legend passthrus
 				`arrow' `diagram' `scalebar' ///  // v1.5 passthrus
 					name(_map, replace) nodraw
-
+		}
 
 		*/
 
@@ -776,11 +788,16 @@ qui {
 
 		if "`textx'" 	  == "" local textx = "`var1'" 
 		if "`texty'" 	  == ""	local texty = "`var2'"
-		if "`vallabsize'" == ""	local vallabsize 1.8
 
-		if "`textcolor'"  == "" local textcolor 		black
-		if "`textsize'"   == "" local textsize  		2.5
-		if "`textlabsize'"   == "" local textlabsize  	2
+
+		if "`textcolor'"  	== "" 	local textcolor 	black
+		if "`textlabcolor'" == "" 	local textlabcolor 	black
+		if "`vallabcolor'"  == "" 	local vallabcolor 	black
+
+
+		if "`textsize'"   	== "" 	local textsize  	3
+		if "`textlabsize'"  == "" 	local textlabsize	2.2
+		if "`vallabsize'" 	== ""	local vallabsize 	2.2
 
 		// axis labels
 
@@ -796,6 +813,20 @@ qui {
 		replace laby = 0.5   	 in 2
 		replace labn = "`texty'" in 2
 
+
+		if "`wrap'" != "" {
+			gen _length = length(labn) if labn!= ""
+			summ _length, meanonly		
+			local _wraprounds = floor(`r(max)' / `wrap')
+
+			forval i = 1 / `_wraprounds' {
+				local wraptag = `wrap' * `i'
+				replace labn = substr(labn, 1, `wraptag') + "`=char(10)'" + substr(labn, `=`wraptag' + 1', .) if _length > `wraptag' & labn!= "" 
+			}
+
+			drop _length
+		}		
+
 
 		// generate the boxes
 		levelsof box, local(lvls)	
@@ -813,14 +844,14 @@ qui {
 			}
 
 		if "`count'" != "" | "`percent'" != "" {
- 			local mylabels (scatter y_mid x_mid, mlabel(`marksym') mlabpos(0) mcolor(none) mlabsize(`vallabsize') ) ///	// 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')) ///
+			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')) ///
+			local yvals (scatter y_mark x0, mcolor(none) mlabel(y_val) mlabpos(9) mcolor(gs6) msize(0.2) mlabsize(`textlabsize') mlabcolor(`textlabcolor') ) ///
 
 		}
 
@@ -832,8 +863,8 @@ qui {
 			`mylabels' ///
 			(pcarrow spike1_y1 spike1_x1 spike1_y2 spike1_x2, lcolor(gs6) mcolor(gs6) msize(0.8) ) ///  // arrow1
 			(pcarrow spike2_y1 spike2_x1 spike2_y2 spike2_x2, lcolor(gs6) mcolor(gs6) msize(0.8) ) ///  // arrow2
-			(scatter laby labx in 1, mcolor(none) mlab(labn) mlabsize("`textsize'") mlabcolor("`textcolor'") mlabpos(0)				 )  ///
-			(scatter laby labx in 2, mcolor(none) mlab(labn) mlabsize("`textsize'") mlabcolor("`textcolor'") mlabpos(0) mlabangle(90))  ///
+			(scatter laby labx in 1, mcolor(none) mlab(labn) mlabsize(`textsize') mlabcolor(`textcolor') mlabpos(0)				 )  ///
+			(scatter laby labx in 2, mcolor(none) mlab(labn) mlabsize(`textsize') mlabcolor(`textcolor') mlabpos(0) mlabangle(90))  ///
 			, ///
 				xlabel(-0.2 1, nogrid) ylabel(-0.2 1, nogrid) ///
 				yscale(range(0 1.1) off) xscale(range(0 1.1) off) ///
@@ -850,11 +881,7 @@ qui {
 	 ********************
 
 	  graph combine _map _legend, ///
-		imargin(zero) ///
-		`title' 	///
-		`subtitle' ///
-		`note' ///
-		`name' `saving'
+		imargin(zero) `options'
 
 
 }