mirror of
https://github.com/apache/arrow.git
synced 2026-10-29 00:56:31 +08:00
Ruifeng Zheng
bf8d1754c9
### Rationale for this change To improve python documentation ### What changes are included in this PR? Add code examples for compute function first/last/first_last ### Are these changes tested? Yes, doc-test ### Are there any user-facing changes? Yes, doc-only changes * GitHub Issue: #49269 Authored-by: Ruifeng Zheng <ruifengz@apache.org> Signed-off-by: AlenkaF <frim.alenka@gmail.com>
258 lines
7.8 KiB
Python
258 lines
7.8 KiB
Python
# Licensed to the Apache Software Foundation (ASF) under one
|
|
# or more contributor license agreements. See the NOTICE file
|
|
# distributed with this work for additional information
|
|
# regarding copyright ownership. The ASF licenses this file
|
|
# to you under the Apache License, Version 2.0 (the
|
|
# "License"); you may not use this file except in compliance
|
|
# with the License. You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing,
|
|
# software distributed under the License is distributed on an
|
|
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
# KIND, either express or implied. See the License for the
|
|
# specific language governing permissions and limitations
|
|
# under the License.
|
|
|
|
"""
|
|
Custom documentation additions for compute functions.
|
|
"""
|
|
|
|
function_doc_additions = {}
|
|
|
|
function_doc_additions["filter"] = """
|
|
Examples
|
|
--------
|
|
>>> import pyarrow as pa
|
|
>>> arr = pa.array(["a", "b", "c", None, "e"])
|
|
>>> mask = pa.array([True, False, None, False, True])
|
|
>>> arr.filter(mask)
|
|
<pyarrow.lib.StringArray object at ...>
|
|
[
|
|
"a",
|
|
"e"
|
|
]
|
|
>>> arr.filter(mask, null_selection_behavior='emit_null')
|
|
<pyarrow.lib.StringArray object at ...>
|
|
[
|
|
"a",
|
|
null,
|
|
"e"
|
|
]
|
|
"""
|
|
|
|
function_doc_additions["mode"] = """
|
|
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)]>
|
|
"""
|
|
|
|
function_doc_additions["min"] = """
|
|
Examples
|
|
--------
|
|
>>> import pyarrow as pa
|
|
>>> import pyarrow.compute as pc
|
|
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
|
|
>>> pc.min(arr1)
|
|
<pyarrow.Int64Scalar: 1>
|
|
|
|
Using ``skip_nulls`` to handle null values.
|
|
|
|
>>> arr2 = pa.array([1.0, None, 2.0, 3.0])
|
|
>>> pc.min(arr2)
|
|
<pyarrow.DoubleScalar: 1.0>
|
|
>>> pc.min(arr2, skip_nulls=False)
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
|
|
|
|
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
|
|
>>> pc.min(arr3)
|
|
<pyarrow.DoubleScalar: 1.0>
|
|
>>> pc.min(arr3, options=pc.ScalarAggregateOptions(min_count=3))
|
|
<pyarrow.DoubleScalar: 1.0>
|
|
>>> pc.min(arr3, options=pc.ScalarAggregateOptions(min_count=4))
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
This function also works with string values.
|
|
|
|
>>> arr4 = pa.array(["z", None, "y", "x"])
|
|
>>> pc.min(arr4)
|
|
<pyarrow.StringScalar: 'x'>
|
|
"""
|
|
|
|
function_doc_additions["max"] = """
|
|
Examples
|
|
--------
|
|
>>> import pyarrow as pa
|
|
>>> import pyarrow.compute as pc
|
|
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
|
|
>>> pc.max(arr1)
|
|
<pyarrow.Int64Scalar: 3>
|
|
|
|
Using ``skip_nulls`` to handle null values.
|
|
|
|
>>> arr2 = pa.array([1.0, None, 2.0, 3.0])
|
|
>>> pc.max(arr2)
|
|
<pyarrow.DoubleScalar: 3.0>
|
|
>>> pc.max(arr2, skip_nulls=False)
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
|
|
|
|
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
|
|
>>> pc.max(arr3)
|
|
<pyarrow.DoubleScalar: 3.0>
|
|
>>> pc.max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
|
|
<pyarrow.DoubleScalar: 3.0>
|
|
>>> pc.max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
This function also works with string values.
|
|
|
|
>>> arr4 = pa.array(["z", None, "y", "x"])
|
|
>>> pc.max(arr4)
|
|
<pyarrow.StringScalar: 'z'>
|
|
"""
|
|
|
|
function_doc_additions["min_max"] = """
|
|
Examples
|
|
--------
|
|
>>> import pyarrow as pa
|
|
>>> import pyarrow.compute as pc
|
|
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
|
|
>>> pc.min_max(arr1)
|
|
<pyarrow.StructScalar: [('min', 1), ('max', 3)]>
|
|
|
|
Using ``skip_nulls`` to handle null values.
|
|
|
|
>>> arr2 = pa.array([1.0, None, 2.0, 3.0])
|
|
>>> pc.min_max(arr2)
|
|
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
|
|
>>> pc.min_max(arr2, skip_nulls=False)
|
|
<pyarrow.StructScalar: [('min', None), ('max', None)]>
|
|
|
|
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
|
|
|
|
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
|
|
>>> pc.min_max(arr3)
|
|
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
|
|
>>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=3))
|
|
<pyarrow.StructScalar: [('min', 1.0), ('max', 3.0)]>
|
|
>>> pc.min_max(arr3, options=pc.ScalarAggregateOptions(min_count=4))
|
|
<pyarrow.StructScalar: [('min', None), ('max', None)]>
|
|
|
|
This function also works with string values.
|
|
|
|
>>> arr4 = pa.array(["z", None, "y", "x"])
|
|
>>> pc.min_max(arr4)
|
|
<pyarrow.StructScalar: [('min', 'x'), ('max', 'z')]>
|
|
"""
|
|
|
|
function_doc_additions["first"] = """
|
|
Examples
|
|
--------
|
|
>>> import pyarrow as pa
|
|
>>> import pyarrow.compute as pc
|
|
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
|
|
>>> pc.first(arr1)
|
|
<pyarrow.Int64Scalar: 1>
|
|
|
|
Using ``skip_nulls`` to handle null values.
|
|
|
|
>>> arr2 = pa.array([None, 1.0, 2.0, 3.0])
|
|
>>> pc.first(arr2)
|
|
<pyarrow.DoubleScalar: 1.0>
|
|
>>> pc.first(arr2, skip_nulls=False)
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
|
|
|
|
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
|
|
>>> pc.first(arr3)
|
|
<pyarrow.DoubleScalar: 1.0>
|
|
>>> pc.first(arr3, options=pc.ScalarAggregateOptions(min_count=3))
|
|
<pyarrow.DoubleScalar: 1.0>
|
|
>>> pc.first(arr3, options=pc.ScalarAggregateOptions(min_count=4))
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
See Also
|
|
--------
|
|
pyarrow.compute.first_last
|
|
pyarrow.compute.last
|
|
"""
|
|
|
|
function_doc_additions["last"] = """
|
|
Examples
|
|
--------
|
|
>>> import pyarrow as pa
|
|
>>> import pyarrow.compute as pc
|
|
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
|
|
>>> pc.last(arr1)
|
|
<pyarrow.Int64Scalar: 2>
|
|
|
|
Using ``skip_nulls`` to handle null values.
|
|
|
|
>>> arr2 = pa.array([1.0, 2.0, 3.0, None])
|
|
>>> pc.last(arr2)
|
|
<pyarrow.DoubleScalar: 3.0>
|
|
>>> pc.last(arr2, skip_nulls=False)
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
|
|
|
|
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
|
|
>>> pc.last(arr3)
|
|
<pyarrow.DoubleScalar: 3.0>
|
|
>>> pc.last(arr3, options=pc.ScalarAggregateOptions(min_count=3))
|
|
<pyarrow.DoubleScalar: 3.0>
|
|
>>> pc.last(arr3, options=pc.ScalarAggregateOptions(min_count=4))
|
|
<pyarrow.DoubleScalar: None>
|
|
|
|
See Also
|
|
--------
|
|
pyarrow.compute.first
|
|
pyarrow.compute.first_last
|
|
"""
|
|
|
|
function_doc_additions["first_last"] = """
|
|
Examples
|
|
--------
|
|
>>> import pyarrow as pa
|
|
>>> import pyarrow.compute as pc
|
|
>>> arr1 = pa.array([1, 1, 2, 2, 3, 2, 2, 2])
|
|
>>> pc.first_last(arr1)
|
|
<pyarrow.StructScalar: [('first', 1), ('last', 2)]>
|
|
|
|
Using ``skip_nulls`` to handle null values.
|
|
|
|
>>> arr2 = pa.array([None, 2.0, 3.0, None])
|
|
>>> pc.first_last(arr2)
|
|
<pyarrow.StructScalar: [('first', 2.0), ('last', 3.0)]>
|
|
>>> pc.first_last(arr2, skip_nulls=False)
|
|
<pyarrow.StructScalar: [('first', None), ('last', None)]>
|
|
|
|
Using ``ScalarAggregateOptions`` to control minimum number of non-null values.
|
|
|
|
>>> arr3 = pa.array([1.0, None, float("nan"), 3.0])
|
|
>>> pc.first_last(arr3)
|
|
<pyarrow.StructScalar: [('first', 1.0), ('last', 3.0)]>
|
|
>>> pc.first_last(arr3, options=pc.ScalarAggregateOptions(min_count=3))
|
|
<pyarrow.StructScalar: [('first', 1.0), ('last', 3.0)]>
|
|
>>> pc.first_last(arr3, options=pc.ScalarAggregateOptions(min_count=4))
|
|
<pyarrow.StructScalar: [('first', None), ('last', None)]>
|
|
|
|
See Also
|
|
--------
|
|
pyarrow.compute.first
|
|
pyarrow.compute.last
|
|
"""
|