Choice and Grid Groups

Choice and grid groups place related answer choices, grid rows or numeric-grid columns beneath group headings. The headings help respondents scan a long question, but they are not selectable and never become response values, reporting rows or recodes.

Use a dictionary instead of a flat list. Python preserves the order in which you define the headings. Existing flat-list definitions continue to work.

Group answer choices

The grouped options form works with Select, Multi Select and Ranking questions:

Code
industry = s.select_question(
    "Which industry do you work in?",
    options={
        "Consumer": ["Retail", "Hospitality", "Consumer goods"],
        "Business": ["Technology", "Professional services", "Manufacturing"],
        "Public and nonprofit": ["Government", "Education", "Charity"],
    },
    randomize=True,
)

The answer remains one of the existing member strings, such as "Retail". The heading "Consumer" is display text only.

Multi-select question with Fruit and Vegetables headings above selectable options

Ranking questions retain one shared ranking while displaying the available items beneath their headings:

Ranking question with Indoor activities and Outdoor activities headings above the available items

Group grid rows and columns

Grid Select, Multi Select Grid, Grid Rating and Numeric Grid questions accept grouped rows. Numeric grids also accept grouped columns.

Code
ratings = s.grid_select_question(
    question="How would you rate these spaces?",
    row_name="space",
    rows={
        "Work environment": ["Lighting", "Noise"],
        "Social spaces": ["Kitchen", "Break room"],
    },
    options={
        "Positive": ["Excellent", "Good"],
        "Negative": ["Poor", "Terrible"],
    },
    randomize=True,
    randomize_options=True,
)

Grouped rows and options remain part of one grid and one response:

Single-select grid with Positive and Negative option headings and Work environment and Social spaces row headings

Numeric grids can group both rows and columns without changing the stored row and column identities:

Numeric grid with Weekdays and Weekend column headings and Work environment and Social spaces row headings

Repeated question groups created with grid_question_group accept the same grouped row structure. This or That and This or That Rating questions can group whole pairs by supplying a dictionary to row_options.

Ordering and randomization

Dictionary insertion order controls the order of group headings. When randomization is enabled:

members shuffle independently inside their own group;
group headings remain in authored order;
Traditional grids and Chat question-by-question layouts use the same order; and
fixed options remain at the end, without splitting or reordering a group.

With randomization disabled, headings and members remain in their authored order.

Authoring rules

Every group heading and group must be non-empty.
Each member must be unique across its choice, row or column list.
Defaults, recodes and stored answers continue to use the member identities, not the headings.
When the main choice list is grouped, additional, fixed, disabled, exclusive and specify options must also appear in one of its groups.
Media items remain valid members where the question supports them and image_label_field is configured.

Choice and grid groups organize values within one question. To combine separate questions under a shared heading or repeat a set of questions across named rows, use Question Groups.