listCount

The listCount function iterates over a list and evaluates a logical statement for each list iteration. listCount returns the count of the number of iterations which evaluate to "true." Though not explicitly tied to tables, table references are imagined to be the most common usage.

Syntax

In its most basic form, listCount accepts two inputs: a list name with optional inclusion/exclusions, and a logical condition with an iterator.

Basic syntax

The syntax examples below use listCount to return a count (total number) of iterations that are "true," and show how to use listCount to include or exclude options.

#Basic format, returning the number of "true" iterations
listCount(LISTNAME; Logical statement with [id])

#Inclusion syntax to limit options from list
listCount(LISTNAME [List IDs to include]; Logical statement with [id])

#Exclusion syntax to limit options from list
listCount(LISTNAME -[List IDs to exclude]; Logical statement with [id])

Advanced syntax

There are a few scenarios with list functions which require the Survey Programmer (SP) to explicitly state the list name along with the element [id] reference to help the system differentiate the list data. In these instances, the list name is prefixed to the [id] reference, separated by a colon. As with the regular element [id] reference, we also wrap this construction in square braces, e.g., '[LISTNAME:id]', to pull the option data through.

One common instance where this occurs is when a condition decorator is placed on a list call, often seen as optsfrom or rowsfrom, etc. The list referenced at '*from' will be iterated through the [id] reference somewhere in the logical statement. Therefore, the other list iterated through the listCount function needs to be clarified further. See the section Condition decorator and listcall 'optsfrom' below for more information.

#Inside iterating decorators, such as list functions and conditions, prefixing the list name to the inner list iterator.
*from: LISTNAME {if listCount(OTHER_LISTNAME, Logical statement and field reference with [OTHER_LISTNAME:id] [id] iterators)}

Another scenario where SPs should prefix a list name to an element ID reference is any time two or more lists are invoked in the list function, e.g.,'listCount(LIST1, LIST2; ...)'. This often happens in a hidden variable using cvalue. Here, all list names will be prefixed to their list 'id' reference. See the section Multiple lists, count of all options in a table below for more information.

#Using two different lists, allowing the logical condition to contain two axes of data, prefixing the list name to the iterator for each. 
listCount(LISTA, LISTB; Logical statement and field reference with [LISTA:id] [LISTB:id] iterators)

Examples

Validation for selecting exactly one brand

In the following awareness table, respondents must select only one brand as a primary supplier (column 4). The validation tag is used to ensure the respondent answers appropriately.

See demo See code Restart demo

Conditioned question with 'showif' and inline rows

In this example, only a subset of the BRANDS list is used in a showif condition defined by the listCount tag. If either option 3 or 4 is selected for both Lenovo and Apple in T1A, the respondent is shown the follow-up question Q2. Since the row items are listed inline at T1A, and used as a derived list in Q2, the list is referenced as 'T1A.rows'.

See demo See code Restart demo

Background variable with 'cvalue' and exclusion syntax

The following example demonstrates the usage of listCount and the cvalue tag in a background variable that counts the number of suppliers used in the last 12 months (options 3 or 4), excluding a hypothetical dummy brand.

See demo See code Restart demo

Multiple lists, count of all options in a table

The example below illustrates the use of multiple lists in listCount to count the number of items ranked 8 or higher in a pulldown table with multiple columns. Both lists must be referenced in this listCount since we have rows, columns, and answer options, which creates three answers per row. The listCount checks each iteration of row (auto brand) and column (auto type), and if an 8 or higher is found, it will be counted.

Note, there are two lists used in the listCount function. Each list name needs to be prefixed to the [id] reference where the list will be iterated through, e.g., the rows and columns 'id' placeholders. The table's cells are then referenced by calling to '[LISTNAME: id]' for the rows and columns with $Q3R[AUTOS:id]C[TYPES:id].

See demo See code Restart demo

Condition decorator and listcall 'optsfrom'

In this example, respondents are asked about which electronic products they have used with each brand. A follow-up question includes any of the products respondents have used, regardless of brand, and also lists the brands the respondent has selected for any product type in T5. Here in T6, the optsfrom tag calls to the PRODUCTS list, and listCount is counting across all items from the BRANDS2 list, looking for any brand that has any product type.

See demo See code Restart demo

Since the optsfrom calls to the PRODUCTS list, it is using the option data [id] reference to iterate through the PRODUCTS list elements. Then, the BRANDS2 list is being referenced within the listCount function. Here, we must explicitly tell the system which list to iterate through; so, we prefix the list [id] reference with the list name and construct [BRANDS2:id].

Disqualification with 'termif'

In the following example, the PROVIDER list includes options of fake service providers. If respondents claim they have previously used or are currently using any of the fake providers, the listCount at the termif condition is defined to ensure they will be disqualified from the survey.

See demo See code Restart demo