grpstats — Compute summary statistics organized by group.
grpstats(X,group) computes grouped summary statistics for numeric or logical matrices. grpstats(T,groupvars,...) returns a table containing grouping variables, group counts, and requested summary columns.
Syntax
tblstats = grpstats(tbl, groupvars)
stats = grpstats(X, group)
[stats1, ..., statsN] = grpstats(X, group, whichstats)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input matrix or table. |
group | Any | Yes | — | Grouping variables, variable selectors, or empty grouping. |
whichstats | Any | No | "mean" | Summary statistic name or names. |
nameValuePairs | Any | Variadic | — | Alpha, DataVars, and VarNames options. |
Returns
| Name | Type | Description |
|---|---|---|
out | Any | Result value. |
Returned values from grpstats 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 grpstats works
- For matrix input,
groupcan be numeric, logical, string, char, categorical, or cell text data. A cell array of grouping variables such as{G1,G2}creates groups from observed value combinations. Empty grouping such as[]computes one all-row group. - For matrix input,
whichstatsaccepts"mean","sem","std","var","min","max","range","meanci","predci","numel", and"gname". Multiple requested statistics return one output per statistic when multiple outputs are requested. meanciandpredcireturnngroups x ncols x 2tensors and honor the"Alpha"option. Intervals use Student's t critical values.- Rows with missing group labels are ignored. NaN values in data variables are omitted from numeric summaries.
- For table input,
groupvarsaccepts table variable selectors or[]for no grouping. Output tables include group variables,GroupCount, and one variable for each data variable/statistic combination. Interval statistics are stored as two-column table variables. - For table input,
"DataVars"selects numeric or logical data variables and"VarNames"replaces the output variable names. Built-in function handles such as@meanand@stdare accepted when they map to supported statistic names; custom function handles are rejected explicitly because general MATLAB function-handle dispatch is not yet implemented forgrpstats.
Examples
Compute group means for a matrix
X = [1 10; 3 30; 2 20; 4 40];
g = [2; 1; 2; 1];
m = grpstats(X,g)Expected output:
m is [3.5 35; 1.5 15] for groups 1 and 2.Return multiple matrix statistics and group names
[m,s,names] = grpstats(X,g,["mean","std","gname"])Expected output:
`m` and `s` are numeric arrays; `names` is a cell array of group labels.Summarize a table with selected data variables
T = table(G,X,Y);
S = grpstats(T,"G",["mean","max"],"DataVars","X")Expected output:
`S` contains `G`, `GroupCount`, `mean_X`, and `max_X`.Using grpstats with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how grpstats changes the result.
Run a small grpstats example, explain the result, then change one input and compare the output.
FAQ
Does grpstats support function handles?⌄
RunMat accepts built-in function handles whose names match supported statistics, such as @mean and @std. Custom function handles are not yet supported.
How are groups ordered?⌄
Numeric and logical groups sort by value. Text groups preserve first-seen order, matching MATLAB's character and string grouping behavior.
Related Stats functions
Summary
binocdf · boxplot · cdf · cdfplot · chi2cdf · corr · corrcoef · corrcov · cov · cov2corr · dummyvar · ecdf · filloutliers · fitdist · geomean · harmmean · icdf · isoutlier · kstest · kurtosis · lsline · mad · mode · nanmax · normalize · normcdf · norminv · normpdf · onehotdecode · onehotencode · pdf · prctile · quantile · refline · rmse · skewness · tabulate · tcdf · tiedrank · tinv · tpdf · ttest2 · wblinv
Ml
bayesopt · classify · confusionmat · crossvalind · cvpartition · fitclinear · fitctree · fitlm · kmeans · knnsearch · lasso · lassoglm · linkage · lscov · mnrfit · optimizableVariable · pdist · pdist2 · perfcurve · predict · regress · ridge · squareform · test · training · tsne
Random
binornd · bootstrp · datasample · dividerand · exprnd · gamrnd · lhsdesign · mvnrnd · normrnd · random · randsample · rng · trnd · unidrnd · unifrnd · wblrnd
Hist
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how grpstats is executed, line by line, in Rust.
- View the source for grpstats 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.