groupsummary — Compute summary statistics by group for table or array data.
groupsummary groups table rows or array observations and computes per-group statistics. Table input returns a table; array input returns the concatenated summary array and can additionally return grouping vectors and counts.
Syntax
G = groupsummary(T, groupvars, method, datavars)
G = groupsummary(T, groupvars, groupbins, method, datavars)
B = groupsummary(A, groupvars, method)
[B, BG, BC] = groupsummary(A, groupvars, groupbins, method)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
T | Any | Yes | — | Input table. |
groupvars | Any | Yes | — | Grouping variable name or names. |
method | Any | Yes | — | Summary method name or names. |
datavars | Any | No | — | Data variable name or names. |
groupbins | Any | Yes | — | Grouping bin specification. |
datavars | Any | No | — | Data variable name or names, optionally followed by name-value pairs. |
A | Any | Yes | — | Numeric array or cell array of numeric arrays. |
groupvars | Any | Yes | — | Grouping array or cell array of grouping arrays. |
nameValuePairs | Any | Variadic | — | Grouping options such as IncludedEdge and IncludeEmptyGroups. |
Returns
| Name | Type | Description |
|---|---|---|
out | Any | Result value. |
B | Any | Summary values. |
BG | Any | Grouping values. |
BC | NumericArray | Group counts. |
Returned values from groupsummary depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:table:InvalidArgument | Arguments or table metadata are invalid. | table: invalid argument |
RunMat:table:InvalidIndex | Table indexing is invalid. | table: invalid index |
RunMat:table:InvalidVariable | A table variable name or value is invalid. | table: invalid variable |
RunMat:readtable:IOError | readtable cannot open or read the requested file. | readtable: file read failed |
RunMat:readtable:UnsupportedFileType | readtable receives a file type outside the text or spreadsheet import backends. | readtable: unsupported file type |
How groupsummary works
- Table forms support grouping-variable selectors, selected data variables, and the implemented mean, sum, median, min, max, count, and numel methods.
- Array forms support numeric vectors, matrices, and cell arrays of numeric arrays. Matrix columns become independent data or grouping columns, and
[B,BG,BC]returns summaries, exact group values, and double counts. - All eight integer classes are supported as documented grouping and numeric data. Group comparison, integer extrema, and array/table output reconstruction use authoritative typed storage, including distinct uint64 values above flintmax.
- Floating summary methods deliberately enter a checked binary64 computation boundary. Wide integer values that cannot be represented exactly reject instead of silently merging or rounding.
- The one-group numeric-edge and positive-bin-count forms support IncludedEdge, IncludeEmptyGroups, and IncludeMissingGroups, with exact integer comparisons. Multi-group bin specifications and time bins are not currently supported.
- Native typed-integer bin counts and boolean controls are independently gated RunMat extensions; equivalent scalar-double and logical controls remain available in MATLAB-compatible mode.
- Additional named methods, function-handle methods, and some table selector forms are not currently supported.
Examples
Summarize an array and return groups
[B,BG,BC] = groupsummary([10;20;30],[1;1;2],'mean')Expected output:
B = [15;30], BG = [1;2], and BC = [2;1].Preserve wide integer groups
base=uint64(9007199254740992); [B,BG]=groupsummary([base+3;base+1;base+4],[base;base+1;base],'max')Expected output:
B and BG remain uint64 and preserve adjacent values above flintmax.Using groupsummary with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how groupsummary changes the result.
Run a small groupsummary example, explain the result, then change one input and compare the output.
Related Table functions
array2table · array2timetable · categorical · cell2table · dictionary · head · height · iscategorical · isordinal · istable · istimetable · ordinal · pivot · rowfilter · struct2table · table · table2array · table2cell · table2struct · table2timetable · timerange · timetable · timetable2table · uitable · vartype · width
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how groupsummary is executed, line by line, in Rust.
- View the source for groupsummary in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.