Rank Question in XLSForm: Order Selected Options
To add a rank question in XLSForm, write rank followed by a choice list name in the type column, such as rank need; the respondent drags the choices into order and the answer is saved as the choice codes in ranked order, for example 4 1 3 2 5. To rank only the options picked in an earlier select_multiple, add selected(${earlier_question}, name) in the choice_filter column. Every example below compiles with pyxform and ODK Validate.
How do I add a rank question?
A community needs assessment asks each respondent to order five needs from most to least urgent:
| type | name | label | hint | required |
|---|---|---|---|---|
| rank need | need_rank | Rank these needs from most to least urgent for your community. | Put the most urgent need at the top. | yes |
| list_name | name | label |
|---|---|---|
| need | 1 | Drinking water |
| need | 2 | Health clinic |
| need | 3 | Primary school |
| need | 4 | Road repair |
| need | 5 | Electricity |
- The choices sheet is the same as for a
select_one: alist_name, a code innameand alabel. - The answer is one value: the codes separated by spaces, first-ranked first. Electricity, water, school, clinic, road is saved as
5 1 3 2 4. - Every choice shown is ranked. The widget has no "top three only" mode; for that, see the first, second, third choice pattern below.
- Mark it
required. The answer stays empty until the enumerator opens the list and confirms an order.
How do I get the first, second and last ranked item?
A ranked answer is a space-separated list, the same shape as a select_multiple answer, so selected-at() reads one position from it. Positions start at zero:
| type | name | label | calculation | relevant | required |
|---|---|---|---|---|---|
| rank need | priority_rank | Rank these needs from most to least urgent. | yes | ||
| calculate | priority_first | selected-at(${priority_rank}, 0) | |||
| calculate | priority_second | selected-at(${priority_rank}, 1) | |||
| calculate | priority_last | selected-at(${priority_rank}, count-selected(${priority_rank}) - 1) | |||
| text | water_problem | What is the main problem with drinking water here? | ${priority_first} = '1' | yes |
selected-at(${priority_rank}, 0)is the top-ranked code,1the second, and so on. Asking for a position that does not exist returns an empty value, not an error.count-selected()counts the items in the list, socount-selected(...) - 1is always the last position, however many choices there are.- The follow-up question uses the calculate in its
relevant: it is asked only when drinking water (code1) was ranked first.
The calculates hold codes, not labels. To show "Drinking water" in a later question or note, see show the choice label, not the value.
How do I rank only the options selected in a previous question?
This is the most common ranking question on the ODK and KoboToolbox forums: ask which options apply, then rank only those. Use one choice list for both questions and filter the rank question with selected(). A household shocks module:
| type | name | label | choice_filter | relevant | calculation | required |
|---|---|---|---|---|---|---|
| select_multiple shock | shocks | Which of these shocks affected the household in the last 12 months? | yes | |||
| rank shock | shock_rank | Rank these shocks from most to least damaging. | selected(${shocks}, name) | count-selected(${shocks}) > 1 | yes | |
| calculate | worst_shock | if(count-selected(${shocks}) > 1, selected-at(${shock_rank}, 0), ${shocks}) | ||||
| calculate | worst_shock_label | jr:choice-name(${worst_shock}, '${shocks}') | ||||
| note | worst_shock_note | Most damaging shock: ${worst_shock_label} |
| list_name | name | label |
|---|---|---|
| shock | 1 | Drought |
| shock | 2 | Flood |
| shock | 3 | Crop pests or disease |
| shock | 4 | Livestock disease |
| shock | 5 | Illness or death of a household member |
| shock | 6 | Loss of a job or income |
selected(${shocks}, name)keeps a choice only if its code was ticked inshocks.namehere is thenamecolumn of the choices sheet, typed as is, with no${}.count-selected(${shocks}) > 1hides the ranking when one shock was picked: there is nothing to order.worst_shockcovers both cases. With two or more shocks it takes the top of the ranking; with one, it takes that shock.
The filter itself is explained in more detail in filter choices by a select_multiple.
Test a filtered rank question in the app your team will use, both on a phone and in the web form. Forum users have reported versions where a filtered rank list was displayed but could not be reordered, and where selected-at() on a rank answer showed nothing in a web form until an update.
How do I ask for only the top three?
The rank widget orders every choice it shows. With 12 crops and a respondent who only knows their main three, that produces nine positions of noise. Ask for the first, second and third choice as three select_one questions, each one hiding what was already picked:
| type | name | label | choice_filter | relevant | required |
|---|---|---|---|---|---|
| select_one crop | crop_1 | Which crop earned the household the most income last season? | name != '0' | yes | |
| select_one crop | crop_2 | Which crop earned the second most? | name != ${crop_1} | yes | |
| select_one crop | crop_3 | Which crop earned the third most? | name != ${crop_1} and name != ${crop_2} | ${crop_2} != '0' | yes |
| list_name | name | label |
|---|---|---|
| crop | 1 | Rice |
| crop | 2 | Maize |
| crop | 3 | Wheat |
| crop | 4 | Potato |
| crop | 5 | Vegetables |
| crop | 6 | Jute |
| crop | 0 | No other crop |
name != ${crop_1}removes the first answer from the second question, so the same crop cannot be picked twice.- "No other crop" (code
0) is hidden from the first question and ends the sequence:crop_3is asked only whencrop_2is a real crop. - Each rank is its own column in the data (
crop_1,crop_2,crop_3), which is easier to analyse than one space-separated value.
This pattern also works on platforms that have no rank widget.
How do I get the position of one item?
There is no function that returns where a given choice sits in the ranking. Check each position in turn with nested if(). The position of drinking water (code 1) among the five needs:
| type | name | label | calculation | required |
|---|---|---|---|---|
| rank need | urgency_rank | Rank these needs from most to least urgent. | yes | |
| calculate | water_position | if(selected-at(${urgency_rank}, 0) = '1', 1, if(selected-at(${urgency_rank}, 1) = '1', 2, if(selected-at(${urgency_rank}, 2) = '1', 3, if(selected-at(${urgency_rank}, 3) = '1', 4, 5)))) |
water_position is 1 when water is ranked first and 5 when it is last. With more than a handful of items, skip this in the form and split the ranked answer into positions at analysis time instead; one calculate per item gets long quickly. Nested conditions are covered in the XLSForm if statement guide.
How do I stop the list order from deciding the ranking?
A rank question starts in the order of the choices sheet. A tired respondent or a rushed enumerator who accepts the list as shown records that order, and the first choice on your sheet "wins" in the data. Shuffle the starting order per interview:
| type | name | label | parameters | required |
|---|---|---|---|---|
| rank need | need_rank_shuffled | Rank these needs from most to least urgent. | randomize=true | yes |
randomize=true goes in the parameters column, not in appearance. The saved codes are unaffected; only the order on screen changes. See randomize choices and question order for seeds and for keeping one order per respondent.
If many interviews by the same enumerator come back with the ranking in exactly the choices-sheet order, the list was probably accepted without being asked. Randomizing the start order makes that pattern impossible to produce by accident.
Common rank question mistakes and how to fix them
These are the messages pyxform returns, which is what ODK Central, KoboToolbox or the XLSForm converter shows when it rejects the form:
| You wrote | Write instead | Error you will see |
|---|---|---|
rank with no list name | rank need | Arguments 'itemset' and 'list_name' must not both be None or empty. |
rank needs when the list is called need | the exact list_name from the choices sheet | [row : 2] List name not in choices sheet: needs |
ranking need or rank_one need | rank need | Unknown question type 'ranking need'. |
selected(${shocks}, name) in choice_filter with no shocks question | add the select_multiple before the rank question, or fix the name | On the 'survey' sheet, the 'choice_filter' value is invalid. Reference variables must contain a name from the 'survey' sheet. Could not find the name 'shocks'. |
selected-at(${need_rank}, 1) for the top item | selected-at(${need_rank}, 0) | No error, but you get the second item: positions start at zero |
A filtered rank question with no relevant | count-selected(${shocks}) > 1 in relevant | No error, but a one-item list is shown for ranking |
randomize=true in appearance | put it in parameters | No error, but the order is not shuffled |
For other messages, see common XLSForm errors or paste the form into the free XLSForm validator.
Does this work the same in ODK, KoboToolbox and SurveyCTO?
No. rank is an ODK XLSForm type, and the three platforms differ more here than on most question types:
| Platform | rank type | First, second, third choice with select_one |
|---|---|---|
| ODK Collect and ODK Central web forms | Yes, as shown above | Yes |
| KoboToolbox (XLSForm upload) | Yes, same syntax | Yes |
| KoboToolbox form builder | Has its own "Ranking" question, saved as begin_rank and rank__level rows | Yes |
| SurveyCTO | No rank field type | Yes, with SurveyCTO's own choice filter syntax and relevance column |
KoboToolbox's form builder "Ranking" question is not the rank type. It stores one answer per rank level between begin_rank and end_rank rows, with the list in a kobo--rank-items column. That layout is KoboToolbox's own and is not standard XLSForm, so a form built that way will not load in ODK Central. If the form has to run on both, write rank need in the XLSForm and upload it.
When to use a rank question
Use rank when the full order matters and the list is short: five to seven items a respondent can hold in mind. Use the first, second, third choice pattern when only the top of the list matters, when the list is long, or when the form must also run on SurveyCTO. For long lists, let the respondent pick what applies first and rank only that. For the other select-style types and how they display, see the XLSForm appearance column.
You can describe the question in plain language instead: "ask which shocks hit the household, then have them rank only the ones they picked, and store the worst one". LooprAI writes the rank question, the choice filter and the calculates, then compiles the form with pyxform before anything is saved.
Next: XLSForm appearance column →
Frequently Asked Questions
How do I create a ranking question in XLSForm?
Write rank followed by a choice list name in the type column, for example rank need, and define that list on the choices sheet. The respondent puts the choices in order and the answer is saved as the choice codes in ranked order, separated by spaces.
How do I rank only the options selected in a previous question?
Use the same choice list in a select_multiple and in the rank question, then write selected(${earlier_question}, name) in the choice_filter column of the rank question. Add count-selected(${earlier_question}) > 1 in relevant so it is skipped when only one option was picked.
How is a rank question saved in the data?
As one column holding the choice codes in ranked order, separated by spaces, such as 5 1 3 2 4. The first code is the top-ranked item. Split the value on spaces at analysis time, or add calculate rows with selected-at() to store each position.
How do I get the top-ranked item in a calculation?
Use selected-at(${rank_question}, 0) in a calculate row. Positions start at zero, so 1 is the second item and 2 the third. The result is the choice code; use jr:choice-name() with a select question on the same list to get its label.
Can respondents rank only their top three?
Not with the rank widget, which orders every choice it shows. Ask three select_one questions on the same list instead, with a choice_filter such as name != ${first_choice} on the second and third so an option already picked cannot be chosen again.
Does the rank question work in KoboToolbox and SurveyCTO?
KoboToolbox accepts the rank type in an uploaded XLSForm; its form builder has a separate Ranking question saved as begin_rank rows, which is not standard XLSForm. SurveyCTO has no rank field type, so use first, second and third choice select_one questions there.
No Credit Card Required
Build the form first. Add hosting when you need it.
Start free with LooprAI, then deploy a managed ODK Central server or run DataSnap checks when your project is ready.
Automation handles the mechanical work.
Researchers decide what the evidence means.