When and Why to Use

Use this to capture numeric input across a grid of rows and columns. Best for:

• Time allocation or quantity distribution
• Budget breakdowns
• Structured numeric input across categories

Supports autosumming, recoding, and custom validation.

Chat Style

• Each row is presented with numeric input fields for each column
• Users enter numbers directly

Traditional Style

• Full grid visible with scrollable columns if needed
• Easier comparison across multiple categories
• Autosums are enabled

Chat style	Traditional with images	Mobile optimized

Configuration Options

Option	Type	Required	Default	Description
question	string	yes	-	The prompt shown to the user
rows	`List[str	MediaItem]`	yes	-
row_name	string	yes	-	Reporting label for rows
columns	List[str]	no	-	Column labels
column_name	string	no	-	Reporting label for columns
image	MediaItem	no	-	Top-level image
min_max	Tuple[int, int]	no	(1, 100)	Range of acceptable numeric values
randomize	bool	no	False	Randomize row order
randomize_columns	bool	no	False	Randomize column order
recodes	Dict[str, str]	no	-	Optional recoding logic
default	`Dict[str, int	Dict[str, int]]`	no	random
autosum_columns	bool	no	False	Automatically sum across rows for each column
autosum_rows	bool	no	False	Automatically sum across columns for each row
custom_validator	`Callable[[Dict[str, Any]], str	None]`	no	-
image_label_field	str	no	-	Used to label media row items
show_image_label	bool	no	True	Show/hide labels for row images
image_size	Tuple[int, int]	no	-	Bounding box for images
tags	s.tag()	no	-	Token substitution and reporting group

Example Code

Basic usage:

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

With recodes and autosum:

s.grid_numeric_question(
    "Distribute your budget across categories",
    row_name="Category",
    rows=["Food", "Housing", "Entertainment"],
    columns=["January", "February", "March"],
    recodes={
        "0-30%": "Low",
        "31-70%": "Medium",
        "71-100%": "High"
    },
    autosum_rows=True
)

With custom validation:

s.grid_numeric_question(
    "How many units of each product did you sell?",
    row_name="Product",
    rows=["Item A", "Item B"],
    columns=["Online", "In-store"],
    custom_validator=lambda d: "Please don't enter the same number for every cell"
        if len(set([v for r in d.values() for v in (r if isinstance(r, dict) else [r])])) == 1
        else None
)

Notes

• Use autosum_columns or autosum_rows to show real-time totals
• Recodes are especially helpful for analysis of numeric ranges
• Validator helps detect lazy input (e.g. straight-lining)