`labeller`

The goal of labeller is find, fix, and double-check common issues that arise when documenting data. This package is useful wherever variable and value labels are found, but particularly useful where those labels have been generated by Survey Solutions.

Note also: while this package does not require selector, some commands in labeller do leverage the questionnaire metadata that selector adds to survey metadata.

Installation

Development version

To get a bug fix, a version not yet published on SSC, or test bleeding-edge features, you can install code from other branches of the repository. The current release is version 0.5.

To install the version in a particular branch:

* set tag to be the name of the target branch
* for example, the development branch, which contains code for the next release
local tag "dev"
* alternatively, v0.5, which contains the code for the current pre-SSC release.
* download the code from that GitHub branch
* install the package
net install labeller, ///
  from("https://raw.githubusercontent.com/lsms-worldbank/labeller/`tag'/src") replace

Previous versions

If you need to install a previously releases version of labeller, then you can use the following method. This can be useful, for example, during reproducibility verifications. To install the version in a particular release, set the local tag to the target release you want to install in this code:

* set the tag to the name of the target release
* for example v1.0, say, if the current version were v2.0
local tag "v1.0"
* download the code from that GitHub release
* install the package
net install labeller, ///
  from("https://raw.githubusercontent.com/lsms-worldbank/labeller/`tag'/src") replace

Commands

Variable labels

Pipes

Find and replace text substitution markers (e.g., %rostertitle%)

Command	Description
lbl_list_pipes	Lists pipes in variable labels from Survey Solutions.
lbl_replace_pipe	Replaces pipes in variable labels with user-provided value
lbl_assert_no_pipes	Asserts that no variable labels have any pipes

Length

Identify labels that might be potentially truncated.

Command	Description
lbl_list_long_var_lbl	List variables whose variable label is longer than the desired character length.
lbl_assert_no_long_var_lbl	Assert that there is no variable in memory whose variable length exceeds the desired character length.

Existence

Check for variables without variable labels

Command	Description
lbl_list_no_var_lbl	List variables without a variable label.
lbl_assert_have_var_lbl	List variables without a variable label.

Inspection and manipulation

Find labels with desired content; modify labels with Designer metadata

Command	Description
lbl_list_matching_var_lbls	Identify variables whose label matches a pattern.
lbl_use_meta	Accesses variable metadata and, optionally, uses it to set the value of data attributes.

Value labels

Find labels with desired content; find and drop unused labels

Command	Description
lbl_list_matching_val_lbls	List value labels whose labels match a pattern.
lbl_list_unused_val_lbls	List value labels not attached to any variable.
lbl_drop_unused_val_lbls	Drop value labels not attached to any variable.

Usage

More details on

What objects labeller manages
How it manages those objects

Variable labels

* missing
lbl_list_no_var_lbl

* too long
lbl_list_long_var_lbl, maxlen(80)

* contains text...
* ... SuSo pipes
lbl_list_pipes
* ... some text
lbl_list_matching_var_lbls, pattern("string to find")

Value labels

* unused
lbl_list_unused_val_lbls, verbose

* contains text
* for example, French characters
lbl_list_matching_val_lbls, pattern("[àâäÀÂÄéèêëÉÈÊËîïôöÔÖùûüçÇ]")

How

Provides functions for the full data documentation workflow:

List problems
Fix them
Assert everything has been addressed

List

Step 1: Take stock of the problem’s scope

* list all pipes and all variables with those pipes
lbl_list_pipe

Fix

Step 2: Treat problems where they appear

* replace "%rostertitle% with "[NAME]" in all variable labels
lbl_replace_pipe, ///
  pipe("%rostertitle%") ///
  replacement("[NAME]")

Assert

Step 3: Confirm that all problems have been resolved

lbl_assert_no_pipes

Learn more

To learn more about the package:

Consult the reference documentation
Read how-to articles

Contact

LSMS Team, World Bank lsms@worldbank.org