Clusters & Charts

Where it is

Clusters & Charts in the sidebar, with three tabs: Clustering, Scale Responses, Options Responses.

Each tab needs answers of its own kind: Clustering needs a free-text question, Scale Responses a scale question, Options Responses a single- or multi-select one. A tab whose question type the study doesn't use, or hasn't collected answers to yet, shows its own empty state; when none of the three has anything, the page shows "No responses yet" and a link to recruit. Ranking and card-sort answers are JSON structures rather than a single choice, so they don't appear under Options Responses.

Clustering

Groups participants' free-text answers to one question into themes.

Each participant's answers are condensed into a vector, k-means sorts those vectors into groups, and each group gets a short thematic label and summary. The vectors are computed automatically as interviews come in, so there is no setup.

1. Choose a Question — only text questions appear.
2. Optionally tick Only Completed.
3. Set Number of Clusters, or click Find Optimal.
4. Click Cluster.

Results: an interactive plot where each point is a participant and colour is cluster membership, plus a Cluster Analysis table with each cluster's Label, Count and Analysis Notes, and the reasoning behind the labelling.

Find Optimal applies the elbow method — it computes the within-cluster spread for a range of cluster counts and picks the point of diminishing returns. Treat it as a starting suggestion, then try a couple of values either side and keep the one whose labels you can actually defend.

You need enough answered responses to fill the clusters you ask for; too few and clustering is refused. Labelling is best-effort — if the model call fails you still get the groups, just with generic labels.

Embedding status

The page reports embedding coverage: total interviews, how many have embeddings, how many need them, and the percentage. Generate Embeddings backfills interviews that finished before automatic indexing. New interviews are embedded when they complete.

Scale Responses

Pick a scale question and get the distribution of answers. Follow-up turns are excluded, and out-of-range or non-numeric replies are skipped.

Options Responses

Pick a single- or multi-select question and get the count per option. Single-select answers match one option; multi-select answers count once per option chosen.

With MCP

list_analyzable_questions {"study_id": "…", "category": "text"}    # or "scale" / "options"
get_optimal_clusters {"study_id": "…", "question_id": "…"}
run_clustering       {"study_id": "…", "question_id": "…", "n_clusters": 4}
get_latest_clustering{"study_id": "…"}
get_scale_responses  {"study_id": "…", "question_id": "…"}
get_options_responses{"study_id": "…", "question_id": "…"}

• list_analyzable_questions is the right first call: it tells you which questions support which analysis, with response counts. It reports exactly the questions the three tabs offer, so an empty list there means an empty tab here.
• For linear studies you can pass question_number instead of question_id. For flow studies, question_id is the step id you authored.
• run_clustering saves its result, so it also appears on this page. get_latest_clustering returns the most recent saved run ready to chart, with exists: false if the study has never been clustered.
• Too few responses for the requested cluster count returns 400 — lower n_clusters or wait.

Reading results honestly

• Clusters are a reading aid, not a finding. The label is a model's summary of a group of vectors; open the responses in a cluster before you quote it.
• Small n stays small. Twelve responses split into four clusters is three people per theme.
• Charts need a denominator. "60% chose Price" means something different across 10 and 200 participants; the response count is on the page for a reason.

Last updated: September 2026