Documentation

Least Fill

For the design rationale, the algorithm, and how this technique is also used inside conjoint_question and MaxDiff, see Least-fill balancing methodology.

When and Why to Use

Use this to dynamically select a subset of items that have the fewest responses (i.e. are underrepresented) in a given quota. Ideal for:

Ensuring even coverage across a large set of items (e.g., brands, ads, concepts)
Avoiding over-exposure or over-sampling of frequently selected items
Dynamically balancing stimulus presentation

This does not enforce quotas or terminate users. It simply ranks items by current counts and returns the least-filled ones.

How It Works

Takes a list of items
Checks which ones are least filled in the named quota
Returns the top N least-filled items
Often paired with multi_select_question or select_question

Configuration Options

Parameter	Type	Required	Description
`number`	`int`	yes	Number of items to return
`from_list`	`List[Any]`	yes	Full list of items to choose from
`quota`	`str`	yes	Name for the counter that tracks per-item assignments. Created on first use — you don't need to set it up separately.

Example Code

python
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'
    # ...and so on
]

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
)

Notes

This is often used for rotating large brand or product lists evenly
Use set_quota() if you want to enforce a fixed distribution with termination
The counter named by quota is created the first time get_least_filled is called with that name — you do not need to set it up beforehand. Two calls that share the same quota name share the same counter; calls with different names track independently.