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.
Portrait Experience
• Each row is presented with numeric input fields for each column
• Users enter numbers directly
Landscape Experience
• Full grid visible with scrollable columns if needed
• Easier comparison across multiple categories
• Autosums are disabled in selected
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 |
**topics | dict | 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)