Quotas

When and Why to Use

Use these together to enforce quota sampling in your survey. This helps control the composition of your sample by limiting how many respondents fall into each defined segment.

quota() defines a single quota line based on a condition
set_quota() groups multiple quota lines and, by default, assigns each respondent to exactly one of them (pass exclusive=False to allow multiple)

If a respondent does not match any defined quota or enters an over-quota group, they are terminated.

For the concepts behind quota enforcement (fielding strategies, interlocked vs. marginal design, click balancing, and how weighting corrects residual imbalance), see the Quota management methodology page. For surveys with more than one quota group, see Combining multiple quota groups.

How It Works

Each quota() defines a named condition and a target proportion (as a float from 0 to 1)
set_quota() applies all defined quotas under a group name
Conditions can use any previous question responses
Respondents are checked live and quotas are updated in real-time

Configuration Options

`quota(name, criteria, quota, min_respondents, max_respondents)`

Parameter	Type	Required	Description
`name`	`str`	yes	Name of the quota line, used in reporting
`criteria`	`bool`	yes	Boolean expression that defines membership in this quota
`quota`	`float`	no	Target proportion for this line (e.g., 0.25 for 25%)
min_respondents	int	no	Minimum number of respondents to fill for this line. Takes precedence over the proportional target when higher.
max_respondents	int	no	Maximum number of respondents assigned to this line. Omit for no explicit cap.

`set_quota(name, quotas, exclusive=True)`

Parameter	Type	Required	Description
`name`	`str`	yes	Name of the overall quota group
`quotas`	`List[Quota]`	yes	List of quota lines created using `quota()`
`exclusive`	`bool`	no	Whether each respondent fills only one matching quota line. Defaults to `True`. Set to `False` to let a respondent count toward every line they match.

Example Code

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"]
)

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)
    ]
)

Notes

By default quotas are exclusive: each respondent fills exactly one matching quota line. Set exclusive=False on set_quota() to let a respondent count toward every line they match
If all quotas are filled or a respondent does not meet any quota, they are terminated
You can use any boolean logic in the criteria to create flexible conditions
Weighted quota proportions must sum to 1.0 (within ±0.5%) across the group. Boost-only lines that set min_respondents without a quota value are exempt; a group made up entirely of boost lines sums to 0 and is not weighted