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)