Create tables tutorial (r9)

Simple tables - Basic structure

The "simple" table structure mirrors other question types in the SPL (Survey Programming Language). The question number is used to define the table ID (TID) or table name. Question text follows this ID, and property-defining tags are listed on subsequent lines.

Similar to questions, tables require a type tag. For simple tables, this means adding "table" to whichever type you are setting up, e.g. "radio table." 

Table rows are defined by either the rowsfrom or rows tags.

Answer options are defined in either a local list or via the optsfrom tag. The series tag provides a shortcut to defining a simple, locally numbered list. It can be used here to define the sequential 1 to 10 scale.

The headings tag sets descriptive text labels at the scale ends of the numbered responses.

Each shape will get a number as it's overall rating.

B1A. How common or rare is each shape?
type: radio table
headings: Common, Rare
series: 1..10
rowsfrom: SHAPES

A table can utilize the pulldown question type, which also requires single choice responses, one answer per row.

A hybrid approach to defining answer options can be used by invoking the series tag along with locally listed options.

This table uses the prompt tag to set 'Select one...' as the text at the top; by default, this space is blank.

B1B. How many of each shape do you typically encounter per day?
type: pulldown table
prompt: Select one...
0. None
series: 1..5
6. More than 5
rowsfrom: SHAPES

Tables that require a select-all-that-apply approach will use the checkbox question type.

A decline to answer (DTA) option can be defined via the dta tag to offer respondents an opt-out for the entire table.  

B1C. Do you talk about shapes in any of these places?
type: checkbox table
optsfrom: PLACE
rowsfrom: SHAPES
dta: 99. I do not talk about them {message: Enter places OR select 'I don't discuss them'}

An exclusive decorator (or tag) can be used to create an interactive "none-of-these" response option so it cannot be selected with other options for each row.

B1D. Do you see shapes in any of these places?
type: checkbox table
optsfrom: PLACE
99. I don't {exclusive: y}
rowsfrom: SHAPES

Continue to work in your FLast_r9_intro survey (visit Training tutorials for set up steps) and add the new content from each practice section via the SPL editor. When the survey compiles successfully, launch Testmode by clicking the Test 2 button from this screen. Review your survey and test your new questions. After testing your survey, be sure to make any necessary corrections.

Next, add dummy data records. Finally, review the data output by viewing a Response report or creating a new export in Deliverables.

An overall table ID is created for each table. In this newly added section, TB1A, TB1B, TB1C, and TB1D are the table IDs (TIDs).

The default table ID separator is R, a row indicator. Thus, every table ID has a data column or field for each of it's rows (i.e., QB1AR1, QB1AR2, QB1AR3, QB1AR4, QB1AR5, QB1BR1, QB1BR2, QB1BR3, etc.)

In the Response report and export files, variables are created for each row.

TB1A creates QB1AR1 through QB1AR5, storing the number selected, from '1' to '10', for each shape. TB1B creates QB1BR1 through QB1BR5, also storing the number selected, from '0' to '6', for each shape.

In total, 10 data locations are exported, five for TB1A and five for TB1B since each has five row-questions.

TB1C is a checkbox table, similar to radio tables.

The Response report shows one variable for each shape, QB1CR1 through QB1CR5, storing a comma-separated string of the option IDs selected. In export files, the data for TB1C is even more granular, creating variables for each shape (row) by each place (option).

R1 is row 1, storing places selected for 'Circle' from the SHAPES list. This creates QB1CR1.1 for the 'At work' option, QB1CR1.2 for the 'At home' option, QB1CR1.3 for the 'In nature' option, and QB1CR1.4 for 'The city' option are created. Each of these locations will contain a '1' or '0', depending on if the option is selected or not for circles.

R2 is row 2, and QB1CR2.1, QB1CR2.2, QB1CR2.3, QB1CR2.4 are created for storing places selected for 'Square' from the SHAPES list. R3 is row 3, storing places selected for 'Triangle' from the SHAPES list, and so on for each of the five shapes.

The dta tags generate a field for the table, TB1C_DTA. This location will store a value of '99' when selected.

In total, TB1C exports 21 locations: four options ('At home', 'At work', 'In nature', 'The city') multiplied by five shapes, plus a DTA field.

TB1D is also a checkbox table creating variables for each shape (row) by each place (option). A similar number of locations are generated for this table.

The difference is the dta tag only creates one extra location. In TB1D, the 'I don't' option creates five additional locations to store a response for each row - QB1DR1.99 'I don't' for circles, QB1DR2.99 for squares, QB1DR3.99 triangles, QB1DR4.99 rectangles, and QB1DR5.99 'I don't' for trapezoids.

Each of these locations will contain a '1' or '0', depending on if the option 'I don't' is selected or not.

In total, TB1D exports 25 locations: five options ('At home', 'At work', 'In nature', 'The city', 'I don't') multiplied by five shapes.

B2. Indicate your preference for each pair of statements.
[Select the level that closest fits you]
Option scale: < Fits Me, Equal, Fits Me >
[RANDOMIZE ROWS]

A triple-pipe tag can be used to display list items that have contrasting option labels on either side. The tag can also be used with any table text tags (i.e., textalign: left ||| right). 

The randomize tag is added to randomize the order in which rows appear to survey takers, as shown in the snapshot. For example, the curved/angled pair could be shown first, while they are the 4th row as defined by the table code.

Snapshot image of resulting table:

B2. Indicate your preference for each pair of statements. 
instruct: Select the level that closest fits you. 
type: radio table
1. < Fits Me
2. Equal
3. Fits Me >
rows:
randomize: y
1. Large shapes ||| Small shapes
2. Solid shapes ||| Shape outlines
3. 3D shapes ||| 2D shapes
4. Curved shapes ||| Angled shapes
5. Irregular shapes ||| Symmetrical shapes

TB2 is a standard radio table creating fields QB2R1 through QB2R5. Each stores a '1', '2', or '3', depending on which option was selected for the pair.

B3A. Which attributes do you associate with each shape?
instruct: Check all that apply for each shape.
type: checkbox table
vscale: y
1. Useful tool
2. Pleasing lines
3. External boundaries
99. None of these {exclusive: y}
colsfrom: SHAPES

B3B. Select two features that best describe each shape.

To enforce a specific number of selections per column, the numchecked tag works well.

B3B. Select two features that best describe each shape.
instruct: Select two for each shape.
type: checkbox table
vscale: y
1. Shapely
2. Geometric
3. Uniform
4. Precise
5. Symbolic
colsfrom: SHAPES
numchecked: == 2

An overall table ID is created for each table in this example, TB3A and TB3B.

The default table ID separator for a vscale table is C, a column indicator.

In the Response report, variables QB3AC1 through QB3AC5 are created, storing a string of comma-separated numbers based on the selections.

In export files, the data for TB3A is even more granular, creating variables for each shape.

For C1, circle selections, we have four data columns — QB3AC1.1 for 'Useful tool', QB3AC1.2 for 'Pleasing lines', QB3AC1.3 for 'External boundaries', and QB3AC1.99 for 'None of these'. Each of these locations will contain a '1' or '0' depending on whether the option is selected or not.

For C2, square selections, QB3AC2.1, QB3AC2.2, QB3AC2.3, and QB3AC2.99 are created. This pattern continues on for each shape.

In total, TB3A exports 20 locations: four options (tool, line, boundary, none) multiplied by five shapes.

TB3B is treated the same way as TB3A since it is a vertical scale checkbox table as well. TB3B has five options, where TB3A has four. It will end up with a few more export variables, but otherwise the reporting is very similar.

In the Response reports, one variable for each shape is created, storing a comma-separated string, just like TB3A. The difference is based on the option IDs selected. TB3A can store any combination of '1', '2', '3', or '99', and TB3B can store any combination of '1', '2', '3', '4', or '5'.

In export files, the data for TB3B will expand out into the more granular levels as well.

In total, TB3B exports 25 locations: five options ('shapely', 'geometric', 'uniform', 'precise', 'symbolic') multiplied by five shapes.

Advanced tables - Basic structure

start table: TID
intro: Table question text here.
type: radio, checkbox, etc.
... more table definition tags here
end table

The advanced structure is the more traditional method for programming tables in our SPL. Advanced tables have 'start' and 'end' tags to contain inner, property-defining tags. The start table tag must include an ID - typically the question number is used to define the table ID (TID) or table name.

Similar to questions, tables require a type tag. Question text for the table is placed on the intro tag.

A multi-type table can be created with the -- (double dash) tag.

The textheading tag adds a heading in the first column, above the list of rows.

The -- tag is used to define each unique column — Use, Color, and Size — within the main "preference" table.

The enablewhen tag is added to C2 and C3 to accommodate the logic requested to only ask color and size when 'Yes' is selected for use.

start table: B4
intro: Enter your preferences for each shape you use.
instruct: Select yes/no to indicate use.
textheading: Shape
rowsfrom: SHAPES
--
heading: Use
type: radio
1. Yes
2. No
--
heading: Color
type: radio
optsfrom: COLORS
enableWhen: anyChecked(__COL1__,1)
--
heading: Size
type: number
datatype: whole
maxlen: 2
size: 3
postfix: inches
enableWhen: anyChecked(__COL1__,1)
end table

B5. Please provide your contact information:
[Fields for name, phone number, and email]
[EMAIL/PHONE OPTIONAL]

This table demonstrates our ability to have different datatypes for two of the rows in a text table. The same method can be used to serve alternate options via pulldown at different rows.

required: n allows respondents to leave the rows blank.

The datatype tag, as seen in the previous tutorial, ensures that the proper format is inputted when an answer is provided.

start table: B5
intro: Please provide your contact information:
type: text

1. Name

2. Phone number (optional)
datatype: phone
required: n

3. Email (optional)
datatype: email
required: n

end table

In TB4 the columns are labeled C1, C2, and C3 by default.

Appending TB4 by each unique column results in QB4C1 for 'Use', QB4C2 for 'Color', and QB4C3 for 'Size'.

In the Response report, the data is comprised of each selection for each shape in each column. This means that each of the table's question columns (Use, Color, and Size) gets a variable for each shape. So, for the first question column - C1 - this creates QB4R1C1 for circle use, QB4R2C1 for square use, QB4R3C1 for triangle use, QB4R4C1 for rectangle use, and QB4R5C1 for trapezoid use.

For the next question column - C2 - the variables created are QB4R1C2 for circle color, QB4R2C2 for square color, QB4R3C2 for triangle color, QB4R4C2 for rectangle color, and QB4R5C2 for trapezoid color.

The last question column creates five more variables ending in C3; QB4R1C3 for circle size, QB4R2C3 for square size, QB4R3C3 for triangle size, QB4R4C3 for rectangle size, and QB4R5C3 for trapezoid size

Since TB4 columns have single choice and open-end options, locations do not expand out for each option like multiple choice data. All of these columns store numeric string data. In total, a TB4 Excel export has 15 locations: three preferences ('use', 'color', 'size') multiplied by five shapes.

TB5 will follow the same data layout as a standard text table. The major differences have to do with the datatype tags. Both email and phone are considered Personally Identifiable Information (PII), and as such, our system will automatically encrypt the resulting input. The encrypted data is only visible by users with a system role of Team Lead+ or those with the survey "add-on" role View Encrypted Data. All others will see the encrypted values that appear as a string of alphanumeric characters.

B5A. Select the properties that you like about each shape.
Options: Angle(s), Point(s), Line(s), Curve(s)
Circle, Square, Triangle, Rectangle, Trapezoid NEW: Ellipse, Crescent, Star, Heart
[ONLY ALLOW RELEVANT PROPERTIES FOR THE SHAPES: NO angles/points with circles/ellipses; curves ONLY with circles/ellipses/crescents/hearts]

To provide options with relevant properties, TB5A uses the cell tag to replace the input field with blank cells.

The cell tag can be used multiple times to set properties in different ways.

TB5A uses a combination of rowsfrom to include the SHAPES list, plus inline rows to define a few new shapes.

Snapshot image of resulting table:

B5A. Select the properties that you like about each shape.
type: radio table
1. Angle(s)
2. Point(s)
3. Line(s)
4. Curve(s)
rowsfrom: SHAPES
rows: 
6. Ellipse
7. Crescent
8. Star
9. Heart
cell: R[1,6] O[1,2]
cell: R[2..5,8] O[4] 

B5B. Do you know the formula to calculate the area of each shape?
Options: Yes, No, N/A
Circle, Square, Triangle, Rectangle, Trapezoid NEW: Ellipse, Crescent, Star, Heart
[INCLUDE OTHER SPECIFY]

In TB5B, rowsfrom is used twice — once to include the SHAPES list, and again to include the inline rows from TB5A. In addition, rows is used to define and include an "Other" option with a blank field locally.

The cell tag is used in this example to remove the 'No' and 'N/A' options from the "Other" row. It would not make sense to enter information for another shape, and then select 'no' or 'N/A' for it.

B5B. Do you know the formula to calculate the area of each shape?
type: radio table
1. Yes
2. No
3. N/A
cell: R[97] O[2,3]
rowsfrom: SHAPES
rowsfrom: TB5A.rows 
rows:
97. {autoother: y}

The sct tag allows for the display of column totals in a table.

B5C. What percent of space would you use for each shape?
instruct: Must total 100%
type: integer table
range: 0-100
postfix: %
rowsfrom: SHAPES
required: n
sct: Total {total: 100} {message: Your total must add up to 100%.}

The revealrows tag applies special dynamic formatting to text-entry tables that allows a certain number of rows to remain hidden until answerable. Because the revealrows value is set to '1', a single text row will be displayed when the page is loaded. When text is entered into the box, the next row is displayed, until all 10 rows are full. This interactive question style encourages more responses.

A single-line validation tag, in conjunction with the required: n, tag can force a response in at least the first row.

series[1..10] defines a numbered list of options at rowsfrom.

B5D. What shapes come to mind?
type: text table
rowsfrom: series[1..10] {text: Shape #[id]}
revealrows: 1
required: n
validation: $QB5DR1 ne "" {message: Enter a shape or 'None' in the first box.}

At TB5A, the rows that have cells blanked out will store a limited set, or subset of option IDs. For example, shapes that do not have round sides will not be able to select option '4. Curve(s)'. QB5AR8 for Star, for example, will never store '4' because curves can't be selected with stars. View the Questions tab of an Excel export to confirm this.

TB5A generates a total of nine data locations, one for each of the five shapes from the SHAPES list, and four more for each inline shape.

TB5B is a very common use for the cell tag used to remove 'No' and the 'N/A' opt-out option from the other specify option row.

TB5B generates a total of 11 data locations, one for each of the five shapes from the SHAPES list, four more for each shape from TB5A.rows (the inline shapes defined at TB5A), and two more for autoother.

TB5C dynamically adds the values typed into each row and shows a running total in the last row.

The sct tags generate a variable called 'QB5CRSCT'.

The total decorator sets the sum value; in this case it must total to 100. The message decorator sets the text that will show if a respondent tries to continue without entering values that add to 100.

While it is possible to set a size tag value, it's not necessary, as the system automatically sizes the response boxes in relation to the range setting.

The required: n tag is added so values do not need to be entered into each row. As long as the overall total adds to 100, some rows can be left blank.

TB5C generates six locations in total, five for the shapes from the SHAPES list, and one for the SCT variable.