Here are some ways to set up some of the more advanced features you might need to add to your survey.

Adding in recodes

Recodes can be added to a survey using the recodes parameter of various question types such as numeric_question, single_choice_question, multi_choice_question. Recodes allow you to map the response to a different value for easy analysis. For example, you might ask a respondent about their age, but then want to group their response into different age ranges. In this case, you can specify a dictionary of recodes where the keys are the new values you want to map to and the values are the old values that the respondent actually selected. To use recodes in a survey question, you simply pass the recodes dictionary to the question type's recodes parameter.

from survey import Survey

s = Survey(**globals())

s.multi_choice_question(
     "Which of the following fruits do you like?",
     options=["Apple", "Banana", "Cherry"],
     recodes={"Apple": "Fruit",
              "Banana": "Fruit",
              "Cherry": "Berry"})

Using topics to pipe values into questions

In addition to a question's main parameters, topics can be specified as keyword arguments. These topics are used to group questions together for reporting purposes and can be useful in analyzing survey results.

For example, if you have a series of questions about different brands of cars, you could specify the brand as a topic for each question. This would make it easier to analyze the results and better understand what people like or dislike about different brands.

To use topics, you simply pass the topic as a keyword argument when creating a question. For example, if you have a topic of "brand" and a question of "What do you like about {brand} cars?", then respondents will see "What do you like about Ford cars?".

Here is an example of using topics in a survey:

from survey import Survey
s = Survey(**globals())

car_brands = s.multi_select_question(
     "When you think about cars, which brands immediately come to mind?",
     options=["Ford", "Toyota", "Honda", "Tesla"],
     topic="car brands")

s.numeric_question(
     "How many cars have you owned in your lifetime?",
     min_max=(0, 10),
     topic="car ownership")

s.multi_choice_question(
     "What is the most important factor in choosing a car?",
     options=["Price", "Performance", "Style", "Safety"],
     topic="car factors")

Handling Repeated Questions

Each question in your survey should have a unique text that exactly matches the survey brief.

If the same question appears multiple times, check if it should:

Be asked only once to each respondent (possibly using conditional logic).
Be asked in different contexts (use unique keyword arguments to differentiate contexts).
Be repeated in the same context (use an index to differentiate questions).

If you need to repeat a question, then add an additional topic as a parameter so it can be uniquely identified for reporting:

Example

s.text_question("Why do you say that?", brand=brand, opinion=opinion)
s.text_question("Why do you say that?", index=1)

Managing Quotas

Quotas ensure that specific demographics or respondent criteria are met. Use the s.set_quota() method to create quota groups and the s.quota() method to define individual quotas.

Example of setting a quota for console ownership distribution:

console = s.multi_choice_question(question="Which of the following game consoles do you own?",
                                  options=["Xbox", "Playstation", "Nintendo Switch"],
                                  randomize=True,
                                  other_options=["None of these"])

s.set_quota(
    name="Console Ownership",
    quotas=[
        s.quota("Xbox", criteria=console == "Xbox", quota=0.20),
        s.quota("Playstation", criteria=console == "Playstation", quota=0.50),
        s.quota("Nintendo Switch", criteria=console == "Nintendo Switch", quota=0.3)
    ]
)

Important: Quotas should sum to 100% and must be placed early in the survey after asking relevant questions.

Handling Lists

When working with lists (e.g., brands), you might want to limit the number of items shown to each respondent. Use the `s.get_least_filled()` method to dynamically select items from a list.

Example

brand_options = ["Dove", "Pantene", "Head & Shoulders", "Herbal Essences", "Garnier", "Tresemme"]

selected_brands = s.get_least_filled(3, brand_options, "selected_brands")

for brand in s.randomize(selected_brands):
    # Ask questions about each selected brand here

Randomization

For questions involving choice or ranking, it's crucial to randomize the order of items to avoid bias. Use the `randomize` attribute or the `s.randomize()` method as needed.

Example:

brands = ["Heinz", "Campbell's", "Progresso", "Amy's", "Healthy Choice"]

for brand in s.randomize(brands):
    familiar = s.multi_choice_question(
        question="Have you bought any {brand} products in the last week?",
        options=["Yes", "No"],
        brand=brand
    )

Custom Response Validation

Responses can be validated using the `custom_validator` parameter, which typically involves a lambda function to check specific conditions.

Example

s.text_question("Please enter the word 'apple'", custom_validator=lambda x: "Please enter the word 'apple'" if x.lower() != "apple" else None)

Dynamic Question Text

Use placeholders in question text, which will be replaced by values of variables passed as keyword arguments.

Example

brand = "TheBrand"
s.text_question("Why do you like {brand}", brand=brand)

Storing Calculated Variables

You might need to store calculated values that are not directly asked in the survey. Use `s.store_value()` for this purpose and the variables will be available for reporting.

Example

from datetime import datetime

birth_year = s.numeric_question("What year were you born in?", min_max=(1920, 2020))
s.store_value("age", datetime.now().year - birth_year)