diff --git a/src/ado/labeller.ado b/src/ado/labeller.ado index 6a527e4..43ed46c 100644 --- a/src/ado/labeller.ado +++ b/src/ado/labeller.ado @@ -1,7 +1,8 @@ cap program drop labeller program define labeller, rclass - version 13.0 +qui { + version 14 * UPDATE THESE LOCALS FOR EACH NEW VERSION PUBLISHED local version "1.0" @@ -37,9 +38,9 @@ cap program drop labeller exit } * Run the subcommand - `subcommand', `parameters' + noi `subcommand', `parameters' } - +} end cap program drop output_verbose @@ -68,7 +69,7 @@ end cap program drop output_veryverbose program define output_veryverbose - syntax, title(string) ttitle1(string) ttitle2(string) [vars(varlist)] + syntax, title(string) ttitle1(string) ttitle2(string) [varlist(varlist)] noi di as text "{pstd}`title'{p_end}" @@ -90,7 +91,7 @@ cap program drop output_veryverbose noi di as text "{p2col `p2_all':{it:{ul:`ttitle1'}}} {it:{ul:`ttitle2'}}" _n * Write each label - foreach varname of local vars { + foreach varname of local varlist { local varlab : variable label `varname' noi di as text "{p2col `p2_all':{bf:`varname'}} {text:`varlab'}" _n } diff --git a/src/ado/lbl_assert_no_long_varlbl.ado b/src/ado/lbl_assert_no_long_varlbl.ado index 11dbc7e..d9dd90e 100644 --- a/src/ado/lbl_assert_no_long_varlbl.ado +++ b/src/ado/lbl_assert_no_long_varlbl.ado @@ -3,7 +3,7 @@ cap program drop lbl_assert_no_long_varlbl version 14 - syntax [varlist], [MAXlen(integer 80)] + syntax, [MAXlen(integer 80) Varlist(varlist)] qui { diff --git a/src/ado/lbl_assert_no_pipes.ado b/src/ado/lbl_assert_no_pipes.ado index 43339bb..e7984b7 100644 --- a/src/ado/lbl_assert_no_pipes.ado +++ b/src/ado/lbl_assert_no_pipes.ado @@ -2,9 +2,15 @@ cap program drop lbl_assert_no_pipes program define lbl_assert_no_pipes +qui { + version 14 * Update the syntax. This is only a placeholder to make the command run - syntax, [IGnore_pipes(string) OUTput_level(string)] + syntax, [IGnore_pipes(string) OUTput_level(string) Varlist(varlist)] + + * Get all variables in varlist or get all variables + ds `varlist' + local varlist "`r(varlist)'" * Set defaults if missing("`output_level'") local output_level "verbose" @@ -14,7 +20,7 @@ cap program drop lbl_assert_no_pipes } * Get the list of pipes used and the vars they are used for - qui lbl_list_pipes, output_level(minimal) + qui lbl_list_pipes, output_level(minimal) varlist("`varlist'") local pipes_found "`r(pipes)'" * Add the vars with remaining pipes for each pipe @@ -36,10 +42,10 @@ cap program drop lbl_assert_no_pipes local title "{err:Pipe %`pipe'% still in variable(s):}" if ("`output_level'" == "verbose") { //noi di `"output_verbose, title("`title'") values("``pipe'_v'")"' - labeller output_verbose title("`title'") values("``pipe'_v'") + noi labeller output_verbose title("`title'") values("``pipe'_v'") } else if ("`output_level'" == "veryverbose") { - labeller output_veryverbose title("`title'") vars("``pipe'_v'") /// + noi labeller output_veryverbose title("`title'") varlist("``pipe'_v'") /// ttitle1("Variable") ttitle2("Variable label") noi di as text "{p2line}" _n } @@ -51,5 +57,5 @@ cap program drop lbl_assert_no_pipes else { noi di as result _n "{pstd}No more pipes in dataset{p_end}" } - +} end diff --git a/src/ado/lbl_assert_var_have_lbl.ado b/src/ado/lbl_assert_varlbls.ado similarity index 72% rename from src/ado/lbl_assert_var_have_lbl.ado rename to src/ado/lbl_assert_varlbls.ado index 6b4bc1c..1822503 100644 --- a/src/ado/lbl_assert_var_have_lbl.ado +++ b/src/ado/lbl_assert_varlbls.ado @@ -1,16 +1,20 @@ *! version XX XXXXXXXXX ADAUTHORNAME ADCONTACTINFO -cap program drop lbl_assert_var_have_lbl - program define lbl_assert_var_have_lbl, rclass +cap program drop lbl_assert_have_varlbl + program define lbl_assert_have_varlbl, rclass - version 13 + version 14 - syntax [varlist] + syntax , Varlist(varlist) qui { + * Get all variables in varlist or get all variables + ds `varlist' + local varlist "`r(varlist)'" + * look for variables without a label - lbl_list_no_var_lbl `varlist' + lbl_list_no_varlbl, varlist(`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)'" @@ -29,7 +33,6 @@ cap program drop lbl_assert_var_have_lbl else { di as result "{pstd}No variables found with a variable label.{p_end}" } - } end diff --git a/src/ado/lbl_list_long_varlbl.ado b/src/ado/lbl_list_long_varlbl.ado index 9272ef5..97b8cd9 100644 --- a/src/ado/lbl_list_long_varlbl.ado +++ b/src/ado/lbl_list_long_varlbl.ado @@ -5,19 +5,19 @@ cap program drop lbl_list_long_varlbl version 14 - syntax [varlist], [MAXlen(integer 80)] + syntax, [MAXlen(integer 80) Varlist(varlist)] qui { * get list of all variables ds `varlist', has(varlabel) - local vars = r(varlist) + local varlist = r(varlist) * initialize list of variables with labels that are too long local vars_lbl_too_long "" * populate list of variables - foreach var of local vars { + foreach var of local varlist { * extract variable label local var_lbl : variable label `var' diff --git a/src/ado/lbl_list_matching_vals.ado b/src/ado/lbl_list_matching_vals.ado new file mode 100644 index 0000000..aa253e5 --- /dev/null +++ b/src/ado/lbl_list_matching_vals.ado @@ -0,0 +1,112 @@ +*! version XX XXXXXXXXX ADAUTHORNAME ADCONTACTINFO + +cap program drop lbl_list_matching_vals + program define lbl_list_matching_vals, rclass + + version 14 + + syntax, pattern(string) [NEGate VERbose Varlist(varlist)] + + qui { + + * get list of variables with value labels + ds `varlist', has(vallabel) + local vars_w_val_lbl "`r(varlist)'" + local n_vars_w_val_lbl : list sizeof vars_w_val_lbl + + * get list of labels for vars in varlist + * providing a varlist if none specified + if (mi("`varlist'")) { + d, varlist + local varlist = r(varlist) + } + local val_lbls_for_varlist "" + foreach var of local varlist { + local val_lbl_curr_var : value label `var' + local val_lbls_for_varlist "`val_lbls_for_varlist' `val_lbl_curr_var'" + } + + * compile the list of labels with matching elements + * by working in a frame so that the data can be converted into + * a data set of labels + tempname val_lbls + frame copy default `val_lbls' + frame `val_lbls' { + + * create a data set of labels + uselabel, clear var + + * capture the list of value labels with a matching element + d // for computing observation count + if (`r(N)' == 0) { + local val_lbls_w_matching_val "" + } + else if (`r(N)' > 0) { + + * labels that match in whole data set + levelsof lname if ustrregexm(label, "`pattern'"), /// + local(val_lbls_w_matching_val) clean + + * construct list of matching variables + if (mi("`negate'")) { + local val_lbls_matching_in_varlist : list val_lbls_for_varlist & val_lbls_w_matching_val + } + if (!mi("`negate'")) { + * all label names + levelsof lname, local(all_val_lbls) clean + * labels to exclude + local val_lbls_to_exclude "`val_lbls_w_matching_val'" + local val_lbls_to_exclude : list val_lbls_to_exclude & val_lbls_for_varlist + * compliment of matching labels + local val_lbls_matching_in_varlist : list all_val_lbls - val_lbls_to_exclude + } + + } + + } + + * compile list of variables whose value labels have a matching element + if (mi("`val_lbls_matching_in_varlist'")) { + local vars_w_matching_val_lbl "" + } + else if (!mi("`val_lbls_matching_in_varlist'")) { + * list variables with one of the variable label names piped into `has()' + ds, has(vallabel `val_lbls_matching_in_varlist') + local vars_w_matching_val_lbl "`r(varlist)'" + * restrict to variables in the varlist with labels + local vars_w_matching_val_lbl : list vars_w_matching_val_lbl & vars_w_val_lbl + } + + * compile the list of matching labels + * capture this from the val_lbls frame so that present in main frame + local val_lbls_matching_in_varlist "`val_lbls_matching_in_varlist'" + + * compute the number of matches + local n_matching_val_lbls : list sizeof val_lbls_matching_in_varlist + local n_matching_vars : list sizeof vars_w_matching_val_lbl + + * report on findings + if (`n_matching_val_lbls' == 0) { + noi: di as result "No matching value labels found" + } + else if (`n_matching_val_lbls' > 0) { + * print basic results message + noi: di as result "Matching value labels found." + noi: di as result "`n_matching_val_lbls' value labels attached to `n_matching_vars' variables." + noi: di as result "Value labels: `val_lbls_matching_in_varlist'" + noi: di as result "Variables: `vars_w_matching_val_lbl'" + * if verbose mode, print out matching value label sets + if (!mi("`verbose'")) { + noi: label list `val_lbls_matching_in_varlist' + } + } + + * return results + return local lbl_count "`n_matching_val_lbls'" + return local val_lbl_list "`val_lbls_matching_in_varlist'" + return local var_count "`n_matching_vars'" + return local varlist "`vars_w_matching_val_lbl'" + + } + +end diff --git a/src/ado/lbl_list_matching_vars.do b/src/ado/lbl_list_matching_vars.ado similarity index 87% rename from src/ado/lbl_list_matching_vars.do rename to src/ado/lbl_list_matching_vars.ado index a9fabfa..fecdadc 100644 --- a/src/ado/lbl_list_matching_vars.do +++ b/src/ado/lbl_list_matching_vars.ado @@ -1,19 +1,19 @@ capture program drop lbl_list_matching_vars - program define lbl_list_matching_vars, rclass + program define lbl_list_matching_vars, rclass qui { - syntax anything (name=pattern), [varlist(varlist)] [NEGate] + syntax anything (name=pattern), [varlist(varlist) NEGate] version 14 * get list of all (matching) variables ds `varlist', has(varlabel) - local vars = r(varlist) + local varlist = r(varlist) local vars_w_match_lbl "" - foreach var of local vars { + foreach var of local varlist { * extract the variable label local var_label : variable label `var' @@ -28,7 +28,6 @@ qui { else if (!mi("`negate'") & (`lbl_matches' == 0)) { local vars_w_match_lbl "`vars_w_match_lbl' `var'" } - } * compute the number of matches @@ -46,8 +45,7 @@ qui { else if (`n_matches' == 0) { noi di as error "No matching variables found" noi di as result "If this result is unexpected, please check the regular expression provided." - } - + } } end diff --git a/src/ado/lbl_list_no_var_lbl.ado b/src/ado/lbl_list_no_varlbl.ado similarity index 65% rename from src/ado/lbl_list_no_var_lbl.ado rename to src/ado/lbl_list_no_varlbl.ado index 4f490d5..a3bb9d7 100644 --- a/src/ado/lbl_list_no_var_lbl.ado +++ b/src/ado/lbl_list_no_varlbl.ado @@ -1,26 +1,23 @@ *! version XX XXXXXXXXX ADAUTHORNAME ADCONTACTINFO -cap program drop lbl_list_no_var_lbl - program define lbl_list_no_var_lbl, rclass +cap program drop lbl_list_no_varlbl + program define lbl_list_no_varlbl, rclass - version 13 + version 14 - syntax [varlist] + syntax, [Varlist(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 "" + local varlist "`r(varlist)'" * compute the number of matches - local n_matches : list sizeof vars + local n_matches : list sizeof varlist * return the varlist and count of matches - return local varlist "`vars'" + return local varlist "`varlist'" return local count_matches "`n_matches'" * message about outcome @@ -31,7 +28,6 @@ cap program drop lbl_list_no_var_lbl else if (`n_matches' == 0) { noi di as result "{pstd}No variables found without a label{p_end}" } - } end diff --git a/src/ado/lbl_list_pipes.ado b/src/ado/lbl_list_pipes.ado index 9391d01..2b1477b 100644 --- a/src/ado/lbl_list_pipes.ado +++ b/src/ado/lbl_list_pipes.ado @@ -3,8 +3,16 @@ cap program drop lbl_list_pipes program define lbl_list_pipes, rclass +qui { + + version 14 + * Update the syntax. This is only a placeholder to make the command run - syntax , [IGnore_pipes(string) OUTput_level(string)] + syntax, [IGnore_pipes(string) OUTput_level(string) Varlist(varlist)] + + * Get all variables in varlist or get all variables + ds `varlist' + local varlist "`r(varlist)'" * Set defaults if missing("`output_level'") local output_level "verbose" @@ -21,7 +29,7 @@ cap program drop lbl_list_pipes ************************************************** * Loop over all variables to list all pipes and all vars each are used for - foreach var of varlist _all { + foreach var of local varlist { * Reset locals used in serach local is_pipe 0 @@ -94,10 +102,10 @@ cap program drop lbl_list_pipes if ("`output_level'" == "verbose") { //noi di `"output_verbose, title("`title'") values("``pipe'_v'")"' - labeller output_verbose title("`title'") values("``pipe'_v'") + noi labeller output_verbose title("`title'") values("``pipe'_v'") } else if ("`output_level'" == "veryverbose") { - labeller output_veryverbose title("`title'") vars("``pipe'_v'") /// + noi labeller output_veryverbose title("`title'") varlist("``pipe'_v'") /// ttitle1("Variable") ttitle2("Variable label") noi di as text "{p2line}" _n } @@ -116,5 +124,5 @@ cap program drop lbl_list_pipes * Output the pipes found return local pipes "`pipes_found'" - +} end diff --git a/src/ado/lbl_replace_pipe.ado b/src/ado/lbl_replace_pipe.ado index 45d16dc..35018d8 100644 --- a/src/ado/lbl_replace_pipe.ado +++ b/src/ado/lbl_replace_pipe.ado @@ -3,8 +3,16 @@ cap program drop lbl_replace_pipe program define lbl_replace_pipe, rclass +qui { + + version 14 + * Update the syntax. This is only a placeholder to make the command run - syntax , pipe(string) REPlacement(string) [TRUNcate(string) OUTput_level(string) missing_ok] + syntax, pipe(string) REPlacement(string) [TRUNcate(string) OUTput_level(string) missing_ok Varlist(varlist)] + + * Get all variables in varlist or get all variables + ds `varlist' + local varlist "`r(varlist)'" * Set defaults if missing("`truncate'") local truncate "error" @@ -30,10 +38,10 @@ cap program drop lbl_replace_pipe * Remove % symbol if used in pipe local pipe = subinstr("`pipe'","%","",.) - * Get the list of pipes used and the vars they are used for - qui lbl_list_pipes, output_level(minimal) + * Get the list of pipes used and the varlist they are used for + qui lbl_list_pipes, output_level(minimal) varlist("`varlist'") local pipes_found "`r(pipes)'" - local vars "`r(`pipe'_v)'" + local varlist "`r(`pipe'_v)'" * Test that the pipe to be replaced was found if !(`: list pipe in pipes_found') { @@ -54,7 +62,7 @@ cap program drop lbl_replace_pipe else { * Loop over each label this pipe is used for - foreach var of local vars { + foreach var of local varlist { * Constructthe new label local lab : variable label `var' @@ -122,11 +130,11 @@ cap program drop lbl_replace_pipe else { local title "{ul:{bf:Pipe %`pipe'% replaced in variable(s):}}" if ("`output_level'" == "verbose") { - //noi di `"output_verbose, title("`title'") values("``pipe'_v'")"' - labeller output_verbose title("`title'") values("`vars'") + noi labeller output_verbose title("`title'") values("`varlist'") } else if ("`output_level'" == "veryverbose") { - labeller output_veryverbose title("`title'") vars("`vars'") /// + noi labeller output_veryverbose title("`title'") /// + varlist("`varlist'") /// ttitle1("Variable") ttitle2("New variable label") noi di as text "{p2line}" _n } @@ -135,5 +143,5 @@ cap program drop lbl_replace_pipe } } - +} end diff --git a/src/dev/run-adodown-util.do b/src/dev/run-adodown-util.do index 54ef973..01f9c79 100644 --- a/src/dev/run-adodown-util.do +++ b/src/dev/run-adodown-util.do @@ -4,7 +4,7 @@ } * Fill in your root path here if "`c(username)'" == "wb393438" { - global clone "C:\Users\wb393438\stata_funs\labeller" + global clone "C:\Users\wb393438\stata_funs\labeller\labeller" } // ad_setup, adf("${clone}") /// diff --git a/src/labeller.pkg b/src/labeller.pkg index 022745e..bb57fa1 100644 --- a/src/labeller.pkg +++ b/src/labeller.pkg @@ -7,7 +7,7 @@ d labeller d A packge with utility commands related to lables. Particularly, but not exclusively, in relation to data sets collected using SurveySolutions. d *** stata -d Version: Stata 14.1 +d Version: Stata 14 d *** author d Author: LSMS Worldbank @@ -20,24 +20,29 @@ 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/lbl_assert_varlbls.ado +f ado/lbl_list_no_varlbl.ado f ado/lbl_replace_pipe.ado f ado/lbl_assert_no_pipes.ado f ado/lbl_list_pipes.ado +f ado/lbl_list_matching_vals.ado f ado/labeller.ado f ado/lbl_assert_no_long_varlbl.ado f ado/lbl_list_long_varlbl.ado +f ado/lbl_list_matching_vars.ado *** helpfiles -f sthlp/lbl_assert_var_have_lbl.sthlp -f sthlp/lbl_list_no_var_lbl.sthlp +f sthlp/lbl_list_matching_vals.sthlp +f sthlp/lbl_assert_varlbls.sthlp +f sthlp/lbl_list_no_varlbl.sthlp f sthlp/lbl_assert_no_long_varlbl.sthlp f sthlp/lbl_list_long_varlbl.sthlp f sthlp/lbl_replace_pipe.sthlp f sthlp/lbl_assert_no_pipes.sthlp f sthlp/lbl_list_pipes.sthlp f sthlp/labeller.sthlp +f sthlp/lbl_list_matching_vars.sthlp + *** ancillaryfiles diff --git a/src/mdhlp/lbl_assert_no_long_varlbl.md b/src/mdhlp/lbl_assert_no_long_varlbl.md index a4a6254..1ef9f1a 100644 --- a/src/mdhlp/lbl_assert_no_long_varlbl.md +++ b/src/mdhlp/lbl_assert_no_long_varlbl.md @@ -4,11 +4,12 @@ __lbl_assert_no_long_varlbl__ - Assert that there is no variable in memory whose # Syntax -__lbl_assert_no_long_varlbl__ , __**max**len__(_integer_) +__lbl_assert_no_long_varlbl__ , [__**max**len__(_integer_) __**v**arlist__(_varlist_) ] | _options_ | Description | |-----------|-------------| | __**max**len__(_integer_) | Maximum character length allowed. +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # Description @@ -22,6 +23,8 @@ If there is at least one variable whose length exceeds the maximum length, the c __**max**len__(_integer_) sets the maximum length of variable labels. +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. + # Examples ``` diff --git a/src/mdhlp/lbl_assert_no_pipes.md b/src/mdhlp/lbl_assert_no_pipes.md index ff6443b..063ad2b 100644 --- a/src/mdhlp/lbl_assert_no_pipes.md +++ b/src/mdhlp/lbl_assert_no_pipes.md @@ -4,12 +4,13 @@ __lbl_assert_no_pipes__ - Asserts that no variable labels have any pipes # Syntax -__lbl_assert_no_pipes__ , [__**ig**nore_pipes__(_string_) __**out**put_level__(_string_)] +__lbl_assert_no_pipes__ , [__**ig**nore_pipes__(_string_) __**out**put_level__(_string_) __**v**arlist__(_varlist_)] | _options_ | Description | |-----------|-------------| | __**ig**nore_pipes__(_string_) | List of pipe names to be ignored | | __**out**put_level__(_string_) | Toggle verbosity level in output | +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # Description @@ -44,6 +45,8 @@ set how verbose the output should be. The valid values for this option are `minimal`, `verbose`, and `veryverbose`. The default is `verbose`. +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. + # Examples This simple example first creates a data set where diff --git a/src/mdhlp/lbl_assert_var_have_lbl.md b/src/mdhlp/lbl_assert_varlbls.md similarity index 74% rename from src/mdhlp/lbl_assert_var_have_lbl.md rename to src/mdhlp/lbl_assert_varlbls.md index 339597b..6bb4435 100644 --- a/src/mdhlp/lbl_assert_var_have_lbl.md +++ b/src/mdhlp/lbl_assert_varlbls.md @@ -4,15 +4,21 @@ __lbl_assert_var_have_lbl__ - List variables without a variable label. # Syntax -__lbl_assert_var_have_lbl__ [varlist] +__lbl_assert_var_have_lbl__, [__**v**arlist__(_varlist_)] + +| _options_ | Description | +|-----------|-------------| +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # 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. +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. +# Options + +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. # Examples diff --git a/src/mdhlp/lbl_list_long_varlbl.md b/src/mdhlp/lbl_list_long_varlbl.md index eb07dff..8b770f7 100644 --- a/src/mdhlp/lbl_list_long_varlbl.md +++ b/src/mdhlp/lbl_list_long_varlbl.md @@ -4,11 +4,12 @@ __lbl_list_long_varlbl__ - List variables whose variable label is longer than th # Syntax -__lbl_list_long_varlbl__ , __**max**len__(_integer_) +__lbl_list_long_varlbl__ , [__**max**len__(_integer_) __**v**arlist__(_varlist_)] | _options_ | Description | |-----------|-------------| | __**max**len__(_integer_) | Maximum character length allowed. +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # Description @@ -26,6 +27,8 @@ By default, the command take the maximum length to be Stata's maximum length for __**max**len__(_integer_) sets the maximum length of variable labels, beyond which a variable is listed by this command. +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. + # Examples ``` diff --git a/src/mdhlp/lbl_list_matching_vals.md b/src/mdhlp/lbl_list_matching_vals.md new file mode 100644 index 0000000..7b0624d --- /dev/null +++ b/src/mdhlp/lbl_list_matching_vals.md @@ -0,0 +1,110 @@ +# Title + +__lbl_list_matching_vals__ - List value labels whose labels match a pattern. + +# Syntax + +__lbl_list_matching_vals__, __pattern__(_string_) [__**neg**ate__ __**ver**bose__ __**v**arlist__(_varlist_)] + +| _options_ | Description | +|-----------|-------------| +| __pattern__(_string_) | Pattern to find in an answer option. Provide either a substring or a regular expression. | +| __**neg**ate__ | Inverts the search, returning value labels that do __not__match the pattern. | +| __**ver**bose__ | Print out labels that match query. Output corresponds to `label list lblnames`. | +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | + +# Description + +While Stata offers some tools for searching the content of variable labels (e.g. `lookfor`), it does not have any methods for similarly searching the contents of value labels. + +This command aims fill this gap by: + +- Searching labels in value labels for a pattern +- Identifying variable labels that contain labels of interest +- Compiling variables that have these labels of interest attached + +This command can be particularly useful for checking that variable do (not) contain patterns of interest. Consider for example: + +- Confirming that value labels contain (e.g., no) +- Identifying value labels that deviate from standards + +# Options + +__pattern__(_string_) provides the text pattern to find in the contents of value labels. Rather be the traitional Stata glob pattern, this pattern is a sub-string or a regular expression. + +__**neg**ate__ inverts the search, returning value labels that do __not__match the pattern. In isolation, `pattern("my_text")` looks for value labels containing `"my_text"`. With `negate`, `pattern("my_search")` search looks instead for value labels that do not contain `"my_text"`. + +__**ver**bose__ manages the how much output is printed. If the `verbose` option is not provided, `lbl_list_matching_vals` reports on whether any matches were found--and, if so, how many value labels match and how many variables the matching value labels describe. If the `verbose` option is specified, the command will additionally print the contents of the matching value labels as a convenience. + +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. + +# Examples + +## Example 1: contain a pattern + +``` +* create some fake data +gen var1 = . +gen var2 = . +gen var3 = . +gen var4 = . + +* create some value labels +label define var1_lbl 1 "Yes" 2 "No" +label define var2_lbl 1 "Oui" 2 "Non" 3 "Oui, oui" +label define var4_lbl 1 "Oui" 2 "Non" + +* apply those labels to some, but not all, variables +label values var1 var1_lbl +label values var2 var2_lbl +label values var4 var4_lbl + +* find value labels with "Oui" and/or "oui" in at least one constituent label +lbl_list_matching_vals, pattern("[Oo]ui") + +* find value labels and print out the contents of the label, for convenience +* i.e., to avoid the next step that many users might logically make: +* `label list matching_lbl` +lbl_list_matching_vals, pattern("[Oo]ui") verbose +``` + +## Example 2: do not contain a pattern + +``` +* find value labels that do not contain a certain pattern +* for example, no "Oui"/"oui" in yes/no labels from a French-language survey +lbl_list_matching_vals, pattern("[Oo]ui") negate +``` + +## Example 3: contain only a certain set of characters + +``` +* create some value labels +label drop _all +* var1_lbl var2_lbl var4_lbl +label define var1_lbl 1 "YES" 2 "NO" +label define var2_lbl 1 "Yes" 2 "No" +label define var3_lbl 1 "yes" 2 "no" +label define var4_lbl 1 "Où" 2 "Là" + +* attach them to variables created above +label values var1 var1_lbl +label values var2 var2_lbl +label values var3 var3_lbl +label values var4 var4_lbl + +* contains no lower-case characters +lbl_list_matching_vals, pattern("[:lower:]") negate + +* contains no French characters +lbl_list_matching_vals, pattern("[àâäÀÂÄéèêëÉÈÊËîïôöÔÖùûüçÇ]") negate + +``` + +# Feedback, bug reports and contributions + +Read more about these commands on [this repo](https://github.com/lsms-worldbank/labeller) where this package is developed. Please provide any feedback by [opening an issue](https://github.com/lsms-worldbank/labeller/issues). PRs with suggestions for improvements are also greatly appreciated. + +# Authors + +LSMS Team, The World Bank lsms@worldbank.org diff --git a/src/mdhlp/lbl_list_matching_vars.md b/src/mdhlp/lbl_list_matching_vars.md index 0fd1bb1..2c76a48 100644 --- a/src/mdhlp/lbl_list_matching_vars.md +++ b/src/mdhlp/lbl_list_matching_vars.md @@ -4,12 +4,12 @@ __lbl_list_matching_vars__ - Identify variables whose label matches a pattern. # Syntax -__lbl_list_matching_vars__ _regexstring_, [__varlist(varlist)__ __**neg**ate__] +__lbl_list_matching_vars__ _regexstring_, [__**neg**ate__ __**v**arlist__(_varlist_)] | _options_ | Description | |-----------|-------------| -| __varlist(varlist)__ | Restricts the scope of search to a variable list | | __**neg**ate__ | Returns variables whose label does __not__ match | +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # Description @@ -26,7 +26,7 @@ This function to fill the gap the following gaps: __**neg**ate__ inverts the match. Rather than return variables with matching variable labels, this option returns variables whose variable label do not match. -__varlist__ restricts the scope of the search to the user-provided variable list. By default, `lbl_list_matching_vars` searches for matches in all variables in memory. With __varlist__, the scope of the search can be narrowed. +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. # Examples diff --git a/src/mdhlp/lbl_list_no_var_lbl.md b/src/mdhlp/lbl_list_no_varlbl.md similarity index 65% rename from src/mdhlp/lbl_list_no_var_lbl.md rename to src/mdhlp/lbl_list_no_varlbl.md index 70a801a..6a96c1a 100644 --- a/src/mdhlp/lbl_list_no_var_lbl.md +++ b/src/mdhlp/lbl_list_no_varlbl.md @@ -1,18 +1,24 @@ # Title -__lbl_list_no_var_lbl__ - List variables without a variable label. +__lbl_list_no_varlbl__ - List variables without a variable label. # Syntax -__lbl_list_no_var_lbl__ [varlist] +__lbl_list_no_varlbl__, [__**v**arlist__(_varlist_)] + +| _options_ | Description | +|-----------|-------------| +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # 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. +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. +# Options + +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. # Examples @@ -28,10 +34,10 @@ label variable var1 "Some label" label variable var4 "Another label" * list variables without variable labels globally -lbl_list_no_var_lbl +lbl_list_no_varlbl * list variables without a label in the varlist -lbl_list_no_var_lbl var3 - var4 +lbl_list_no_varlbl, varlist(var3 - var4) ``` # Feedback, bug reports and contributions diff --git a/src/mdhlp/lbl_list_pipes.md b/src/mdhlp/lbl_list_pipes.md index ec794d6..6ba101e 100644 --- a/src/mdhlp/lbl_list_pipes.md +++ b/src/mdhlp/lbl_list_pipes.md @@ -4,12 +4,13 @@ __lbl_list_pipes__ - Lists pipes in variable labels from Survey Solutions # Syntax -__lbl_list_pipes__ , [__**ig**nore_pipes__(_string_) __**out**put_level__(_string_)] +__lbl_list_pipes__ , [__**ig**nore_pipes__(_string_) __**out**put_level__(_string_) __**v**arlist__(_varlist_)] | _options_ | Description | |-----------|-------------| | __**ig**nore_pipes__(_string_) | List of pipe names to be ignored | | __**out**put_level__(_string_) | Toggle verbosity level in output | +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # Description @@ -35,6 +36,8 @@ The valid values for this option are `minimal`, `verbose`, and `veryverbose`. The default is `verbose`. +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. + # Examples This simple example first creates a data set where the pipe `%unit%` is diff --git a/src/mdhlp/lbl_replace_pipe.md b/src/mdhlp/lbl_replace_pipe.md index 73440a9..68dd75e 100644 --- a/src/mdhlp/lbl_replace_pipe.md +++ b/src/mdhlp/lbl_replace_pipe.md @@ -4,7 +4,7 @@ __lbl_replace_pipe__ - Replaces pipes in variable labels with user-provided valu # Syntax -__lbl_replace_pipe__ , __pipe__(_string_) __**rep**lacement__(_string_) [__**trun**cate__(_string_) __**out**put_level__(_string_) __missing_ok__] +__lbl_replace_pipe__ , __pipe__(_string_) __**rep**lacement__(_string_) [__**trun**cate__(_string_) __**out**put_level__(_string_) __missing_ok__ __**v**arlist__(_varlist_)] | _options_ | Description | |-----------|-------------| @@ -13,6 +13,7 @@ __lbl_replace_pipe__ , __pipe__(_string_) __**rep**lacement__(_string_) [__**tru | __**trun**cate__(_string_) | Toggle behavior when the new label is too long | | __**out**put_level__(_string_) | Toggle verbosity level in output | | __missing_ok__ | Suppresses error when the pipe does not exist in any variable label | +| __**v**arlist__(_varlist_) | Restrict the scope of variables to consider | # Description @@ -63,6 +64,8 @@ replace does not exist in any variable label in the dataset. The default behavior is that the code is interrupted with an error if the pipe does not exist. +__**v**arlist__(_varlist_) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With __varlist__(), the scope of the search can be narrowed. + # Examples This simple example first creates a data set where diff --git a/src/sthlp/lbl_assert_no_long_varlbl.sthlp b/src/sthlp/lbl_assert_no_long_varlbl.sthlp index a38e22e..51e6c85 100644 --- a/src/sthlp/lbl_assert_no_long_varlbl.sthlp +++ b/src/sthlp/lbl_assert_no_long_varlbl.sthlp @@ -11,13 +11,14 @@ {title:Syntax} -{phang}{bf:lbl_assert_no_long_varlbl} , {bf:{ul:max}len}({it:integer}) +{phang}{bf:lbl_assert_no_long_varlbl} , [{bf:{ul:max}len}({it:integer}) {bf:{ul:v}arlist}({it:varlist}) ] {p_end} -{synoptset 15}{...} +{synoptset 16}{...} {synopthdr:options} {synoptline} {synopt: {bf:{ul:max}len}({it:integer})}Maximum character length allowed.{p_end} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} {synoptline} {title:Description} @@ -36,6 +37,9 @@ {pstd}{bf:{ul:max}len}({it:integer}) sets the maximum length of variable labels. {p_end} +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. +{p_end} + {title:Examples} {input}{space 8}* create set of variables diff --git a/src/sthlp/lbl_assert_no_pipes.sthlp b/src/sthlp/lbl_assert_no_pipes.sthlp index 0e1e98e..aea05d7 100644 --- a/src/sthlp/lbl_assert_no_pipes.sthlp +++ b/src/sthlp/lbl_assert_no_pipes.sthlp @@ -11,7 +11,7 @@ {title:Syntax} -{phang}{bf:lbl_assert_no_pipes} , [{bf:{ul:ig}nore_pipes}({it:string}) {bf:{ul:out}put_level}({it:string})] +{phang}{bf:lbl_assert_no_pipes} , [{bf:{ul:ig}nore_pipes}({it:string}) {bf:{ul:out}put_level}({it:string}) {bf:{ul:v}arlist}({it:varlist})] {p_end} {synoptset 20}{...} @@ -19,6 +19,7 @@ {synoptline} {synopt: {bf:{ul:ig}nore_pipes}({it:string})}List of pipe names to be ignored{p_end} {synopt: {bf:{ul:out}put_level}({it:string})}Toggle verbosity level in output{p_end} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} {synoptline} {title:Description} @@ -56,6 +57,9 @@ The valid values for this option are {inp:minimal}, {inp:verbose}, and {inp:veryverbose}. The default is {inp:verbose}. {p_end} +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. +{p_end} + {title:Examples} {pstd}This simple example first creates a data set where diff --git a/src/sthlp/lbl_assert_var_have_lbl.sthlp b/src/sthlp/lbl_assert_varlbls.sthlp similarity index 74% rename from src/sthlp/lbl_assert_var_have_lbl.sthlp rename to src/sthlp/lbl_assert_varlbls.sthlp index 4537ef3..70391c4 100644 --- a/src/sthlp/lbl_assert_var_have_lbl.sthlp +++ b/src/sthlp/lbl_assert_varlbls.sthlp @@ -1,7 +1,7 @@ {smcl} {* 01 Jan 1960}{...} {hline} -{pstd}help file for {hi:lbl_assert_var_have_lbl}{p_end} +{pstd}help file for {hi:lbl_assert_varlbls}{p_end} {hline} {title:Title} @@ -11,18 +11,26 @@ {title:Syntax} -{phang}{bf:lbl_assert_var_have_lbl} [varlist] +{phang}{bf:lbl_assert_var_have_lbl}, [{bf:{ul:v}arlist}({it:varlist})] {p_end} +{synoptset 16}{...} +{synopthdr:options} +{synoptline} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} +{synoptline} + {title:Description} -{pstd}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. +{pstd}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. {p_end} {pstd}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. {p_end} -{pstd}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. +{title:Options} + +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. {p_end} {title:Examples} diff --git a/src/sthlp/lbl_list_long_varlbl.sthlp b/src/sthlp/lbl_list_long_varlbl.sthlp index 451ad6b..1281663 100644 --- a/src/sthlp/lbl_list_long_varlbl.sthlp +++ b/src/sthlp/lbl_list_long_varlbl.sthlp @@ -11,13 +11,14 @@ {title:Syntax} -{phang}{bf:lbl_list_long_varlbl} , {bf:{ul:max}len}({it:integer}) +{phang}{bf:lbl_list_long_varlbl} , [{bf:{ul:max}len}({it:integer}) {bf:{ul:v}arlist}({it:varlist})] {p_end} -{synoptset 15}{...} +{synoptset 16}{...} {synopthdr:options} {synoptline} {synopt: {bf:{ul:max}len}({it:integer})}Maximum character length allowed.{p_end} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} {synoptline} {title:Description} @@ -42,6 +43,9 @@ {pstd}{bf:{ul:max}len}({it:integer}) sets the maximum length of variable labels, beyond which a variable is listed by this command. {p_end} +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. +{p_end} + {title:Examples} {input}{space 8}* create set of variables diff --git a/src/sthlp/lbl_list_matching_vals.sthlp b/src/sthlp/lbl_list_matching_vals.sthlp new file mode 100644 index 0000000..afc8cb4 --- /dev/null +++ b/src/sthlp/lbl_list_matching_vals.sthlp @@ -0,0 +1,122 @@ +{smcl} +{* 01 Jan 1960}{...} +{hline} +{pstd}help file for {hi:lbl_list_matching_vals}{p_end} +{hline} + +{title:Title} + +{phang}{bf:lbl_list_matching_vals} - List value labels whose labels match a pattern. +{p_end} + +{title:Syntax} + +{phang}{bf:lbl_list_matching_vals} [varlist], {bf:pattern}({it:string}) [{bf:{ul:neg}ate} {bf:{ul:v}erbose}] +{p_end} + +{synoptset 16}{...} +{synopthdr:options} +{synoptline} +{synopt: {bf:pattern}({it:string})}Pattern to find in an answer option. Provide either a substring or a regular expression.{p_end} +{synopt: {bf:{ul:neg}ate}}Inverts the search, returning value labels that do {bf:not}match the pattern.{p_end} +{synopt: {bf:{ul:v}erbose}}Print out labels that match query. Output corresponds to {inp:label list lblnames}.{p_end} +{synopt: {bf:varlist}({it:varlist})}Restrict the scope of variables to consider{p_end} +{synoptline} + +{title:Description} + +{pstd}While Stata offers some tools for searching the content of variable labels (e.g. {inp:lookfor}), it does not have any methods for similarly searching the contents of value labels. +{p_end} + +{pstd}This command aims fill this gap by: +{p_end} + +{pstd}- Searching labels in value labels for a pattern +- Identifying variable labels that contain labels of interest +- Compiling variables that have these labels of interest attached +{p_end} + +{pstd}This command can be particularly useful for checking that variable do (not) contain patterns of interest. Consider for example: +{p_end} + +{pstd}- Confirming that value labels contain (e.g., no) +- Identifying value labels that deviate from standards +{p_end} + +{title:Options} + +{pstd}{bf:pattern}({it:string}) provides the text pattern to find in the contents of value labels. Rather be the traitional Stata glob pattern, this pattern is a sub-string or a regular expression. +{p_end} + +{pstd}{bf:negate} inverts the search, returning value labels that do {bf:not}match the pattern. In isolation, {inp:pattern({c 34}my_text{c 34})} looks for value labels containing {inp:{c 34}my_text{c 34}}. With {inp:negate}, {inp:pattern({c 34}my_search{c 34})} search looks instead for value labels that do not contain {inp:{c 34}my_text{c 34}}. +{p_end} + +{pstd}{bf:verbose} manages the how much output is printed. If the {inp:verbose} option is not provided, {inp:lbl_list_matching_vals} reports on whether any matches were found--and, if so, how many value labels match and how many variables the matching value labels describe. If the {inp:verbose} option is specified, the command will additionally print the contents of the matching value labels as a convenience. +{p_end} + +{title:Examples} + +{dlgtab:Example 1: contain a pattern} + +{input}{space 8}* create some fake data +{space 8}gen var1 = . +{space 8}gen var2 = . +{space 8}gen var3 = . +{space 8}gen var4 = . +{space 8} +{space 8}* create some value labels +{space 8}label define var1_lbl 1 "Yes" 2 "No" +{space 8}label define var2_lbl 1 "Oui" 2 "Non" 3 "Oui, oui" +{space 8}label define var4_lbl 1 "Oui" 2 "Non" +{space 8} +{space 8}* apply those labels to some, but not all, variables +{space 8}label values var1 var1_lbl +{space 8}label values var2 var2_lbl +{space 8}label values var4 var4_lbl +{space 8} +{space 8}* find value labels with "Oui" and/or "oui" in at least one constituent label +{space 8}lbl_list_matching_vals, pattern("[Oo]ui") +{space 8} +{space 8}* find value labels and print out the contents of the label, for convenience +{space 8}* i.e., to avoid the next step that many users might logically make: +{space 8}* `label list matching_lbl` +{space 8}lbl_list_matching_vals, pattern("[Oo]ui") verbose +{text} +{dlgtab:Example 2: do not contain a pattern} + +{input}{space 8}* find value labels that do not contain a certain pattern +{space 8}* for example, no "Oui"/"oui" in yes/no labels from a French-language survey +{space 8}lbl_list_matching_vals, pattern("[Oo]ui") negate +{text} +{dlgtab:Example 3: contain only a certain set of characters} + +{input}{space 8}* create some value labels +{space 8}label drop _all +{space 8}* var1_lbl var2_lbl var4_lbl +{space 8}label define var1_lbl 1 "YES" 2 "NO" +{space 8}label define var2_lbl 1 "Yes" 2 "No" +{space 8}label define var3_lbl 1 "yes" 2 "no" +{space 8}label define var4_lbl 1 "Où" 2 "Là" +{space 8} +{space 8}* attach them to variables created above +{space 8}label values var1 var1_lbl +{space 8}label values var2 var2_lbl +{space 8}label values var3 var3_lbl +{space 8}label values var4 var4_lbl +{space 8} +{space 8}* contains no lower-case characters +{space 8}lbl_list_matching_vals, pattern("[:lower:]") negate +{space 8} +{space 8}* contains no French characters +{space 8}lbl_list_matching_vals, pattern("[àâäÀÂÄéèêëÉÈÊËîïôöÔÖùûüçÇ]") negate +{space 8} +{text} +{title:Feedback, bug reports and contributions} + +{pstd}Read more about these commands on {browse "https://github.com/lsms-worldbank/labeller":this repo} where this package is developed. Please provide any feedback by {browse "https://github.com/lsms-worldbank/labeller/issues":opening an issue}. PRs with suggestions for improvements are also greatly appreciated. +{p_end} + +{title:Authors} + +{pstd}LSMS Team, The World Bank lsms@worldbank.org +{p_end} diff --git a/src/sthlp/lbl_list_matching_vars.sthlp b/src/sthlp/lbl_list_matching_vars.sthlp index 610e05c..6a7ecd8 100644 --- a/src/sthlp/lbl_list_matching_vars.sthlp +++ b/src/sthlp/lbl_list_matching_vars.sthlp @@ -11,14 +11,14 @@ {title:Syntax} -{phang}{bf:lbl_list_matching_vars} {it:regexstring}, [{bf:varlist(varlist)} {bf:{ul:neg}ate}] +{phang}{bf:lbl_list_matching_vars} {it:regexstring}, [{bf:{ul:neg}ate} {bf:{ul:v}arlist}({it:varlist})] {p_end} {synoptset 16}{...} {synopthdr:options} {synoptline} -{synopt: {bf:varlist(varlist)}}Restricts the scope of search to a variable list{p_end} {synopt: {bf:{ul:neg}ate}}Returns variables whose label does {bf:not} match{p_end} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} {synoptline} {title:Description} @@ -40,7 +40,7 @@ {pstd}{bf:{ul:neg}ate} inverts the match. Rather than return variables with matching variable labels, this option returns variables whose variable label do not match. {p_end} -{pstd}{bf:varlist} restricts the scope of the search to the user-provided variable list. By default, {inp:lbl_list_matching_vars} searches for matches in all variables in memory. With {bf:varlist}, the scope of the search can be narrowed. +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. {p_end} {title:Examples} diff --git a/src/sthlp/lbl_list_no_var_lbl.sthlp b/src/sthlp/lbl_list_no_varlbl.sthlp similarity index 66% rename from src/sthlp/lbl_list_no_var_lbl.sthlp rename to src/sthlp/lbl_list_no_varlbl.sthlp index 0e60556..44e5762 100644 --- a/src/sthlp/lbl_list_no_var_lbl.sthlp +++ b/src/sthlp/lbl_list_no_varlbl.sthlp @@ -1,28 +1,36 @@ {smcl} {* 01 Jan 1960}{...} {hline} -{pstd}help file for {hi:lbl_list_no_var_lbl}{p_end} +{pstd}help file for {hi:lbl_list_no_varlbl}{p_end} {hline} {title:Title} -{phang}{bf:lbl_list_no_var_lbl} - List variables without a variable label. +{phang}{bf:lbl_list_no_varlbl} - List variables without a variable label. {p_end} {title:Syntax} -{phang}{bf:lbl_list_no_var_lbl} [varlist] +{phang}{bf:lbl_list_no_varlbl}, [{bf:{ul:v}arlist}({it:varlist})] {p_end} +{synoptset 16}{...} +{synopthdr:options} +{synoptline} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} +{synoptline} + {title:Description} -{pstd}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. +{pstd}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. {p_end} {pstd}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. {p_end} -{pstd}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. +{title:Options} + +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. {p_end} {title:Examples} @@ -38,10 +46,10 @@ {space 8}label variable var4 "Another label" {space 8} {space 8}* list variables without variable labels globally -{space 8}lbl_list_no_var_lbl +{space 8}lbl_list_no_varlbl {space 8} {space 8}* list variables without a label in the varlist -{space 8}lbl_list_no_var_lbl var3 - var4 +{space 8}lbl_list_no_varlbl, varlist(var3 - var4) {text} {title:Feedback, bug reports and contributions} diff --git a/src/sthlp/lbl_list_pipes.sthlp b/src/sthlp/lbl_list_pipes.sthlp index 5ab7396..3a13a34 100644 --- a/src/sthlp/lbl_list_pipes.sthlp +++ b/src/sthlp/lbl_list_pipes.sthlp @@ -11,7 +11,7 @@ {title:Syntax} -{phang}{bf:lbl_list_pipes} , [{bf:{ul:ig}nore_pipes}({it:string}) {bf:{ul:out}put_level}({it:string})] +{phang}{bf:lbl_list_pipes} , [{bf:{ul:ig}nore_pipes}({it:string}) {bf:{ul:out}put_level}({it:string}) {bf:{ul:v}arlist}({it:varlist})] {p_end} {synoptset 20}{...} @@ -19,6 +19,7 @@ {synoptline} {synopt: {bf:{ul:ig}nore_pipes}({it:string})}List of pipe names to be ignored{p_end} {synopt: {bf:{ul:out}put_level}({it:string})}Toggle verbosity level in output{p_end} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} {synoptline} {title:Description} @@ -46,6 +47,9 @@ The valid values for this option are The default is {inp:verbose}. {p_end} +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. +{p_end} + {title:Examples} {pstd}This simple example first creates a data set where the pipe {inp:%unit%} is diff --git a/src/sthlp/lbl_replace_pipe.sthlp b/src/sthlp/lbl_replace_pipe.sthlp index a31f670..6959bb6 100644 --- a/src/sthlp/lbl_replace_pipe.sthlp +++ b/src/sthlp/lbl_replace_pipe.sthlp @@ -11,7 +11,7 @@ {title:Syntax} -{phang}{bf:lbl_replace_pipe} , {bf:pipe}({it:string}) {bf:{ul:rep}lacement}({it:string}) [{bf:{ul:trun}cate}({it:string}) {bf:{ul:out}put_level}({it:string}) {bf:missing_ok}] +{phang}{bf:lbl_replace_pipe} , {bf:pipe}({it:string}) {bf:{ul:rep}lacement}({it:string}) [{bf:{ul:trun}cate}({it:string}) {bf:{ul:out}put_level}({it:string}) {bf:missing_ok} {bf:{ul:v}arlist}({it:varlist})] {p_end} {synoptset 20}{...} @@ -22,6 +22,7 @@ {synopt: {bf:{ul:trun}cate}({it:string})}Toggle behavior when the new label is too long{p_end} {synopt: {bf:{ul:out}put_level}({it:string})}Toggle verbosity level in output{p_end} {synopt: {bf:missing_ok}}Suppresses error when the pipe does not exist in any variable label{p_end} +{synopt: {bf:{ul:v}arlist}({it:varlist})}Restrict the scope of variables to consider{p_end} {synoptline} {title:Description} @@ -81,6 +82,9 @@ The default behavior is that the code is interrupted with an error if the pipe does not exist. {p_end} +{pstd}{bf:{ul:v}arlist}({it:varlist}) restricts the scope of the search to the user-provided variable list. By default, the command searches for matches in all variables in memory. With {bf:varlist}(), the scope of the search can be narrowed. +{p_end} + {title:Examples} {pstd}This simple example first creates a data set where diff --git a/src/tests/lbl_no_long_varlbl.do b/src/tests/lbl_no_long_varlbl.do index ae361d5..c51bd64 100644 --- a/src/tests/lbl_no_long_varlbl.do +++ b/src/tests/lbl_no_long_varlbl.do @@ -26,6 +26,8 @@ labeller * Setup * ============================================================================== +clear + * create set of variables gen var1 = . gen var2 = . @@ -69,7 +71,7 @@ else { * ------------------------------------------------------------------------------ * list variables with longer than max length -lbl_list_long_varlbl var1 - var3 +lbl_list_long_varlbl, varlist(var1 - var3) local long_lbls_in_varlist = r(varlist) local long_lbls_in_varlist : list clean long_lbls_in_varlist diff --git a/src/tests/test-lbl_list_matching_vals.do b/src/tests/test-lbl_list_matching_vals.do new file mode 100644 index 0000000..203bafd --- /dev/null +++ b/src/tests/test-lbl_list_matching_vals.do @@ -0,0 +1,236 @@ +* 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 +* ============================================================================== + +clear + +* create set of variables +gen var1 = . +gen var2 = . +gen var3 = . +gen var4 = . + +* create some value labels +label define var1_lbl 1 "Yes" 2 "No" +label define var2_lbl 1 "Oui" 2 "Non" 3 "Oui, oui" +label define var4_lbl 1 "Oui" 2 "Non" + +* apply labels +label values var1 var1_lbl +label values var2 var2_lbl +label values var4 var4_lbl + +* ============================================================================== +* Test +* ============================================================================== + +* ------------------------------------------------------------------------------ +* Lists matching value labels and variables +* ------------------------------------------------------------------------------ + +* expect vars: var2 var4 +* expect val lbls: var2_lbl var4_lbl +lbl_list_matching_vals, pattern("[Oo]ui") +local vars_matched = r(varlist) +local vars_matched : list clean vars_matched +local val_lbls_matched = r(val_lbl_list) +local val_lbls_matched : list clean val_lbls_matched + +* test variables +capture assert "`vars_matched'" == "var2 var4" +di as result "Lists matching variables" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* test value labels +capture assert "`val_lbls_matched'" == "var2_lbl var4_lbl" +di as result "Lists matching value labels" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* ------------------------------------------------------------------------------ +* Lists matching value labels and variables in varlist +* ------------------------------------------------------------------------------ + +* expect vars: var2 +* expect val lbls: var2_lbl +lbl_list_matching_vals, pattern("[Oo]ui") varlist(var1 - var2) +local vars_matched_in_varlist = r(varlist) +local vars_matched_in_varlist : list clean vars_matched_in_varlist +local val_lbls_matched = r(val_lbl_list) +local val_lbls_matched : list clean val_lbls_matched + +* test variables +capture assert "`vars_matched_in_varlist'" == "var2" +di as result "Lists matching variables" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* test value labels +capture assert "`val_lbls_matched'" == "var2_lbl" +di as result "Lists matching value labels" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* ------------------------------------------------------------------------------ +* Lists no matches when no matches found +* ------------------------------------------------------------------------------ + +* expect: no vars +* informs no matches +lbl_list_matching_vals, pattern("Evet") +local var_count = r(var_count) +local lbl_count = r(lbl_count) + +capture assert "`var_count'" == "0" +di as result "Lists no variables" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +capture assert "`lbl_count'" == "0" +di as result "Lists no value labels" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* ------------------------------------------------------------------------------ +* Provides verbose output +* ------------------------------------------------------------------------------ + +* expect output equivalent to: label list var2_lbl var4_lbl +lbl_list_matching_vals, pattern("[Oo]ui") verbose + + +* ------------------------------------------------------------------------------ +* Inverts list when negate specified +* ------------------------------------------------------------------------------ + +* expect variables: var1 +* expect values: var1_lbl +lbl_list_matching_vals, pattern("[Oo]ui") negate +local vars_matched = r(varlist) +local vars_matched : list clean vars_matched +local val_lbls_matched = r(val_lbl_list) +local val_lbls_matched : list clean val_lbls_matched + +* test variables +capture assert "`vars_matched'" == "var1" +di as result "Lists matching variables" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* test value labels +capture assert "`val_lbls_matched'" == "var1_lbl" +di as result "Lists matching value labels" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* ------------------------------------------------------------------------------ +* Inverts list of matches in varlist when negate specified +* ------------------------------------------------------------------------------ + +* add a variable with labels +gen var5 = . +label values var5 var1_lbl + +* expect variables: var1 +* expect values: var1_lbl +lbl_list_matching_vals, pattern("[Oo]ui") negate varlist(var2 - var5) +local vars_matched = r(varlist) +local vars_matched : list clean vars_matched +local val_lbls_matched = r(val_lbl_list) +local val_lbls_matched : list clean val_lbls_matched + +* test variables +capture assert "`vars_matched'" == "var5" +di as result "Lists matching variables" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + +* test value labels +capture assert "`val_lbls_matched'" == "var1_lbl" +di as result "Lists matching value labels" +if _rc != 0 { + di as error "❌ Test failed" + error 0 +} +else { + di as result "✅ Test passed" +} + + + +* ============================================================================== +* Teardown +* ============================================================================== + +drop var1 - var5 +label drop var1_lbl var2_lbl var4_lbl diff --git a/src/tests/test-lbl_list_matching_vars.do b/src/tests/test-lbl_list_matching_vars.do index efff056..6ae0f44 100644 --- a/src/tests/test-lbl_list_matching_vars.do +++ b/src/tests/test-lbl_list_matching_vars.do @@ -26,6 +26,8 @@ labeller * Setup * ============================================================================== +clear + * create set of variables gen var1 = . gen var2 = . diff --git a/src/tests/test-lbl_list_no_var_lbl.do b/src/tests/test-lbl_list_no_varlbl.do similarity index 95% rename from src/tests/test-lbl_list_no_var_lbl.do rename to src/tests/test-lbl_list_no_varlbl.do index 8753d5f..227ef6c 100644 --- a/src/tests/test-lbl_list_no_var_lbl.do +++ b/src/tests/test-lbl_list_no_varlbl.do @@ -45,13 +45,14 @@ label variable var4 "Another label" * ------------------------------------------------------------------------------ * list variables without variable labels globally -lbl_list_no_var_lbl +lbl_list_no_varlbl + 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" +di as result "lbl_list_no_varlbl lists variables without labels globally" if _rc != 0 { di as error "❌ Test failed" error 0 @@ -65,7 +66,7 @@ else { * ------------------------------------------------------------------------------ * list variables without a label in the varlist -lbl_list_no_var_lbl var3 - var4 +lbl_list_no_varlbl, varlist(var3 - var4) local vars_wo_lbl_in_varlist = r(varlist) local vars_wo_lbl_in_varlist : list clean vars_wo_lbl_in_varlist @@ -89,7 +90,7 @@ else { * ------------------------------------------------------------------------------ * assert that all variables have a label -capture lbl_assert_var_have_lbl +capture lbl_assert_varlbls * test di as result "lbl_assert_var_have_lbl errors if any var is without a label"