scipy.stats.mode#

scipy.stats.mode(a, axis=0, nan_policy='propagate', keepdims=None)[source]#

Return an array of the modal (most common) value in the passed array.

If there is more than one such value, only one is returned. The bin-count for the modal bins is also returned.

Parameters:
aarray_like

n-dimensional array of which to find mode(s).

axisint or None, optional

Axis along which to operate. Default is 0. If None, compute over the whole array a.

nan_policy{‘propagate’, ‘raise’, ‘omit’}, optional

Defines how to handle when input contains nan. The following options are available (default is ‘propagate’):

  • ‘propagate’: treats nan as it would treat any other value

  • ‘raise’: throws an error

  • ‘omit’: performs the calculations ignoring nan values

keepdimsbool, optional

If set to False, the axis over which the statistic is taken is consumed (eliminated from the output array) like other reduction functions (e.g. skew, kurtosis). If set to True, the axis is retained with size one, and the result will broadcast correctly against the input array. The default, None, is undefined legacy behavior retained for backward compatibility.

Warning

Unlike other reduction functions (e.g. skew, kurtosis), the default behavior of mode usually retains the axis it acts along. In SciPy 1.11.0, this behavior will change: the default value of keepdims will become False, the axis over which the statistic is taken will be eliminated, and the value None will no longer be accepted.

New in version 1.9.0.

Returns:
modendarray

Array of modal values.

countndarray

Array of counts for each mode.

Notes

The mode of object arrays is calculated using collections.Counter, which treats NaNs with different binary representations as distinct.

Deprecated since version 1.9.0: Support for non-numeric arrays has been deprecated as of SciPy 1.9.0 and will be removed in 1.11.0. pandas.DataFrame.mode can be used instead.

The mode of arrays with other dtypes is calculated using numpy.unique. In NumPy versions 1.21 and after, all NaNs - even those with different binary representations - are treated as equivalent and counted as separate instances of the same value.

Examples

>>> import numpy as np
>>> a = np.array([[3, 0, 3, 7],
...               [3, 2, 6, 2],
...               [1, 7, 2, 8],
...               [3, 0, 6, 1],
...               [3, 2, 5, 5]])
>>> from scipy import stats
>>> stats.mode(a, keepdims=True)
ModeResult(mode=array([[3, 0, 6, 1]]), count=array([[4, 2, 2, 1]]))

To get mode of whole array, specify axis=None:

>>> stats.mode(a, axis=None, keepdims=True)
ModeResult(mode=[3], count=[5])
>>> stats.mode(a, axis=None, keepdims=False)
ModeResult(mode=3, count=5)