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)

Whether a respondent is screened out depends on the fielding strategy. Strict requires an open matching line in every quota group encountered; quota driven and respondent driven require one in at least one group. A line reaching its completion target does not necessarily stop accepting respondents. See Fielding strategies.

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 against recorded completion counts; reporting updates can lag completions

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	Positive completion target for this line, replacing the percentage-derived target even when lower. Omit or use `0` to use the quota proportion times the survey's target respondents, truncated to a whole number.
`max_respondents`	`int`	no	Optional assignment limit under strict and quota-driven fielding. Under strict, this replaces the completion target as the admission limit. Respondent-driven fielding does not enforce it.

`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, open quota line. Defaults to `True`. Set to `False` to count a respondent toward every matching line that is open under the selected strategy.

Example Code

python
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 one matching, open line, chosen by the lowest ratio of completes to completion target. Set exclusive=False to count toward every matching, open line
Screening and survey completion follow the selected fielding strategy, not simply whether one line is full
You can use any boolean logic in the criteria to create flexible conditions
A group with only minimums and no quota proportions is not used for weighting. Its criteria still participate in quota qualification under the selected fielding strategy
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