findgroups — Assign sorted group numbers while preserving exact grouping identifiers.
G = findgroups(A) assigns one-based double group numbers in sorted unique-key order. Numeric grouping includes all eight integer classes, whose values are compared exactly. Missing strings, empty character vectors, NaN, NaT, and undefined categorical values produce NaN in G.
Syntax
varargout = groupingBuiltin(args...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
args | Any | Variadic | — | MATLAB-compatible arguments. |
Returns
| Name | Type | Description |
|---|---|---|
varargout | Any | Builtin outputs. |
Returned values from findgroups depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:grouping:InvalidInput | Inputs are malformed, have incompatible lengths, or request unsupported grouped output. | grouping builtin: invalid input |
RunMat:grouping:CallbackFailed | A grouped callback fails or returns incompatible outputs. | grouping builtin: callback failed |
RunMat:grouping:TooLarge | The requested dense or combinatorial output exceeds RunMat's materialization limit. | grouping builtin: output is too large |
How findgroups works
- A must be a scalar or vector. G has the same size and row-or-column orientation as A.
findgroups(A1,...,AN)groups sorted unique tuples. Every input vector must have the same size, and a missing value in any role makes the corresponding G element NaN.[G,ID] = findgroups(A)returns sorted unique identifiers in A's class. Integer IDs preserve authoritative values above flintmax.[G,ID1,...,IDN] = findgroups(A1,...,AN)preserves each identifier output's corresponding input class.[G,TID] = findgroups(T)groups all supported table variables and preserves their names and classes in TID.- Supported grouping variables are numeric, logical, string, cell arrays of character vectors, categorical, datetime, duration, and calendarDuration. Sparse and complex grouping variables reject explicitly.
- Matrix-as-columns grouping,
findgroups(T,selector), timetable input, and resident input are independent gated RunMat extensions. The table selector form accepts exactly one selector and never ignores trailing arguments.
Examples
Group strings
G = findgroups(["b";"a";"b"])Expected output:
G = [2; 1; 2]Group exact integers
A = uint64([9007199254740992 9007199254740993 9007199254740992]);
[G,ID] = findgroups(A)Expected output:
G = [1 2 1]
ID = uint64([9007199254740992 9007199254740993])Using findgroups with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how findgroups changes the result.
Run a small findgroups example, explain the result, then change one input and compare the output.
FAQ
Are group numbers integer-typed?⌄
No. G contains positive integer-valued doubles and NaN for missing rows. Integer grouping identifiers retain their integer class in ID or TID.
Are integer values converted to double for grouping?⌄
No. RunMat compares authoritative signed or unsigned integer values directly, including values above flintmax.
Can I pass a matrix as A?⌄
MATLAB documents grouping vectors. RunMat can interpret matrix columns as grouping roles only when the matrix-as-columns extension is enabled.
Can findgroups consume GPU-resident data?⌄
Only in RunMat extension mode. The gate is checked recursively before any resident input or table variable is gathered.
Does findgroups accept timetables?⌄
Timetable input is a separate RunMat extension. Its identifier output is currently an ordinary table of selected variable values; row times are not grouping variables.
Related Array functions
Grouping
accumarray · combinations · discretize · groupcounts · grp2idx · splitapply
Sorting Sets
argsort · intersect · ismember · ismembertol · issorted · issortedrows · setdiff · setxor · sort · sortrows · union · unique
Shape
blkdiag · cat · circshift · diag · flip · fliplr · flipud · horzcat · ipermute · kron · permute · repelem · repmat · reshape · rot90 · squeeze · toeplitz · tril · triu · vertcat
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how findgroups is executed, line by line, in Rust.
- View the source for findgroups 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.