API Reference

In the MX8 platform, surveys are written in python using the Surveys class.

Surveys should always start with the code block:

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

You can import other python libraries that are part of the standard library, e.g. datetime and math, but not modules that are not in the standard library, like pandas.

API Reference

Survey class for creating surveys.

Example usage:

Surveys should always start with the following code block:

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

Then call the following methods to add different questions to the survey.

media property

Access the media collection.

The media collection contains images and videos that can be used in questions. The media are added to the survey automatically and can be uploaded from the MX8 dashboard. Additional columns added in the dashboard will be added to the media collection.

Each item in the media collection is a MediaItem object. You can access the media collection by iterating over the media object, and pass it to the image parameter of questions.

Columns can be accessed using dot notation. For example, if you have a column called "brand" in your media collection, then you can access it using media.brand. You can also get all the values of a column using the get_media_values function.

If you have not uploaded any media to the survey, then a dummy media collection will be used that contains dummy images with the following columns:

name
description
product
brand
campaign
agency
id

You can create your own metadata columns in the MX8 dashboard and these will be added to the media collection after you have created the survey and uploaded the media.

The columns are automatically used when reporting the results. For example, if you have a column called "brand" and you ask a question about the brand, then the results will be automatically grouped by brand.

Example usage:

from survey import Survey
s = Survey(**globals())
for media in s.media:
    s.select_question(f"What do you think of this image?",
                            options=["Like", "Dislike"],
                            image=media)

note

Add a note to the survey.

Presents a note to the user that they must acknowledge. This could be a introductory message, a warning, or any text based piece of information.

If require_response is set to False, then the note will be presented to the user, but they will not be required to acknowledge it.

Example usage:

from survey import Survey
s = Survey(**globals())
s.note("Welcome to our market research survey! Your feedback is"
       "important to us as it helps us understand market trends"
       "and consumer behavior. This survey is designed to gather"
       "information about your experiences and preferences related"
       "to our industry and company. Your responses will be kept"
       "confidential and used only for research purposes. Thank"
       "you for taking the time to participate!")

Parameters:

Name	Type	Description	Default
`copy`	`str`	The note to present to the user	required
`require_response`	`bool`	Whether the user must acknowledge the note	`True`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`

Topics

Additional topics can be specified as keyword arguments.

Topics are applied to any format strings in the question text. For example, if you have a topic of "brand" and a note of "We are now going to show you an ad for {brand} cars.", then respondents will see "We are now going to show you an ad for Ford cars?"

get_consent

Gets consent for the survey.

Asks the user the standard MX8 consent question. Terminates the respondent if they do not agree to the consent.

Example usage:

from survey import Survey
s = Survey(**globals())
s.get_consent()
:
    topic (str): the topic to use for the consent question
    client (str): the description of the client to use for the consent question
    consent_text (str): override this value to set a custom text for the consent question
    image (MediaItem): An option image to show the user, from the s.media collection

text_question

Add a text question to the survey.

Asks an open ended question to the respondent. The response is validated by AI according to the validation instructions and scored on a scale of 1-5. If the response does not meet the quality_threshold, the respondent will be asked to clarify their response. If after max_attempts the response does not meet the termination_threshold, the survey will terminate.

To prevent termination, set the quality_threshold to 1.

Example usage:

from survey import Survey
s = Survey(**globals())
s.text_question("When you think about cars, which brands immediately come to mind?")

Default values: If no default value is provided, the survey will generate a random string of 10 characters for the test data.

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`default`	`str`	the default answer to use in generating test data	`None`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`validation_instructions`	`str`	a string describing validation rules for the question	`None`
`quality_threshold`	`int`	the minimum score (on a scale of 1-5) required for a valid response, defaults to 3	`3`
`termination_threshold`	`int`	the minimum score required to terminate, defaults to 1, e.g. no termination	`1`
`max_attempts`	`int`	the maximum number of attempts to get a valid response	`3`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`
`number_of_responses`	`int`	the number of responses to collect. Only supported in landscape orientation.	`1`
`min_responses`	`int`	the minimum number of responses to collect. Only supported in landscape orientation.	`None`

Topics

Additional topics can be specified as keyword arguments. These are only visible in the reporting and are used to group questions together. For example, if you have a series of questions about different brands of cars, then you could specify the brand as a topic for each question.

Topics are applied to any format strings in the question text. 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?"

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"])
for brand in car_brands:
    s.text_question(f"What do you like about {brand} cars?",
                    topic=brand)

Custom Errors

Text questions by default are validated by AI to ensure that the response is a valid response. You can provide custom instructions for the validation by using the validation_instructions parameter.

By default, users are given 3 attempts to provide a valid response. If they fail to do so, the survey will terminate. You can change the maximum number of attempts by using the max_attempts parameter, and you can disable the termination by setting the terminate_after_max_attempts parameter to False.

If disabled, the the validation error will be included in any calls to s.count_validation_errors().

If you do not want to use the AI validation, you can provide a custom_validator function that takes the response as a parameter and returns a string if the response is invalid. This is typically a lambda function that takes the response as a parameter and returns a string if the response is invalid.

e.g. custom_validator=lambda x: "Are you sure you meant Sleepy Cows?" if x == "Sleepy Cows" else None

numeric_question

Add a numeric question to the survey.

This present the user with a number choice of choosing a number between a range of numbers.

Example usage:

from survey import Survey
s = Survey(**globals())
s.numeric_question("What year were you born in?",
                   min_max=(1900, 2024))

Recodes: Recodes can be used to change the values of the responses.

Recodes for numeric question take the format of a dictionary where the key is the range of values to be recoded, and the value is the value to recode to. You can also use percentages to recode a percentage of the values.

Example usage:

from survey import Survey
s = Survey(**globals())
s.numeric_question("How old are you?",
                    min_max=(18, 100),
                    recodes={
                        "18-25": "18-25",
                        "26-54": "26-54",
                        "55-74": "55-74",
                        "75-100": "75+"
                    })
s.numeric_question("How many times have you visited our website?",
                    min_max=(0, 100),
                    recodes={
                        "0-30%": "Low",
                        "31-70%": "Medium",
                        "71-100%": "High"
                    })

Default values: If no default value is specified, then the test data will consist of random values between the min and max value.

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`min_max`	`Tuple[int, int]`	the min and max range of the numbers	`DEFAULT_MIN_MAX`
`default`	`str`	the default value to use when generating test data.	`None`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`

Topics

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"])
for brand in car_brands:
    s.numeric_question(f"How many {brand} cars have you owned?",
                        min_max=(0, 10),
                        recodes={
                            "0-30%": "Low",
                            "31-70%": "Medium",
                            "71-100%": "High"
                        },
                        topic=brand)

Custom Errors

If you want to return a specific response to the user if they enter a specific value, you can use the custom_validator parameter. This is typically a lambda function that takes the response as a parameter and returns a string if the response is invalid.

It is typically used for "gotcha" questions, where the user is asked to enter a specific value to ensure they are paying attention, e.g.

custom_validator=lambda x: "Are you sure that you're 150 years old" if x > 150 else None

select_question

Add a multiple-choice question to the survey.

This present the user with a number of choices of which the user can choose exactly one.

Example usage:

from survey import Survey
s = Survey(**globals())
s.select_question("What is your gender?",
                   options=["Male", "Female", "Non-Binary"])

Randomnization: Set randomize to True to randomize the order of the options. If you have any additional options you do not want to have randomized, then you can specify these in the fixed_options parameter.

Default values: If no default value is specified, then the test data will consist of random values chosen from the options.

Recodes: Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question on a five point scale, but want to store the response on a three point scale, you can use recodes to map the response to the correct value.

Disabling Options: Options can be disabled using the disabled_options parameter. This is useful if you want to disable an option based on a previous response. For example, if you want to ask a question about what they enjoyed about the experience, and then ask about what they didn't enjoy, you can disable the options they selected in the first question.

Other, please specify: If you want to allow the user to specify an option that is not in the list, you can set the specify_option parameter. This will present the user with an additional option to specify their own value.

from survey import Survey
s = Survey(**globals())
s.select_question("On a scale of 1 to 5, how much do you like this product?",
    options=["1", "2", "3", "4", "5"],
    recodes={
        "1": "dislike",
        "2": "dislike",
        "3": "neutral",
        "4": "like",
        "5": "like"})

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`options`	`List[str \| MediaItem]`	a list of strings or items from s.media containing the options	required
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`randomize`	`bool`	whether to randomize the order of the options	`False`
`fixed_options`	`List[str]`	a list of strings containing the fixed options	`None`
`skip_empty`	`Optional[bool`	if set to True, the question will be skipped if there are no options	`False`
`disabled_options`	`List[str]`	a list of strings containing options to be disabled	`None`
`specify_option`	`str`	An 'other' that the user will be asked to specify	`None`
`specify_text`	`str`	The text to ask the user to specify the 'other' option, defaults to "Please specify"	`DEFAULT_SPECIFY_TEXT`
`default`	`str \| List[str]`	the default value(s) to use when generating test data.	`None`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`
`image_label_field`	`Optional[str]`	the field to use as the label for the image if using media items in the options	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the image to display	`None`

Topics

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"])
for brand in car_brands:
    s.select_question(f"How many {brand} cars have you owned?",
                        options=["0", "1", "2", "3", "4+"],
                        recodes={
                            "0": "never owned",
                            "1": "single owner",
                            "2": "loyalist",
                            "3": "loyalist",
                            "4+": "enthusiast"},
                        topic=brand)

Custom Errors

It is typically used for "gotcha" questions, where the user is asked to enter a specific value to ensure they are paying attention.

e.g. custom_validator=lambda x: "Are you sure you meant Sleepy Cows?" if x == "Sleepy Cows" else None

multi_select_question

Add a multi-select question to the survey.

This present the user with a number of choices of which the user can choose one or more.

Example usage:

from survey import Survey
s = Survey(**globals())
s.select_question("What is your gender?",
                   options=["Male", "Female", "Non-Binary"])

Default values: If no default value is specified, then the test data will consist of random values chosen from the options.

Recodes: Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question about what they enjoyed about the experience, and classify it into different categories, you can use recodes to map the response to the correct value.

Disabled Options: Options can be disabled using the disabled_options parameter. This is useful if you want to disable an option based on a previous response. For example, if you want to ask a question about what they enjoyed about the experience, and then ask about what they didn't enjoy, you can disable the options they selected in the first question.

from survey import Survey
s = Survey(**globals())
enjoyment = s.multi_select_question("What did you enjoy about the experience?",
    options=["The food", "The service", "The atmosphere", "The price"],
    fixed_options=["Other"],
    exclusive_options=["Other"],
    recodes={
        "The food": "food",
        "The service": "service",
        "The atmosphere": "atmosphere",
        "The price": "price",
        "Other": "other"})
if "Other" in enjoyment:
    s.text_question("What else did you enjoy about the experience?")

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`options`	`List[str \| MediaItem]`	a list of strings or items from s.media containing the options	required
`max_options`	`Optional(int`	the maximum number of options to be selected, defaults to all options	`None`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`randomize`	`bool`	whether to randomize the order of the options	`False`
`fixed_options`	`List[str]`	a list of strings containing the fixed options	`None`
`exclusive_options`	`List[str]`	a list of strings containing the exclusive options	`None`
`specify_option`	`str`	An 'other' that the user will be asked to specify	`None`
`specify_text`	`str`	The text to ask the user to specify the 'other' option, defaults to "Please specify"	`DEFAULT_SPECIFY_TEXT`
`skip_empty`	`Optional[bool`	if set to True, the question will be skipped if there are no options	`False`
`default`	`str`	the default value to use when generating test data.	`None`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`
`image_label_field`	`Optional[str]`	the field to use as the label for the image if using media items in the options	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the image to display	`None`

Topics

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"])
for brand in car_brands:
    s.select_question(f"Which of the following do you associate with {brand} cars?",
                        options=["Reliability", "Safety", "Performance", "Luxury"],
                        topic=brand)

Custom Errors

It is typically used for "gotcha" questions, where the user is asked to enter a specific value to ensure they are paying attention.

e.g. custom_validator=lambda x: "Are you sure you meant Sleepy Cows?" if "Sleepy Cows" in x else None

grid_select_question

Add a grid select question to the survey.

This presents the user with a grid of options where they can select one option from each row.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_select_question("Please rate the following aspects of the product",
    rows=["Quality", "Price", "Service", "Delivery"],
    options=["Poor", "Fair", "Good", "Very Good", "Excellent"])

Recodes: Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question about what they enjoyed about the experience, and classify it into different categories, you can use recodes to map the response to the correct value.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_select_question("Please rate the following aspects of the product",
    row_name="Product Aspect",
    rows=["Quality", "Price", "Service", "Delivery"],
    options=["Poor", "Fair", "Good", "Very Good", "Excellent"],
    recodes={
        "Poor": "1",
        "Fair": "2",
        "Good": "3",
        "Very Good": "4",
        "Excellent": "5"
    })

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`rows`	`List[str \| MediaItem]`	a list of strings or items from s.media containing the rows	required
`options`	`List[str]`	a list of strings containing the options	required
`style`	`str`	the style of the question, can be "button" or "radio", defaults to "radio"	`'radio'`
`randomize`	`bool`	bool: whether to randomize the order of the rows	`False`
`randomize_options`	`bool`	(bool): whether to randomize the order of the options	`False`
`fixed_options`	`List[str]`	a list of strings containing the fixed options	`None`
`specify_option`	`str`	An 'other' that the user will be asked to specify	`None`
`specify_text`	`str`	The text to ask the user to specify the 'other' option, defaults to "Please specify"	`DEFAULT_SPECIFY_TEXT`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`skip_empty`	`Optional[bool`	if set to True, the question will be skipped if there are no rows	`False`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`
`image_label_field`	`Optional[str]`	the field to use as the label for the image if using media items in the rows	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image in the rows	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the image to display	`None`
`default`	`Dict[str, str]`	a dictionary of default values to use when generating test data	`None`

Topics

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"])
for brand in car_brands:
    s.grid_select_question(f"Please rate the following aspects of {brand} cars",
        row_name="Product Aspect",
        rows=["Quality", "Price", "Service", "Delivery"],
        options=["Poor", "Fair", "Good", "Very Good", "Excellent"],
        topic=brand)

Custom Errors

By default, the custom_validator parameter is set to a straight-line check that raises an error if the respondent enters the same value for each cell but you can override this by passing a custom validator function.

grid_multi_select_question

Add a grid multi-select question to the survey.

This presents the user with a grid of options where they can select multiple option from each row.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_multi_select_question("What do you associate with these brands? Select all that apply",
    rows=["Coke", "Pepsi", "Dasani", "Fanta"],
    options=["Tasty", "Refreshing", "Cool", "Value", "Convenient"])

Recodes: Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question about what they enjoyed about the experience, and classify it into different categories, you can use recodes to map the response to the correct value.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_multi_select_question("What do you associate with these brands? Select all that apply",
    row_name="Brand",
    rows=["Coke", "Pepsi", "Dasani", "Fanta"],
    options=["Tasty", "Refreshing", "Cool", "Value", "Convenient"],
    recodes={
        "Tasty": "Product",
        "Refreshing": "Product",
        "Cool": "Brand",
        "Value": "Pricing",
        "Convenient": "Distribution"
    })

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`rows`	`List[str]`	a list of strings containing the rows	required
`row_name`	`str`	the name of the row	required
`options`	`List[str \| MediaItem]`	a list of strings containing the options	required
`style`	`str`	the style of the question, either "button" or "checkbox", defaults to "checkbox"	`'checkbox'`
`randomize`	`bool`	bool: whether to randomize the order of the rows	`False`
`randomize_options`	`bool`	(bool): whether to randomize the order of the options	`False`
`fixed_options`	`List[str]`	a list of strings containing the fixed options	`None`
`exclusive_options`	`List[str]`	a list of strings containing the exclusive options	`None`
`specify_option`	`str`	An 'other' that the user will be asked to specify	`None`
`specify_text`	`str`	The text to ask the user to specify the 'other' option, defaults to "Please specify"	`DEFAULT_SPECIFY_TEXT`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`default`	`Dict[str, List[str]]`	a dictionary of default values to use when generating test data	`None`
`skip_empty`	`Optional[bool`	if set to True, the question will be skipped if there are no rows	`False`
`image_label_field`	`Optional[str]`	the field to use as the label for the image if using media items in the rows	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image in the rows	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the image to display	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`

Topics

Custom Errors

grid_rating_question

Add a grid rating question to the survey.

This presents the user with a grid of options where they can rate each row on user defined scale.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_rating_question("Please rate the following aspects of the product",
    rows=["Quality", "Price", "Service", "Delivery"],
    row_name="Product Aspect",
    number_of_points=5)

Recodes: Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question about what they enjoyed about the experience, and classify it into different categories, you can use recodes to map the response to the correct value.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_rating_question("Please rate the following aspects of the product",
    row_name="Product Aspect",
    rows=["Quality", "Price", "Service", "Delivery"],
    number_of_points=5,
    recodes={
        "1": "Poor",
        "2": "Poor",
        "3": "Fair",
        "4": "Fair",
        "5": "Good"
    })

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`rows`	`List[str]`	a list of strings or items from s.media containing the rows	required
`row_name`	`str`	the name of the row	required
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`number_of_points`	`int`	the number of points to rate the row on, defaults to 5 or the number of labels	`None`
`style`	`str`	the style of the question, either "slider", "button" or "star"	`'slider'`
`first_point`	`int`	the value of the first point, defaults to 1 or the first label	`None`
`labels`	`Dict[int, str]`	a dictionary of labels to use on the question	`None`
`randomize`	`bool`	whether to randomize the order of the rows	`False`
`default`	`Dict[str, int]`	a dictionary of default values to use when generating test data	`None`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`skip_empty`	`Optional[bool`	if set to True, the question will be skipped if there are no rows	`False`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`
`image_label_field`	`Optional[str]`	the field to use as the label for the image if using media items in the rows	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image in the rows	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the images to display	`None`

Topics

Topics are applied to any format strings in the question text.

Custom Errors

grid_numeric_question

Add a grid numeric question to the survey.

This presents the user with a grid of options where they can select one option from each row.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_numeric_question("How many hours do you spend per week on the following activities?",
    rows=["Work", "Sleep", "Exercise", "Socializing"],
    row_name="Activity",
    columns=["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
    randomize=True,
    )

Recodes: Recodes can be used to change the values of the responses.

Example usage:

from survey import Survey
s = Survey(**globals())
s.grid_numeric_question("How many hours do you spend per week on the following activities?",
    rows=["Work", "Sleep", "Exercise", "Socializing"],
    row_name="Activity",
    columns=["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
    randomize=True,
    recodes={
        "0-30%": "Low",
        "31-70%": "Medium",
        "71-100%": "High"
    })

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`rows`	`List[str]`	a list of strings containing the rows	required
`row_name`	`str`	the name of the row	required
`columns`	`List[str]`	a list of strings containing the columns	`None`
`column_name`	`str`	the name of the column	`None`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`min_max`	`Tuple[int, int]`	the minimum and maximum values for the question	`DEFAULT_MIN_MAX`
`randomize`	`bool`	bool: whether to randomize the order of the rows	`False`
`randomize_columns`	`bool`	(bool): whether to randomize the order of the columns	`False`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question.	`None`
`default`	`Dict[str, int]`	a dictionary of default values to use when generating test data	`None`
`autosum_columns`	`bool`	whether to autosum the columns	`False`
`autosum_rows`	`bool`	whether to autosum the rows	`False`
`image_label_field`	`Optional[str]`	the field to use as the label for the image if using media items in the rows	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image in the rows	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the images to display	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`

Custom Errors

this_or_that_question

Add a this or that question to the survey.

This presents the user with a series of questions where they can select one option from each row.

Example usage:

from survey import Survey
s = Survey(**globals())
s.this_or_that_question("Which of the following do you prefer?",
    row_options=[
        ["Apples", "Oranges"],
        ["Coke", "Pepsi"],
        ["Dogs", "Cats"],
        ["Winter", "Summer"]
    ])

Recodes: Recodes can be used to change the values of the responses.

Recodes for this or that question take the format of a dictionary where the key is the range of values to be recoded, and the value is the value to recode to. You can also use percentages to recode a percentage of the values.

Example usage:

from survey import Survey
s = Survey(**globals())
s.this_or_that_question("Which of the following do you prefer?",
    row_options=[
        ["Apples", "Oranges"],
        ["Coke", "Pepsi"],
        ["Dogs", "Cats"],
        ["Winter", "Summer"]
    ])

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`row_options`	`List[List[str]]`	a list of lists containing the options	required
`randomize`	`bool`	bool: whether to randomize the order of the rows	`False`
`randomize_columns`	`bool`	(bool): whether to randomize the order of the columns	`False`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question.	`None`
`default`	`Dict[str, str]`	a dictionary of default values to use when generating test data	`None`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`image_label_field`	`str`	the label to show above the image	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image in the rows	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the images to display	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`

Custom Errors

this_or_that_rating_question

Add a this or that rating question to the survey.

This presents the user with a series of questions where they can rate one option from each row.

Example usage:

from survey import Survey
s = Survey(**globals())
s.this_or_that_rating_question("Which of the following do you prefer?",
    number_of_points=5,
    row_options=[
        ["Apples", "Oranges"],
        ["Coke", "Pepsi"],
        ["Dogs", "Cats"],
        ["Winter", "Summer"]
    ])

Recodes: Recodes can be used to change the values of the responses.

Example usage:

from survey import Survey
s = Survey(**globals())
s.this_or_that_rating_question("Which of the following do you prefer?",
    row_options=[
        ["Apples", "Oranges"],
        ["Coke", "Pepsi"],
        ["Dogs", "Cats"],
        ["Winter", "Summer"]
    ])

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`row_options`	`List[List[str]]`	a list of lists containing the options	required
`randomize`	`bool`	bool: whether to randomize the order of the rows	`False`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question.	`None`
`default`	`Dict[str, str]`	a dictionary of default values to use when generating test data	`None`
`get_custom_error`	`Callable[[str], str \| None]`	a function to return a custom error message	required
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`

Custom Errors

show_image

Show an image to the respondent.

This will show an image to the respondent for a set number of seconds.

Example usage:

from survey import Survey
s = Survey(**globals())
for media in s.media:
    s.show_image("Take a look at this image for 5 seconds",
                image=media,
                number_seconds=5)

Parameters:

Name	Type	Description	Default
`image`	`MediaItem`	the image to show	required
`number_seconds`	`int`	the number of seconds to show the image for	`5`

play_video

Play a video to the respondent.

This will play a video to the respondent and then present them with a message at the end, which defaults to "Thank you for watching the video!".

The Video is automatically watermarked with the user's IP address if the security parameter is set to True and always DRM protected to prevent copying or screen recording. Links to the video are only valid for 60 seconds.

Example usage:

from survey import Survey
s = Survey(**globals())
for media in s.media:
    s.play_video(video=media)
    ... now ask questions about the video

Dial testing

You can also add a dial to the video to allow the respondent to indicate their feelings as they watch the video. The dial can be set to one of the following values: - "none" - no dial is shown - "right" - a dial is shown on the right of the video - "bottom" - a dial is shown at the bottom of the video

The dial defaults to a range of 0-100, with captions "Dislike", "Neutral", and "Like" but you can set the labels and caption for the dial using the dial_labels and dial_caption parameters.

Parameters:

Name	Type	Description	Default
`video`	`MediaItem`	the video to play	required
`end_message`	`str`	the message to show the respondent at the end of the video	`'Thank you for watching the video!'`
`start_message`	`str`	the message to show the respondent at the start of the video	`"Hit play when you're ready to watch the video."`
`dial`	`str`	the position of the dial, either "none", "right", or "bottom", defaults to "none"	`'none'`
`dial_labels`	`Dict[int, str]`	the labels to show on the dial	`None`
`dial_caption`	`str`	the caption to show above the dial	`'Please adjust the slider to reflect your feelings as you watch the video.'`

embed_content

Embed content from a URL in the survey.

Currently only supports embedding content from YouTube.

Example usage:

from survey import Survey
s = Survey(**globals())
s.embed_content("Watch this video", "https://www.youtube.com/watch?v=2gcsgfzqN8k", duration=231)

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`url`	`str`	the URL to embed in the survey	required
`duration`	`int`	the number of seconds to wait before allowing the user to continue	required

get_location

Get the location of the user.

Adds two questions to the survey. The first asks for the users zipcode and the second validates the zipcode based on the location_type

Example Usage

s.get_location("city", 1001)

Default values: If no default value is specified, then the test data will consist of random values chosen from the options.

Recodes: The location question does not support recodes.

Parameters:

Name	Type	Description	Default
`location_type`	`str`	the type of location to pick up, e.g. city	required
`default`	`str`	the default value to look	`None`
`number_options`	`int`	the number of options to show the user	`5`

quota staticmethod

Creates a quota element.

Used to create an individua quota line that makes up part of a quota.

Example usage:

from survey import Survey
s = Survey(**globals())
age = s.numeric_question(question="How old are you?",
                        min_max=(18, 100),
                        recodes={
                            "0-17": "Under 18",
                            "18-34": "18-34",
                            "35-54": "35-54",
                            "55-120": "55+"
                        })
gender = s.select_question(question="What is your gender?",
                                options=["Male", "Female"])
# Check age and gender quotas
s.set_quota(
    name="Quads",
    quotas=[
        s.quota("Younger Men", criteria=(age < 40) & (gender == "Male"), quota=0.25),
        s.quota("Older Men", criteria=(age >= 40) & (gender == "Male"), quota=0.25),
        s.quota("Younger Women", criteria=(age < 40) & (gender == "Female"), quota=0.25),
        s.quota("Older Women", criteria=(age >= 40) & (gender == "Female"), quota=0.25)
    ]
)

Parameters:

Name	Type	Description	Default
`name`	`str`	the name to be given to this quota line when it is reported	required
`criteria`	`bool`	the boolean condition based on the responses to other questions that the respondent must meet to be included in this quota line	required
`quota`	`float`	the prortion of the respondednts that should fall into this quota	required

set_quota

Sets a quota group based on a number of quota lines.

Takes a group of individual quotas from s.quota() and creates a group that each respondent must fall into at least one category. Any respondents that do not fall into one of the groups, or respondents that are over-quota, will be terminated.

Example usage:

from survey import Survey
s = Survey(**globals())
age = s.numeric_question(question="How old are you?",
                        min_max=(18, 100),
                        recodes={
                            "0-17": "Under 18",
                            "18-34": "18-34",
                            "35-54": "35-54",
                            "55-120": "55+"
                        })
gender = s.select_question(question="What is your gender?",
                                options=["Male", "Female"])
# Check age and gender quotas
s.set_quota(
    name="Quads",
    quotas=[
        s.quota("Younger Men", criteria=(age < 40) & (gender == "Male"), quota=0.25),
        s.quota("Older Men", criteria=(age >= 40) & (gender == "Male"), quota=0.25),
        s.quota("Younger Women", criteria=(age < 40) & (gender == "Female"), quota=0.25),
        s.quota("Older Women", criteria=(age >= 40) & (gender == "Female"), quota=0.25)
    ]
)

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of this group of quotas, for example "demos"	required
`quotas`	`List[Quota]`	a list of quotas to be added, each created using s.quota()	required

get_least_filled

Get the least filled quotas from a list of elements in a quota.

If you want to ask about a large number of items and you want to make sure that you have a minimum number of respondents for each item, then you can use this function to get the least filled items from a list of items.

Note that this function will return the least filled items from the list, and will not terminate the respondent based on the number of other respondents that have already selected those items. If you want to terminate the respondent based on the number of other respondents that have already selected those items, then you should use the set_quota() function to establish the quotas.

Example usage:

from survey import Survey
s = Survey(**globals())
brand_list = ['Acura', 'Alfa Romeo', 'Aston Martin', 'Audi', 'Bentley',
              'BMW', 'Bugatti', 'Buick', 'Cadillac', 'Chevrolet', 'Chrysler',
              'Citroen', 'Dodge', 'Ferrari', 'Fiat', 'Ford', 'Geely', 'Genesis',
              'GMC', 'Honda', 'Hyundai', 'Infiniti', 'Jaguar', 'Jeep', 'Kia',
              'Koenigsegg', 'Lamborghini', 'Land Rover', 'Lexus', 'Lincoln',
              'Lotus', 'Maserati', 'Mazda', 'McLaren', 'Mercedes-Benz', 'Mini',
              'Mitsubishi', 'Nissan', 'Pagani', 'Peugeot', 'Polestar', 'Porsche',
              'Ram', 'Renault', 'Rolls-Royce', 'Subaru', 'Suzuki', 'Tesla', 'Toyota',
              'Volkswagen', 'Volvo']brands = s.get_least_filled(number=10,
                            from_list=brand_list,
                            quota="Brand familiarity")
familiar_brands = s.multi_select_question(
    question="Which of the following car brands have you heard of?",
    options=brands)

Parameters:

Name	Type	Description	Default
`number`	`int`	the number of items to return	required
`from_list`	`List[str]`	the list of items to choose from	required
`quota`	`str`	the name of the quota to check against	required

terminate

Terminate the survey.

Call this function if a condition has been met that means you want to terminate the survey, for example if the consumer does not qualify for a specific reason.

If you are wanting to set quotas, you should us the set_quota function which also terminats if respondents do not qualify for the quotas

Example usage:

    if has_xbox = False:
        s.terminate("Sorry you don't qualify for this survey"
                    "because you don't have an Xbox")

Parameters:

Name	Type	Description	Default
`reason`	`str`	The reason to give to the user to explain why they don't qualify.	required

terminate_if

Terminate the survey if a condition is met.

Call this function with the condition you want to check and then terminate the user if the condition is true.

Example usage:

    if s.terminate_if(has_xbox = False, "Sorry you don't qualify for this survey"
                      "because you don't have an Xbox")

Parameters:

Name	Type	Description	Default
`condition`	`bool`	The condition to check and terminate the user if it's True	required
`reason`	`str`	The reason to give to the user to explain why they don't qualify.	required

complete

Complete the survey.

Call this function at the end of the survey to complete the survey and thank the user.

Example usage:

    from survey import Survey
    s = Survey(**globals())
    # Add questions here
    s.complete()

rating_question

Add a rating question to the survey.

This presents the user with a number of choices of which the user can choose one that represents their opinion on a sliding scale.

There are three available styles:

style="slider" - For the slider style, the user can drag the slider.
style="button" - For the button style, the user can click on the button they want.
style="card" - For the card style, question are shown in card format.

In both the slider and button styles, the rating scale is presented as a number with optional text labels for appropriate points on the scale. For the card style, no numbers are shown, only the text labels.

Example usage:

from survey import Survey
s = Survey(**globals())
s.rating_question("How much do you like this product?",
                  number_of_points=5,
                  style="slider",
                  labels={
                      1: "Dislike",
                      3: "Neutral",
                      5: "Like"
                  })

Default values: If no default value is specified, then the test data will consist of random values chosen from the options.

Recodes: Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question about what they enjoyed about the experience, and classify it into different categories, you can use recodes to map the top two box response to a different value.

from survey import Survey
s = Survey(**globals())
s.rating_question("On a scale of 1 to 5, how much do you like this product?",
    number_of_points=5,
    style="slider",
    labels={
        1: "Dislike",
        3: "Neutral",
        5: "Like"
    },
    recodes={
        "1": "dislike",
        "2": "dislike",
        "3": "neutral",
        "4": "like",
        "5": "like"})

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`number_of_points`	`int`	the number of points on the scale (default to 5 or the number of labels)	`None`
`first_point`	`int`	the first point on the scale (default to 1 or the first label)	`None`
`style`	`str`	the style of the scale, either "slider", "button", "star" or "card"	`'slider'`
`labels`	`Dict[int, str]`	a dictionary of text labels for each point on the scale	`None`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`default`	`str`	the default value to use when generating test data.	`None`
`dont_know_option`	`str`	Optionally add a "Don't know" option to the question using this text.	`''`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`

Using the don't know option

If you want to add a "Don't know" option to the question, then you can specify the text to use for the "Don't know" option using the dont_know_option parameter. If the user selects this option then the response will be recorded as a value of -999 in the survey data and reported as the text specified in the dont_know_option parameter.

Topics

Topics are applied to any format strings in the question text. For example, if you have a topic of "brand" and a question of "How do you rate {brand} cars?", then respondents will see "How do you rate Ford cars?"

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"])
for brand in car_brands:
    s.rating_question(f"How do you rate {brand} cars?",
                        number_of_points=5,
                        style="slider",
                        labels={
                            1: "Dislike",
                            3: "Neutral",
                            5: "Like"
                        },
                        topic=brand)

Custom Errors

It is typically used for "gotcha" questions, where the user is asked to enter a specific value to ensure they are paying attention.

net_promoter_score_question

Add a rating question to the survey.

This presents the user with a number of choices of which the user can choose one that represents their opinion on a sliding scale.

There are three available styles:

style="slider" - For the slider style, the user can drag the slider.
style="button" - For the button style, the user can click on the button they want.
style="card" - For the card style, question are shown in card format.

Example usage:

from survey import Survey
s = Survey(**globals())
s.net_promoter_score_question("How much do you like this product?",
                  number_of_points=11,
                  style="slider",
                  labels={
                      1: "Dislike",
                      3: "Neutral",
                      5: "Like"
                  })

Default values: If no default value is specified, then the test data will consist of random values chosen from the options.

Recodes: Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question about what they enjoyed about the experience, and classify it into different categories, you can use recodes to map the top two box response to a different value.

from survey import Survey
s = Survey(**globals())
s.net_promoter_score_question("On a scale of 1 to 5, how much do you like this product?",
    number_of_points=5,
    style="slider",
    labels={
        1: "Dislike",
        3: "Neutral",
        5: "Like"
    },
    recodes={
        "1": "dislike",
        "2": "dislike",
        "3": "neutral",
        "4": "like",
        "5": "like"})

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`number_of_points`	`int`	the number of points on the scale (default to 5 or the number of labels)	`11`
`first_point`	`int`	the first point on the scale (default to 1 or the first label)	`None`
`style`	`str`	the style of the scale, either "slider", "button", "star" or "card"	`'slider'`
`labels`	`Dict[int, str]`	a dictionary of labels (default {0:"Not at all likely", 10:"Extremely likely"})	`None`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`default`	`str`	the default value to use when generating test data.	`None`
`dont_know_option`	`str`	Optionally add a "Don't know" option to the question using this text.	`''`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`
`min_promoter_score`	`int`	minimum score need for promoter (default to 9)	`None`
`max_detractor_score`	`int`	minimum score need for detractor (default to 6)	`None`

Using the don't know option

Topics

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"])
for brand in car_brands:
    s.net_promoter_score_question(f"How do you rate {brand} cars?",
                        number_of_points=5,
                        style="slider",
                        labels={
                            1: "Dislike",
                            3: "Neutral",
                            5: "Like"
                        },
                        topic=brand)

Custom Errors

It is typically used for "gotcha" questions, where the user is asked to enter a specific value to ensure they are paying attention.

ranking_question

Add a ranking question to the survey.

This presents the user with a number of choices of which the user must rank in order of preference.

There are two available styles:

style="button" - For the button style, the user clicks on the buttons they want.
style="card" - For the card style, question are shown in card format.

Example usage:

from survey import Survey
s = Survey(**globals())
s.ranking_question("Rank the following car brands in order of preference",
                    options=["Ford", "Toyota", "Honda", "Tesla"],
                    labels=("Least", "Most"),

Default values: If no default value is specified, then the test data will consist of the options returned in a random order.

Recodes:

Recodes are used to map the response to a different value. This is useful for when you want to map a response to a different value. For example, if you want to ask a question about what they enjoyed about the experience, and ranks the different activities, you can use recodes to map the top two box response to a different value.

from survey import Survey
s = Survey(**globals())
s.ranking_question("Rank the following activities in order of preference",
                    options=["Eating", "Drinking", "Sleeping", "Working"],
                    labels=("Least", "Most"),
                    recodes={
                        "Eating": "eating",
                        "Drinking": "drinking",
                        "Sleeping": "sleeping",
                        "Working": "working"
                    })

Parameters:

Name	Type	Description	Default
`question`	`str`	the question to ask the consumer	required
`options`	`List[str]`	a list of strings or items from s.media containing the options	required
`min_options`	`int \| None`	Optional(int): the minimum number of options to be ranked, defaults to all options	`None`
`max_options`	`Optional(int`	the number of options to be ranked, defaults to all options	`None`
`style`	`str`	the style of the scale, either "button" or "card"	`'button'`
`labels`	`Tuple[str, str]`	a tuple of text labels for the least and most options	`('Least', 'Most')`
`randomize`	`bool`	whether to randomize the order of the options	`False`
`fixed_options`	`Optional[List[str]]`	a list of options that will not be randomized	`None`
`default`	`str`	the default value to use when generating test data.	`None`
`skip_empty`	`Optional[bool`	if set to True, the question will be skipped if there are no options	`False`
`recodes`	`Dict[str, str]`	a dictionary of recodes to use on this question. Generally less useful on text questions.	`None`
`dont_know_option`	`str`	Optionally add a "Don't know" option to the question using this text.	`''`
`custom_validator`	`Callable[[str], str \| None]`	a function to return a custom error message	`None`
`image_label_field`	`Optional[str]`	the field to use as the label for the image if using media items in the rows	`None`
`show_image_label`	`bool`	whether to show the image label or just to show the image in the rows	`True`
`image_size`	`Optional[Tuple[int, int]]`	the bounding box size of the images to display	`None`

Topics

Topics are applied to any format strings in the question text. For example, if you have a topic of "brand" and a question of "Rank the following {brand} cars in order of preference?", then respondents will see "Rank the following Ford cars in order of preference?"

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"])
brand_cars = {
    "Ford": ["Fiesta", "Focus", "Mustang", "F150"],
    "Toyota": ["Corolla", "Camry", "Prius", "RAV4"],
    "Honda": ["Civic", "Accord", "CR-V", "Pilot"],
    "Tesla": ["Model S", "Model 3", "Model X", "Model Y"]
}
for brand in car_brands:
    s.ranking_question(f"Rank the following {brand} cars in order of preference?",
                        options=brand_cars[brand],
                        labels=("Least", "Most"),
                        topic=brand)

Custom Errors

It is typically used for "gotcha" questions, where the user is asked to enter a specific value to ensure they are paying attention.

e.g. custom_validator=lambda x: "Are you sure you meant Sleepy Cows?" if "Sleepy Cows" in x else None

get_media_values

Gets all the values of the passed metadata column from the media collection.

This is useful if you want to get all the values of a column in the media collection and use them to create questions.

Example usage:

from survey import Survey
s = Survey(**globals())
car_brands = s.get_media_values("brand")
for car in s.media:
    s.select_question("What brand is this car?",
                            options=car_brands,
                            image=car)

Parameters:

Name	Type	Description	Default
`column`	`str`	the name of the column to get the values for.	required

get_image

Get the image with the specified values from the media collection.

Example usage:

from survey import Survey
s = Survey(**globals())
ford_image = s.get_image(brand="Ford")
s.image_question("What do you think of this Ford car?", image=ford_image)
s.complete()

get_video

Get the video with the specified values from the media collection.

Example usage:

from survey import Survey
s = Survey(**globals())
ford_video = s.get_video(brand="Ford")
s.play_video(video=ford_video)
s.complete()

get_images

Get the images with the specified values from the media collection.

Example usage:

from survey import Survey
s = Survey(**globals())
for image in s.get_images(brand="Ford"):
    s.image_question("What do you think of this Ford car?", image=image)
s.complete()

get_videos

Get the videos with the specified values from the media collection.

Example usage:

from survey import Survey
s = Survey(**globals())
for video in s.get_videos(brand="Ford"):
    s.play_video(video=video)
s.complete()

store_value

Stores a string or integer value in the survey.

Typically used to store a value calculated from a previous question.

Example usage:

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

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the value to store	required
`value`	`str`	the value to store	required

Topics

get_value

Get a previously stored value. Useful if you want to define survey logic based on values that you have previously stored.

Example usage:

from datetime import datetime
from survey import Survey
s = Survey(**globals())
birth_year = s.numeric_question("What year were you born in?",
                    min_max=(1920, 2020),
                    )
s.store_value("age", birth_year - datetime.now().year)
s.terminate_if(s.get_value("age") < 18, "Sorry this survey is for 18+ only.")

Parameters:

Name	Type	Description	Default
`name`	`str`	the name of the value to retrieve	required

random

Returns a random float between 0 and 1.

randomize

Randomizes a list of items.

Typically used when iterating over a list of items that you want to ask questions about.

Example usage:

from survey import Survey
s = Survey(**globals())
car_brands = s.randomize(["Ford", "Toyota", "Honda", "Tesla"])
for brand in s.randomize(car_brands):
    s.select_question(f"What do you think of {brand} cars?",
                            options=["Like", "Dislike"])

max_diff_question

Add a MaxDiff question to the survey.

This presents the user with a series of sets of items, and asks the user to select the most and least preferred items in each set.

The items are presented in a random order, and the user is asked to select the most and least preferred items in each set. The items are presented in a random order, and the user is asked to select the most and least preferred items in each set.

Example usage:

from survey import Survey
s = Survey(**globals())
car_brands = ["Ford", "Toyota", "Honda", "Tesla", "Chevrolet", "BMW", "Audi", "Mercedes"]
s.max_diff_question("Which of the following car brands do you prefer?",
                    items=car_brands,
                    labels=["Least", "Most"])

Portrait orientation

If you want to use portrait orientation, then the questions are asked multiple times, once for each label, and you must include a placholder for the labels in the question text. For example, if you have a question "Which of the following cars do you prefer?", and you want to use portrait orientation, then include a placeholder for the label in the question text, i.e., "Which of the following cars do you prefer the {label}?"

from survey import Survey
s = Survey(**globals())
car_brands = ["Ford", "Toyota", "Honda", "Tesla", "Chevrolet", "BMW", "Audi", "Mercedes"]
s.max_diff_question("Which of the following cars do you prefer the **{label}**?",
                    items=car_brands,
                    labels=["Least", "Most"])

Default values: If no default value is specified, then the test data will consist of random values chosen from the options.

Args:

question (str): the question to ask the consumer items (Union[List[str], List[List[str]]): a list of strings containing the items to rank, or a list of the sets of items to rank labels (List[str]): the two labels to use for the most and least preferred items image (MediaItem): An option image to show the user, from the s.media collection recodes (Dict[str, str]): a dictionary of recodes to use on this question. randomize (bool): if set to True, the order of the items will be randomized custom_validator (Callable[[str], str | None]): a function to return a custom error message

Topics

Topics are applied to any format strings in the question text. For example, if you have a topic of "brand" and a question of "Which of the following {brand} cars do you prefer?", then respondents will see "Which of the following Ford cars do you prefer?"

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"])
for brand in car_brands:
    s.max_diff_question(f"Which of the following {brand} cars do you prefer?",
                        items=brand_cars[brand],
                        labels=["Least", "Most"],
                        brand=brand)

Custom Errors

It is typically used for "gotcha" questions, where the user is asked to enter a specific value to ensure they are paying attention.

e.g. custom_validator=lambda x: "Are you sure you meant Sleepy Cows?" if "Sleepy Cows" in x else None

count_validation_errors

Returns the number of validation errors in the survey, or for a specific question.

Parameters:

Name	Type	Description	Default
`question`	`Optional[str]`	if passed, only counts errors for this question.	`None`

authenticate_by_phone_number

Authenticate the respondent by phone number.

This function asks the respondent to enter their phone number and sends a code to that number. The respondent must then enter the code to authenticate.

Example usage:

from survey import Survey
s = Survey(**globals())
s.authenticate_by_phone_number("This is a high security survey, please enter your phone number" +
                               "to continue, and we will send you a verification code.")

Parameters:

Name	Type	Description	Default
`question_1`	`str`	the question to ask the consumer to enter their phone number	required
`question_2`	`str`	the question to ask the consumer to enter the code	`'Please enter the code we sent you.'`
`termination_message`	`str`	the message to show the user if the code is incorrect	`'Sorry, the code you entered was incorrect'`
`store_phone_number`	`bool`	if set to True, the phone number will be stored in the survey data	`False`
`image`	`MediaItem`	An option image to show the user, from the s.media collection	`None`
`default_country`	`str`	the default country code to use for the phone number	`'US'`

call_api

Calls an external API. This is only available to call out to pre-approved domains.

:param url: The URL of the request. :param method: HTTP method ("GET" or "POST"). :param data: Data to send for POST requests. :param params: Query parameters for GET requests. :param headers: HTTP headers for the request. :param timeout: Request timeout in seconds. :return: Response object from the HTTP request. :raises ValueError: If the URL domain is not allowed.

Question Type: text_question

Question Type: multi_select_question

Question Type: grid_multi_select_question

Question Type: grid_rating_question

Question Type: ranking_question