bump to v1.73

CITATION.cff

@@ -3,6 +3,6 @@ authors:
 - family-names: "Naqvi"
   given-names: "Asjad"
 title: "Stata package ``sankey''"
-version: 1.72
-date-released: 2024-02-12
+version: 1.73
+date-released: 2024-03-16
 url: "https://github.com/asjadnaqvi/stata-sankey"

README.md

@@ -9,8 +9,8 @@
 
 ---
 
-# sankey v1.72
-(12 Feb 2024)
+# sankey v1.73
+(16 Mar 2024)
 
 This package allows users to draw Sankey plots in Stata. It is based on the [Sankey Guide](https://medium.com/the-stata-guide/stata-graphs-sankey-diagram-ecddd112aca1) published on [the Stata Guide](https://medium.com/the-stata-guide) on Medium on October 2021.
 
@@ -25,7 +25,7 @@ SSC (**v1.71**):
 ssc install sankey, replace
 ```
 
-GitHub (**v1.72**):
+GitHub (**v1.73**):
 
 ```
 net install sankey, from("https://raw.githubusercontent.com/asjadnaqvi/stata-sankey/main/installation/") replace
@@ -63,7 +63,6 @@ graph set window fontface "Arial Narrow"
 The syntax for the latest version is as follows:
 
 ```stata
-
 sankey value [if] [in], from(var) to(var) 
             [ by(var) palette(str) colorby(layer|level) colorvar(var) stock colorvarmiss(str) colorboxmiss(str)
               smooth(1-8) gap(num) recenter(mid|bot|top) ctitles(list) ctgap(num) ctsize(num) ctposition(bot|top) 
@@ -79,10 +78,10 @@ See the help file `help sankey` for details.
 The most basic use is as follows:
 
 ```
-sankey value, from(var1) to(var2) by(level)
+sankey value, from(var1) to(var2) [by(level)]
 ```
 
-where `var1` and `var2` are source and destination variables respectively against which the `value` variable is plotted. The `by()` variable defines the levels.
+where `var1` and `var2` are source and destination variables respectively against which the `value` variable is plotted. The `by()` variable defines the levels and has been made optional since v1.72. If this option is not specified, then one level is assumed.
 
 
 
@@ -427,6 +426,12 @@ Please open an [issue](https://github.com/asjadnaqvi/stata-sankey/issues) to rep
 
 ## Change log
 
+
+**v1.73 (16 Mar 2024)**
+- If the `from()` and `to()` variables have value labels, then the order of the value labels is respected. This allows the users to have full control of the order of the drawing of the layers through value labels (requested by Katie Naylor + others).
+- The command now throws an error if `from()` and `to()` have different format types. Both have to be either string or numeric variables. This was necessary to implement in order to implement the above change.
+- Minor code cleanups.
+
 **v1.72 (12 Feb 2024)**
 - Fixed `labprop` from wrong calculation the label sizes.
 - `valcond()` now passes on to box labels. Was removed but has been put back in.

installation/sankey.ado

@@ -1,6 +1,7 @@
-*! sankey v1.72 (12 Feb 2024)
+*! sankey v1.73 (18 Mar 2024)
 *! Asjad Naqvi ([email protected])
 
+*v1.73 (18 Mar 2024): Values determine the order of drawing. Add caution that numbers mean the same across the categories.
 *v1.72 (12 Feb 2024): labprop fixes, valcond() fixes. by() changed to optional. Assumes one layer with a warning. ctcolor() added. ctsize() switched to string.
 *v1.71 (15 Jan 2024): fixed a bug where value labels of to() and from() were overwriting each other.
 *v1.7  (06 Nov 2023): fix valcond() dropping labels in bars, added percent (still in beta), added ctpos() option. minor cleanups  
@@ -76,17 +77,17 @@ version 15
 
 
 	if "`stype2'" != "" & "`stype2'" != "order" & "`stype2'" != "value" {
-		di as err "Valid options for {bf:sort2()} are {it:order (default)} or {it:value}."
+		display as error "Valid options for {bf:sort2()} are {it:order (default)} or {it:value}."
 		exit 198
 	}	
 
 	if "`colorby'" != "" & "`colorvar'" != "" {
-		di as err "Both colorby() and colorvar() are not allowed."
+		display as error "Both colorby() and colorvar() are not allowed."
 		exit 198
 	}
 
 	if "`novalleft'" != "" & "`novalright'" != "" {
-		di as err "Both {it:novalleft} and {it:novalright} are not allowed. If you want to hide values use the {it:novalues} option instead."
+		display as error "Both {it:novalleft} and {it:novalright} are not allowed. If you want to hide values use the {it:novalues} option instead."
 		exit 198
 	}	
 
@@ -95,7 +96,7 @@ version 15
 		qui gen `_temp' = mod(`colorvar',1)
 		summ `_temp', meanonly
 		if r(max) > 0 {
-			di as err "colorvar() needs to be integers starting at 1."
+			display as error "colorvar() needs to be integers starting at 1."
 			exit 198
 		}
 	}
@@ -131,26 +132,51 @@ preserve
 
 	keep `varlist' `from' `to' `by' clrlvl
 
-		// convert value labels to strings
-		cap confirm numeric var `from'
-		if _rc==0 {
-			if "`: value label `from''" != "" {
-				decode `from', gen(temp1)		
-				drop `from'
-				ren temp1 `from'
-			}
+		// drop missing categories
+		cap confirm numeric var `from'	
+		if !_rc {  
+			local fcheck = 0
+			drop if `from'==.
 		}
-
-		cap confirm numeric var `to'
-		if _rc==0 {
-			if "`: value label `to''" != "" {
-				decode `to', gen(temp2)		
-				drop `to'
-				ren temp2 `to'
-			}
-		}		
+		else {
+			local fcheck = 1
+			drop if `from'==""
+		}
+
+		cap confirm numeric var `to'	
+		if !_rc {  
+			local tcheck = 0
+			drop if `to'==.
+		}
+		else {
+			local tcheck = 1
+			drop if `to'==""
+		}	
 
+		if ("`fcheck'"=="0" & "`tcheck'"=="1") | ("`tcheck'"=="0" & "`fcheck'"=="1") {
+			display as error "Format error: {bf:from()} and {bf:to()} have different formats. They should be both either numeric or string variables."
+			exit 198
+		}
 
+
+		// if strings, convert to numeric, otherwise leave them alone.
+
+		/*
+		cap confirm string var `from'
+		if !_rc {
+			encode `from', gen(_temp1)		
+			drop `from'
+			ren _temp1 `from'
+		}
+		
+		cap confirm string var `to'
+		if !_rc {
+			encode `to', gen(_temp2)		
+			drop `to'
+			ren _temp2 `to'
+		}	
+			*/
+
 	collapse (sum) `varlist' (mean) clrlvl , by(`from' `to' `by')
 
 	gen markme = .