Documentation

Survey formatting best practices for MX8 Labs

Use these best practices to format a Word document, Google Doc, or questionnaire for AI programming in the MX8 Labs Research Platform. State question types, response lists, and logic explicitly so the platform can program the survey as intended.

The examples show how to write those instructions. Each is a reusable fragment: replace the question text and options, then update question numbers and references to match your questionnaire.

The blocks contain instructions for AI programming. For Python implementations and parameter definitions, follow the linked platform references. Read Survey logic best practices for the general conventions and Creating a new survey for the paste workflow.

How to write each question

  • Put the question identifier and text first, then state the question type on its own line.
  • Label response options, grid rows, and grid columns explicitly.
  • Reference options by their exact wording, such as "Nike", and identify the source question in every rule.
  • Put termination, show, skip, randomization, and validation rules on separate lines.
  • Give every question with a termination rule a qualifying simulation default. Defaults affect test data only; see Setting test data defaults.
  • Express instructions in plain text. Color and highlighting do not carry survey logic.

Single-select and termination

State fixed options by their full response text. This example randomizes the brand list, keeps "Other (please specify)" at the bottom, and screens out respondents immediately after Q3 unless they selected "Nike".

Example

Q3. Which of the following brands have you purchased most recently?

Type: Single-Select

Response Options:

  • Nike
  • Adidas
  • Converse
  • New Balance
  • Other (please specify)

Programming instructions:

  • randomize = True
  • Fixed Options = Other (please specify)
  • If Q3 is NOT "Nike", Terminate immediately after Q3
  • default = "Nike"

To terminate after a whole screener instead, place the termination rules after its final question and state where they run, for example: After Q5, terminate if Q3 is NOT "Nike". Include a qualifying default on each question used by those rules.

See Select Question and Terminating respondents.

Display styles

The question type determines how respondents answer; style controls its presentation. For example, add style = list to a single-select question to request a list presentation.

Question typeStyles
Single-selectdefault, button, list, dropdown
Multi-selectdefault, button, list, dropdown
Rankingdefault, button, list
Grid Selectbutton, radio
Multi-Select Gridbutton, checkbox
Rating and Grid Ratingslider, button, star
Net Promoter Scoreslider, button, star

Use the linked references to check scale limits and how each style appears in the traditional and chat experiences.

Multi-select

Specify how many options respondents may select and which options are exclusive. "None of the above" cannot be selected together with another answer.

Example

Q4. Which streaming services do you currently subscribe to? Select up to three.

Type: Multi-Select

Response Options:

  • Netflix
  • Hulu
  • Disney+
  • Max
  • Peacock
  • Other (please specify)
  • None of the above

Programming instructions:

  • randomize = True
  • Fixed Options = Other (please specify), None of the above
  • Exclusive Options = None of the above
  • Min options = 1
  • Max options = 3
  • If "None of the above" at Q4, Skip to Q10

See Multi Select Question.

Branching

Name the source question, response, and destination on each line. Ensure Q6 and Q10 exist in the questionnaire that uses this fragment.

Example

Q5. Do you currently subscribe to any streaming services?

Type: Single-Select

Response Options:

  • Yes
  • No

Programming instructions:

  • If Q5 = "Yes", Show Q6
  • If Q5 = "No", Skip to Q10

Numeric open ends and recodes

State the permitted numeric range, the screening condition, and the reporting categories separately. Use non-overlapping age bands with matching labels.

Example

Q1. How old are you?

Type: Open-End (Numeric)

Programming instructions:

  • Allowed range = 0-100
  • If Q1 < 18, Terminate immediately after Q1
  • default = 34

Recode Q1 for reporting:

  • 18-24 as "18-24"
  • 25-44 as "25-44"
  • 45-54 as "45-54"
  • 55-100 as "55+"

See Number Question for numeric ranges and recodes.

Quotas

Place quota instructions after the relevant question or questions. Quotas can use one question or nested combinations and are pre-populated in the platform's Quota tab.

Example

Q2. What is your gender?

Type: Single-Select

Response Options:

  • Male
  • Female
  • Non-binary
  • Prefer not to say

Set Quota:

  • If "Male" at Q2, 50%
  • If "Female" at Q2, 50%

These are illustrative targets for two categories. Before using the fragment, define targets and the treatment of every eligible response, including "Non-binary" and "Prefer not to say", so the quota scheme matches the study population. See Setting up quotas.

Stored variables and flags

A recode groups responses to one question for reporting. A stored variable records an additional calculated value, such as a segment combining age and gender. Specify its name, input questions, conditions, and output labels.

Using Q1 and Q2 above:

Example

Create stored variable "Age_Gen" after Q2.

Use the numeric age from Q1 and the exact response text from Q2.

Conditions and output labels:

  • If Q1 is 18-24 AND Q2 is "Male", store "18-24 Male"
  • If Q1 is 25-44 AND Q2 is "Male", store "25-44 Male"
  • If Q1 is 45-54 AND Q2 is "Male", store "45-54 Male"
  • If Q1 is 55-100 AND Q2 is "Male", store "55+ Male"
  • If Q1 is 18-24 AND Q2 is "Female", store "18-24 Female"
  • If Q1 is 25-44 AND Q2 is "Female", store "25-44 Female"
  • If Q1 is 45-54 AND Q2 is "Female", store "45-54 Female"
  • If Q1 is 55-100 AND Q2 is "Female", store "55+ Female"
  • If Q2 is "Non-binary" OR Q2 is "Prefer not to say", store "Else"

This example groups the final two responses together. Choose output categories that fit the analysis and document any grouping. See Calculated variables for stored scalar and multi-select values, or Derived questions for combining existing questions after fieldwork.

Grid Select and Grid Rating

Use Grid Select when respondents choose one labeled category per row. List columns in the order they should appear, and keep ordered scales fixed.

Example

Q6A. How satisfied are you with each aspect of your most recent cinema visit?

Type: Grid Select Question

Rows:

  • Ticket price
  • Seat comfort
  • Sound quality
  • Concessions

Columns, in this order:

  • Very dissatisfied
  • Somewhat dissatisfied
  • Neither satisfied nor dissatisfied
  • Somewhat satisfied
  • Very satisfied

Programming instructions:

  • Randomize rows = True
  • Do not randomize columns

Use Grid Rating for numeric scale points with anchor labels:

Example

Q6B. How satisfied are you with each aspect of your most recent cinema visit?

Type: Grid Rating Question

Rows:

  • Ticket price
  • Seat comfort
  • Sound quality
  • Concessions

Programming instructions:

  • 5-point scale from 1 to 5
  • Labels: "1" = "Not satisfied", "5" = "Very satisfied"
  • Randomize rows = True

See Grid Select Question and Grid Rating Question.

Filtered grids and shared ordering

Define the source question and filtering rule before the grid. If several questions use the same brands, state that their randomized order must be reused.

Example

Q5. Which online merchants have you heard of?

Type: Multi-Select

Response Options:

  • eBay
  • Amazon
  • Temu
  • Etsy
  • None of the above

Programming instructions:

  • Exclusive Options = None of the above
  • Fixed Options = None of the above

Filtering and shared ordering:

  • For Q7 and Q8, include only merchants selected at Q5.
  • If "None of the above" at Q5, skip Q7 and Q8.
  • Randomize the eligible merchants once per respondent.
  • Reuse that merchant row order in Q7 and Q8.

Q7. How likely are you to consider buying from each merchant?

Type: Grid Select Question

Rows: eligible merchants from Q5

Columns, in this order:

  • Very unlikely
  • Somewhat unlikely
  • Neither likely nor unlikely
  • Somewhat likely
  • Very likely

Programming instructions:

  • Do not randomize columns

Q8. Which features does each merchant offer? Select all that apply per merchant.

Type: Multi-Select Grid Question

Rows: the same eligible merchants, in the same order as Q7

Columns:

  • Free shipping
  • Flash deals
  • Exclusive discounts
  • Handcrafted items
  • Money back guarantee
  • None of these

Programming instructions:

  • Exclusive Options = None of these
  • Fixed Options = None of these

Multi-select grid exclusivity applies within each row: selecting "None of these" deselects the other answers for that merchant. For an additional validation rule, state the condition and the exact message respondents should receive. See Multi Select Grid Question.

Single-item rating scales and NPS

State the number of points, first and last values, and anchor labels.

Example

Q7. How important is price when choosing where to buy apparel?

Type: Rating Question

Programming instructions:

  • 5-point scale from 1 to 5
  • Labels: "1" = "Not at all important", "5" = "Very important"

For an NPS question:

Example

Q8. How likely are you to recommend {brand} to a friend or colleague?

Type: Net Promoter Score Question

Programming instructions:

  • 11-point scale from 0 to 10
  • Labels: "0" = "Not at all likely", "10" = "Extremely likely"
  • Use the brand name collected earlier as the "brand" tag.

The NPS question reports the classified promoter, passive, or detractor response. If analysis needs each respondent's exact selected scale point, use a Rating Question instead. See Net Promoter Score Question for the classification rules.

Text open ends and validation

Describe what makes an acceptable answer and specify the AI quality threshold when needed. The threshold uses a 1-5 quality score.

Example

Q9. What would make you more likely to visit a cinema in the next three months?

Type: Open-End (Text)

Programming instructions:

  • Ask all
  • Validation instructions = Give a specific reason related to cinema visits.
  • Quality threshold = 3

For a deterministic rule, specify a custom validator and its error message, for example: Require at least 5 characters; otherwise show "Please enter at least 5 characters." A custom validator replaces AI quality validation. See Text Question.

Ranking

Set both limits when the respondent must rank an exact number of items.

Example

Q10. Rank your top three reasons for choosing a quick-service restaurant, where 1 is the most important.

Type: Ranking Question

Response Options:

  • Price
  • Speed of service
  • Menu variety
  • Location / convenience
  • Healthy options
  • Loyalty rewards

Programming instructions:

  • randomize = True
  • Min options = 3
  • Max options = 3

See Ranking Question.

Tagged loops and stimulus assignment

Describe which media are eligible, how many each respondent sees, the assignment method, and the repeated questions. Use tags to identify the stimulus and its position on every response in the loop. Those tags can be used as rows, columns, or filters in reporting.

Example

Stimulus assignment

  • Eligible media: items with Media_Group = "Evaluation"
  • Exclude items with Media_Group = "Post"
  • Assign 4 eligible items per respondent using least-filled assignment.
  • Randomize the presentation order of the 4 assigned items.

Loop

Repeat Q21-Q23 for each assigned item, in positions 1-4.

Tag every question in the loop with the stimulus file name and position.

Q21. Please review the following advertisement.

Type: Message / Media display

Programming instructions:

  • Show the assigned item.
  • For an image, require 5 seconds before the respondent can continue.
  • For a video, play the assigned video.
  • End message: "Thanks for reviewing, please press Next to continue."

Q22. Overall, how appealing is this advertisement to you?

Type: Single-Select

Response Options:

  • Extremely appealing
  • Very appealing
  • Somewhat appealing
  • Not too appealing
  • Not at all appealing

Programming instructions:

  • Do not randomize

Q23. What worked well or did not work well about this advertisement?

Type: Open-End (Text)

Programming instructions:

  • Ask only for the item in Position 1.

Set up the Media_Group metadata before programming and ensure the eligible pool can supply the requested number of items. Least-fill assignment balances coverage; it is separate from a respondent quota. See Least Fill, Adding metadata to questions, and the wide and long export formats for the resulting response layout.

Numeric grids with totals

State whether totals run down columns or across rows, which earlier value they must match, and what happens if they do not match. In this fragment, collect total_cost and brand before asking the grid and carry those values as tags for piping and reporting.

Example

Q10. Of the {total_cost} you spent with {brand}, how much was in each category?

Type: Grid Numeric Question

Rows:

  • Apparel
  • Shoes
  • Home goods

Columns:

  • Spend

Programming instructions:

  • Allowed range per entry = 0-1000
  • Auto sum columns = True
  • Tags = total_cost, brand

Custom validation: The sum of the Spend column must equal {total_cost}.

If the sum does not match, show:

"Please ensure the entries sum to the total you spent."

Use row totals when that matches the question's layout. Check the totals and validation in the chosen respondent experience; see Numeric Grid Question.

Media metadata and image options

Upload images and videos as materials and add the metadata columns used by the questionnaire before programming. For example, create Boolean fields named Sponsor_Tag and Narrator_Tag:

FileSponsor_TagNarrator_Tag
Snacks.pngTrueFalse
Clothes.pngTrueTrue
Dogs.mp4FalseTrue

Reference the exact field names and values in the instructions:

Example

Programming instructions:

Ask Ad1 only for media where Narrator_Tag = True.

Ad1. Did the narrator have any impact on how this ad made you feel?

Type: Single-Select

Response Options:

  • Yes
  • No
  • I didn't notice a narrator

For image-based answer options, name the uploaded files and specify the size and label visibility:

Example

Logo. Which of the following brands are you aware of?

Type: Multi-Select Question

Response Options: uploaded image files

  • Nike.png
  • Adidas.png
  • Converse.png

Programming instructions:

  • image_size = (100, 100)
  • Image label field = file_name
  • Show image labels = False

See Including media in your survey for upload and metadata setup. Question references describe image sizing and labels for each supported instrument.

Quick reference

NeedQuestionnaire instruction
Randomize unordered optionsrandomize = True
Keep options fixedFixed Options = Other (please specify), None of the above
Make an option exclusiveExclusive Options = None of the above
Limit selectionsMin options = 1 and Max options = 3, on separate lines
Set a qualifying simulation defaultdefault = "qualifying response"
TerminateIf "<exact option>" at Q1, Term
Show a follow-upIf Q5 = "Yes", Show Q6
Preserve order across questionsReuse the randomized merchant order from Q7

Before fielding, review the programmed questions, simulation, and respondent flow using Testing and Reviewing Your Survey.