mode — Find the most frequent values, their frequencies, and ties.
mode(A) counts values along the first nonsingleton dimension. Ties return the smallest value in M; requesting three outputs also returns the sorted tied set for each slice in cell array C.
Syntax
M = mode(X)
M = mode(X, dim_or_vecdim_or_all)
[M, F] = mode(X)
[M, F] = mode(X, dim_or_vecdim_or_all)
[M, F, C] = mode(X)
[M, F, C] = mode(X, dim_or_vecdim_or_all)Inputs
X- Type
Any- Required
- Yes
- Description
- Input data array.
dim_or_vecdim_or_all- Type
Any- Required
- Yes
- Description
- Reduction axis, vector of axes, or 'all'.
Returns
M- Type
Any- Description
- Most frequent value along the selected dimension.
F- Type
NumericArray- Description
- Frequency counts for each reported mode.
C- Type
Any- Description
- Cell array containing all tied modal values per slice.
Returned values from mode depend on how many outputs the caller requests.
Errors
RunMat:mode:InvalidArgument- When
- Arguments are malformed, duplicated, or unrecognised.
- Message
mode: invalid argument
RunMat:mode:InvalidDimension- When
- Dimension argument is zero or negative.
- Message
mode: dimension must be >= 1
RunMat:mode:ComplexUnsupported- When
- Input data is complex-valued.
- Message
mode: complex inputs are not supported; gather real data first
RunMat:mode:Internal- When
- Internal conversion/allocation/shape handling fails.
- Message
mode: internal operation failed
Outputs and ties
Use M = mode(A) for modal values, [M,F] = mode(A) for double frequency counts, and [M,F,C] = mode(A) for all tied values as sorted column vectors in a cell array. Ties in M select the smallest tied value.
NaN observations are ignored. An all-NaN or empty reduced slice produces NaN in M, zero in F, and an empty 0-by-1 tied column in C.
Real single, double, logical, and typed-integer data are supported. For nonempty integer or logical slices, modal values and tied values retain the input class, including exact wide integers; frequency counts are double. An empty reduced slice requires double NaN output.
Dimensions
mode(A,dim) reduces one 1-based dimension, mode(A,vecdim) reduces several dimensions, and mode(A,"all") reduces all elements. A dimension beyond the input rank is a singleton selection and returns each value as its own mode.
Resident inputs
The current implementation gathers GPU input through its owning provider, computes frequencies and ties on the host, and uploads requested numeric outputs and tied-value cell contents back through that same provider when supported. Complex GPU input is gathered and then rejected by the same complex-input diagnostic as host input. This is a materialization boundary, not a provider-resident mode kernel.
A provider-side mode operation is declared, but the current runtime does not route through it. Provider support and a validated runtime route are required before claiming resident sorting/counting.
Examples
Mode of a vector with a majority
x = [1 2 2 3 3 3 4]; m = mode(x); disp(m);Expected output:
3Inspect tied modal values
x = [1 1 2 2]; [m,f,c] = mode(x); disp(m); disp(f); disp(c{1});Expected output:
m = 1; f = 2; c{1} = [1; 2]Column-wise mode
A = [1 2 1; 2 2 3; 2 4 3]; m = mode(A); disp(m);Expected output:
[2 2 3]Mode along the second dimension
A = [1 2 1; 2 2 3; 2 4 3]; m = mode(A, 2); disp(m);Expected output:
[1; 2; 2]Mode over all elements
A = [1 2 3; 2 3 2]; m = mode(A, "all"); disp(m);Expected output:
2Ignore NaNs while counting
x = [1 NaN 2 2 NaN]; [m,f] = mode(x); disp(m); disp(f);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 tied value; C contains all tied values as a sorted column for each slice.
What happens with NaN values?⌄
NaNs are skipped. An all-NaN slice returns NaN, frequency zero, and an empty tied-value column.
Are logical and integer inputs supported?⌄
Yes. For nonempty slices, modal and tied values preserve logical or exact integer class; frequencies are double.
Can I reduce all elements?⌄
Use mode(A,"all").
Does mode execute on the GPU?⌄
Not yet. Resident input is gathered for host counting, then supported requested outputs are uploaded to the source provider.
Related Stats functions
Summary
anova1 · binocdf · binscatter · boxplot · cdf · cdfplot · chi2cdf · corr · corrcoef · corrcov · cov · cov2corr · dummyvar · ecdf · filloutliers · fitdist · geomean · grpstats · harmmean · icdf · isoutlier · ksdensity · kstest · kurtosis · lsline · mad · nanmax · normalize · normcdf · norminv · normpdf · onehotdecode · onehotencode · pca · pdf · prctile · qqplot · quantile · refline · rmse · scatterhist · skewness · tabulate · tcdf · tiedrank · tinv · tpdf · ttest · ttest2 · wblinv
Ml
bayesopt · classify · confusionmat · crossvalind · cvpartition · fitclinear · fitctree · fitlm · kmeans · knnsearch · lasso · lassoglm · linkage · lscov · mnrfit · nlparci · optimizableVariable · pdist · pdist2 · perfcurve · predict · regress · ridge · squareform · test · training · tsne
Random
binornd · bootstrp · datasample · dividerand · exprnd · gamrnd · gpurng · lhsdesign · mvnrnd · normrnd · random · randsample · rng · trnd · unidrnd · unifrnd · wblrnd
Hist
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.