When & Why to Use
Call standard_screener() when you need a ready-made demographic screener that:
- Adds the core demo questions (age, gender, region, etc.) in the right order
- Weights the data to national averages for the chosen country, where the selected screener supports weighting
- Closes quotas automatically once the targets are met
Use it to jump-start GenPop surveys or any study that just needs a quick, balanced sample without hand-building the screener every time.
Supported Screeners
Standard screeners are available only for supported country and screener-name combinations:
| Country code | Available templates | Typical use-case |
|---|---|---|
| US | GenPop, NestedGenPop | General population or nested quotas |
| GB | GenPop, 16to54 | UK GenPop or younger audience |
| AU | GenPop | Australian general population |
Need something else? Register a new template in SCREENER_REGISTRY and it becomes instantly callable.
Function Signature
standard_screener(country: str | None = None, name: str = "GenPop", id: str | None = None) -> None
| Arg | Type | Required | Default | Description |
|---|---|---|---|---|
| country | str | None | ✗ | None | ISO-style code used by MX8 Labs ("US", "GB", "AU", ...) |
| name | str | ✗ | "GenPop" | Template name listed in Supported Screeners |
| id | str | None | ✗ | None | Optional stable identifier prefix for the generated screener questions; if not set, each question's text is used |
What Happens Under the Hood
- Looks up the template in SCREENER_REGISTRY.
- Injects the questions into the current survey (self).
- Applies built-in quota weights so fieldwork stays on-target.
No return value; the survey object is modified in place.
Example Code
# US general population survey
s.standard_screener("US")
# UK younger audience, ages 16-54
s.standard_screener("GB", "16to54")
# Nested quotas in a US screener
s.standard_screener(country="US", name="NestedGenPop")
# Stable identifier prefix for the generated screener questions
s.standard_screener(country="US", id="screener")
Notes & Tips
- Chainable - call other survey builders before or after; order doesn't matter.
- Extensible - create custom screeners by adding lambdas to SCREENER_REGISTRY.
- Idempotent - calling the same screener twice only adds one set of questions.
- Compliance - questions are locally adapted (e.g., ethnicity lists) to each market.
That's it. One line, instant screener weighted to national averages.