mode — Return most frequent values in MATLAB and RunMat.
mode(A) returns the most frequent value along a dimension. Tie-breaking, frequency outputs, and optional tied-value cell outputs follow MATLAB semantics.
Syntax
M = mode(X)
M = mode(X, dim_or_all)
[M, F] = mode(X)
[M, F] = mode(X, dim_or_all)
[M, F, C] = mode(X)
[M, F, C] = mode(X, dim_or_all)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input data array. |
dim_or_all | Any | Yes | — | Reduction axis (positive integer) or 'all'. |
Returns
| Name | Type | Description |
|---|---|---|
M | Any | Most frequent value along the selected dimension. |
F | NumericArray | Frequency counts for each reported mode. |
C | Any | Cell array containing all tied modal values per slice. |
Returned values from mode depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:mode:InvalidArgument | Arguments are malformed, duplicated, or unrecognised. | mode: invalid argument |
RunMat:mode:InvalidDimension | Dimension argument is zero or negative. | mode: dimension must be >= 1 |
RunMat:mode:GpuUnsupported | Input is GPU-resident and mode requires host data. | mode: GPU tensors must be gathered to the host before mode can be computed |
RunMat:mode:ComplexUnsupported | Input data is complex-valued. | mode: complex inputs are not supported; gather real data first |
RunMat:mode:Internal | Internal conversion/allocation/shape handling fails. | mode: internal operation failed |
How mode works
mode(A)reduces along the first non-singleton dimension ofA.mode(A, dim)reduces along the specified dimension (1-based,>= 1).mode(A, 'all')collapses every element ofAinto a single scalar mode.[M, F, C] = mode(A, ...)additionally returns the frequencyFof the mode (as a double) and a cell arrayCof sorted tied values per slice.- Ties resolve to the smallest tied value in
M, whileCcontains the full tied set sorted in ascending order. - NaN entries are ignored. If a slice is entirely
NaN(or empty), the correspondingMvalue isNaN,Fis0, and the cell entry is an empty0 × 1column. - Logical, integer, and boolean inputs are promoted to double precision before counting frequencies.
- Dimensions larger than
ndims(A)treat the input as having trailing singleton dimensions, so each slice contains a single element.
Examples
Mode of a vector with a clear majority
x = [1 2 2 3 3 3 4];
m = mode(x)Expected output:
m = 3Ties return the smallest value with the full sorted set
x = [1 1 2 2];
[m, f, c] = mode(x)Expected output:
m = 1
f = 2
c = {[1; 2]}Column-wise mode of a matrix
A = [1 2 1; 2 2 3; 2 4 3];
m = mode(A)Expected output:
m = [2 2 3]Mode along the second dimension
A = [1 2 1; 2 2 3; 2 4 3];
m = mode(A, 2)Expected output:
m = [1; 2; 2]Mode across every element
A = [1 2 3; 2 3 2];
m = mode(A, 'all')Expected output:
m = 2NaN values are ignored unless every element is NaN
x = [1 NaN 2 2 NaN];
[m, f] = mode(x)Expected output:
m = 2
f = 2Using mode with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how mode changes the result.
Run a small mode example, explain the result, then change one input and compare the output.
FAQ
How are ties resolved?⌄
M returns the smallest value among the tied set. The third output C contains every tied value sorted in ascending order as a column vector.
What happens with NaN values?⌄
NaN entries are skipped while counting frequencies. If a slice is entirely NaN, RunMat returns NaN for the mode, 0 for the frequency, and an empty 0 × 1 column in the cell array.
Does mode support logical or integer inputs?⌄
Yes. Logical and integer arrays are promoted to double precision before counting, matching MATLAB.
Can I reduce across all elements of an array?⌄
Use mode(A, 'all') to collapse every element of A into a single scalar.
Does mode execute on the GPU?⌄
Not today. GPU tensors are gathered to the host so the result remains bit-for-bit MATLAB compatible; future providers may expose dedicated mode kernels.
Related Stats functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how mode is executed, line by line, in Rust.
- View the source for mode 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.