When and Why to Use
Use this when a study targets minors and you need a parent/guardian to:
confirm how many children fall within an age window,
record each child’s age and gender (with optional recodes/labels),
select which child is currently available to continue.
Ideal for: youth studies, parental permission flows, household sampling where one child continues.
Chat Experience
Guided, multi-step prompts (count → ages → genders → availability).
Optional custom wording for each step (four question text fields).
Gender labels and “son/daughter” terms configurable via gender_map.
Traditional Experience
Sequential screens and compact multi-field forms.
Numeric inputs for counts/ages; single/multi-select for genders.
Final selector for the available child (or “None of the above”).
Configuration Options
Option | Type | Required | Default | Description |
min_age | int | no | 13 | Minimum eligible age. |
max_age | int | no | 17 | Maximum eligible age. |
age_recodes | Optional[dict[int, str]] | no | None | Map raw ages to recoded labels (e.g., 13→“13–15”). |
gender_map | Optional[dict[str, str]] | no | { "Male": "son", "Female": "daughter" } | Maps gender → child term for copy/substitution. |
question_1_text | Optional[str] | no | "How many children do you have between the ages of {min_age} and {max_age}?" | Custom text for count prompt. |
question_2_text | Optional[str] | no | "For each child, please let us know their age" | Custom text for ages prompt. |
question_3_text | Optional[str] | no | "Now, please let us know their gender" | Custom text for genders prompt. |
question_4_text | Optional[str] | no | "Which, if any, of your children are available to take the survey now?" | Custom text for availability prompt. |
Return Value
Optional[StringResponse] — Returns a structured string payload with age and gender information for the selected child. Returns None if the respondent reports no eligible children or selects “none available.”
Example Code
Basic usage
from survey import Survey s = Survey(**globals()) child_info = s.kid_picker_question( min_age=13, max_age=17, ) if child_info: s.note("Please ask your {child} to take the survey now.", child=child_info) else: s.terminate("Sorry, this survey is for children only.") s.complete()With age recodes and custom labels
child_info = s.kid_picker_question( min_age=5, max_age=18, age_recodes={5: "5–8", 6: "5–8", 7: "5–8", 8: "5–8", 9: "9–12", 10: "9–12"}, gender_map={"Male": "boy", "Female": "girl"}, )Custom question copy
child_info = s.kid_picker_question( question_1_text="Between {min_age} and {max_age}, how many children live in your household?", question_2_text="Please enter each child's age.", question_3_text="Please select each child's gender.", question_4_text="Which child can take the survey now (if any)?" )
Notes
If no eligible children are reported, the function returns None and you should end or reroute the survey.
age_recodes are applied only to reporting/labels; underlying validation still uses raw ages.
You can add inclusive options (e.g., “Non-binary,” “Prefer not to say”) via your gender list, then map to terms as needed in gender_map.
Keep availability optional; respondents may choose “None of the above.”