def mode(array, n=1):
"""
Return top-n most common values and number of times they occur in a passed
numerical (chunked) array, in descending order of occurance. If there are
more than one values with same count, smaller one is returned first.
Parameters
----------
array : pyarrow.Array or pyarrow.ChunkedArray
Returns
-------
An array of <input type "Mode", int64_t "Count"> structs
Examples
--------
>>> import pyarrow as pa
>>> import pyarrow.compute as pc
>>> arr = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
>>> modes = pc.mode(arr, 2)
>>> modes[0]
<pyarrow.StructScalar: {'mode': 2, 'count': 5}>
>>> modes[1]
<pyarrow.StructScalar: {'mode': 1, 'count': 2}>
"""
options = ModeOptions(n=n)
return call_function("mode", [array], options)
def mode(array, n=1, *, skip_nulls=True, min_count=0):
"""
Return top-n most common values and number of times they occur in a passed
numerical (chunked) array, in descending order of occurrence. If there are
multiple values with same count, the smaller one is returned first.
Parameters
----------
array : pyarrow.Array or pyarrow.ChunkedArray
n : int, default 1
Specify the top-n values.
skip_nulls : bool, default True
If True, ignore nulls in the input. Else return an empty array
if any input is null.
min_count : int, default 0
If there are fewer than this many values in the input, return
an empty array.
Returns
-------
An array of <input type "Mode", int64_t "Count"> structs
Examples
--------
>>> import pyarrow as pa
>>> import pyarrow.compute as pc
>>> arr = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
>>> modes = pc.mode(arr, 2)
>>> modes[0]
<pyarrow.StructScalar: {'mode': 2, 'count': 5}>
>>> modes[1]
<pyarrow.StructScalar: {'mode': 1, 'count': 2}>
"""
options = ModeOptions(n, skip_nulls=skip_nulls, min_count=min_count)
return call_function("mode", [array], options)
