conjoint-design

Exact captured content · path skills/conjoint-design/SKILL.md · sha256 f9609fa20fa44967… · revision 668a5d0755adac02ef01c31d306c47b6d3d08f8f

Download the exact captured file

---
name: conjoint-design
description: "Designs a choice-based conjoint (CBC) study: attributes and levels that don't overlap, prohibited combinations, tasks, concepts per task and a none option, a randomized design with level balance and minimal overlap (or fully randomized for AMCEs) generated by script, checks of level frequency, attribute association and relative D-efficiency, and a sample size from the Johnson-Orme rule. Use for \"conjoint study\", \"design a conjoint\", \"discrete choice experiment\", \"which feature bundle\", \"trade-off research\", \"CBC design\", \"how many conjoint tasks\" or \"check my conjoint design\"."
license: MIT
metadata:
  version: "0.1.0"
  status: "beta"
  author: "QuestionPunk"
  source: "questionpunk/research-skills"
  requires-account: "false"
  plugin: "pricing-research"
---

# Conjoint design

Designs a choice-based conjoint (CBC) study: attributes and levels that a respondent can trade off, the task
layout, a randomized design generated and checked by script, and the sample size.
[`scripts/conjoint_design.py`](scripts/conjoint_design.py) (Python 3.9+, standard library only) writes and
checks the design; run it, do not hand-build or hand-check a design. Run it by its path inside this skill's
folder (`python3 <skill-dir>/scripts/conjoint_design.py`); examples below write `scripts/...` for short.
Sources: [`references/sources.md`](references/sources.md). How the generator and the efficiency number work:
[`references/design-method.md`](references/design-method.md) (read it when asked how the design was built or
why two tools disagree).

## When to use

- "Design a conjoint", "conjoint study", "CBC design", "which feature bundle should we offer", "trade-off
  research", "how many conjoint tasks / respondents".
- "Check my conjoint design" (a design file from another tool, or one written by this skill).

Do not use it for:

| Request | Use instead |
|---|---|
| Analyzing choices already collected | `conjoint-analysis` |
| Ranking a list of features or messages (no bundles) | `maxdiff-design` |
| Price only, one product | `gabor-granger-analysis` or `van-westendorp-analysis` |
| Writing the screener or the rest of the questionnaire | `screener-writer`, `survey-from-decision` |
| Adaptive CBC, menu-based conjoint, partial profiles, alternative-specific designs | Not covered: say so |

A skill named here may not be installed. If it is missing, say so, name the method the request needs, and
do not stretch this skill to cover it.

## What to ask for

Ask only for what is missing, in one message. The decision comes first: what will the company choose
between (a bundle, a price point, a feature set)?

| Input | Default |
|---|---|
| Decision the study informs | Required for a new design: it decides which attributes belong (not needed to check a file) |
| Attributes and levels | Draft them from the decision, then confirm. 3 to 6 attributes, 2 to 5 levels each |
| Prohibited combinations | None. Add only combinations that cannot exist, not ones that seem unlikely |
| Concepts per task | 3 |
| None option | Yes when the decision includes "would they buy at all"; otherwise no |
| Tasks per respondent | 10 (8 to 15 is usual) |
| Versions | 100 |
| Method | `balanced`; `random` with no prohibitions when the analysis will report AMCEs (fully randomized) |
| Subgroups to report | None; ask each one's expected share of the sample |

## Steps

1. **Write the attributes.** Each attribute is one dimension the buyer cares about; levels are mutually
   exclusive, concrete ("$40 a week", not "low price") and span the realistic range. No attribute may imply
   another ("Premium tier" next to a feature list that differs by tier). Keep level counts similar: more
   levels inflate an attribute's importance. Price levels must contain a number (`$40` is fine) if you want
   willingness to pay. A range such as "$40-$70" becomes 3 to 5 evenly spaced levels.
2. **Save the spec** as a text file:

   ```text
   Brand: FreshBox | GreenPlate | HomeChef
   Meals per week: 2 | 3 | 4
   Price per week: $40 | $50 | $60 | $70
   prohibit: Meals per week=4 & Price per week=$40
   ```

   Separate levels with `|` and join prohibition conditions with `&` (a name or level containing `&` needs
   the JSON spec in `references/design-method.md`). A prohibition names two or more attributes.

3. **Generate the design**, with one of these (they are alternatives; each writes its own file):

   ```bash
   # Utilities, shares and WTP (the usual case): balanced design, none option
   python3 scripts/conjoint_design.py design spec.txt --tasks 10 --concepts 3 --none --subgroups 2 --out design.csv
   # AMCEs: fully randomized, from a spec with no prohibit lines
   python3 scripts/conjoint_design.py design spec_amce.txt --tasks 10 --concepts 2 --method random --out design_amce.csv
   ```

   To check a design from another tool instead (it needs `task` and `concept` columns, `version` when there
   are several, one column per attribute; `--spec` is optional and adds the prohibition check):

   ```bash
   python3 scripts/conjoint_design.py check their_design.csv --spec spec.txt --subgroups 2
   python3 scripts/conjoint_design.py sample-size --max-levels 4 --tasks 10 --concepts 3 --subgroups 2
   ```

   Pass `--subgroups N` whenever results will be reported for N subgroups, or the sample line ignores them.
   `--json` gives every number as JSON. `--out` never overwrites the spec. Exit code 2 means the spec, the
   file or the request is impossible (one-level attribute, more concepts than distinct profiles, prohibitions
   that leave too few profiles or a singular design, a concept number used twice in a task): fix it; nothing
   is written.
4. **Read the diagnostics.** Relative D-efficiency (aim for 90% or more; under 80% is flagged; both are this
   skill's conventions), level counts (max/min near 1), overlap and Cramér's V between attributes (near 0
   unless a prohibition links them). With `balanced`, overlap is 0% except where an attribute has fewer
   levels than concepts. With `random`, overlap, lower efficiency and the odd task showing the same concept
   twice are expected: independence requires them. If a balanced design's efficiency is low, cut
   prohibitions or add versions.
5. **Size the sample** from the script's line: the larger of the Johnson-Orme planning number (also computed
   from the least shown level in this design), 300 per study and, per reported subgroup, 200 or the
   exposure minimum, whichever is larger. If subgroups are unequal, divide the per-subgroup number by the
   smallest subgroup's share.
6. **Hand off.** Give the design file and its format: header `version,task,concept,<one column per
   attribute>`, one row per version × task × concept, concepts numbered in on-screen order, a `none` row with
   blank attributes per task when used. Respondents take versions in rotation. Record each respondent's
   version and their choice per task (concept number or `none`); `conjoint-analysis` reads the design plus
   that file.

## Output

```markdown
## Conjoint design: <decision it informs>

**Attributes and levels**
| Attribute | Levels |
|---|---|
**Prohibited:** <list, or none>

**Task layout:** <t> tasks, <a> concepts per task, <none option or not>; <v> versions, <method> method,
seed <s>. Task wording: "<If these were your only options, which would you choose?>" (with a none option:
"<Which of these would you choose?>" and a none button "<None of these: I would not buy any>").

**Design checks:** relative D-efficiency <x>% (vs the best design without prohibitions); level counts
<min to max ratio>; overlap <...>; largest Cramér's V <v> (<attribute pair, and why>). Warnings: <every
script warning, or none>.

**Sample:** at least <total n> respondents (<rule that set it>)<; at least <per-subgroup n> per reported
subgroup, if any>.

**Files:** spec <path>, design <path>. Analyze with `conjoint-analysis`.
```

## Checks before answering

- Does every attribute tie to the decision, and could a respondent tell every pair of levels apart?
- Are levels concrete, mutually exclusive and in a realistic range, with prices as numbers?
- Is every prohibition a combination that truly cannot exist?
- Did the design and every number in the answer come from the script, with its warnings repeated?
- Is relative D-efficiency stated with what it is relative to (the best design without prohibitions)?
- Is the sample size the larger of the Johnson-Orme rule and the 300 / 200 floors?
- If AMCEs are planned, was `--method random` used with no prohibitions?
- Is the design file format stated, so the fieldwork records version and concept numbers?
- For a checked file with no new design, skip the layout lines the file cannot tell you.

## Field it (optional)

To run this on QuestionPunk, connect its MCP server (`https://app.questionpunk.com/api/v1`, OAuth sign-in). Tools: `survey_create` (the survey), `question_create` (answer type `conjoint_analysis`, `itemDetails {num_tasks, profiles_per_task, include_none_option}`, `textItemDetails {attributes: [{name, levels}]}`). QuestionPunk builds its own randomized, level-balanced tasks for each respondent, so it does not field this design file and does not enforce prohibitions or fully randomized (AMCE) assignment. Use it only when the study fits that: no prohibitions, no AMCE analysis, 1 to 20 tasks and 2 or 3 concepts per task; otherwise field the design file with a tool that shows tasks exactly as written. Ask the user before creating, changing or publishing anything. If a tool says a permission is missing, reconnect and approve the requested access.