CSPro 7.3 introduces new ways to work with dynamic value sets. Dynamic value sets define the acceptable options for a field and they vary based on responses previously given. Typical value sets, defined in the data dictionary, define a fixed set of responses for a field, but with a dynamic value set, you can customize these responses based on specific conditions.

Prior to CSPro 7.3, you could create dynamic value sets using arrays, but working with these was cumbersome and not intuitive. Now there is a valueset object that allow for simpler, and more sophisticated, value set creation. Four scenarios are presented below that show how to use the new valueset object.

Easily Create a Dynamic Value Set in a Loop

A typical task is to create a value set based on some attributes entered previously. For example, you might want to present a list of people in a household who are aged 15+ as eligible heads of household. Using the valueset object with a for loop with a where condition makes this task trivial:

PROC HOUSEHOLD_HEAD

preproc

    valueset household_head_vs;

    for numeric line_number in PERSON_ROSTER where AGE >= 15 do
        household_head_vs.add(NAME, line_number);
    endfor;

    setvalueset(HOUSEHOLD_HEAD, household_head_vs);

Combining Value Sets

Suppose you have a question that asks about the way that someone deceased. In the dictionary there is one set of responses that applies to all people and an additional set of responses that applies to females aged 12+. Now you can easily create a dynamic value set, conditionally adding the female aged 12+ responses:

PROC MORTALITY_REASON

onfocus

    valueset mortality_reason_vs = MORTALITY_REASON_ALL_PEOPLE_VS;

    if SEX = 2 and AGE >= 12 then
        mortality_reason_vs.add(MORTALITY_REASON_FERTILE_WOMEN_VS);
    endif;

    setvalueset(MORTALITY_REASON, mortality_reason_vs);

Removing a Value Based on a Previous Selection

Sometimes a questionnaire has a series of questions that asks about preferences, such as, “What is your favorite color?,” and then, “What is your second favorite color?” The list of options for the second question can exclude the selected answer to the first question. The valueset object makes this task very easy:

PROC SECOND_FAVORITE_COLOR

preproc

    valueset second_favorite_color_vs = FAVORITE_COLOR_VS;

    second_favorite_color_vs.remove(FAVORITE_COLOR);

    setvalueset(SECOND_FAVORITE_COLOR, second_favorite_color_vs);

Iterate Through Value Set Codes and Labels

Finally, there are two lists that are part of a value set, accessed using the codes and labels attributes. Just as valueset is a new object in CSPro 7.3, lists, though around in some form for years, are now fully useable objects. This simplifies iterating through the codes and labels of a value set. For example, if the first two digits of the county code are equal to the state code, a dynamic value set for counties could be created as follows:

PROC COUNTY

preproc

    valueset filtered_county_vs;

    numeric first_county_code = STATE * 100;
    numeric last_county_code = first_county_code + 99;

    do numeric counter = 1 while counter <= COUNTY_VS.codes.length()

        if COUNTY_VS.codes(counter) in first_county_code:last_county_code then
            filtered_county_vs.add(COUNTY_VS.labels(counter), COUNTY_VS.codes(counter));
        endif;

    enddo;

    setvalueset(COUNTY, filtered_county_vs);
#Logic   

There are many ways of formatting the text data you collect in a CSPro application. For example, in the United States it is common to write a telephone number as xxx-xxx-xxxx or (xxx) xxx-xxxx. If only a text field is used, the interviewer could enter either format. However, not knowing the format creates extra work post-data collection, so as the application developer you will want to accept a single format.

This is done using the regexmatch function which was introduced in CSPro 7.2. The function takes two strings, the target and a regular expression and returns whether there is a match or not. In this example, the target string is the telephone number and the regular expression string describes the valid variations of the telephone number.

Regular expressions have their own syntax separate from CSPro logic. To help write your regular expression you can use any regular expression editor that supports the ECMAScript (JavaScript) engine (or flavor).

Writing a Regular Expression

Let us write a regular expression that describes a telephone number in the following format: xxx-xxx-xxxx. We will use the online regular expression editor regex101, make sure to select ECMAScript as the flavor. Start by typing the phone number 123-456-7890 into the test string field. As you write the regular expression, you will notice that the test string is highlighted as it is described by the regular expression.

Step 1

alt text

Begin your regular expression by asserting its position at the start of a newline. This will keep your phone number from matching something like otherData123-456-7890.

Step 2

alt text

The first character is any number from 0 to 9.

Step 3

alt text

The following two characters are also any numbers from 0 to 9. Signal that the pattern will repeat three times.

Step 4

alt text

The next character is a hyphen, and will match nothing else, so enter the literal hyphen character.

Step 5

alt text

Notice the pattern of the next four characters is the same as the past four. Wrap everything, but the caret in parentheses to create a capture group and signal that the pattern will repeat two times.

Step 6

alt text

The last four characters are any numbers from 0 to 9. Signal that the pattern will repeat four times.

Step 7

alt text

Finally, end your regular expression by asserting its position at the end of a newline. This will keep your phone number from matching something like 123-456-7890otherData.

Validating a Text Field

With your regular expression in hand, you are ready to validate the telephone number in CSPro. Call regexmatch passing in the telephone number and the regular expression. If 0 is returned then display an error message and re-enter. This allows the interviewer to correct the telephone number. Otherwise, if 1 is returned, do nothing and let the interview continue.

PROC TELEPHONE_NUMBER

postproc

    if regexmatch(TELEPHONE_NUMBER, "^([0-9]{3}-){2}[0-9]{4}$") = 0 then
        errmsg("Invalid format! Use the following format: xxx-xxx-xxxx.");
        reenter;
    endif;

To see a working example, download the regexmatch application.

#Logic   

Before sending interviewers into the field, consider what would happen if CSEntry automatically updated during your survey. If you developed a CSPro application for a previous version or the current version of CSEntry, you may not want the next update. Fortunately, it is simple to disable automatic updates for CSEntry or all apps on Android.

Disable automatic updates for CSEntry

  1. Open the Google Play Store alt text.
  2. Tap Menu alt text > My apps & games.
  3. Select CSEntry.
  4. Tap More alt text.
  5. Uncheck the box next to “Auto-update.”

Disable automatic updates for all apps

  1. Open the Google Play Store alt text.
  2. Tap Menu alt text > Settings.
  3. Tap Auto-update apps.
  4. Select Do not auto-update apps.

Update apps manually

  1. Open the Google Play Store alt text.
  2. Tap Menu alt text > My apps & games.
  3. Apps with an update available are labeled “Update.”
  4. Tap Update All to update all apps. For individual apps, find the specific app you want to update and tap Update.
    Tip: In some cases, you may need to restart your device to update an app.
#Android    #CSEntry   

CSPro on www.census.gov

Download the latest versions of CSPro, CSEntry, and CSWeb. Watch CSPro videos and learn about upcoming U.S. Census Bureau workshops.

CSPro Help

CSPro Help is an excellent resource whether you are just getting started or an expert user. The help is available offline with an installation of CSPro or online at http://www.csprousers.org/help.

CSPro Examples

CSPro Examples are a collection of data entry, edits & batch, and tabulation projects. Some projects are standalone, while others simply demonstrate common techniques. Here, you can see how the developers of CSPro design and code their applications. Feel free to use anything you see in these projects in your own project. The examples are an optional install. If selected they will be installed to your Documents folder under CSPro.

Debugging

Use of errmsg and trace

One of the most effective debugging tools at your disposal is the errmsg function. It can be useful to place them in PROCs, so you can see the order in which your application is executed. When this becomes burdensome, use the trace function. By enabling trace you’ll see the execution of your application as it enters and exits each PROC. To see even more detail, set trace to output logic statements.

Has your application taken an unexpected path? Use trace in much the same way you would use errmsg to log the values of the conditional statement.

PROC GLOBAL

PROC DEBUGGING_FF

preproc

    // Enable trace to see path of execution
    trace(on);

postproc

    // Disable trace
    trace(off);

PROC ELIGIBLE

    // Log user-generated information
    trace("AGE %d > 15 and SEX %d = 2", AGE, SEX);

    // Begin outputting logic statements
    set trace;

    if AGE > 15 and SEX = 2 then
        skip to FERTILITY_FORM;
    endif;

    // Stop outputting logic statements
    set trace(off);

Use of Log Files

Log files expose a layer of detail otherwise unavailable.

Specifics of every synchronization will be written to the sync log. Depending on your OS you will find the sync log in either one of two places:

  • Android: csentry\sync.log
  • Windows: Users\username\AppData\Roaming\CSPro\sync.log

CSWeb makes use of two log files. These logs will only exist if you are using CSWeb:

  • csweb\logs\api.log
  • csweb\logs\ui.log

The API log records details related to the underlying RESTful API, while the UI log records actions related the navigation of the website.

Forum/Email

Need additional assistance? You can post questions to our forum at http://www.csprousers.org/forum. The forum has a couple of advantages. You may get a quicker response, because anyone in the CSPro Users community can respond. Also, it is likely someone has the same question as you, so it benefits the entire CSPro Users community to see the answer. As a secondary option, you can email the team at cspro@lists.census.gov. It is important to use the above email and not contact us directly. This helps us manage email support across our team.

Writing a clear question can be a challenge, but it is worth the extra effort. A clear question will lead to a quicker and more accurate response. Here are some tips to consider when writing your next question:

  • First, search the forum for an answer. Your question may have already been addressed.
  • Write a one sentence subject line in your forum post or email that summarizes the issue.
  • Start your post or email by expanding on your subject line and fill in necessary details.
  • Tell us how to reproduce the issue in bullet points.
  • If necessary, include just enough code to reproduce the issue.
    • This may be a snippet of code or a simplified application, but you should not be sending the entire application.
    • To prepare projects for attachment, use CSPack (Tools > Pack Application).
  • If useful, attach the appropriate log file (sync.log, api.log, or ui.log).
  • Proof-read your question— is everything clear?
  • Finally, be prepared to answer follow-up questions when contacted by the team.
#Beginner