Conjoint Question

When and Why to Use

Use this to run a CBC study where each respondent picks one option from a small set of competing product concepts across a sequence of tasks. Ideal for:

Measuring how attribute levels (brand, price, feature, packaging) drive choice
Estimating individual-level utility scores via Hierarchical Bayes
Simulating share-of-preference across competitive scenarios

For background on the method, see Choice-Based Conjoint. For the model that produces utility scores and simulated share, see Utility and simulated share methodology.

How Task Sets Work

task_sets is a mapping of task-set id to an ordered list of tasks, where each task is a list of concept ids. Each respondent is assigned one task set using least-fill balancing, which keeps per-task-set exposure roughly even across the fielding. Each task in the assigned set is then presented to the respondent as a select question — a single-choice pick from the concepts in that task.

The simplest way to generate balanced concepts and task sets is the Conjoint Planning Tool, which produces a code block you can paste straight into the survey alongside your screener.

Dict-Backed vs Media-Backed Concepts

Concepts can be defined in two shapes:

Dict-backed concepts — Python dicts whose concept_id_tag key (default id) identifies the concept. required_tags lists which fields the platform will require to be present on every concept and will attach to each selected response, so they can drive reporting rows.
Media-backed concepts — MediaItem objects rendered using the same labels, sizing, and media tags as other media-bearing questions. Use image_label_field, show_image_label, and image_size to configure rendering.

Configuration Options

Option	Type	Required	Default	Description
`question`	`str`	yes	-	The question to ask for each conjoint task
`concepts`	`list[dict]` or `list[MediaItem]`	yes	-	Concept dictionaries or media items to use in tasks
`task_sets`	`dict[str, list[list[str]]]`	yes	-	Mapping of task-set id to tasks, where each task contains concept ids
`concept_id_tag`	`str`	no	`'id'`	Tag containing the concept id referenced by `task_sets`
`required_tags`	`list[str]` or `None`	no	`None`	Concept tags to require and report with selected dict-backed concepts
`dont_know_option`	`str`	no	`''`	Optional fixed non-concept option label
`randomize`	`bool`	no	`False`	Randomize option order within each task
`image_label_field`	`str` or `None`	no	`None`	Media field to use as the display label for media concepts
`show_image_label`	`bool`	no	`True`	Whether to show media labels
`image_size`	`tuple[int, int]` or `None`	no	`None`	Bounding box size for media options
`tags`	`dict[str, Any]` or `None`	no	`None`	Tags attached to each conjoint task question

Example Code

Dict-backed concepts:

from survey import Survey

s = Survey(**globals())

concepts = [
    {"id": "A", "brand": "Apple",   "color": "Black",  "network": "5G", "price": "$800"},
    {"id": "B", "brand": "Apple",   "color": "Blue",   "network": "5G", "price": "$1000"},
    {"id": "C", "brand": "Samsung", "color": "Black",  "network": "4G", "price": "$600"},
    {"id": "D", "brand": "Samsung", "color": "Silver", "network": "5G", "price": "$800"},
]

task_sets = {
    "TS001": [["A", "C"], ["B", "D"], ["A", "D"], ["B", "C"]],
    "TS002": [["A", "B"], ["C", "D"], ["A", "C"], ["B", "D"]],
}

s.conjoint_question(
    question="Which product would you choose?",
    concepts=concepts,
    task_sets=task_sets,
    required_tags=["brand", "color", "network", "price"],
    dont_know_option="None of these",
    randomize=True,
    tags={"study": "smartphone_cbc"},
)

s.complete()

Notes

Each task response includes the selected concept id, the values of required_tags for dict-backed concepts, and the platform-added conjoint_task_set and conjoint_task tags.
If dont_know_option is selected, it is treated as a fixed non-concept option (no concept tags are attached).
The Conjoint Planning Tool produces both the concepts and task_sets structures; paste its output directly into the survey instead of writing them by hand.
See Choice-Based Conjoint for end-to-end study design and Utility and simulated share methodology for the reporting outputs.