v1.21

CITATION.cff

@@ -5,6 +5,6 @@ authors:
 - family-names: "Colston"
   given-names: "Jared"
 title: "Stata package ``waffle''"
-version: 1.2
-date-released: 2024-05-26
+version: 1.21
+date-released: 2024-06-27
 url: "https://github.com/asjadnaqvi/stata-waffle"

README.md

@@ -1,15 +1,15 @@
 ![StataMin](https://img.shields.io/badge/stata-2015-blue) ![issues](https://img.shields.io/github/issues/asjadnaqvi/stata-waffle) ![license](https://img.shields.io/github/license/asjadnaqvi/stata-waffle) ![Stars](https://img.shields.io/github/stars/asjadnaqvi/stata-waffle) ![version](https://img.shields.io/github/v/release/asjadnaqvi/stata-waffle) ![release](https://img.shields.io/github/release-date/asjadnaqvi/stata-waffle)
 
-[Installation](#Installation) | [Syntax](#Syntax) | [Examples](#Examples) | [Feedback](#Feedback) | [Change log](#Change-log)
+[Installation](#Installation) | [Syntax](#Syntax) | [Citation guidelines](#Citation-guidelines) | [Examples](#Examples) | [Feedback](#Feedback) | [Change log](#Change-log)
 
 ---
 
 ![waffle_banner](https://github.com/asjadnaqvi/stata-waffle/assets/38498046/9aaba239-7774-4005-99d2-9f87b65235bc)
 
 
 
-# waffle v1.2
-(26 May 2024)
+# waffle v1.21
+(27 June 2024)
 
 This package provides the ability to draw waffles Stata. It is based on the [Waffle plots](https://medium.com/the-stata-guide/stata-graphs-waffle-plots-613808b51f73) guide on Medium.
 
@@ -20,12 +20,12 @@ The package is still beta and is being constantly improved. It might still be mi
 
 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.
 
-The SSC version (**v1.11**):
+The SSC version (**v1.2**):
 ```
 ssc install waffle, replace
 ```
 
-Or it can be installed from GitHub (**v1.2**):
+Or it can be installed from GitHub (**v1.21**):
 
 ```
 net install waffle, from("https://raw.githubusercontent.com/asjadnaqvi/stata-waffle/main/installation/") replace
@@ -86,6 +86,35 @@ waffle variable, by()
 
 where `variable(s)` are a set of numeric variables.
 
+
+
+## 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{waffle,
+   author = {Naqvi, Asjad AND Colston, Jared},
+   title = {Stata package ``waffle''},
+   url = {https://github.com/asjadnaqvi/stata-waffle},
+   version = {1.21},
+   date = {2024-07-21}
+}
+```
+
+*or simple text*
+
+```
+Naqvi, A. & Colston, J. (2024). Stata package "waffle" version 1.21. Release date 21 June 2024. https://github.com/asjadnaqvi/stata-waffle.
+```
+
+
+*or see [SSC citation](https://ideas.repec.org/c/boc/bocode/s459059.html) (updated once a new version is submitted)*
+
+
+
 ## Examples
 
 Set up the data in wide form:
@@ -324,6 +353,11 @@ Please open an [issue](https://github.com/asjadnaqvi/stata-waffle/issues) to rep
 
 ## Change log
 
+**v1.21 (27 May 2024)**
+- Fixed a bug where the program was running into an error if `by()` was not specified.
+- Fixed and improved returned locals. See `return list` after running the command.
+- The program now displays the value of each dot after the graph is drawn.
+
 **v1.2 (26 May 2024)**
 - Program has been converted into r-class where `r(dot)` returns the value of each box. See `return list` after running the command.
 - Fixed a major bug with long data format that was not displaying the totals correctly.

installation/stata.toc

@@ -1,7 +1,7 @@
-v 1.2
+v 1.21
 d 'WAFFLE': A Stata package for waffle plots
 d
-d Distribution-Date: 20240526
+d Distribution-Date: 20240627
 d
 
 

installation/waffle.ado

@@ -1,6 +1,7 @@
-*! waffle v1.2 (26 May 2024)
+*! waffle v1.21 (27 Jun 2024)
 *! Asjad Naqvi and Jared Colston
 
+*v1.21 (27 Jun 2024): by _cats bug. Post graph now shows dotval as an output. return locals fixed.
 *v1.2  (26 May 2024): Fix long graph normalization bug. better treatment of null shares. r(dot) added.
 *v1.11 (05 May 2024): Bug fixes to how data was collapsed under different conditions. normvar now needs to be already the sum value.
 *v1.1  (04 Apr 2024): Re-release. Allows wide and long form data.
@@ -12,7 +13,7 @@
 
 capture program drop waffle 
 
-program waffle, sortpreserve rclass
+program waffle, rclass sortpreserve 
 version 15
 
 syntax varlist(numeric min=1) [if] [in], ///
@@ -75,9 +76,12 @@ quietly {
 	}
 	if `length' == 1 {	
 
+		local byoff = 0
+
 		if "`by'" == ""	{
 			gen _by = 1 
 			local by _by
+			local byoff = 1
 		}		
 
 		cap ren `by' _cats
@@ -154,7 +158,9 @@ quietly {
 
 
 
-	if "percent" != "" {
+	return local maxdots `obsv'
+
+	if "`percent'" != "" {
 		local dotval = 100 / `obsv'
 		return local dot `dotval'
 	}
@@ -164,6 +170,7 @@ quietly {
 	}
 
 
+
 	expand `obsv' if _tag==1, gen(_control)	
 
 	sort _grp  _cats _control `over'
@@ -182,6 +189,9 @@ quietly {
 	egen _tag2 = tag(_grp `over')
 	egen _tag3 = group(`over')
 
+
+
+
 	levelsof _grp , local(lvls)
 	levelsof _tag3, local(ovrs)
 
@@ -213,15 +223,23 @@ quietly {
 	}	
 
 
-	cap confirm numeric var _cats
-	if !_rc {
-		decode _cats, gen(_temp)
+	if "`byoff'" != "1" {
+
+		cap confirm numeric var _cats
+		if !_rc {
+			decode _cats, gen(_temp)
+		}
+		else {
+			gen _temp = _cats
+		}
 	}
 	else {
-		gen _temp = _cats
+		gen _temp = string(_cats)
 	}
 
 
+
+
 	if "`format'"  == "" {
 		if "`showpct'"  == "" {
 			local format %15.0fc
@@ -356,6 +374,7 @@ quietly {
 				aspect(`aspect') `options'	
 
 
+	noi display in yellow "Each dot has a value of `dotval'. See {stata return list} for stored values."
 
 	*/
 	}

installation/waffle.pkg

@@ -1,4 +1,4 @@
-v 1.2
+v 1.21
 d {bf:WAFFLE}: A Stata package for Waffle plots.
 d See {helpb waffle} after installation.
 d
@@ -8,9 +8,9 @@ d KW: Stata
 d KW: graphs
 d KW: waffle
 d
-d Distribution-Date: 20240526
+d Distribution-Date: 20240627
 d
-d This  version: 26 May 2024
+d This  version: 27 Jun 2024
 d First version: 01 Mar 2022
 d License: MIT
 d

installation/waffle.sthlp

@@ -1,7 +1,7 @@
 {smcl}
-{* 26May2024}{...}
+{* 27Jun2024}{...}
 {hi:help waffle}{...}
-{right:{browse "https://github.com/asjadnaqvi/stata-waffle":waffle v1.2 (GitHub)}}
+{right:{browse "https://github.com/asjadnaqvi/stata-waffle":waffle v1.21 (GitHub)}}
 
 {hline}
 
@@ -93,15 +93,15 @@ Even if you have these installed, it is highly recommended to check for updates:
 
 {title:Examples}
 
-See {browse "https://github.com/asjadnaqvi/stata-streamplot":GitHub}.
+See {browse "https://github.com/asjadnaqvi/stata-waffle":GitHub}.
 
 {hline}
 
 
 {title:Package details}
 
-Version      : {bf:waffle} v1.2
-This release : 26 May 2024
+Version      : {bf:waffle} v1.21
+This release : 27 Jun 2024
 First release: 01 Mar 2022
 Repository   : {browse "https://github.com/asjadnaqvi/stata-waffle":GitHub}
 Keywords     : Stata, graph, waffle
@@ -112,6 +112,26 @@ E-mail       : [email protected], [email protected]
 Twitter      : {browse "https://twitter.com/AsjadNaqvi":@AsjadNaqvi}
 
 
+{title:Feedback}
+
+Please submit bugs, errors, feature requests on {browse "https://github.com/asjadnaqvi/stata-waffle/issues":GitHub} by opening a new issue.
+
+
+{title:Citation guidelines}
+
+Suggested citation guidlines for this package:
+
+Naqvi, A. and Colston, J. (2024). Stata package "waffle" version 1.21. Release date 27 June 2024. https://github.com/asjadnaqvi/stata-waffle.
+
+@software{waffle,
+   author = {Naqvi, Asjad AND Colston, Jared},
+   title = {Stata package ``waffle''},
+   url = {https://github.com/asjadnaqvi/stata-waffle},
+   version = {1.21},
+   date = {2024-06-27}
+}
+
+
 {title:References}
 
 {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.