Merge pull request #16 from lsms-worldbank/flag-vars-without-var-lbl

Flag variables without variable labels

run-adodown-util.do

@@ -5,8 +5,7 @@
   else if "`c(username)'" == "wb393438" {
       global clone "C:\Users\wb393438\stata_funs\labeller"
   } 
-
-
+
   /*
   ad_setup, adf("${clone}")  ///
       name("labeller")             ///

src/ado/lbl_assert_var_have_lbl.ado

@@ -0,0 +1,35 @@
+*! version XX XXXXXXXXX ADAUTHORNAME ADCONTACTINFO
+
+cap program drop   lbl_assert_var_have_lbl
+    program define lbl_assert_var_have_lbl, rclass
+
+  version 13
+
+  syntax [varlist]
+
+  qui {
+
+    * look for variables without a label
+    lbl_list_no_var_lbl `varlist'
+    local any_wo_var_lbl = (`r(count_matches)' > 0)
+    local n_wo_var_lbl = "`r(count_matches)'"
+    local which_no_var_lbl "`r(varlist)'"
+
+    * return results
+    return local varlist "`which_no_var_lbl'"
+    return local any_matches "`any_wo_var_lbl'"
+    return local count_matches "`n_wo_var_lbl'"
+
+    * if any variables without labels found, message and error
+    if (`any_wo_var_lbl' == 1) {
+      di as error "{pstd}Variables found without a variable label :{p_end}",
+      di as error "{phang}`which_no_var_lbl'{p_end}"
+      error 9
+    }
+    else {
+      di as result "{pstd}No variables found with a variable label.{p_end}"
+    }
+
+  }
+
+end

src/ado/lbl_list_no_var_lbl.ado

@@ -0,0 +1,37 @@
+*! version XX XXXXXXXXX ADAUTHORNAME ADCONTACTINFO
+
+cap program drop   lbl_list_no_var_lbl
+    program define lbl_list_no_var_lbl, rclass
+
+  version 13
+
+  syntax [varlist]
+
+  qui {
+
+    * get all variables that lack a variable label
+    ds `varlist', not(varlabel)
+    local vars "`r(varlist)'"
+
+    * reset varlist to avoid collision with varlist in syntax
+    local varlist ""
+
+    * compute the number of matches
+    local n_matches : list sizeof vars
+
+    * return the varlist and count of matches
+    return local varlist "`vars'"
+    return local count_matches "`n_matches'"
+
+    * message about outcome
+    if (`n_matches' >= 1) {
+      noi di as result "{pstd}Variables found without a variable label :{p_end}"
+      noi di as result "{phang}`vars'{p_end}"
+    }
+    else if (`n_matches' == 0) {
+      noi di as result "{pstd}No variables found without a label{p_end}"
+    }
+
+  }
+
+end

src/labeller.pkg

@@ -20,11 +20,15 @@ d
 d Distribution-Date: 20231109
 d
 *** adofiles
+f ado/lbl_assert_var_have_lbl.ado
+f ado/lbl_list_no_var_lbl.ado
+f ado/labeller.ado
 f ado/lbl_assert_no_long_varlbl.ado
 f ado/lbl_list_long_varlbl.ado
-f ado/labeller.ado
 
 *** helpfiles
+f sthlp/lbl_assert_var_have_lbl.sthlp
+f sthlp/lbl_list_no_var_lbl.sthlp
 f sthlp/lbl_assert_no_long_varlbl.sthlp
 f sthlp/lbl_list_long_varlbl.sthlp
 f sthlp/labeller.sthlp

src/mdhlp/lbl_assert_var_have_lbl.md

@@ -0,0 +1,47 @@
+# Title
+
+__lbl_assert_var_have_lbl__ - List variables without a variable label.
+
+# Syntax
+
+__lbl_assert_var_have_lbl__ [varlist]
+
+# Description
+
+For small data sets, visual inspection can identify variables without a variable label. For larger data sets (or repeat encounters with data sets), it is better to have a tool variables, if any, that remain without a variable label. 
+
+This command does that. If any variables without variable labels are found, it returns and error and lists which variables are missing variable labels. If all variables have variable labels, it reports this fact. In this way, the user knows whether action is needed, and for which variables.
+
+By default, the command combs over all variables in memory when compiling a list. By providing a variable list, users can restrict the scope of the search to the user-specified range.
+
+# Examples
+
+```
+* create set of variables
+gen var1 = .
+gen var2 = .
+gen var3 = .
+gen var4 = .
+
+* apply variable labels to only some variables
+label variable var1 "Some label"
+label variable var4 "Another label"
+
+* assert that all variables have variable labels, globally
+lbl_assert_var_have_lbl
+
+* assert that all variables have variable labels, in the varlist
+lbl_assert_var_have_lbl var3 - var4
+```
+
+# Feedback, bug reports and contributions
+
+Read more about the commands in this package at https://github.com/lsms-worldbank/labeller.
+
+Please provide any feedback by opening an issue at https://github.com/lsms-worldbank/labeller/issues.
+
+PRs with suggestions for improvements are also greatly appreciated.
+
+# Authors
+
+LSMS Team, The World Bank [email protected]

src/mdhlp/lbl_list_no_var_lbl.md

@@ -0,0 +1,47 @@
+# Title
+
+__lbl_list_no_var_lbl__ - List variables without a variable label.
+
+# Syntax
+
+__lbl_list_no_var_lbl__ [varlist]
+
+# Description
+
+For small data sets, visual inspection can identify variables without a variable label. For larger data sets (or repeat encounters with data sets), it is better to have a tool variables, if any, that remain without a variable label. 
+
+This command does that.  If any variables without variable labels are found, it lists them. If all variables have variable labels, it says so. That way, the user knows whether action is needed, and for which variables.
+
+By default, the command combs over all variables in memory when compiling a list. By providing a variable list, users can restrict the scope of the search to the user-specified range.
+
+# Examples
+
+```
+* create set of variables
+gen var1 = .
+gen var2 = .
+gen var3 = .
+gen var4 = .
+
+* apply variable labels to only some variables
+label variable var1 "Some label"
+label variable var4 "Another label"
+
+* list variables without variable labels globally
+lbl_list_no_var_lbl
+
+* list variables without a label in the varlist
+lbl_list_no_var_lbl var3 - var4
+```
+
+# Feedback, bug reports and contributions
+
+Read more about the commands in this package at https://github.com/lsms-worldbank/labeller.
+
+Please provide any feedback by opening an issue at https://github.com/lsms-worldbank/labeller/issues.
+
+PRs with suggestions for improvements are also greatly appreciated.
+
+# Authors
+
+LSMS Team, The World Bank [email protected]

src/tests/test-lbl_list_no_var_lbl.do

@@ -0,0 +1,108 @@
+* Kristoffer's root path
+if "`c(username)'" == "wb462869" {
+    global clone "C:\Users\wb462869\github\labeller"
+}
+else if "`c(username)'" == "wb393438" {
+    global clone "C:\Users\wb393438\stata_funs\labeller\labeller"
+}
+
+* Set global to ado_fldr
+global src_fldr  "${clone}/src"
+global test_fldr "${src_fldr}/tests"
+global data_fldr "${test_fldr}/testdata"
+
+* Install the version of this package in
+* the plus-ado folder in the test folder
+cap mkdir "${test_fldr}/plus-ado"
+repado , adopath("${test_fldr}/plus-ado") mode(strict)
+
+cap net uninstall labeller
+net install labeller, from("${src_fldr}") replace
+
+* output version of this package
+labeller
+
+* ==============================================================================
+* Setup
+* ==============================================================================
+
+* create set of variables
+gen var1 = .
+gen var2 = .
+gen var3 = .
+gen var4 = .
+
+* apply variable labels to only some variables
+label variable var1 "Some label"
+label variable var4 "Another label"
+
+* ==============================================================================
+* List
+* ==============================================================================
+
+* ------------------------------------------------------------------------------
+* Lists variables without labels globally
+* ------------------------------------------------------------------------------
+
+* list variables without variable labels globally
+lbl_list_no_var_lbl
+local vars_wo_lbl = r(varlist)
+local vars_wo_lbl : list clean vars_wo_lbl
+
+* test
+capture assert "`vars_wo_lbl'" == "var2 var3"
+di as result "lbl_list_no_var_lbl lists variables without labels globally"
+if _rc != 0 {
+    di as error "❌ Test failed"
+    error 0
+}
+else {
+    di as result "✅ Test passed"
+}
+
+* ------------------------------------------------------------------------------
+* lists variables with without labels in varlist
+* ------------------------------------------------------------------------------
+
+* list variables without a label in the varlist
+lbl_list_no_var_lbl var3 - var4
+local vars_wo_lbl_in_varlist = r(varlist)
+local vars_wo_lbl_in_varlist : list clean vars_wo_lbl_in_varlist
+
+* test
+capture assert "`vars_wo_lbl_in_varlist'" == "var3"
+di as result "vars_wo_lbl_in_varlist lists variables with without labels in varlist"
+if _rc != 0 {
+    di as error "❌ test failed"
+    error 0
+}
+else {
+    di as result "✅ test passed"
+}
+
+* ==============================================================================
+* Assert
+* ==============================================================================
+
+* ------------------------------------------------------------------------------
+* Assertion fails if violations present
+* ------------------------------------------------------------------------------
+
+* assert that all variables have a label
+capture lbl_assert_var_have_lbl
+
+* test
+di as result "lbl_assert_var_have_lbl errors if any var is without a label"
+if _rc == 0 {
+    di as error "❌ Test failed"
+    error 0
+}
+else {
+    di as result "✅ Test passed"
+}
+
+* ==============================================================================
+* Teardown
+* ==============================================================================
+
+drop var1 - var4