listSum

The listSum function iterates over a list and a field reference. The function returns the sum of the referenced survey fields.

Syntax

In its most basic form, listSum accepts two inputs: a list name with optional inclusion/exclusions, and a field reference constructed with an iterator. 

Basic syntax

The syntax examples below use listSum to return a sum of the referenced fields, and show how to use listSum to include or exclude options. 

#Basic format
listSum(LISTNAME; Field reference with [id])

#Inclusion syntax to limit options from list
listSum(LISTNAME [IDs to include]; Field reference with [id])

#Exclusion syntax to limit options from list
listSum(LISTNAME -[IDs to exclude]; Field reference 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 listSum function needs to be clarified further. See the section Condition decorator and listcall 'rowsfrom' 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 listSum(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.,'listSum(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, sum of all option values selected 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. 
listSum(LISTA, LISTB; Logical statement and field reference with [LISTA:id] [LISTB:id] iterators)

Examples

Background variable with 'cvalue'

A background variable using the cvalue tag calculates the total number of purchases made across all brands in table 1. In this example, [id] is the iterator which pulls through each option ID from the BRANDS list. Each field reference constructed becomes, '$Q1R1', '$Q1R2', and so on. The function then returns the sum of these fields. 

See demo See code Restart demo

Conditioned question with 'showif' and inline rows

In this example, a follow-up question is displayed if 20% or more is allocated to a brand subset (all options excluding '97. Other') in a "Share of Wallet" question. The showif tag is used to dynamically show or hide the question. Since the brand list in question is listed inline at T2 (a derived list), the list is referenced as T2.rows. 

See demo See code Restart demo

Multiple lists, sum of all option values selected in a table

In the next example, we use two lists to calculate a listSum used within a cvalue tag for the hidden variable TOTAL. Similar to the above example, one list is provided inline at T4, as opposed to the standalone list, PRODS. Thus, the row options at T4 are referenced as T4.rows.

Note, there are two lists used in the listSum 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 $Q4R[T4.rows:id]C[PRODS:id].

See demo See code Restart demo

Condition decorator and listcall 'rowsfrom'

In this example, respondents are asked about which electronic products they carry of each of the following brands. A follow-up question includes any of the products for which respondents had a quantity of two or more, regardless of brand. Here in T6, the rowsfrom tag calls to the PRODUCTS list, and listSum is adding across all items from the BRANDS2 list, looking for the products that have two or more as a total quantity.

See demo See code Restart demo

Note that while the PRODUCTS list is the referenced row list for T6, it was used for the columns in T5. So, PRODUCTS is using the option data [id] reference to iterate through its list elements in the column 'id' placeholder. Meanwhile, the BRANDS2 list is also being referenced within the listSum function. It is being iterated through the row 'id' placeholder. 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].